Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 130 additions & 0 deletions .github/workflows/python-release.yml
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 ./...
Comment thread
gambtho marked this conversation as resolved.
Resolved
- 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
14 changes: 14 additions & 0 deletions docs/.vitepress/browser.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,20 @@ test('landing and specification reflow at narrow, tablet and enlarged-text width
} finally { await page.close() }
})

test('Python integration is navigable and readable on desktop and mobile', async () => {
const page = await browser.newPage({ reducedMotion: 'reduce' })
try {
for (const width of [390, 1440]) {
await page.setViewportSize({ width, height: 1000 })
await ready(page, '/python')
assert.equal(await page.getByRole('heading', { level: 1, name: 'Python integration' }).count(), 1)
assert.equal(await page.locator('.vp-doc').getByText('Registry', { exact: false }).count() > 0, true)
assert.equal(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth), true)
assert.equal(await page.locator('.VPSidebar a[href="/python"]').count(), 1)
}
} finally { await page.close() }
})

test('legacy specification fragments land beside their relocated sections', async () => {
for (const [old, current] of [
['822-case-documents-and-assertions', '32-case-documents-and-assertions'],
Expand Down
4 changes: 3 additions & 1 deletion docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { publishCatalog } from '../../scripts/schema-bundles.mjs'
const root = fileURLToPath(new URL('../..', import.meta.url))
const repository = 'https://github.com/agent-primitives/suite'
const sourceRef = process.env.GITHUB_SHA || 'main'
const pages = ['index', 'schemas', 'conformance', 'go', 'releases', 'hosting', 'legacy-draft', 'directory-identity', 'experimental-flow']
const pages = ['index', 'schemas', 'conformance', 'go', 'python', 'releases', 'hosting', 'legacy-draft', 'directory-identity', 'experimental-flow']

export default defineConfig({
title: 'AgentSuite',
Expand Down Expand Up @@ -72,6 +72,7 @@ export default defineConfig({
{ text: 'Specification', link: '/spec' },
{ text: 'Schemas', link: '/schemas' },
{ text: 'Go usage', link: '/go' },
{ text: 'Python usage', link: '/python' },
{ text: 'Conformance', link: '/conformance' }
],
sidebar: [
Expand All @@ -80,6 +81,7 @@ export default defineConfig({
{ text: 'Schemas', link: '/schemas' },
{ text: 'Conformance fixtures', link: '/conformance' },
{ text: 'Go usage', link: '/go' },
{ text: 'Python usage', link: '/python' },
{ text: 'Versions and releases', link: '/releases' },
{ text: 'Directory identity migration', link: '/directory-identity' },
{ text: 'Experimental flow', link: '/experimental-flow' },
Expand Down
9 changes: 8 additions & 1 deletion docs/.vitepress/site.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ const html = name => readFile(path.join(dist, `${name}.html`), 'utf8')
const catalog = JSON.parse(await readFile(path.join(root, 'docs/schema-catalog.json'), 'utf8'))

test('all documentation pages render with root-based navigation and assets', async () => {
const pages = ['404', 'index', 'spec', 'schemas', 'conformance', 'go', 'releases', 'hosting', 'legacy-draft', 'directory-identity', 'experimental-flow']
const pages = ['404', 'index', 'spec', 'schemas', 'conformance', 'go', 'python', 'releases', 'hosting', 'legacy-draft', 'directory-identity', 'experimental-flow']
assert.deepEqual((await readdir(dist)).filter(name => name.endsWith('.html')).sort(), pages.map(name => `${name}.html`).sort())
for (const page of pages) {
const content = await html(page)
Expand All @@ -26,6 +26,13 @@ test('all documentation pages render with root-based navigation and assets', asy
assert.match(home, /https:\/\/github.com\/agent-primitives\/suite/)
})

test('Python integration renders the complete package-to-digest path and owner boundaries', async () => {
const content = await html('python')
for (const value of ['Package', 'Registry', 'set_instructions', 'write_oci', 'publish', 'root_digest', 'artifact_digest', 'AGENTSUITE_GO_ORACLE_ROOT']) assert.ok(content.includes(value), value)
for (const value of ['does not execute', 'origin', 'owner', 'development', 'pypi']) assert.ok(content.includes(value), value)
assert.ok((await html('go')).includes('href="/python"'))
})

test('experimental flow documentation renders the explicit opt-in and runtime boundary', async () => {
const content = await html('experimental-flow')
for (const name of ['ValidatePathFlowV1Alpha1', 'ValidateDirectoryFlowV1Alpha1', 'VerifyEvaluationFlowV1Alpha1']) assert.ok(content.includes(name))
Expand Down
144 changes: 144 additions & 0 deletions docs/python.md
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.
7 changes: 7 additions & 0 deletions docs/releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -371,6 +371,13 @@ execution contracts. v0.2.0 introduced the filesystem policy package.
See the [normative policy contract](../spec.md#appendix-b-standalone-policy-contracts-normative)
and [reference schemas](schemas.md).

## Python release preparation

Before the first SDK release, the Suite v0.8 freeze commit must also contain the
final SDK code and SDK version bump. Keep those immutable tags, merge the reviewed
schema catalog, then follow [Python release qualification](python.md#owner-controlled-release-qualification).
Qualification is not an upload; the protected `pypi` environment requires release-owner approval.

## Compatibility

Go module versions and format/schema versions are independent. A Go release does
Expand Down
10 changes: 6 additions & 4 deletions python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,10 @@ bytes. It does not execute evaluations, qualify a runtime, enforce policy or
resolve administrative restrictions.

This development distribution is not a PyPI release. Publication and release
qualification are separate maintainer steps. Local writing and canonical identity
helpers are included; registry clients, network fetching and public outer-archive
loading are not.
qualification are separate maintainer steps. Local writing, canonical identity
helpers and digest-preserving registry publication are included; registry pull and
public outer-archive loading are not. See the [complete integration path](../docs/python.md)
for explicit credentials, publication failures and owner-controlled release plumbing.

## Install

Expand Down Expand Up @@ -89,7 +90,8 @@ Instruction and tool-schema pins hash their exact literal bytes.

`artifact_digest` is the distinct SHA-256 of the exact OCI manifest bytes, or
`None` for directory input. It is not the Suite root digest or an aggregate hash
of content. No public aggregate digest or registry-reference API is provided.
of content. No public aggregate digest is provided. `Registry.publish` returns a registry reference
using the exact OCI manifest identity, not this root/document identity.

The pure `canonical_bytes(value)` and `digest(value)` helpers use RFC 8785, not
sorted Python JSON. `variant_digest(value)` blanks only the top-level
Expand Down
2 changes: 1 addition & 1 deletion python/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description = "AgentSuite package reader and format models"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"
dependencies = ["rfc8785==0.1.4", "jsonschema==4.26.0", "referencing==0.37.0", "google-re2==1.1.20251105"]
dependencies = ["rfc8785==0.1.4", "jsonschema==4.26.0", "referencing==0.37.0", "google-re2==1.1.20251105", "requests==2.34.2"]

[tool.setuptools.packages.find]
where = ["src"]
Expand Down
1 change: 1 addition & 0 deletions python/requirements-dev.txt
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
Loading
Loading