recognitium-zero 1.1.0
Recognitium 0.0 — Compliance-grade AI audit trail with conversation tracking. We never see your data.
Requires Python: >=3.9
Keywords: ai audit trail gdpr compliance governance receipts recognitium

# recognitium-zero

**Recognitium 0.0 — Proves your AI did what you say it did.**

Compliance-grade AI audit trail. One line of code. We never see your data.

## Install

```bash
pip install recognitium-zero
```

## Quick Start

```python
from recognitium_zero import R0

r = R0(api_key="r0_...")

# Option 1: Wrap any AI function call
response = r.wrap(openai.chat.completions.create)(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

# Option 2: Wrap an OpenAI client (all calls receipted automatically)
from openai import OpenAI
client = r.openai(OpenAI())
response = client.chat.completions.create(model="gpt-4", messages=...)

# Option 3: Wrap an Anthropic client
from anthropic import Anthropic
client = r.anthropic(Anthropic())
response = client.messages.create(model="claude-3-opus-20240229", ...)

# Check your receipt
print(r.last_receipt)
# → Receipt(receipt_id='r0r_...', chain_position=42, physics_quality='FULL', ...)
```

## How It Works

1. **SDK hashes your request locally** (HMAC-SHA-256, salted with your API key) — your data never leaves your machine. Rainbow table attacks are impossible.
2. **SDK sends only the salted hash** to the Recognitium 0.0 API — we never see your data
3. **Recognitium 0.0 API generates a receipt** — Ed25519-signed, hash-chained, tamper-evident
4. **SDK returns the original AI response** — unchanged, plus the receipt

## What You Get

- **Immutable audit trail** — hash-chained receipts, tamper-evident
- **Computation commitment** — sequential hash chain (deterministic, verifiable)
- **GDPR compliance** — we never see your data (only hashes)
- **Compliance exports** — JSON/PDF for auditors, regulators, lawyers
- **1-line integration** — wrap existing code, zero changes to your AI

## Conversation Tracking

Every turn in a multi-turn conversation is automatically tracked with a `conversation_id` and `turn_number`.

```python
from recognitium_zero import R0
from anthropic import Anthropic

r = R0(
    api_key="r0_...",
    labels={"department": "lending", "employee_id": "ML-2847"}
)
client = r.anthropic(Anthropic())

messages = []
with r.conversation() as conv_id:
    # Turn 1
    messages.append({"role": "user", "content": "Should we approve this mortgage?"})
    r = client.messages.create(model="claude-3-haiku-20240307", max_tokens=200, messages=messages)
    messages.append({"role": "assistant", "content": r.content[0].text})

    # Turn 2 — same conversation_id, turn_number=2
    messages.append({"role": "user", "content": "What if there's also a car loan?"})
    r = client.messages.create(model="claude-3-haiku-20240307", max_tokens=200, messages=messages)

# A judge can query: "Show me all receipts from conversation conv_id"
# Result: 2 turns, department=lending, employee=marie.laurent, timestamped, signed.
```

Auto-detection also works without the context manager — the SDK groups receipts by the hash of the first message.

## Compliance Export

```python
# Export your complete chain for auditors
export = r.export()
# → JSON with all receipts, chain integrity proof,
#   and a compliance statement certifying zero data exposure.
```

## Verify Chain Integrity

```python
# Prove your chain hasn't been tampered with
verification = r.verify_chain()
print(verification)
# → {"chain_valid": true, "chain_length": 4291, ...}
```

## Salted Hashing (Rainbow Table Defense)

```python
# Hash any value with your per-customer salt (derived from API key)
hash_val = r.hash({"messages": [...], "model": "gpt-4"})
# → "8f3a2b9c..." (HMAC-SHA-256, salted — different per customer)
```

## Negative Proof (Prove Absence)

```python
# Prove that a specific action did NOT occur through R0
action_hash = r.hash({"messages": [...], "model": "gpt-4"})
proof = r.prove_absence(action_hash)
assert proof["absence_proven"]  # True: no matching receipt in verified chain
```

## Receipt Verification

```python
# Verify a receipt's integrity (full: recomputes hash from all fields)
result = r.verify_receipt(r.last_receipt, mode="full")
assert result["signature_valid"] and result["hash_verified"]

# Or verify locally without any API call
assert r.last_receipt.verify_hash()
```

## Security Hardening (v1.0.0)

### Rogue Server Defense (Mirror Check)

The SDK verifies that every field in the returned receipt matches what it sent. If the server changes any field — action_hash, response_hash, action_class, provider, model, or metadata — the SDK raises `ReceiptIntegrityError` immediately.

```python
from recognitium_zero import R0, ReceiptIntegrityError

r = R0(api_key="r0_...")

try:
    response = r.wrap(my_ai_call)(prompt="Hello")
except ReceiptIntegrityError as e:
    # CRITICAL: Server returned a receipt with modified fields.
    # This means the server may be compromised. Alert security team.
    alert_security_team(e)
```

### Fail-Closed Mode (Internet Outage Defense)

Control what happens when the API is unreachable:

```python
# Compliance-grade: fail if receipt can't be created (DEFAULT)
r = R0(api_key="r0_...", on_error="raise")

# Business continuity: log warning, return None for receipt
r = R0(api_key="r0_...", on_error="warn")

# Silent: swallow errors (not recommended for compliance)
r = R0(api_key="r0_...", on_error="ignore")
```

### Client-Side Chain Anchoring (Quantum Defense)

Write receipt hashes to a local append-only file. Even if Ed25519 is broken by a quantum computer and the server is fully compromised, your local anchor proves the chain existed.

```python
r = R0(api_key="r0_...", anchor_path="~/.r0/chain_anchor.jsonl")

# Later: verify your local anchor matches the server
result = r.verify_local_chain()
assert result["valid"]  # True if all local anchors match server
```

## Pricing

- **Unlimited**: €5,000/month (enterprise compliance)

## Why Recognitium 0.0?

| | Helicone | LangSmith | Braintrust | **Recognitium 0.0** |
|---|---|---|---|---|
| **Sees your data?** | Yes | Yes | Yes | **No** |
| **GDPR safe?** | DPA needed | DPA needed | DPA needed | **By architecture** |
| **Tamper-proof?** | No | No | No | **Yes (hash chain)** |
| **Computation commitment?** | No | No | No | **Yes (hash chain)** |

---

Built on Recognitium cryptographic governance technology.