Metadata-Version: 2.4
Name: antaris-contracts
Version: 4.9.15
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)

**Shared contracts layer for the Antaris Analytics Suite.**

**v4.0.0** — Unified state schemas • Migration tooling • Fail-closed semantics • Debug CLI

Version aligned with antaris-suite v4.0.0. Apache 2.0 license.

antaris-contracts defines the versioned state schemas, failure semantics, migration tooling, and debug CLI shared across every antaris package. It is the single source of truth for how data is shaped, how failures are handled, and how state evolves across versions — without coupling the packages to each other.

Zero runtime dependencies. Pure Python stdlib. 60+ tests. Safe to import anywhere.

## Installation

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

Requires Python 3.9+.

## Versioned State Schemas

Every antaris package persists state through dataclass contracts defined here. All schemas carry a `schema_version` field, support `to_dict()` / `from_dict()` / `to_json()` / `from_json()` round-trips, and silently ignore unknown keys for forward compatibility.

### MemoryState (`antaris_contracts.schemas.memory`)

```python
from antaris_contracts import MemoryEntry, MemoryShard, MemoryIndex, SearchResult

# Create a memory entry
entry = MemoryEntry(
    content="User prefers concise responses",
    source="conversation.py",
    line=42,
    category="preference",
    importance=0.9,
    confidence=0.85,
    memory_type="semantic",
    tags=["user-pref", "style"],
)

# Serialize → dict → JSON → back
restored = MemoryEntry.from_json(entry.to_json())
assert restored.content == entry.content

# Shards track on-disk partitions with integrity checks
shard = MemoryShard(
    shard_id="shard_2026-02_preference",
    category="preference",
    entries=[entry],
    entry_count=1,  # mismatch with len(entries) = partial write
)

# Index is a derived cache — rebuildable from shards
index = MemoryIndex(
    total_entries=150,
    shard_count=6,
    categories=["general", "preference", "strategic"],
    shard_manifest={"shard_2026-02_preference.json": "abc123"},
)
```

### RouterState (`antaris_contracts.schemas.router`)

```python
from antaris_contracts import ClassificationResult, RouteDecision, RouterState

# Task classification output
classification = ClassificationResult(
    tier="complex",
    confidence=0.92,
    reasoning=["multi-step reasoning", "code generation detected"],
    signals=["code_block", "chain_of_thought"],
)

# Routing decision with SLA tracking and fallback chain
decision = RouteDecision(
    model="claude-sonnet-4-5-20250929",
    provider="anthropic",
    tier="complex",
    confidence=0.92,
    confidence_basis="classifier",
    reasoning=["high complexity tier", "SLA-compliant model selected"],
    fallback_chain=["claude-haiku-4-5-20251001", "gpt-4o-mini"],
    classification=classification,
    sla_compliant=True,
    supports_streaming=True,
)

# Persisted router state with cost tracking
state = RouterState(
    session_id="sess-abc123",
    total_requests=250,
    total_cost_usd=1.47,
    requests_by_tier={"simple": 180, "complex": 70},
    cost_by_model={"claude-sonnet-4-5-20250929": 1.20, "claude-haiku-4-5-20251001": 0.27},
    recent_decisions=[decision],
)
```

### GuardState (`antaris_contracts.schemas.guard`)

```python
from antaris_contracts import (
    PatternMatch, GuardDecision, GuardPolicyRule, GuardPolicy, AuditRecord,
)

# Pattern match from injection detection
match = PatternMatch(
    pattern_id="prompt-injection-01",
    pattern_type="injection",
    matched_text="ignore all previous instructions",
    score=0.95,
    severity="high",
)

# Guard decision — fail-closed on crash (CRITICAL, is_safe=False)
decision = GuardDecision(
    threat_level="BLOCKED",
    is_safe=False,
    is_blocked=True,
    matches=[match],
    score=0.95,
    message="Prompt injection detected",
    pii_found=False,
    audit_id="audit-xyz",
)

# Composable security policy
policy = GuardPolicy(
    policy_id="strict-prod",
    name="strict",
    rules=[
        GuardPolicyRule(rule_id="r1", rule_type="injection_scan", enabled=True),
        GuardPolicyRule(rule_id="r2", rule_type="pii_filter", enabled=True),
        GuardPolicyRule(rule_id="r3", rule_type="rate_limit",
                        parameters={"rpm": 60}),
    ],
    threat_threshold=0.5,
    block_threshold=0.8,
    enable_pii_filter=True,
)

# Append-only audit log entry
record = AuditRecord(
    audit_id="audit-xyz",
    timestamp="2026-02-20T14:30:00Z",
    source_id="user-123",
    action="block",
    risk_level="high",
    decision=decision,
)
```

### ContextState (`antaris_contracts.schemas.context`)

```python
from antaris_contracts import ContextItem, ContextSection, ContextPacket

# Build a context window with budgeted sections
memories_section = ContextSection(
    name="memories",
    budget=1024,
    used=256,
    compression_level="light",
    items=[
        ContextItem(content="User prefers Python", tokens=4, priority=0.9),
        ContextItem(content="Last error was ImportError", tokens=6, priority=0.7),
    ],
)

packet = ContextPacket(
    task="Debug the authentication module",
    memories=[{"content": "auth uses JWT", "importance": 0.8}],
    pitfalls=["Don't expose tokens in logs"],
    sections=[memories_section],
    total_budget=4096,
    total_used=256,
    strategy="hybrid",
)

# If total_budget is exceeded, lowest-priority sections are dropped — never
# silently truncated mid-entry
```

### PipelineState (`antaris_contracts.schemas.telemetry`)

```python
from antaris_contracts import (
    TelemetryEvent, PerformanceMetrics,
    MODULE_PIPELINE, MODULE_GUARD, MODULE_ROUTER,
    BASIS_CLASSIFIER, BASIS_GUARD,
)

# Unified telemetry event emitted by every antaris module
event = TelemetryEvent(
    event_id="ev-001",
    timestamp="2026-02-20T14:30:00Z",
    session_id="sess-abc123",
    module=MODULE_ROUTER,
    event_type="route_selected",
    confidence=0.92,
    basis=BASIS_CLASSIFIER,
    evidence=["multi_step_reasoning", "code_block_detected"],
    payload={"model": "claude-sonnet-4-5-20250929", "tier": "complex"},
    performance=PerformanceMetrics(latency_ms=45.2, cost_usd=0.000125),
    correlations=["ev-000"],     # related events
    triggers=["ev-002"],         # events this one caused
    user_id="u-123",
    trace_id="trace-abc",
)

# Append to JSONL log
with open("telemetry.jsonl", "a") as f:
    f.write(event.to_jsonl_line())
```

## Migration Tooling

State schemas evolve across versions. The migration system provides chained migrations, automatic version detection, and explicit failure on unknown versions — no silent data corruption.

### Version Chain

```
2.0.0 → 2.1.0 → 2.1.1 → 2.2.0 (current)
```

Each step adds fields with safe defaults. Migrations are pure functions (dict-in, dict-out) with no I/O.

### Migrate Persisted Data

```python
from antaris_contracts import migrate, SchemaVersion
from antaris_contracts.migration import MigrationError, get_migration_path
import json

# Auto-detect source version from data
raw = json.loads(open("state.json").read())
migrated = migrate(raw)  # → schema_version="2.2.0"

# Explicit source and target
migrated = migrate(raw, from_version="2.0.0", to_version="2.2.0")

# Same-version is a safe no-op (returns deep copy)
migrated = migrate(raw, to_version="2.2.0")

# Dry-run: inspect the migration path without applying
steps = get_migration_path("2.0.0", "2.2.0")
# → [("2.0.0", "2.2.0")]  (direct path registered)

steps = get_migration_path("2.1.0", "2.2.0")
# → [("2.1.0", "2.2.0")]  (direct shortcut)

steps = get_migration_path("2.1.1", "2.2.0")
# → [("2.1.1", "2.2.0")]
```

### What Each Migration Adds

| Step | Fields Added |
|---|---|
| 2.0.0 → 2.1.0 | `memory_type`, `type_metadata`, `correlations`, `triggers` |
| 2.1.0 → 2.1.1 | `trace_id`, removes `_heartbeat_contaminated` artifact |
| 2.1.1 → 2.2.0 | `escalated`, `original_confidence`, `escalation_reason`, `sla_compliant`, `sla_breaches`, `sla_adjustments`, `ab_variant`, `explanation`, `supports_streaming`, `pattern_version`, `audit_id`, `user_id`, `conversation_id`, `agent_id`, `strategy` |

### Error Handling

```python
from antaris_contracts.migration import MigrationError

# Unknown version → MigrationError
migrate({"schema_version": "9.9.9"})
# MigrationError: Unknown source schema version: '9.9.9'

# Downgrade → MigrationError
migrate({"schema_version": "2.2.0"}, to_version="2.0.0")
# MigrationError: Downgrade not supported: 2.2.0 → 2.0.0

# Missing version with no from_version → MigrationError
migrate({"content": "no version field"})
# MigrationError: Cannot determine source schema version
```

### Version Enum

```python
from antaris_contracts import SchemaVersion

# All known versions in order
SchemaVersion.ordered()
# → [V2_0_0, V2_1_0, V2_1_1, V2_2_0]

# Comparison
SchemaVersion.V2_0_0 < SchemaVersion.V2_2_0   # True
SchemaVersion.V2_2_0 <= SchemaVersion.V2_2_0   # True
```

## Failure Semantics

Every schema documents its failure behavior as inspectable, predictable objects — not hidden exceptions. The contracts define how each component degrades:

| Component | Failure Mode | Behavior |
|---|---|---|
| **MemoryEntry** | Deserialization failure | Skip and log — never silently mutate |
| **MemoryEntry** | Empty `content` | Rejected at ingest time |
| **MemoryEntry** | Missing `hash` | Recomputed from `(source, line, content[:100])` |
| **MemoryShard** | Partial write | Detected via `entry_count` mismatch; discard and reload from WAL |
| **MemoryIndex** | Corruption | Delete and rebuild from shards (index is a cache) |
| **RouterState** | File corruption | Reset to empty state, log warning |
| **ClassificationResult** | All classifiers fail | Return `tier="simple"`, `confidence=0.0` |
| **RouteDecision** | Primary model down | Iterate `fallback_chain`; never silently drop |
| **GuardDecision** | Classifier crash | **Fail-closed**: `threat_level="CRITICAL"`, `is_safe=False` |
| **GuardPolicy** | Parse failure | Keep previous policy active, emit warning |
| **AuditRecord** | Write failure | Best-effort; log error, don't affect guard decision |
| **ContextPacket** | Budget exceeded | Drop lowest-priority sections — never truncate mid-entry |
| **ContextSection** | Compression failure | Use uncompressed content as fallback |
| **TelemetryEvent** | Sink failure | Non-fatal; write warning to stderr, pipeline continues |

## Concurrency Model

| Component | Contract |
|---|---|
| **MemoryShard** | File lock held during write; reads are lock-free (MVCC-style) |
| **MemoryIndex** | Atomic writes via temp-file + rename pattern |
| **RouterState** | Last-writer-wins for cost tracking (acceptable approximation) |
| **GuardPolicy** | Atomic reload: new policy replaces old only after successful parse |
| **AuditRecord** | Append-mode writes; partial JSON lines are skipped on read |
| **TelemetryEvent** | Append-only JSONL; partial line writes produce invalid lines skipped on read |

## Debug CLI

`antaris-debug` is installed as a console script. Zero dependencies beyond stdlib.

### Inspect a Memory Store

```bash
$ antaris-debug memory inspect ./my_agent_workspace

============================================================
  Memory Store: ./my_agent_workspace
============================================================

  Index file:   PRESENT
  Index entries:     150
  Index shards:       6
  Tag index:         12 tags
  Schema ver:   2.2.0
  Last modified: 2026-02-20 14:30:00 UTC

  Shards on disk: 6
    shard_2026-01_general.json                    45 entries  [OK]
    shard_2026-01_strategic.json                  12 entries  [OK]
    shard_2026-02_general.json                    68 entries  [OK]
    shard_2026-02_preference.json                 25 entries  [OK]

  Total entries (actual scan): 150
  Index health: OK
============================================================
```

### Search Memories

```bash
$ antaris-debug memory search ./my_agent_workspace "authentication bug"

  Memory search: 'authentication bug'
  Store: ./my_agent_workspace
  Found 3 matching entries — showing top 3

  [1] score=1.800  hits=2
      JWT token validation was failing because the secret was rotated but the cache...
      source=debug_session.py  type=episodic  importance=0.90  confidence=1.00

  [2] score=0.850  hits=1
      User reported authentication timeout after 30s idle
      source=ticket_1234.md  type=episodic  importance=0.85  confidence=0.90
```

### Validate a Schema File

```bash
$ antaris-debug schema validate ./state.json

  Schema validation: ./state.json

  (root) OK [MemoryEntry]  schema_version=2.2.0  extra_fields=8

  Result: 1 object(s)  0 error(s)  0 warning(s)
  VALIDATION PASSED
```

Validates against all known contract signatures — `MemoryEntry`, `MemoryShard`, `MemoryIndex`, `RouterState`, `RouteDecision`, `GuardDecision`, `GuardPolicy`, `ContextPacket`, `TelemetryEvent`, and more. Detects schema version mismatches and missing required fields.

### Tail Telemetry Logs

```bash
$ antaris-debug telemetry tail ./telemetry.jsonl -n 5

  Telemetry tail: ./telemetry.jsonl
  Total events: 1240  —  showing last 5

  2026-02-20 14:30:00 UTC  [  router] route_selected  conf=0.920  basis=classifier
      evidence: ['multi_step_reasoning', 'code_block_detected']
      perf: lat=45.2ms, cost=$0.000125
  2026-02-20 14:30:01 UTC  [   guard] guard_decision  conf=1.000  basis=guard
  2026-02-20 14:30:01 UTC  [ context] context_built  conf=1.000  basis=context_budget
      perf: lat=12.3ms
  2026-02-20 14:30:02 UTC  [pipeline] request_complete
      perf: lat=892.0ms, cost=$0.003200
  2026-02-20 14:30:05 UTC  [  memory] memory_stored  conf=0.850
```

### Telemetry Summary and Dashboard

```bash
# Aggregate stats by module and event type
$ antaris-debug telemetry summary ./telemetry.jsonl

# Rich dashboard with latency percentiles and guard allow/deny ratio
$ antaris-debug telemetry dashboard ./telemetry.jsonl
```

### Trace a Pipeline Session

```bash
$ antaris-debug pipeline trace sess-abc123 ./telemetry.jsonl

  Pipeline trace: session_id='sess-abc123'
  Source: ./telemetry.jsonl
  Found 8 events out of 1240 total

  [  1] 2026-02-20 14:30:00 UTC  [pipeline] request_start
  [  2] 2026-02-20 14:30:00 UTC  [  router] route_selected  [lat=45.2ms]
  [  3] 2026-02-20 14:30:01 UTC  [   guard] guard_decision  [lat=8.1ms]
  [  4] 2026-02-20 14:30:01 UTC  [ context] context_built   [lat=12.3ms]
  [  5] 2026-02-20 14:30:02 UTC  [pipeline] request_complete [lat=892.0ms]
```

## Testing

52 tests covering all schemas, serialization round-trips, migration chains, version ordering, and error paths:

```bash
cd antaris-contracts && python -m pytest tests/ -v
```

## Zero Runtime Dependencies

antaris-contracts has no runtime dependencies beyond the Python standard library. It is safe to import in any environment — no version conflicts, no transitive dependencies, no surprises.

## Part of the Antaris Analytics Suite — v3.1.0

- **[antaris-memory](https://pypi.org/project/antaris-memory/)** — Persistent memory for AI agents
- **[antaris-router](https://pypi.org/project/antaris-router/)** — Adaptive model routing with SLA enforcement
- **[antaris-guard](https://pypi.org/project/antaris-guard/)** — Security and prompt injection detection
- **[antaris-context](https://pypi.org/project/antaris-context/)** — Context window optimization
- **[antaris-pipeline](https://pypi.org/project/antaris-pipeline/)** — Agent orchestration pipeline
- **antaris-contracts** — Versioned schemas, failure semantics, and debug CLI (this package)

## Phase 4 Roadmap

**v2.0:** Enhanced state versioning (backward compatibility guarantees)  
**v3.0+:** Multi-tenant schema isolation (support for shared memory pools across teams)

## Full Documentation

📖 **[Read the full antaris-contracts documentation on antarisanalytics.ai](https://antarisanalytics.ai/packages/antaris-contracts)**

## Phase 4 Roadmap

**v2.0:** Enhanced state versioning and backward compatibility guarantees — multi-version support in migrations  
**v3.0+:** Multi-tenant schema isolation and shared memory pool support across team agents  
**v4.0+:** Pluggable schema validators and custom failure semantics per tenant

## License

Apache 2.0 — see [LICENSE](LICENSE)
