# Python Package Release

`kaizen-agentic` publishes as the `kaizen-agentic` Python package on the Coulomb
Gitea PyPI registry. Public [pypi.org](https://pypi.org/) distribution is optional
and not required for ecosystem use.

## Install (consumers)

Dependencies such as `pyyaml` resolve from public PyPI. Use Gitea as an extra index:

```bash
export GITEA_PACKAGE_USER=<gitea-user>
export GITEA_PACKAGE_TOKEN=<package-token>

pip install kaizen-agentic \
  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
```

Global CLI via pipx:

```bash
pipx install kaizen-agentic \
  --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
```

Do not commit tokenized index URLs. Inject credentials via environment variables or
CI secrets.

## Local Release

Build and validate artifacts:

```bash
make package-check
```

Publish to the Coulomb organization registry:

```bash
TWINE_USERNAME=<gitea-user> \
TWINE_PASSWORD=<package-token> \
make publish-gitea
```

Package upload endpoint:

```text
https://gitea.coulomb.social/api/packages/coulomb/pypi
```

Consumer simple index:

```text
https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
```

## Gitea repository secrets (one-time)

Configure in Gitea: **Repository → Settings → Actions → Secrets**.

| Secret | Value |
|--------|-------|
| `PACKAGE_USER` | `tegwick` — Gitea username that owns the package token |
| `PACKAGE_TOKEN` | Gitea API token named `inter-hub-pkg-rep` (`write:package`) |

Token custody (OpenBao):

```text
platform/data/operators/inter-hub/package-management
  → field: inter-hub-pkg-rep
```

Paste the **plaintext** token into the Gitea secret UI. `inter-hub-pkg-rep` is the
token name in Gitea, not a username.

Gitea rejects secret names prefixed with `GITEA_` — use `PACKAGE_USER` / `PACKAGE_TOKEN`
(not `GITEA_PACKAGE_USER`). Workflows use `runs-on: haskelseed` and native `git clone`
(no GitHub Marketplace actions).

The publish workflow fails at the upload step when either secret is missing or
invalid. Do not commit tokens to the repository.

**Smoke-test (2026-06-16):** `workflow_dispatch` run #3042 authenticated successfully
(`409 Conflict` on re-upload of `1.1.0` — expected). Root causes of earlier `401`s:
wrong token (`GITEA_API_TOKEN` ≠ package token), wrong username (`inter-hub-pkg-rep`
is a token name), and a stale org-level secret. Build uses `.build-venv` (PEP 668).

Verify secrets without cutting a release:

1. Open **Actions → Publish Python package → Run workflow** (`workflow_dispatch`),
   or dispatch via API:
   `POST /api/v1/repos/coulomb/kaizen-agentic/actions/workflows/publish-python-package.yml/dispatches`
   with body `{"ref":"main"}`
2. Confirm the run completes and `twine upload` succeeds
3. Optional: `pip install kaizen-agentic==<version> --extra-index-url ...`

The publish job uses an isolated `.build-venv` on the runner (PEP 668 safe).

## Pre-tag release checklist

Before `git tag vX.Y.Z && git push origin vX.Y.Z`:

- [ ] `make release-check` passes (tests, flake8, version consistency, agent parity)
- [ ] `make package-check` builds and validates `dist/*`
- [ ] `CHANGELOG.md` has a dated `[X.Y.Z]` section matching `pyproject.toml`
- [ ] `PACKAGE_USER` and `PACKAGE_TOKEN` secrets are set
- [ ] Publish workflow smoke-tested via `workflow_dispatch` (or prior tag release)
- [ ] `make agents-sync-package` run if `agents/` changed since last release

## Gitea Actions Release

The `.gitea/workflows/publish-python-package.yml` workflow publishes on tags
matching `v*`.

Example:

```bash
git tag v1.2.0
git push origin v1.2.0
```

## Public PyPI (optional)

When pypi.org credentials are configured (`~/.pypirc` or `TWINE_PASSWORD` API
token with `TWINE_USERNAME=__token__`):

```bash
make release-publish
python -m twine upload dist/*
```

## Scheduled-run runner prerequisites (WP-0006)

A runner that executes a scheduled kaizen agent task (fired by activity-core)
needs:

- **`kaizen-agentic` on PATH** — `pip install kaizen-agentic` (or `pipx install
  kaizen-agentic`) using the Gitea PyPI extra index when installing from the
  internal registry:
  ```bash
  pip install kaizen-agentic \
    --extra-index-url https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
  ```
- **Repo checkout reachable** at the `host_paths[<host>]` registered in State
  Hub, with a valid `.kaizen/schedule.yml` (`kaizen-agentic schedule validate`).
- **No State Hub required for `prepare`** — `schedule prepare` reads local
  `.kaizen/` state only. The hub is needed by the *resolver* (activity-core),
  not by the prepared session.

**Enabling a definition** (activity-core operator): keep the kaizen definitions
at `enabled: false` until a manual smoke test passes (see
[INTEGRATION_PATTERNS.md Pattern 2](INTEGRATION_PATTERNS.md) and the
[activity-core handoff checklist](integrations/activity-core-handoff-wp0006.md)),
then flip one definition to `enabled: true` in staging before fleet-wide enable.