🚧 Pre-alpha

This release is the repository scaffold. The models land in follow-up releases (see the roadmap). Everything under Core features describes the design these releases implement.

✨ Core features

Chronicle records what an agent did, the control plane stores and shows it, and TokenOps reads it to govern spend. Those three only work together if they agree on the shape of the data. This package is that agreement, and nothing else.

🚀 Quickstart

Requires Python 3.10+. The package is typed (PEP 561).

pip install agentplane-primitives   # once the first release is published

Until then, install from source:

git clone https://github.com/theagentplane/primitives.git
cd primitives
pip install -e .
python -c "import agentplane_primitives as p; print(p.__version__)"

When you need more

🧩 How it fits

flowchart LR
    P["primitives<br/>Trace · Span · Envelope"]
    C["Chronicle<br/>edge SDK: record, save, replay"]
    CP["Control plane<br/>storage, query, visualization"]
    T["TokenOps<br/>governance"]

    C -->|imports| P
    CP -->|imports| P
    T -->|imports| P
    C -->|"envelopes over HTTP"| CP
    T -->|"reads cost data"| CP

The control plane owns the schema, and this package is where that schema is defined and shared. Chronicle never talks to a database. It sends envelopes to the control plane, which keeps its own storage layout and maps from these models.

🎯 Scope

🔖 Versioning

SemVer for the package, plus a schema_version (major.minor) on every payload.

• Additive-only within a major. New optional fields are allowed. A new enum member is additive for the writer, but older readers reject it, so consumers upgrade before emitters.
• A breaking change is a new major. The control plane accepts the current and previous major.
• Pre-1.0: pin the exact minor. From 1.0: >=1.2,<2.

Full policy: docs/versioning.md.

🛠 Development

Uses uv.

uv sync                                   # environment with the dev group
uv run pytest --cov                       # tests
uv run ruff check . && uv run ruff format --check .
uv run mypy                               # strict type check
uv build                                  # sdist and wheel

🗺 Roadmap

1. ✅ Repository scaffold
2. ✅ Trace, Span, Envelope, the llm and tool payload variants, enums, ids
3. ✅ The traceparent carrier
4. ✅ Committed JSON Schema and the CI drift check
5. First release (0.1.0): see RELEASING.md

Reference

src/agentplane_primitives/   # installable package (typed; version in _version.py)
├── enums/                   # closed lists, one file each: kind, state, status, link type
├── types/                   # field types: id types, metadata key and label types
├── models/                  # the models: base class now; Trace, Span, Envelope to come
├── utils/                   # helper functions: id generation, reserved-key check (traceparent later)
└── schemas/                 # generated JSON Schema, committed and drift-checked in CI
                             # (more models and the traceparent carrier arrive in later PRs)
docs/                        # design notes and the versioning policy
tests/                       # unit tests
.github/                     # CI, release, dependency updates, templates

🛟 Support

Contributors

Thanks to everyone who has contributed.