Skip to main content

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 None is omitted, so the API server applies the CRD's default.
  • Free-form fields such as StationSpec.template are Any.
  • Enums are str enums; 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 PLURAL and SHORT_NAMES; GROUP, VERSION and API_VERSION are 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.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for re-cinq-agent-contracts 0.17.0
File Size Uploaded Provenance Actions
re_cinq_agent_contracts-0.17.0.tar.gz 12.4 kB With provenance Details for re_cinq_agent_contracts-0.17.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for re-cinq-agent-contracts 0.17.0
File Interpreter ABI Platform Actions
re_cinq_agent_contracts-0.17.0-py3-none-any.whl Python 3 none any Details for re_cinq_agent_contracts-0.17.0-py3-none-any.whl

Total release size: 23.5 kB

Release files / re_cinq_agent_contracts-0.17.0.tar.gz

Download URL re_cinq_agent_contracts-0.17.0.tar.gz
Size 12.4 kB
Tags Source
SHA-256 checksum
How to use checksums
cd903be1762964640e17d4d84ffea2d921a7960b071ab4a001462b0b3424d9b6
BLAKE2b-256 checksum
How to use checksums
efa822decc7c859985ea518c5c20a381914ce9810400308f312143146d6cba79
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 5, 2026.

Transparency log

Release files / re_cinq_agent_contracts-0.17.0-py3-none-any.whl

Download URL re_cinq_agent_contracts-0.17.0-py3-none-any.whl
Size 11.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
80db09b123cca2db90563f5fc520a120ce4ea340fcbf5122f68e528bdfd192f5
BLAKE2b-256 checksum
How to use checksums
76032e1af79e83a7ac103fe6e4473141f4fbaccfafefb1a9e7e9d2f0323f0109
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 5, 2026.

Transparency log

Security for re-cinq-agent-contracts 0.17.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.

Select from 2 files

Attestation for re_cinq_agent_contracts-0.17.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 5, 2026.

Transparency log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page