adapter-schemas

The framework-free wire contract shared by Adagio's action backend and every execution adapter (adagio-server, Adagio Desktop, and future HPC/AWS/GCP adapters). It is the single source of truth for the pull-agent ↔ action boundary so the contract cannot drift between the backend and the adapters that talk to it.

It depends on nothing but pydantic — no FastAPI, no ORM, no adapter app code — so any service can install it cheaply and any language can consume the exported JSON Schema.

Install

After the 0.5.0 release is published to PyPI:

pip install adapter-schemas==0.5.0

Use

from adapter_schemas import ClaimedJob, NodeStatusReport, NodePhase, CONTRACT_VERSION

CONTRACT_VERSION is the wire protocol version ("2"). It is intentionally separate from this package's distribution version (0.5.0): the package can be repackaged/refactored without changing the on-the-wire contract, and vice-versa.

Layout

src/adapter_schemas/agent.py    the contract models (canonical)
src/adapter_schemas/__init__.py public API re-export + __all__
schema/adapter-schemas.json     JSON Schema projection (generated; lattice/TS source)
scripts/export_schema.py        regenerate schema/ from the models
tests/                          standalone-import + round-trip smoke tests

Regenerating the JSON Schema

The models are the source of truth; the JSON Schema is generated from them. After any model change:

python scripts/export_schema.py

Consumers in other languages (lattice's TypeScript) generate their types from schema/adapter-schemas.json — they must not hand-mirror the Python models. CI should run the export and fail if the checked-in schema is out of date.

Versioning / compatibility

• Additive, backward-compatible changes → bump the minor package version.
• Breaking wire changes → bump CONTRACT_VERSION and the package minor while the package is pre-1.0 (the package major after 1.0).
• Adapters pin a compatible range (e.g. adapter-schemas>=0.5.0,<0.6).

Action and the runner use synchronized vendored copies for development builds; published Python distributions use this package as an ordinary PyPI dependency. Storage transfer is deliberately outside this server-path execution contract: jobs read and write paths on their runtime target. The one exception is artifact content, below.

Artifact content (0.4.0)

A runner that advertises the artifact_content capability can be sent an ArtifactContentRequest when a user opens a visualization one of its jobs saved. It uploads that file, or answers ArtifactUnavailable. Runners without the capability are never asked, so this is additive within wire contract 2. Only visualizations are requested; pipeline inputs and data artifacts are not.

Telemetry hardening (0.3.1)

Reports are bounded to one MiB of serialized JSON. Individual event/provenance metadata is limited to 64 KiB; traceback/error text to 65,536 characters; log entries to 4,096 characters; and log/event batches to 32 entries. These limits do not apply to pipeline input files or job counts. Runners split logs into bounded batches, retain full logs locally, and omit oversized optional metadata with a telemetry_truncated marker. Existing v2 runners should be updated before enforcing these bounds for workloads producing large reports.

A runner may report interrupted only for its own leased job (for example during shutdown). It is terminal and does not request a retry. Unknown event types are rejected for this wire version; forward-compatible event evolution is separate work.

The version above identifies the release candidate in this checkout; it does not assert that a package or Git release tag has been published. Verify publication and immutable consumer pins as part of release promotion.

Publishing

The GitHub repository can remain private. The MIT-licensed distributions on PyPI contain the Python contract code; the source archive also includes the generated JSON Schema and its tests. No Git history or application implementation is published.

See RELEASING.md in the repository for Trusted Publisher setup and release gates.

Cache phases (0.5.0)

Nodes distinguish preparing, preparing_cache, checking_cache, and using_cache from running (the scientific action). All four phases are active and non-terminal; only cached confirms successful reuse. Progress ticks need not change phase. Stage timings remain optional metadata on the existing node_finished event.

Deploy the Action backend accepting these phases before an updated runtime server starts sending them. Older runners remain supported. An older backend rejects unknown phase enum values; this update does not negotiate capabilities.

Development consumers may vendor a reviewed commit using the sync script. Before a consumer release, re-sync from the immutable v0.5.0 release tag. This also replaces development pins when the schema PR was squash-merged.