# 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 Actions Release

The `.gitea/workflows/publish-python-package.yml` workflow publishes on tags
matching `v*`. Configure these repository secrets before cutting a release:

- `GITEA_PACKAGE_USER`
- `GITEA_PACKAGE_TOKEN`

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/*
```