Metadata-Version: 2.5
Name: adapter-schemas
Version: 0.3.1
Summary: Framework-free wire contract shared by Adagio's action backend and its execution adapters.
Project-URL: Homepage, https://github.com/cymis/adapter-schemas
Project-URL: Repository, https://github.com/cymis/adapter-schemas
Project-URL: Issues, https://github.com/cymis/adapter-schemas/issues
Author: Cymis
License-Expression: MIT
License-File: LICENSE
Keywords: adagio,adapter,contract,pydantic,schemas
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# 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.3.1 release is published to PyPI:

```
pip install adapter-schemas==0.3.1
```

## Use

```python
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.3.1`): 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.3`).

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.

## 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.
