AxiomTrace

Cryptographically verifiable execution records for AI agents.

When an AI agent says "I called web_search and got these results" — can you prove it?

AxiomTrace wraps any agent (LangGraph, CrewAI, OpenAI SDK, or any Python function) and produces a tamper-evident hash chain of its execution. Every LLM call, tool invocation, and state transition is signed with Ed25519 and chained so that tampering with any record breaks all records that follow it.

axiomtrace verify --run-id <id> --db axiomtrace.db ✓ 12 records verified ✓ chain intact ✓ signatures valid

Why this exists

Existing observability tools (OpenTelemetry, LangSmith, audit log tables) record what agents do — but they don't prove it. A database administrator can run UPDATE audit_log SET output = 'clean'. A compromised process can write false tool results to its own trace. Logs are text. Text can be changed.

AxiomTrace solves a different problem: non-repudiation. Each record is signed by a private key held only by the middleware. Each record hashes the previous one. To forge or alter any record you need the private key — and even with it, the altered chain will not match any previously published checkpoint.

This matters in:

• Regulated industries (finance, healthcare, legal) where AI decisions must be auditable by external parties
• Multi-agent systems where one agent's output becomes another agent's input and you need to trace the full dependency chain
• Compliance workflows where a human approver needs proof of what the agent actually did before the approval was granted

How it works

Every agent action becomes a ProvenanceRecord: record_id ← unique ID for this event run_id ← which agent run this belongs to sequence_num ← 0, 1, 2, 3... strictly monotonic event_type ← LLM_CALL | TOOL_CALL | RUN_START | RUN_END | ERROR timestamp_utc ← captured by middleware, not the agent agent_id ← which agent produced this event payload ← tool inputs/outputs, model name, token counts, etc. payload_hash ← SHA-256 of all meaningful fields prev_record_hash ← chain_hash of the previous record chain_hash ← SHA-256(prev_record_hash + payload_hash) signature ← Ed25519 signature of chain_hash

Changing any field changes payload_hash. That changes chain_hash. That breaks every subsequent record's prev_record_hash. The verifier detects the exact record where the chain broke.

Quickstart

Install:

pip install axiomtrace

Wrap your agent:

from axiomtrace.interceptors import TraceSession, traced_tool
from axiomtrace.storage import Ledger

ledger = Ledger.create("sqlite:///axiomtrace.db")

@traced_tool
def web_search(query: str) -> str:
    # your real implementation
    return "results"

@traced_tool
def write_report(content: str) -> str:
    return "report.pdf"

with TraceSession(agent_id="my-agent", ledger=ledger) as session:
    results = web_search("supply chain risk 2026")
    write_report(results)

print(session.verify().summary())
# ✓ 4 records verified  ✓ chain intact  ✓ signatures valid

Verify from the CLI:

axiomtrace verify --run-id <run-id> --db axiomtrace.db
axiomtrace inspect --run-id <run-id> --db axiomtrace.db
axiomtrace runs --db axiomtrace.db
axiomtrace export --run-id <run-id> --db axiomtrace.db --output chain.json

Start the REST API:

uvicorn axiomtrace.api.main:app --reload
# Open http://localhost:8000/docs

Tamper detection

# Build a chain
with TraceSession(agent_id="agent", ledger=ledger) as session:
    web_search("query")

records = session.records()

# Simulate an attacker changing a tool result
tampered = list(records)
tampered[2] = tampered[2].model_copy(
    update={"payload": {**tampered[2].payload, "output": "INJECTED"}}
)

# Verifier catches it immediately
from axiomtrace.core import ChainVerifier
result = ChainVerifier(session._signer.public_key).verify(tampered)

print(result.summary())
# ✕ chain broken at record 2  2/4 records valid

Architecture

Your agent code ↓ @traced_tool / TraceSession ← Phase 2: interceptors ↓ ChainBuilder ← Phase 1: hash chain engine ↓ signs with Ed25519 AsyncWriter (100ms flush) ← Phase 3: async storage ↓ PostgreSQL / SQLite ledger ← append-only, trigger-protected ↓ axiomtrace verify (CLI) ← Phase 4: verification axiomtrace.api (REST) ← Phase 5: REST API

Project structure

src/axiomtrace/ ├── core/ # Hash chain, Ed25519 signing, verification ├── interceptors/ # TraceSession, @traced_tool, LLM patching ├── storage/ # SQLAlchemy ledger, async writer ├── cli/ # Typer CLI commands └── api/ # FastAPI REST service

Running locally

git clone https://github.com/yourusername/axiomtrace
cd axiomtrace
pip install -e .
pytest tests/

Running with Docker

docker-compose up
# API at http://localhost:8000
# pgAdmin at http://localhost:5050

Test suite

Phase 1 — Chain core 31 tests Phase 2 — Interceptors 27 tests Phase 3 — Storage 16 tests Phase 4 — CLI 23 tests Phase 5 — REST API 26 tests ───────────────────────────────── Total 123 tests

What it does NOT do

AxiomTrace is not a general monitoring or observability tool. It does not:

• Replace OpenTelemetry or LangSmith for performance monitoring
• Prevent a malicious agent from lying before the middleware intercepts it
• Provide real-time alerting
• Store raw LLM prompts and responses (only hashes, by design)

See docs/threat-model.md for a full discussion of the security model and its limits.

Tech stack

| Layer | Technology | Why | |---|---|---| | Chain core | Python, hashlib, cryptography | Ed25519 asymmetric signing | | Data models | Pydantic v2 | Immutable, validated records | | Storage | SQLAlchemy + SQLite/PostgreSQL | Trigger-enforced append-only | | API | FastAPI + Uvicorn | Auto OpenAPI docs, async | | CLI | Typer + Rich | Clean terminal output | | Tests | pytest | 123 tests, all passing |

License

MIT — see LICENSE