Skip to main content

Distribution

This page captures the repo’s distribution and publishing paths.

Python Package

  • Package name target: ts-agents
  • Build backend: setuptools
  • Build command:
uv build

Publishing automation lives in .github/workflows/publish-pypi.yml.

The workflow is designed for GitHub Actions -> PyPI trusted publishing and runs on version tags (v*) or manual dispatch.

Optional TestPyPI validation lives in .github/workflows/publish-testpypi.yml. It is a separate build/publication and does not establish byte identity with a later PyPI build.

GitHub Release Flow

Release tags use the form vX.Y.Z.

Recommended release steps:

  1. update CHANGELOG.md
  2. merge the release changes and synchronize a clean source revision
  3. install the locked test profile with uv sync --frozen --all-extras on Python 3.11-3.13
  4. run bash scripts/check_release_quality.sh and uv run --no-sync python -m pytest -q
  5. build into a fresh directory with uv build --out-dir /tmp/ts-agents-release-dist
  6. check metadata with uv tool run twine check /tmp/ts-agents-release-dist/*
  7. run python scripts/verify_release_artifacts.py --dist-dir /tmp/ts-agents-release-dist --report /tmp/artifact-verification.json
  8. run bash scripts/smoke_install_wheel.sh <python-version> /tmp/ts-agents-release-dist on Python 3.11-3.14 and rebuild/install from an extracted, Git-free sdist
  9. record the commit/tree, source digest, commands, environment, test counts, and qualification limits
  10. push an annotated version tag targeting that revision
  11. let publish-pypi.yml qualify the tagged source, build once, verify contents, smoke-install those artifacts, and publish those same artifacts
  12. download the workflow distributions, compare PyPI downloads against their hashes, and create a GitHub release with the distributions, checksums, and qualification evidence

The base install is qualified on Python 3.11-3.14. Full tests use the locked optional dependency stack on 3.11-3.13. Background jobs require POSIX (Linux/macOS or WSL); Linux is the CI qualification platform. Remote sandbox termination, native Windows background jobs, and external agent interactions are outside this release qualification. Version 0.4.1 ships only the ts-agents console entrypoint; UI/hosted apps and built-in agents have been removed.

Sandbox Container Image

The sandbox container is built from Dockerfile.sandbox.

  • Local build:
./build_docker_sandbox.sh
  • Published image target:
ghcr.io/fnauman/ts-agents-sandbox

Automation lives in .github/workflows/publish-sandbox-image.yml.

The published image is intended to give users a prebuilt sandbox backend instead of requiring a local Docker build before first use.

Notes

  • Ordinary CI runs on PR revisions and main pushes, with superseded PR runs cancelled and explicit job timeouts. It builds distributions once and shares the verified wheel across the interpreter smoke matrix. Tag pushes use the independent release qualification workflow instead of repeating ordinary CI.
  • CI smoke-tests the base wheel on Python 3.11-3.14 outside the checkout, including discovery, skills, workflows, autoresearch, run catalogs, and job completion.
  • CI also runs a narrow ruff + mypy quality gate over the release/package surface.
  • The publish workflow also gates real PyPI publishing on the same artifact smoke matrix.
  • Locked-stack tests and fresh base dependency resolution cover different environments. Neither establishes compatibility with every declared minimum.
  • Retain source identity, workflow logs, and artifact hashes with each release. GitHub/PyPI publication must be verified by downloading the artifacts.