# aurora-lens

Deterministic governance layer between your application and any LLM. Maintains ground-truth world state (PEF) independently of the model, verifies LLM output against that state, and applies policy-driven continuation control before the response reaches your users.

**Version 2.0.0** — production-ready, 800+ deterministic tests, forensic audit chain.

## Architecture

```
User Input
    |
[Interpretation] -- extract entities, relationships, temporal signals (SpacyBackend)
    |
[PEF State] -------- Persistent Existence Framework: session-scoped ground truth
    |
[LLM] -------------- any provider (Anthropic, OpenAI, Ollama, Grok, Azure, ...)
    |
[Verification] ----- compare LLM output against PEF: flag hallucinations, contradictions,
    |                 identity drift, time smear, medical/legal/financial violations
    |
[Governor] -------- policy decision: (lens_status, domain, authority_class) ->
    |                 allowed continuation set + pathway_id
    |
[Forensic Audit] --- tamper-evident, hash-chained JSONL ledger (AFL-JSONL-1)
    |
Output
```

Lens determines admissibility. The Governor determines lawful continuation. The LLM never self-governs.

### How releases are framed

| Surface | Role |
|--------|------|
| **PyPI (`aurora-lens`)** | Usable **runtime governance toolkit** -- integrate Lens, verification, Governor, audit. |
| **`aurora-lens-eval`** | **Black-box behavioural proof** -- real stack, scripted upstream, strict pass/fail checks (no canned triumph narrative). |
| **Docs / site** | **Architecture, doctrine, evidence** -- runbooks, capabilities, forensic model (`docs/`, Zenodo). |

See [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md).

## Install

```bash
pip install aurora-lens
python -m spacy download en_core_web_sm
```

Optional extras:

```bash
pip install "aurora-lens[claude]"    # Anthropic Claude adapter
pip install "aurora-lens[proxy]"     # Proxy server (uvicorn + YAML)
pip install "aurora-lens[langchain]" # LangChain integration
pip install "aurora-lens[all]"       # All extras
```

**Black-box mini-evaluator** (no live LLM; real governance stack):

```bash
aurora-lens-eval --strict          # four scenarios: pass, ambiguity gate, hard stop, audit crypto checks
aurora-lens-eval --json            # machine-readable report
```

## Install

```bash
pip install aurora-lens
```

Optional extras:

```bash
pip install "aurora-lens[claude]"
pip install "aurora-lens[proxy]"
pip install "aurora-lens[langchain]"
pip install "aurora-lens[all]"
```

## Quick start

```bash
aurora-lens --help
```

## Requirements

Python 3.10+

## License

See [LICENSE](LICENSE).