re-cinq-agent-contracts (Python)
Pydantic models and a small client for the ai-agent-subsystem
Custom Resources: Agent, Station, AgentDefinition, ModelCatalog and AgentSpawner (API group
agents.re-cinq.com/v1beta1).
The models are generated from the D structs that define the CRDs, the same source the CRD YAML and
the TypeScript, Go and Java contracts come from, so they cannot drift. CI fails if the committed
file stops matching the model, and a test decodes every manifest in examples/ and fails on any
field the models do not know.
Install
pip install "re-cinq-agent-contracts[kubernetes]"
The kubernetes extra brings the official client the examples use. Versions follow the
subsystem's releases. Requires Python 3.10+ and Pydantic 2.11+.
Models
Every resource and nested type is a Pydantic model. Attributes are snake_case and accept either
name on input (AgentSpec(station_ref=...) or AgentSpec.model_validate({"stationRef": ...})).
Write the wire form with model_dump(by_alias=True, exclude_none=True).
- A field left at
Noneis omitted, so the API server applies the CRD's default. - Free-form fields such as
StationSpec.templateareAny. - Enums are
strenums; an unknown value decodes to the first member, the same rule the controller applies, so a newer cluster does not break an older client. - Fields the models do not know are kept and written back, so reading and re-applying a resource does not drop them.
- Each kind has
PLURALandSHORT_NAMES;GROUP,VERSIONandAPI_VERSIONare module constants.
Client
AgentContractsClient wraps the kubernetes package's CustomObjectsApi and works in one
namespace (ai-agents by default):
from kubernetes import client, config
from agent_contracts import Agent, AgentContractsClient, AgentSpec, ObjectMeta
config.load_config() # kubeconfig, or the pod's service account in a cluster
agents = AgentContractsClient(client.CustomObjectsApi())
run = agents.create_agent(Agent(
metadata=ObjectMeta(generate_name="story-writer-run-"),
spec=AgentSpec(station_ref="story-writer", parameters={"title": "The Last Lighthouse"}),
))
finished = agents.wait_for_agent(run.metadata.name, timeout=1800)
print(finished.status.phase)
| Method | Does |
|---|---|
create_agent |
Start one run. |
get_agent, find_agents |
Read one run, or list runs by label selector. |
wait_for_agent |
Poll until the run is SUCCEEDED or FAILED; AgentNotFinishedError after the timeout. |
get_model_catalog |
The models the subsystem can run with its configured keys. |
apply_agent_definition, apply_station |
Server-side apply a recipe or runtime (field manager agent-contracts, forced). |
is_terminal |
Whether a run has finished. |
Development
make regen from the repository root rewrites src/agent_contracts/types_generated.py; do not
edit it by hand. make contracts-python runs the tests with a 100% coverage gate on the client.
Metadata
Release files for re-cinq-agent-contracts 0.21.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| re_cinq_agent_contracts-0.21.0.tar.gz | 12.4 kB | With provenance | Details for re_cinq_agent_contracts-0.21.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| re_cinq_agent_contracts-0.21.0-py3-none-any.whl | Python 3 | none | any | Details for re_cinq_agent_contracts-0.21.0-py3-none-any.whl |
Total release size: 23.5 kB
Release files / re_cinq_agent_contracts-0.21.0.tar.gz
| Download URL | re_cinq_agent_contracts-0.21.0.tar.gz |
|---|---|
| Size | 12.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f8c70ce3ced11ad3cd1698e2be0d99c9b5862aae87ba95d93f8fbd38c67c7d7f
|
|
BLAKE2b-256 checksum How to use checksums |
4f73a11e09e60d5dbcd4aa3e00e0d0a63c8d434ae3c8bc8299301068f055be34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / re_cinq_agent_contracts-0.21.0-py3-none-any.whl
| Download URL | re_cinq_agent_contracts-0.21.0-py3-none-any.whl |
|---|---|
| Size | 11.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ae0671741004e6c80719ddd2546ebab2ebd17aa8edc0db729edafe1cd5e5b2fd
|
|
BLAKE2b-256 checksum How to use checksums |
bd6d828003e31e79c7243bf11807440fa5e2f27f0cfba2d41d0ccd628a04378c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for re-cinq-agent-contracts 0.21.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for re_cinq_agent_contracts-0.21.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.