Skip to content

ADR 0003 — Publish as public Python library on PyPI

Status: Accepted Date: 2026-05-25 Deciders: principal-architect (eric) Supersedes: PRD §9 open question "Do we publish the framework as a public library?"

Context

The PRD left this open: should v1.0+ be private-use only, or shipped as a public PyPI package? At v1.0 documentation: - All 168 framework artifacts documented - 13 runtime modules, 90% test coverage, 342 tests - Constitutional governance + privacy runtime work end-to-end with mock LLM - Anthropic SDK integration is opt-in via [llm] extra - License: Apache 2.0

Arguments for private: - Less surface area to maintain backward compatibility for - No public bug triage burden - Internal experimentation is faster without API stability commitments

Arguments for public: - Skills marketplace is already public — the framework as glue is the missing open piece - Constitutional governance + spec-driven dev are recognizably useful patterns for anyone building multi-agent systems - Open-source forcing function: keeps the spec/runtime in sync (other people reading the code is the strongest review) - Discovery loop: pubilc users find bugs we wouldn't have hit

Decision

Publish as public on PyPI as mult-agentes from v1.1.0 onward.

The PyPI publish workflow ships in v1.1 (/.github/workflows/publish.yml). First release will be v1.1.0 cut from main after this ADR merges.

Consequences

Positive

  • Public discoverability + skills marketplace alignment
  • Community contributions become possible
  • Forcing function on docs quality (already at 100% per Diátaxis)

Negative

  • Backward compatibility commitments — semver discipline becomes binding
  • Public security disclosure process needed (we have SECURITY.md)
  • Issue/PR bandwidth allocation

Risks + mitigations

  • R: someone uses unstable internals → M: declare public API surface in src/__init__.py exports; everything else is _private
  • R: copyright/PII in audit chain reaches public users → M: chain is HMAC-keyed per deployment; never bundled
  • R: marketplace skills shipped in package balloon size → M: skills are NOT bundled; package contains framework only, users install skills separately

Compatibility

Public API at v1.1.0 (everything else is _internal):

from mult_agentes import (
    # pipeline
    PipelineOrchestrator, Capsule, Constraints, TaskSpec,
    # privacy
    PIIDetector, PermissionManager, AuditChain,
    # ai
    ModelManager, AgentMetrics,
    # observability
    SLOMonitor, PrometheusExporter, HealthEndpoint,
)

Semver pledge: breaking changes only on major version bumps. Deprecation warnings for at least one minor version before removal.

Open follow-ups

  • Set up PyPI Trusted Publishing on first release (zero secrets needed)
  • Publish docs to claudinoinsights.github.io/mult-agentes/ via docs.yml
  • Announce on r/LocalLLaMA, HN, and Anthropic Discord after first stable release

References