aelitium 0.2.3

Tamper-evident evidence bundles for AI outputs

AELITIUM

Can you prove what your AI model actually said?

AELITIUM turns AI outputs into tamper-evident evidence bundles that can be verified anywhere, on any machine — offline, no server required.

---

30-second demo

pip install aelitium

aelitium pack --input examples/ai_output_min.json --out ./bundle
# STATUS=OK rc=0
# AI_HASH_SHA256=8b647717...

aelitium verify --out ./bundle
# STATUS=VALID rc=0

# Tamper with the bundle, then verify:
aelitium verify --out ./bundle
# STATUS=INVALID rc=2 reason=HASH_MISMATCH

Store the hash. Verify the bundle later — on any machine, any time, without contacting AELITIUM or any server.

# Find uninstrumented LLM calls in your codebase:
aelitium scan ./src
# LLM call sites detected: 4
# Missing evidence capture:
#   ⚠ openai — worker.py:42
#   ⚠ anthropic — agent.py:17

All commands accept --json for structured output.

---

Why this exists

AI outputs are usually stored in logs or databases.

Those records can be edited, overwritten, selectively deleted, or disputed later.

When AI outputs influence decisions — finance, healthcare, support automation, legal workflows — teams eventually face the question:

"Can you prove what the model actually said?"

AELITIUM provides a deterministic, cryptographic evidence bundle that allows anyone to verify the output independently.

---

How it works

AI output (JSON)
      ↓
aelitium pack      ← deterministic SHA-256 hash + manifest
      ↓
evidence bundle    ← canonical JSON + ai_manifest.json
      ↓
aelitium verify   ← STATUS=VALID / STATUS=INVALID

The bundle contains a canonicalized payload, a deterministic SHA-256 hash, and a manifest with schema, timestamp, and canonicalization method. Anyone with the bundle can verify its integrity — no network required.

---

Capture adapter (OpenAI / Anthropic)

No manual JSON. The capture adapter intercepts the API call, records request and response hashes at call time, and writes the bundle automatically.

from openai import OpenAI
from engine.capture.openai import capture_chat_completion

client = OpenAI()
result = capture_chat_completion(
    client, "gpt-4o",
    [{"role": "user", "content": "What is the capital of France?"}],
    out_dir="./evidence",
)
print(result.ai_hash_sha256)  # deterministic proof of this exact call

aelitium verify-bundle ./evidence
# STATUS=VALID rc=0
# AI_HASH_SHA256=...
# BINDING_HASH=...   ← cryptographic link between request and response

See Capture layer for Anthropic, streaming, and signing.

---

Detect when the model changed

Prove when the same AI request started producing different answers.

# Bundle from last week (model v1)
aelitium compare ./bundle_last_week ./bundle_today
# STATUS=CHANGED rc=2
# REQUEST_HASH=SAME
# RESPONSE_HASH=DIFFERENT
# INTERPRETATION=Same request produced a different response

This is tamper-evident logging for model behavior: if the request hash is identical but the response hash differs, the change came from the model — not your code.

Run the full example:

python examples/model_drift_detector.py

If the model silently changed behavior between runs:

STATUS=CHANGED rc=2
INTERPRETATION=Same request produced a different response

That means the change came from the model — not your code.

---

Reproducibility

AELITIUM is designed to be deterministic. The same AI output always produces the same hash, on any machine.

Run the full reproducibility check from a clean environment:

bash scripts/verify_repro.sh

This script creates a fresh virtual environment, installs the project, runs the test suite, packs the example twice, and confirms the resulting hashes match.

=== RESULT: PASS ===
AI_HASH_SHA256=8b647717...

All tests also pass on two independent machines (A + B) with identical hashes.

---

CLI reference

aelitium

Command	Description
validate --input <file>	Validate against ai_output_v1 schema
canonicalize --input <file>	Print deterministic hash
pack --input <file> --out <dir>	Generate canonical JSON + manifest
verify --out <dir>	Verify integrity of a pack output dir
verify-bundle <dir>	Verify bundle: hash + signature + binding hash
compare <bundle_a> <bundle_b>	Compare two bundles — detect model behavior change
verify-receipt --receipt <file> --pubkey <file>	Verify Ed25519 authority receipt offline
export --bundle <dir>	Export bundle in compliance format (EU AI Act Art.12)
scan <path>	Scan Python files for uninstrumented LLM call sites

Exit codes: 0 = success, 2 = failure. Designed for CI/CD pipelines.

---

Documentation

• Why AELITIUM — problem statement, positioning, and what this is for
• Architecture — canonicalization pipeline, evidence bundle, module map
• Security model — threats addressed, guarantees, limitations
• Trust boundary — what AELITIUM proves and what it does not
• 5-minute demo — full walkthrough with expected output
• Python integration — drop-in helper + FastAPI example
• Capture layer — OpenAI adapter, auto-packing, trust gap explanation
• Engine contract — bundle schema and guarantees
• Evidence Bundle Spec — open draft standard for verifiable AI output bundles; AELITIUM is the reference implementation

---

Design principles

• Deterministic — same input always produces the same hash, on any machine
• Offline-first — verification never requires network access
• Fail-closed — any verification error returns rc=2; no silent failures
• Auditable — every pack includes a manifest with schema, timestamp, and hash
• Pipeline-friendly — all output parseable (STATUS=, AI_HASH_SHA256=, --json)

---

Trust boundary

AELITIUM provides tamper-evidence, not truth guarantees.

What AELITIUM proves:

• the bundle contents have not changed since packing
• the canonicalized payload matches the recorded hash
• (with capture adapter) the request hash matches the exact API payload sent

What AELITIUM does not prove:

• that the model output was correct or safe
• that the system that packed the bundle was trustworthy
• that the model actually produced the output (without capture adapter)

Integrity ≠ completeness. AELITIUM proves that captured events were not altered. It does not guarantee that all events were captured. Capture completeness depends on the integration layer — SDK wrapper, proxy, or observer. If the agent controls its own logging, an observer-based capture pattern provides stronger guarantees. See TRUST_BOUNDARY.md for the full analysis.

Stronger provenance — signing authorities, hardware-backed keys — is the direction of P3.

---

Compliance alignment

AELITIUM provides tamper-evident evidence bundles that support the following regulatory and audit requirements:

Framework	Requirement	How AELITIUM helps
EU AI Act — Article 12	Logging and traceability of high-risk AI system outputs	Evidence bundles provide immutable, verifiable records of AI outputs with deterministic hashes
SOC 2 — CC7	System monitoring and integrity controls	Independent offline verification confirms records have not been altered after creation
ISO 42001	AI management system auditability	Canonical bundles with schema versioning support third-party audits without infrastructure access
NIST AI RMF — MG 2.2	Traceability of AI decisions and outputs	Each bundle contains a complete, reproducible record: payload, hash, timestamp, and optional signature

AELITIUM does not replace logging infrastructure. It adds cryptographic integrity on top of any existing pipeline — offline, without a server, without a blockchain.

---

License

Apache-2.0. See LICENSE.