Metadata-Version: 2.4
Name: koopman-audit
Version: 0.1.0
Summary: Mathematically verifiable audit layer for LLM inference via Koopman operator theory
Author-email: Aevion LLC <contact@aevion.ai>
License: MIT
Project-URL: Homepage, https://github.com/aevion/koopman-audit
Project-URL: Documentation, https://github.com/aevion/koopman-audit#readme
Project-URL: Repository, https://github.com/aevion/koopman-audit
Project-URL: Issues, https://github.com/aevion/koopman-audit/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"

# Koopman Audit

**Mathematically verifiable audit layer for LLM inference.**

The first Koopman operator-based compliance verification system for AI. Provides real-time behavioral certification via Extended Dynamic Mode Decomposition (EDMD) with cryptographically hash-chained audit trails.

[![PyPI version](https://badge.fury.io/py/koopman-audit.svg)](https://badge.fury.io/py/koopman-audit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## The Core Idea

Large language models are dynamical systems. Their hidden states evolve through time as tokens are generated. We apply Koopman operator theory — a 1931 mathematical framework — to extract verifiable invariants from these trajectories without modifying the model or requiring ground-truth labels.

**The compliance gate:**
```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Prompt    │────▶│  LLM        │────▶│ Hidden      │
│             │     │  Inference  │     │ States      │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                                │
                                                ▼
                                       ┌─────────────┐
                                       │ EDMD        │
                                       │ Koopman     │
                                       │ Operator K  │
                                       └──────┬──────┘
                                                │
                                                ▼
                                       ┌─────────────┐
                                       │ Rank Check  │
                                       │ rank(K) ≥ 5 │
                                       └──────┬──────┘
                                                │
                                       ┌────────┴────────┐
                                       ▼                 ▼
                                  ┌─────────┐      ┌─────────┐
                                  │  PASS   │      │  BLOCK  │
                                  │ + Cert  │      │ + Audit │
                                  └─────────┘      └─────────┘
```

---

## Validated Calibration Data

**SmolLM2-360M (N=9 trials, 100% full-rank recovery):**

| Category | λ̂ Mean | λ̂ Std | Full Rank | Tail Gap Δ |
|----------|--------|-------|-----------|------------|
| Benign | 0.8425 | 0.0375 | 100% (9/9) | 0.0020 |
| Hallucination | 0.8268 | 0.0143 | 100% (9/9) | 0.0018 |
| Jailbreak | 0.8752 | 0.0284 | 100% (9/9) | 0.0022 |

**Key Finding:** Jailbreak prompts exhibit measurably higher Koopman eigenvalue (greater instability) than benign prompts. The tail gap Δ ≈ 0.002 indicates marginal category separation at 0.4B scale — larger models expected to show exaggerated separation.

---

## Installation

```bash
pip install koopman-audit
```

---

## Quick Start

### Basic Usage

```python
from koopman_audit import EDMDConfig, compute_gate
import numpy as np

# Generate or extract entropy trace from model
# (e.g., from hidden state activations during inference)
entropy_trace = np.random.randn(50)  # Your data here

# Configure EDMD
config = EDMDConfig(
    d=5,              # embedding dimension
    tau=1,            # delay lag
    min_tokens=25,    # minimum sequence length
    lambda_prior=0.88 # regularization parameter
)

# Compute compliance gate
result = compute_gate(entropy_trace, config)

print(f"Rank: {result.rank_achieved}/5")
print(f"Lambda: {result.lambda_hat:.4f}")
print(f"Tail gap: {result.tail_gap:.6f}")
print(f"Pass: {result.pass_gate}")
print(f"Audit hash: {result.audit_hash}")
```

### Multi-Layer Aggregation

```python
from koopman_audit import aggregate_layers

# Signals from multiple transformer layers
layer_signals = {
    2: layer_2_activations,   # 25% depth
    5: layer_5_activations,   # 50% depth
    8: layer_8_activations,   # 75% depth
    11: layer_11_activations, # 100% depth
}

agg = aggregate_layers(layer_signals, config)
print(f"Aggregated score: {agg['aggregated_rank_score']:.4f}")
print(f"All pass: {agg['all_pass']}")
```

### Proof Ledger

```python
from koopman_audit import ProofLedger

# Initialize append-only audit log
ledger = ProofLedger("./proof_ledger.jsonl")

# Log inference event
entry_id = ledger.append(
    session_id="uuid-v4",
    gate_result={
        "pass": result.pass_gate,
        "rank": result.rank_achieved,
        "lambda": result.lambda_hat,
    },
    model_id="gemma-4-26b",
    prompt_hash="sha256:abc...",
    category="benign"
)

# Verify chain integrity
is_valid, errors = ledger.verify_chain()
print(f"Chain integrity: {is_valid}")

# Export NIST AI RMF report
report = ledger.export_nist_rmf_report()
```

---

## Mathematical Foundation

### Delay Embedding

Given signal $x(t)$, construct Hankel matrix:

$$H_{ij} = x(j + (i-1)\tau)$$

### Koopman Operator

Tikhonov-regularized regression:

$$K_\lambda = X' X^T (X X^T + \lambda I)^{-1}$$

### Compliance Gate

$$\mathcal{G}(K) = (\mathbb{1}[\text{rank}(K) \geq r^*], \sigma_{\min}(K))$$

Where $r^* = 5$ (full rank) and $\sigma_{\min}$ is the smallest singular value.

---

## Intellectual Property

- **P-001 Provisional Patent**: "Dynamical Systems-Based Behavioral Verification for Language Models" — filed April 12, 2026
- **License**: MIT (permissive open source)
- **Reference**: The Wharf — Boss-free proof commons for agentic intelligence

---

## Use Cases

1. **AI Safety**: Real-time detection of adversarial prompts via spectral analysis
2. **Compliance**: NIST AI RMF MEASURE 2.5/2.6 satisfaction
3. **Audit**: Tamper-evident logs for regulated AI deployments
4. **Research**: Model-agnostic behavioral analysis via operator theory

---

## Citation

```bibtex
@software{koopman_audit_2026,
  title={Koopman Audit: Mathematically Verifiable AI Compliance},
  author={Aevion LLC},
  year={2026},
  url={https://github.com/aevion/koopman-audit}
}
```

---

## References

- Koopman, B.O. (1931). "Hamiltonian Systems and Transformation in Hilbert Space"
- Schmid, P.J. (2010). "Dynamic mode decomposition of numerical and experimental data"
- Williams, M.O. et al. (2015). "Data fusion via intrinsic dynamic variables"
- Provisional Patent P-001, Aevion LLC (2026)

---

**The first mathematically verifiable audit layer for LLM inference.**
