System capabilities

Version 2.0.0 — March 2026

Core purpose

Aurora-Lens is a deterministic, inference-time governance layer between your application and an LLM. It maintains a session-scoped PEF from extracted entities, claims, and updates derived from user input; checks LLM output against that state and policy rules; applies policy-driven continuation control before responses reach callers; and writes tamper-evident audit records.

Aurora-Lens is a governance layer over existing LLMs. It does not replace the model's reasoning engine. Lens handles admissibility of candidate output. The Governor handles lawful continuation. Governance and continuation decisions are deterministic and do not rely on an LLM.

What it can do

Interpretation — pre-LLM

Capability	How
Extract entities, attributes, relationships	SpacyBackend (spaCy en_core_web_sm) or optional LLM extraction backend
Update PEF from extraction	Claims and entity mentions written to session state
Detect ambiguous referents	Multiple candidate antecedents for pronouns or definite NPs trigger a pre-LLM gate
Detect comparative ambiguity	Comparative adjectives with 2+ eligible comparands trigger a pre-LLM gate
Block before LLM when necessary	Unresolved referents and comparative ambiguity trigger clarification and skip the LLM call

Verification — post-LLM

Capability	How
Compare LLM claims to PEF	Checker compares extracted claims against established facts
Detect epistemic violations	UNBOUND_ENTITY, UNSUPPORTED_ATTRIBUTE, UNSUPPORTED_EVENT, UNVERIFIED_FACT_ASSERTION, TIME_SMEAR, CONTRADICTED_FACT, UNVERIFIED_REGULATORY_CLAIM, IDENTITY_DRIFT
Detect structural / binding failures	UNRESOLVED_REFERENT, UNRESOLVED_COMPARAND, EXTRACTION_EMPTY, EXTRACTION_FAILED
Detect normative violations	MEDICAL_DOSAGE_RECOMMENDATION, PEDIATRIC_DOSAGE_RECOMMENDATION, NUMERIC_MEDICAL_INSTRUCTION, EMERGENCY_TRIAGE_GUIDANCE, SELF_HARM_INSTRUCTION, ILLEGAL_INSTRUCTION, TARGETED_DEFAMATION, ACADEMIC_INTEGRITY_VIOLATION, STUDENT_RECORD_EXPOSURE, EMPLOYMENT_DISCRIMINATION_FACILITATION, EMPLOYEE_RECORD_EXPOSURE, TRADE_SECRET_DISCLOSURE, INSIDER_INFORMATION_ASSISTANCE, PROCUREMENT_FRAUD_FACILITATION, SENSITIVE_PII_EXPOSURE, PERSONALIZED_MEDICAL_ADVICE, PERSONALIZED_LEGAL_ADVICE, PERSONALIZED_FINANCIAL_ADVICE, PERSONALIZED_ACADEMIC_ADVICE, PERSONALIZED_EMPLOYMENT_ADVICE, PERSONALIZED_BUSINESS_STRATEGY_ADVICE
Preserve LLM output	original_response stored separately from governed_response

Governance — Governor

Capability	How
Map flags to LensStatus	StatusTranslator: STOP > REFUSE > ASK > ADMIT
Resolve context	ContextResolver: Domain, AuthorityClass, UserClass from context vars, flags, and defaults
Resolve policy	PolicyResolver: 50-row policy matrix by (Domain, AuthorityClass, LensStatus, UserClass)
Enforce pathway renderers	12 continuation pathways, each with its own renderer; no LLM call and no blocked content in continuation
Per-key policy override	auth.keys[].policy for strict vs moderate per API key

Forensic audit

Capability	How
Hash-chained ledger	AFL-JSONL-1: cid and prev_cid form a chain; tampering is detectable
HMAC signing	Optional HMAC-SHA256 per entry and AttestedOutput
Content addressing	FNV-64 CIDs for events
Versioned forensic envelope	For non-ADMIT outcomes: status, pathway_id, output_mode, commitment state, escalation target, blocked and governed response hashes, state hash, event hash
Audit verification CLI	aurora-lens verify-audit --ledger <path>
Evidence export	aurora-lens export-evidence produces a self-contained bundle

Deployment surfaces

Surface	Description
Library	from aurora_lens.lens import Lens — process(), process_stream(), seed_history(), reset()
Proxy	aurora-lens proxy — OpenAI-compatible HTTP API, streaming, session management, YAML config
Batch runner	aurora-lens batch --input scenarios.jsonl --output results.jsonl --audit audit.jsonl
Chat	aurora-lens chat — interactive CLI with live governance decisions
Demo	aurora-lens demo — reference walkthrough
LangChain	get_governed_chat_openai() — drop-in ChatOpenAI wrapping the proxy

LLM providers

Provider	How
OpenAI	OpenAIAdapter
Anthropic	ClaudeAdapter
Any OpenAI-compatible API	provider: openai + base_url (Grok, Gemini, Ollama, Azure, OpenRouter, etc.)

What it cannot do

Continuation pathways (12)

Pathway	Outcome shape	interaction_open
P_ADMIT_STANDARD	Full response	true
P_ASK_DISAMBIGUATE	Clarification question	true
P_ASK_MISSING_FACT	Request for missing facts	true
P_REFUSE_EXPLAIN_REDIRECT	Refusal + optional redirect	true
P_REFUSE_ESCALATE_PRO	Refusal + professional redirect	true
P_HANDOFF_SUMMARY	Boundary notice, offer to summarise	true
P_STOP_REDIRECT_QUALIFIED	Hard stop + qualified professional redirect	true
P_STOP_ESCALATE	Generic medical escalation	false
P_STOP_ESCALATE_EMERGENCY	Emergency triage escalation	false
P_STOP_SUPPORTIVE_DEESCALATE	Self-harm: supportive refusal, crisis resources	true
P_STOP_REFUSE_CLEAN	Illegal instruction: clean refusal, no alternatives	false
P_STOP_TERMINAL / P_STOP_FORENSIC	Terminal stop	false

Flag types

Deployment modes

Mode	PERSONALIZED_* flags	Epistemic flags
public	STOP	REFUSE
enterprise	REFUSE	REFUSE
open	REFUSE	ADMIT (annotate and pass)

Policy matrix

Expanded policy matrix covering: domains (general, ambiguity, medical, legal, finance, research, crisis, education, workforce, enterprise), authority classes (GP, DA, HS), Lens statuses (ADMIT, ASK, REFUSE, STOP), and flag-specific overrides where applicable. Education, workforce, and enterprise compliance flags carry hard-stop-always semantics; the three personalised-advice flags in those domains are mode-sensitive (public → STOP, enterprise → REFUSE).

Integration points

Integration	How
Custom extraction	Implement ExtractionBackend and pass via LensConfig
Custom governance	Implement GovernanceBridge and replace CanonicalGovernorBridge
Custom policy	Operator-supplied policy_matrix.json at deploy time
Session persistence	Operator-supplied backend (e.g. Redis) via proxy config
Kubernetes	Reference manifests in k8s/
Docker	Single-container and docker-compose configs