# AELITIUM

> Can you prove what your AI model actually said?

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
![tests](https://img.shields.io/badge/tests-146%20passing-brightgreen)
![python](https://img.shields.io/badge/python-3.10%2B-blue)

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

---

## 30-second demo

```bash
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
```

```bash
# 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.

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.

```python
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
```

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

See [Capture layer](docs/INTEGRATION_CAPTURE.md) for Anthropic, streaming, and signing.

---

## Detect when the model changed

Prove when the same AI request started producing different answers.

```bash
# 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 AI provider accountability: if the request did not change but the response did, 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
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) |

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

---

## Documentation

- [Why AELITIUM](docs/WHY_AELITIUM.md) — problem statement, positioning, and what this is for
- [Architecture](docs/ARCHITECTURE.md) — canonicalization pipeline, evidence bundle, module map
- [Security model](docs/SECURITY_MODEL.md) — threats addressed, guarantees, limitations
- [Trust boundary](docs/TRUST_BOUNDARY.md) — what AELITIUM proves and what it does not
- [5-minute demo](docs/AI_INTEGRITY_DEMO.md) — full walkthrough with expected output
- [Python integration](docs/INTEGRATION_PYTHON.md) — drop-in helper + FastAPI example
- [Capture layer](docs/INTEGRATION_CAPTURE.md) — OpenAI adapter, auto-packing, trust gap explanation
- [Engine contract](docs/ENGINE_CONTRACT.md) — bundle schema and guarantees
- [Evidence Bundle Spec](docs/EVIDENCE_BUNDLE_SPEC.md) — 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

**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

Stronger provenance — signing authorities, hardware-backed keys — is the direction of [P3](docs/RELEASE_AUTHORITY_SERVICE.md). See [TRUST_BOUNDARY.md](docs/TRUST_BOUNDARY.md) for the full analysis.

---

## 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](LICENSE).
