Metadata-Version: 2.4
Name: antaris-contracts
Version: 1.0.0
Summary: Versioned state schemas, failure semantics, and debug CLI for the Antaris Analytics Suite.
Author-email: Antaris Analytics <dev@antarisanalytics.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Antaris-Analytics/antaris-contracts
Project-URL: Documentation, https://antarisanalytics.ai
Project-URL: Repository, https://github.com/Antaris-Analytics/antaris-contracts
Keywords: ai,agents,llm,schemas,contracts,telemetry,debugging
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# antaris-contracts

[![PyPI version](https://badge.fury.io/py/antaris-contracts.svg)](https://badge.fury.io/py/antaris-contracts)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

**Versioned state schemas, failure semantics, and debug tooling for the antaris-suite.**

antaris-contracts defines the shared data contracts used across all antaris packages — ensuring consistent serialization, migration, and observability without coupling the packages to each other.

## Installation

```bash
pip install antaris-contracts
```

## What's Included

- **State schemas** — Versioned dataclass contracts for memory, router, guard, context, and telemetry state
- **Migration tooling** — Chained schema migrations with version detection and rollback safety
- **Failure semantics** — Canonical error types and failure modes documented in `FAILURE_SEMANTICS.md`
- **Concurrency model** — Lock ordering and thread-safety contracts in `CONCURRENCY_MODEL.md`
- **`antaris-debug` CLI** — Inspect memory stores, tail telemetry logs, validate schema files

## CLI Usage

```bash
# Inspect a memory workspace
antaris-debug memory inspect ./my_agent_workspace

# Search memories
antaris-debug memory search ./my_agent_workspace "important decision"

# Tail a telemetry log
antaris-debug telemetry tail ./telemetry.jsonl

# Validate a schema file
antaris-debug schema validate ./state.json
```

## Schema Usage

```python
from antaris_contracts.schemas.memory import MemoryState
from antaris_contracts.schemas.router import RouterState
from antaris_contracts.migration import migrate

# Load and auto-migrate state
raw = json.loads(open("state.json").read())
state = migrate(raw, target_version="2.2.0")
```

## Zero Runtime Dependencies

antaris-contracts has no runtime dependencies beyond the Python standard library. It is safe to import in any environment.

## Part of antaris-suite

| Package | Role |
|---------|------|
| antaris-contracts | Schemas + contracts (this package) |
| antaris-memory | Persistent agent memory |
| antaris-router | Intelligent model routing |
| antaris-guard | Input/output safety layer |
| antaris-context | Context window management |
| antaris-pipeline | Orchestration + telemetrics |

## License

Apache 2.0 — see [LICENSE](LICENSE)
