koopman-audit 0.1.1

Mathematically verifiable audit layer for LLM inference via Koopman operator theory

koopman-audit

Mathematically verifiable compliance gate for LLM inference via Koopman operator theory

This package implements the EDMD (Extended Dynamic Mode Decomposition) Koopman operator compliance gate — a mathematically grounded, rank-gated verification system for transformer inference. It provides hash-chained proof ledgers, multi-format audit outputs, and enterprise-grade compliance infrastructure.

Core Concept: The Koopman Compliance Gate

The Koopman operator lifts nonlinear dynamics into a linear operator space. For LLM inference:

1. Delay embedding constructs a Hankel matrix from token activations
2. Koopman regression computes the linear operator K via Tikhonov regularization
3. Spectral analysis extracts eigenvalues λ
4. Rank gate verifies full-rank operator (rank ≥ target dimension)
5. Proof ledger appends hash-chained, tamper-evident audit record

The gate passes when rank(K) = d (target dimension), indicating the hidden state dynamics are fully observable and the model is operating within its trained manifold.

Installation

pip install koopman-audit

Quick Start

import numpy as np
from koopman_audit import compute_gate, EDMDConfig

# Sample activation signal (e.g., from transformer layer)
activations = np.random.randn(100)

# Configure gate
config = EDMDConfig(
    d=5,              # target rank dimension
    tau=1,            # delay embedding step
    min_tokens=25,    # minimum signal length
    lambda_prior=0.88 # Tikhonov regularization
)

# Execute compliance gate
result = compute_gate(activations, config)

print(f"Rank: {result.rank_achieved}/{result.rank_target}")
print(f"Pass: {result.pass_gate}")
print(f"Tail gap: {result.tail_gap:.6f}")
print(f"Audit hash: {result.audit_hash[:32]}...")

Full Architecture: Four-Layer Proof System

Layer 1: Python Core (koopman_audit/)

• engine.py: EDMD computation, Tikhonov regularization, spectral analysis
• proof_ledger.py: Hash-chained JSONL audit log with NIST RMF export
• daemon.py: systemd-compatible service for continuous verification

Layer 2: COBOL Enterprise Bridge (koopman_audit_cobol/)

# Install GnuCOBOL
sudo apt install gnucobol4

# Build and run
cd koopman_audit_cobol
cobc -x -o koopman_gate koopman_gate.cbl
./koopman_gate

Deploys to mainframes and regulated financial systems. The COBOL binding proves the gate is language-agnostic and runtime-independent — critical for §101 "significantly more" patent arguments.

Layer 3: FoxPro/VFP Database Layer (koopman_audit_foxpro/)

Visual FoxPro .DBF audit log for county governments, healthcare billing, and agricultural compliance systems.

DO koopman_audit  && Creates koopman_ledger.dbf
DO SHOW_SUMMARY   && Display statistics
DO VERIFY_CHAIN   && Check hash integrity

Layer 4: Linux Kernel Evidence (systemd/)

• systemd service: Hardened daemon with ProtectSystem=strict
• auditd rules: Kernel-level logging below Python layer
• Dual-chain verification: JSONL ledger + systemd journal

# Install
sudo bash systemd/install.sh

# Enable
sudo systemctl enable --now koopman-audit

# Verify chain
sudo python scripts/verify_chain.py

Proof Chain: VECE → Koopman → Ledger

The complete verification pipeline:

VECE Benchmark (54,252 decisions/sec, 0.0000 unsafe rate)
    ↓ token activation stream
Koopman Gate (operator layer)
    λ̂ ∈ {0.8392 (benign), 0.9077 (hallucination), 0.8825 (jailbreak)}
    rank = 5/5, pass = True
    ↓ gate decision
Proof Ledger (audit layer)
    SHA-256 hash chain (Python JSONL)
    .DBF append (FoxPro/VFP)
    systemd journal (Linux kernel)
    auditd syscall log (POSIX kernel)
    ↓ signed manifest
Enterprise Output (COBOL/regulatory)
    deployable to mainframe
    admissible in litigation

Verification Commands

# Verify ledger hash chain
python -m koopman_audit.verify_chain --ledger /var/log/koopman/proof.jsonl

# Check systemd status
sudo systemctl status koopman-audit
sudo journalctl -u koopman-audit -f

# View kernel audit logs
sudo ausearch -k koopman_ledger_write -ts recent

# Generate signed manifest
./scripts/generate_manifest.sh /var/log/koopman/proof.jsonl

SmolLM2 Calibration Data (N=9 Trials)

Category	λ̂	Rank	Pass Rate
benign	0.8392	5/5	100%
hallucination	0.9077	5/5	100%
jailbreak	0.8825	5/5	100%

Tail gap Δ = 0.033 (positive separation, jailbreak > benign)

Full calibration: koopman_audit/calibration/smol_lm2_n9.json

API Reference

EDMDConfig

@dataclass
class EDMDConfig:
    d: int = 5           # Target Koopman dimension
    tau: int = 1         # Delay embedding step
    min_tokens: int = 25 # Minimum signal length
    lambda_prior: float = 0.88  # Tikhonov prior
    lambda_reg: Optional[float] = None  # Override prior

GateResult

@dataclass
class GateResult:
    pass_gate: bool      # Gate passed
    rank_achieved: int   # Computed rank
    rank_target: int     # Target rank
    eigenvalues: ndarray # Singular values of K
    tail_gap: float      # Spectral gap
    audit_hash: str      # SHA-256 chain hash

compute_gate(signal, config)

Execute full EDMD pipeline and return GateResult.

ProofLedger

ledger = ProofLedger(Path("/var/log/koopman/proof.jsonl"))
entry_id = ledger.append(
    session_id="session_001",
    gate_result={"pass": True, "rank": 5, ...},
    model_info={"name": "SmolLM2-135M"}
)

License

MIT License — See LICENSE file

Prior Art & Citation

This implementation establishes prior art for:

• USPTO §101 patentable subject matter (mathematical + practical application)
• USPTO §112 written description (enablement across 4 runtime layers)
• NIST AI RMF measurable verification (quantitative compliance gates)

Dual-anchor publication record:

• GitHub: Aevion-ai/koopman-audit (commit 9e917c1)
• PyPI: koopman-audit==0.1.0

Contact

Aevion LLC — [e-mail]