Package publishing policy

AGILAB publishes a small set of Python packages to PyPI so public installs, notebook examples, worker environments, and release evidence can resolve the same versioned runtime without relying on a source checkout.

User-facing install surfaces

For public users, the supported entry points are:

  • agilab: the top-level UI and CLI package.

  • agi-core: the compact notebook/API runtime used by the public notebook examples.

Documentation, release notes, quick starts, and demos should point users to those surfaces first.

Internal runtime packages

The following core runtime packages are also published to PyPI:

  • agi-env

  • agi-node

  • agi-cluster

They are runtime building blocks used by agi-core, agilab, app worker environments, and CI validation. Their publication is intentional, but they are not promoted as independent user products.

Published UI support package

agi-gui is also published to PyPI from src/agilab/lib/agi-gui. It is not part of the core runtime: it depends on the headless agi-env package and adds the Streamlit/UI dependencies used by AGILAB pages and apps-pages bundles. Worker environments should keep using agi-env unless they explicitly need to render UI.

Why keep them published

Publishing these runtime packages keeps the release process reproducible:

  • pip install agilab and uvx agilab can resolve the exact package graph.

  • agi-core can pin the matching agi-env, agi-node, and agi-cluster versions for a release.

  • agilab can pin the matching agi-gui version for the UI/page surface without making worker-only installs depend on Streamlit.

  • App worker environments can install the same runtime components in isolation from the manager environment.

  • CI and release evidence can validate the same dependency graph that external users receive from PyPI.

Release rule

For each public release, publish the runtime packages and agi-gui with the same version as agilab and agi-core unless a deliberate packaging migration removes that need. Do not skip agi-node, agi-cluster, or agi-gui from the publish matrix while agi-core and agilab depend on them as external packages.

If AGILAB later embeds the agi_node and agi_cluster Python modules directly into a single wheel, that migration must update dependency metadata, installer tests, notebook examples, and the release preflight before the standalone runtime packages can be retired from the public publish flow.

Release cadence and post releases

AGILAB uses date-based public versions. A normal public release should advance to a deliberate new version. Real PyPI publication must not silently auto-create .postN releases when a version collision is detected; the release tool is expected to stop and require an explicit version choice instead.

.postN releases are acceptable only as corrective packaging releases for an already published date-based version. They are not the standard delivery cadence, and multiple same-day post releases should be treated as release process debt to review, not as a velocity metric. TestPyPI rehearsals are the exception: retry-oriented .postN bumps are allowed there because TestPyPI is often reused during dry runs.

Typing policy

The root package and core runtime packages set disallow_untyped_defs = true for project code. The repository also keeps a curated strict slice runnable via tools/shared_core_strict_typing.py or the shared-core-typing workflow profile; that slice includes agi-core and selected shared support modules and runs mypy with --strict.

ignore_missing_imports = true is still used at package boundaries to avoid making third-party stub availability a blocker for runtime development. That setting should not be read as permission for untyped AGILAB APIs: new public runtime code should remain typed, and the curated strict slice should expand as shared APIs stabilize.

Packaging notes

setup.py is intentionally kept alongside pyproject.toml. It is not a leftover from an incomplete packaging migration. pyproject.toml remains the canonical source for PyPI metadata, dependency resolution, and uv-based workflows, while setup.py is the compatibility build entry point used by the Dask worker distribution path that still emits .egg artifacts.

Removing setup.py is valid only after the worker distribution path no longer depends on egg packaging, and that migration must update the build helpers, installer tests, distributed execution tests, and release preflight in the same change.