[INFRA] PyPI Publishing Pipeline (Common + Agents)

[scottchronicity]

Context

Orpheus components are currently only consumable by cloning the repository. Publishing orpheus-common and each agent as independent PyPI packages enables third-party integrations, reuse in other wildlife monitoring projects, and a clean dependency model for contributors who only want to use a subset of the system.

The goal: pip install orpheus-agent-bird-detection should work.

Dependencies

Requires: [INFRA] Independent Component Versioning System

Architecturally Significant Requirements (ASRs)

Interface (Contract):

• Each component has a pyproject.toml conforming to the PEP 517/518 build standard.
• Package names follow the orpheus-<component-type>-<name> convention: orpheus-common, orpheus-agent-bird-detection, orpheus-agent-audio-motion, etc.
• Extras: agents declare extras_require for optional hardware dependencies (e.g., [jetson] for ALSA/GPIO bindings).
• Build backend: hatchling or setuptools >= 61.0 (must support dynamic = ["version"] reading from VERSION file).

Implementation (Internal Logic):

• Template pyproject.toml for agent packages: project name, description, Python requires (>=3.9), dependencies, optional extras.
• Template pyproject.toml for orpheus-common: classifiers, author, license, README long description.
• Build validation: python -m build --wheel must succeed for every component in CI.
• Test PyPI: publish to TestPyPI on every PR touching a component, publish to PyPI on version tag.

Architectural Constraints

• Packages must declare python_requires = ">=3.9" — no 3.10+ only packages.
• Hardware-specific dependencies (ALSA, GPIO, CUDA) must be in optional extras_require, not required dependencies, so packages install cleanly on developer machines.
• README files for each component must be suitable as PyPI long descriptions (no repo-relative image paths).
• Must not require a monorepo install tool (pip-installable as standalone packages).

Acceptance Criteria

Feature: PyPI Publishing Pipeline

  Scenario: Install orpheus-common from PyPI
    Given orpheus-common has been published to PyPI
    When running "pip install orpheus-common" in a clean environment
    Then the package installs without errors on Python 3.9, 3.10, and 3.11

  Scenario: Install agent from PyPI
    Given orpheus-agent-bird-detection has been published to PyPI
    When running "pip install orpheus-agent-bird-detection"
    Then the package installs with orpheus-common as a transitive dependency

  Scenario: Hardware extras install cleanly on developer machine
    Given orpheus-agent-audio-motion is installed without extras
    When running "pip install orpheus-agent-audio-motion"
    Then the package installs without requiring ALSA or GPIO libraries
    And the [jetson] extra can be installed separately on Jetson hardware

  Scenario: Build wheel in CI
    Given a PR modifies any file in platform/orpheus-common
    When the CI pipeline runs
    Then "python -m build --wheel" succeeds for orpheus-common
    And the wheel is uploaded to TestPyPI as a pre-release artifact

Definition of Done

• pyproject.toml added to platform/orpheus-common and all agents using the approved template.
• Template documents created: docs/templates/pyproject-agent.toml.template and docs/templates/pyproject-common.toml.template.
• Hardware-specific dependencies moved to [jetson] extras across all relevant agents.
• CI step: python -m build --wheel validates every component's package build on each PR.
• TestPyPI publication configured for pre-release validation on tagged commits.
• CONTRIBUTING.md updated with instructions for releasing a new package version.

---

Architectural Dependencies

• Requires [INFRA] Independent Component Versioning System #38: [INFRA] Independent Component Versioning System