AI Contracts (In-Repo)

This package is the in-repo contract surface for Action Planner consumers. Keep this README brief; use WORKFLOW.md for end-to-end workflow and release details.

Source of truth

• Primitive authoring remains in protocol + typed param definitions:
  • src/protocols/**/protocol.py
  • src/agents_workflows/action_planner/domain/models/primitives.py
• Contract artifacts are generated from runtime models in this repo:
  • scripts/contracts/export_schemas.py

Generated artifacts

Generation writes JSON schemas and primitive catalogs into packages/ai-contracts/generated/schemas/:

• primitive-catalog.json
• primitive.schema.json
• action-planner-submit.schema.json
• action-planner-output.schema.json
• action-block.schema.json
• TypeScript declarations in generated/types/*.d.ts
• Zod validators in generated/zod/*.js

Commands

From repo root:

• make contracts-generate (runs export + gen + update:version)
• make contracts-check (runs check:export + check:gen + check:version)
• make contracts-hardening-check (runs ai-contracts hardening pytest coverage)

contract-version.json records the latest package version and the generated-artifact digest (artifacts_sha256).

Consumer imports

JavaScript/TypeScript consumers can import either:

• package entrypoint values:
  • @chaoslabs/ai-contracts-v2 exports primitiveSchemaJson, actionPlannerSubmitSchema, actionPlannerOutputSchema, actionBlockSchema, primitiveCatalog, primitiveSchema, actionPlannerSubmitZod, actionPlannerOutputZod, actionBlockZod
• direct schema paths:
  • @chaoslabs/ai-contracts-v2/primitive.schema.json
  • @chaoslabs/ai-contracts-v2/action-planner-submit.schema.json
  • @chaoslabs/ai-contracts-v2/action-planner-output.schema.json
  • @chaoslabs/ai-contracts-v2/action-block.schema.json
  • @chaoslabs/ai-contracts-v2/primitive-catalog.json
• generated type paths:
  • @chaoslabs/ai-contracts-v2/types/primitive
  • @chaoslabs/ai-contracts-v2/types/action-planner-submit
  • @chaoslabs/ai-contracts-v2/types/action-planner-output
  • @chaoslabs/ai-contracts-v2/types/action-block
• generated zod paths:
  • @chaoslabs/ai-contracts-v2/zod/primitive
  • @chaoslabs/ai-contracts-v2/zod/action-planner-submit
  • @chaoslabs/ai-contracts-v2/zod/action-planner-output
  • @chaoslabs/ai-contracts-v2/zod/action-block

Primitive change workflow

1. Add/update primitive in protocol + typed params.
2. Run make contracts-generate.
3. Commit both runtime changes and generated artifacts together.