Repository navigation
Add Python OCI publication and release qualification #85
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
574e84a
feat: add digest-preserving OCI registry publication
gambtho 0792c3b
build: add owner-gated Python release qualification
gambtho 5d52108
docs: explain the Python package publication path
gambtho aa8572a
fix: bind registry credentials and release checks to exact authorities
gambtho d6bdc23
test: author portable registry fixtures and oracle path checks
gambtho File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,130 @@ | ||
| name: python-release | ||
|
|
||
| on: | ||
| workflow_dispatch: | ||
| inputs: | ||
| sdk_tag: | ||
| description: Existing immutable SDK tag (python/vX.Y.Z) | ||
| required: true | ||
| type: string | ||
| suite_tag: | ||
| description: Existing frozen Suite tag (v0.8.P), catalogued before dispatch | ||
| required: true | ||
| type: string | ||
| publish: | ||
| description: Upload verified artifacts (requires owner-configured pypi approval) | ||
| type: boolean | ||
| default: false | ||
|
|
||
| permissions: {} | ||
|
|
||
| concurrency: | ||
| group: python-release-${{ inputs.sdk_tag }} | ||
| cancel-in-progress: false | ||
|
|
||
| jobs: | ||
| qualify: | ||
| if: github.ref == 'refs/heads/main' | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| contents: read | ||
| env: | ||
| SDK_TAG: ${{ inputs.sdk_tag }} | ||
| SUITE_TAG: ${{ inputs.suite_tag }} | ||
| GOWORK: 'off' | ||
| AGENTSUITE_GO_ORACLE_ROOT: ${{ github.workspace }}/contract-source | ||
| steps: | ||
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | ||
| with: | ||
| ref: ${{ github.sha }} | ||
| fetch-depth: 0 | ||
| fetch-tags: true | ||
| persist-credentials: false | ||
| - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 | ||
| with: | ||
| python-version: '3.14' | ||
| - name: Validate tag namespaces before executing release source | ||
| run: | | ||
| python - <<'PY' | ||
| import os, re | ||
| assert re.fullmatch(r'python/v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)', os.environ['SDK_TAG']), 'exact SDK tag required' | ||
| assert re.fullmatch(r'v0\.8\.(0|[1-9]\d*)', os.environ['SUITE_TAG']), 'frozen v0.8 tag required' | ||
| PY | ||
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | ||
| with: | ||
| ref: refs/tags/${{ inputs.sdk_tag }} | ||
| path: sdk-source | ||
| persist-credentials: false | ||
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | ||
| with: | ||
| ref: refs/tags/${{ inputs.suite_tag }} | ||
| path: contract-source | ||
| persist-credentials: false | ||
| - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 | ||
| with: | ||
| node-version: '22' | ||
| - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5.6.0 | ||
| with: | ||
| go-version-file: contract-source/go.mod | ||
| - name: Verify frozen source against the pinned trusted catalog | ||
| run: | | ||
| SUITE_SHA=$(git -C contract-source rev-parse HEAD) | ||
| node scripts/schema-release.mjs check --release "$SUITE_TAG" --ref "$SUITE_SHA" --catalog-ref "$GITHUB_SHA" | ||
| - name: Qualify SDK and frozen Go output parity | ||
| run: | | ||
| python -m pip install --only-binary=google-re2 -r sdk-source/python/requirements-dev.txt ./sdk-source/python | ||
| PYTHONPATH="$GITHUB_WORKSPACE/sdk-source/python/src" python -m pytest sdk-source/python/tests -q | ||
| PYTHONPATH="$GITHUB_WORKSPACE/sdk-source/python/src" python -m pytest contract-source/python/tests -q | ||
| GOWORK=off go -C contract-source test -count=1 ./... | ||
| - name: Build direct and sdist-derived distributions | ||
| run: | | ||
| python -m build sdk-source/python --outdir dist | ||
| mkdir derived-source derived-wheel | ||
| python - <<'PY' | ||
| import pathlib, tarfile | ||
| with tarfile.open(next(pathlib.Path('dist').glob('*.tar.gz'))) as archive: | ||
| archive.extractall('derived-source', filter='data') | ||
| PY | ||
| python -m build --wheel derived-source/* --outdir derived-wheel | ||
| - name: Bind exact source, schema and artifact identities | ||
| run: | | ||
| python scripts/check-python-release.py qualify \ | ||
| --sdk-repo sdk-source --contract-repo contract-source \ | ||
| --catalog-repo . --catalog-ref "$GITHUB_SHA" \ | ||
| --sdk-tag "$SDK_TAG" --contract-tag "$SUITE_TAG" \ | ||
| --wheel dist/*.whl --sdist dist/*.tar.gz --sdist-wheel derived-wheel/*.whl \ | ||
| --out qualification.json | ||
| - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 | ||
| with: | ||
| name: python-release-qualified | ||
| path: | | ||
| dist/*.whl | ||
| dist/*.tar.gz | ||
| qualification.json | ||
| if-no-files-found: error | ||
|
|
||
| publish: | ||
| if: github.ref == 'refs/heads/main' && inputs.publish | ||
| needs: qualify | ||
| runs-on: ubuntu-latest | ||
| environment: pypi | ||
| permissions: | ||
| contents: read | ||
| id-token: write | ||
| steps: | ||
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | ||
| with: | ||
| ref: ${{ github.sha }} | ||
| persist-credentials: false | ||
| - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 | ||
| with: | ||
| python-version: '3.14' | ||
| - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 | ||
| with: | ||
| name: python-release-qualified | ||
| path: qualified | ||
| - name: Recheck downloaded distributions before publishing authority is used | ||
| run: python scripts/check-python-release.py verify-artifacts --qualification qualified/qualification.json --dist qualified/dist | ||
| - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3 | ||
| with: | ||
| packages-dir: qualified/dist | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| # Python integration | ||
|
|
||
| The `agent-suite` distribution imports as `agent_suite`. It reads, validates, | ||
| edits, writes and publishes AgentSuite packages. It does not execute agents or | ||
| evaluations, enforce policy, or qualify a runtime. | ||
|
|
||
| This page tracks **main's development SDK**, currently `0.1.0.dev0`. It does not | ||
| announce a PyPI release or claim frozen Suite v0.8.0 compatibility. A release must | ||
| pass the frozen-contract qualification described below before publication. | ||
|
|
||
| ## Install from a checkout | ||
|
|
||
| From the repository root, with CPython 3.10 or newer: | ||
|
|
||
| ```sh | ||
| python -m pip install --only-binary=google-re2 ./python | ||
| ``` | ||
|
|
||
| The native RE2 dependency is exactly pinned; unsupported platforms must not fall | ||
| back to a source build or Python `re`. The CI matrix covers Python 3.10 and 3.14 | ||
| on Linux, macOS and Windows. Go is a conformance reference, not a runtime dependency. | ||
| Schemas ship as exact, offline package assets; loading never downloads schemas. | ||
|
|
||
| ## Inspect, edit and publish | ||
|
|
||
| Use an extracted content directory or local OCI layout. The selected package must | ||
| contain the `writer` agent used here. Both output paths must be fresh, and their | ||
| existing parents must satisfy the native reader's ownership and permission checks. | ||
|
|
||
| ```python | ||
| import os | ||
| from agent_suite import Package, Registry | ||
|
|
||
| credentials = { | ||
| "https://registry.example": ( | ||
| os.environ["REGISTRY_USERNAME"], | ||
| os.environ["REGISTRY_PASSWORD"], | ||
| ), | ||
| } | ||
|
|
||
| with Package.load("./support-suite") as package: | ||
| agent = package.agents["writer"] | ||
| print(agent.declaration.id, agent.source.file, agent.source.pointer) | ||
| instructions = "".join(agent.instructions.content.iter_text()) | ||
| package.set_instructions("writer", instructions + "\nAnswer briefly.\n") | ||
| assert package.validate() == () | ||
| layout = package.write_oci("./out-layout") | ||
|
|
||
| reference = Registry("registry.example", credentials=credentials).publish( | ||
| layout, "team/support" | ||
| ) | ||
| print(reference) # registry.example/team/support@sha256:... | ||
| ``` | ||
|
|
||
| `Package.load` performs complete schema and graph validation, including policy and | ||
| evaluation declarations. `validate()` checks the captured package, not a running | ||
| agent. Raw JSON mutation is unsupported; `set_instructions` refreshes the selected | ||
| literal, agent and Suite pins bottom-up and refuses a stale input graph. | ||
|
|
||
| After an edit, reacquire views: earlier frozen metadata remains historical, but | ||
| old literal handles are closed. To read authored JSON metadata without inventing | ||
| defaults, use `json.loads(agent.document.data)`; typed declarations and literal | ||
| content remain separate. `iter_text()` decodes UTF-8 strictly; `iter_bytes()` | ||
| preserves arbitrary literal bytes. | ||
|
|
||
| ## Keep the identities separate | ||
|
|
||
| - `root_digest` is the validated Suite root's RFC 8785 identity. It is not an OCI | ||
| address or an aggregate hash of every content file. | ||
| - `digest(value)` and `canonical_bytes(value)` use RFC 8785. `variant_digest(value)` | ||
| blanks only the top-level `variantDigest`. Instruction and schema literals hash | ||
| their exact bytes rather than canonicalized JSON. | ||
| - `artifact_digest` identifies the **exact OCI manifest bytes**. It is absent for | ||
| extracted directories and cleared by edits; reload the written OCI layout for | ||
| its new identity. `oci_manifest_digest(manifest_bytes)` hashes those exact bytes. | ||
| - `Registry.publish` returns `authority/repository@sha256:…` using that exact | ||
| manifest identity, never `root_digest`. | ||
|
|
||
| Unedited OCI copies preserve their original envelope, manifest and compressed | ||
| layer. Regenerated OCI output is deterministic. Native directory writing may | ||
| refuse modes accepted in OCI; writers do not repair modes or flatten unsupported | ||
| links. No public aggregate-content identity or generic manifest builder is exposed. | ||
|
|
||
| ## Credentials, transfer and failures | ||
|
|
||
| `Registry(origin, *, credentials=None, timeout=30.0)` accepts a registry authority | ||
| (defaulting to HTTPS) or an explicit HTTP(S) origin. Explicit HTTP is unencrypted; | ||
| use it only where that is intended, such as an owned loopback test registry. | ||
| Repository names are passed separately to `publish(layout, repository)`; this | ||
| method accepts a fully validated local OCI layout, not an extracted directory. | ||
|
|
||
| Credentials are a mapping from **exact normalized HTTP origins** to | ||
| `(username, password)` tuples. A registry token can be the password. If a Bearer | ||
| challenge uses a different token-service origin, include credentials for that | ||
| origin explicitly when it needs them; registry credentials are not copied there. | ||
| No credential files, netrc, ambient proxy credentials or response cookies are used. | ||
| The client does not expose a credential store, login flow or transport framework. | ||
|
|
||
| All transfer input is verified and captured into bounded-memory, seekable disk | ||
| snapshots before the first request. The source may then disappear without | ||
| changing the uploaded bytes. Config and layer blobs are uploaded before the | ||
| original manifest, addressed by digest. A final manifest read confirms exact | ||
| remote bytes before the reference is returned; it is verification of this upload, | ||
| not a registry pull API. Already-present blobs make repeated publication cheap. | ||
|
|
||
| Server upload locations retain their existing query parameters. Authorization is | ||
| not forwarded to a different upload origin. Bounded 307/308 redirects preserve | ||
| request methods and replay the snapshot; HTTPS is not downgraded. Other redirect | ||
| statuses and unsupported responses fail rather than changing a PUT into a GET. | ||
| No multipart, chunk-resume, background retry or registry cleanup framework exists. | ||
|
|
||
| Local `LoadError` refusals retain file/pointer diagnostics. Transfer failures raise | ||
| contextual `ValueError` without server bodies, secret-bearing URLs or tokens. | ||
| Failure after a remote write can leave blobs or a manifest present; it never | ||
| returns a guessed success. Retry the whole publication to confirm the same digest. | ||
|
|
||
| ## Owner-controlled release qualification | ||
|
|
||
| The manual `python-release.yml` workflow takes an existing `python/vX.Y.Z` SDK tag, | ||
| a frozen `v0.8.P` Suite tag, and `publish` (default **false**). It never creates tags | ||
| or changes schema IDs. The first release requires the final SDK code and version | ||
| bump in the frozen v0.8 release commit; tag that immutable source, merge the | ||
| reviewed schema-catalog update, then dispatch qualification from main. Main can | ||
| restore draft IDs afterwards because qualification checks out both exact tags. | ||
| Frozen maintenance-branch SDK patch tags are supported without requiring ancestry | ||
| from current draft main. | ||
|
|
||
| Trusted tools and the reviewed catalog are pinned to the dispatch revision. They | ||
| check exact schema bytes, source/tag/version identities, wheel and sdist provenance, | ||
| and Go conformance from the selected contract revision. Test-only | ||
| `AGENTSUITE_GO_ORACLE_ROOT` selects that frozen Go checkout; it adds no runtime Go. | ||
| The downloaded wheel and sdist are re-hashed against the qualification record | ||
| before any upload. | ||
|
|
||
| The release owner must configure PyPI Trusted Publishing and a protected `pypi` | ||
| environment requiring that owner's approval before opting into upload. Running | ||
| qualification does not upload by default. The first PyPI upload and Suite v0.8.0 | ||
| release are owner actions, not actions performed by a pull request. | ||
|
|
||
| ## Boundaries | ||
|
|
||
| The SDK does not run tests, models, providers or deployment tools. Stored test and | ||
| policy validation is not execution or enforcement. There is no registry pull, | ||
| tag publication, signing, referrer, CLI, runtime wrapper or telemetry API. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,5 @@ | ||
| build==1.6.1 | ||
| mypy==2.4.0 | ||
| pytest==9.1.1 | ||
| types-requests==2.33.0.20261006 | ||
| setuptools==84.2.1 |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.