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.21.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.21.0
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)

Table of built distributions (wheels) for re-cinq-agent-contracts 0.21.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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