aura-state 0.2.0__tar.gz

aura_state-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: python -m pytest tests/ -q

aura_state-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+# Publishes to PyPI automatically when you create a GitHub Release.
+# Uses Trusted Publishing (OIDC) — no API token or password needed.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi        # must match the Environment name on PyPI's pending publisher
+    permissions:
+      id-token: write        # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

aura_state-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+.aura_cache/
+.aura_trace/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Local agent instructions
+agent.md

aura_state-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to Aura-State
+
+## Getting Started
+
+```bash
+git clone <repo-url>
+cd aura-state
+pip install -e .
+python -m pytest tests/ -v   # 65 tests should pass
+```
+
+## Architecture
+
+```
+aura_state/
+├── core/           → Engine, bandit router, health/edge metrics, verification loop, providers
+├── compiler/       → Schema compiler, JSON generator, DSPy-inspired teleprompting
+├── verification/   → Temporal verifier (CTL), conformal prediction, Z3 proof engine
+├── execution/      → AuraTrace debugger, AST sandbox
+├── memory/         → Context pruner
+├── consensus/      → Multi-run extraction with voting
+└── loaders/        → JSON/YAML graph loader
+```
+
+## Running Benchmarks
+
+```bash
+# Synthetic (no API key)
+python examples/benchmark/run_benchmark.py
+
+# Live (requires OPENAI_API_KEY in .env)
+python examples/benchmark/run_live.py --model gpt-4o-mini --runs 3
+```
+
+## Pull Requests
+
+1. Create a feature branch.
+2. Write tests for your changes.
+3. Ensure `python -m pytest tests/ -v` passes (all 65 tests).
+4. Open a PR with a clear description of *what* and *why*.
+
+## Design Principles
+
+- Every feature uses a real algorithm, not an API wrapper.
+- `AuraEngine` is the single entrypoint. All internals are always active.
+- Math is executed in a sandboxed AST interpreter, never by the LLM.
+- The DAG is the source of truth for state transitions.
+- Formal verification happens *before* execution, not after.

aura_state-0.2.0/LAUNCH.md

@@ -0,0 +1,98 @@
+# Launch kit — Aura-State
+
+Positioning: **dev-first**. Hero = developers building agents who are tired of "chain calls and hope."
+One-liner: **Build LLM agents you can actually prove things about.**
+Landing page: https://claude.ai/code/artifact/bff455f7-c4c5-44f5-8127-ba820fb9b6f6
+
+Honesty guardrail for all copy: it's a real, correct core (Z3/CTL/conformal, adversarial tests) but **v0.2, early, OSS — not a hardened enterprise product.** Never claim battle-tested / production-proven. The defense against skeptics is that the tests run the actual solvers against adversarial inputs.
+
+---
+
+## Product Hunt
+
+**Name:** Aura-State
+**Tagline (≤60 chars):** Build LLM agents you can prove things about
+**Alt taglines:**
+- Verification for AI agents that runs in the loop, not the sidebar
+- Formal proofs for your agents — Z3, model checking, no API key to try
+
+**Description (~260 chars):**
+Most agent frameworks let you chain LLM calls and hope. Aura-State runs your workflow as a typed state machine and verifies every step in the loop — Z3 proves extracted data, CTL model-checks the graph, taint analysis makes it injection-proof, and conformal risk control decides when to escalate to a human. Open source, MIT, five runnable demos with no API key.
+
+**First comment (maker):**
+Hi PH 👋 I built Aura-State because "the agent verifier" in most stacks is either an assertion, an LLM judging another LLM, or a test suite that runs after the fact — none of which is a guarantee.
+
+Aura-State moves verification *into* the loop:
+- **Z3** proves each extraction against your obligations (`total == area * rate`); a hallucinated value is rejected with the counterexample, not passed downstream.
+- **CTL model checking** proves reachability/completion/ordering over the whole graph before it runs.
+- **Static taint** proves untrusted input can't reach a dangerous tool — injection-proof by construction, tracking provenance not content.
+- **Conformal Risk Control** calibrates a threshold so the false-action rate is provably ≤ ε, else it escalates to a human.
+- And the verifier **repairs the plan** from its own counterexamples, then compiles everything into a portable contract.
+
+It's early (v0.2) and open source. Every guarantee is a demo you can run in ~10s with no API key, and the tests run the real solvers against adversarial inputs. Would love feedback from anyone building agents in high-stakes domains. Repo: github.com/munshi007/Aura-State
+
+---
+
+## Show HN
+
+**Title:** Show HN: Aura-State – Verify LLM agents in the loop with Z3, CTL, and conformal prediction
+
+**Body:**
+Aura-State is a Python framework that runs an LLM agent as a typed state machine and verifies every step *in the loop* rather than beside it.
+
+Concretely: a node declares proof obligations (`total == area * rate`) and they're checked with Z3 inside the extract→verify→retry loop — a value that can't be proven is rejected with the counterexample, not accepted. The workflow graph is model-checked with CTL (reachability, completion, ordering) at the init state. A static taint pass over the graph proves untrusted input can't reach a dangerous sink (injection-proof by construction — provenance, not content). Conformal Risk Control calibrates an act/abstain threshold with a finite-sample bound on the false-action rate. And counterexamples from any of these feed a replanner that repairs the design and re-verifies.
+
+Why I built it: the "verification" in most agent stacks is an assertion, an LLM-judge, or a post-hoc eval — none of which is a guarantee, and the judge is itself unverifiable. I wanted the check to be a solver.
+
+It's v0.2 and early. What I care most about getting right is correctness of the primitives, so the tests run the actual solvers against adversarial inputs (the classic `__subclasses__` sandbox escape, a wrong extraction, a genuine dead-end, empirical conformal coverage). Five demos run with no API key.
+
+Repo (MIT): https://github.com/munshi007/Aura-State
+Happy to go deep on the CTL init-state handling, the fail-closed AST→Z3 compiler, or the jackknife+ conformal — those are the parts people usually get subtly wrong.
+
+---
+
+## YC application answers
+
+**What does your company do? (one line)**
+Aura-State is an open-source framework that lets developers build LLM agents with formal guarantees — Z3 proofs, model checking, and calibrated risk control run inside the agent's loop.
+
+**What is it, longer:**
+Agents are moving into decisions where being wrong is expensive, but the tooling to *prove* an agent behaved is missing — teams rely on assertions, LLM-judges, and eval suites, which are heuristics, not guarantees. Aura-State runs the agent as a typed state machine and verifies each step with real solvers: Z3 for data obligations, CTL model checking for the graph, static taint for injection-safety, and conformal risk control for calibrated abstention. The design compiles into a portable, faithful-by-construction contract that a runtime can enforce.
+
+**Why now?**
+Three things converged in 2026: agents are being deployed into regulated, high-stakes workflows; the EU AI Act's high-risk obligations (traceability, human oversight) took effect; and the research on formal methods for LLM agents matured (CaMeL, AgentSpec, VeriGuard, conformal risk control). The verification techniques are proven; nobody has packaged them into a framework developers actually build in.
+
+**Why us / why this is defensible?**
+The moat isn't the orchestration — it's getting the verification primitives *correct*. Most "LLM verification" projects ship subtly wrong math (interpolated conformal quantiles, reversed CTL, fail-open provers). Aura-State's are correct and adversarially tested, and the design→contract compiler makes the spec faithful by construction — killing the "who writes and maintains the policy" problem every competitor concedes.
+
+**Traction / status:** v0.2 open source, 117 tests, five runnable demos. Pre-launch.
+
+---
+
+## Launch tweet / thread
+
+**Tweet 1:**
+Most agent frameworks: chain LLM calls and hope.
+
+Aura-State: run the agent as a state machine and *prove* each step.
+
+Z3 rejects a hallucinated value in the loop. CTL model-checks the graph. Taint makes it injection-proof. Open source, no API key to try 🧵
+
+**Tweet 2:**
+The verifier isn't another LLM judging the first one — it's a solver.
+
+A node declares `obligations = ["total == area * rate"]`. If the extraction can't be *proven* to satisfy it, it's rejected with the counterexample and retried. Fail-closed.
+
+**Tweet 3:**
+Injection-proof by construction: label a node `untrusted_source` and a tool `dangerous_sink`, and Aura-State statically proves untrusted data can't reach it — tracking provenance, not content, so encodings can't fool it.
+
+Everyone else sells detection. This is impossibility.
+
+**Tweet 4:**
+"Knows when it doesn't know" — made real. Conformal Risk Control calibrates a threshold so the agent's false-action rate is provably ≤ 5%. Below it, it escalates to a human instead of guessing.
+
+**Tweet 5:**
+And when a check fails, the verifier *repairs the plan* from its own counterexample and re-verifies — then compiles the whole thing into a portable contract.
+
+v0.2, MIT, 5 demos run in ~10s with no API key 👇
+github.com/munshi007/Aura-State

aura_state-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Munshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aura_state-0.2.0/PKG-INFO

@@ -0,0 +1,374 @@
+Metadata-Version: 2.5
+Name: aura-state
+Version: 0.2.0
+Summary: Build LLM agents you can prove things about — Z3 proofs, CTL model checking, and conformal risk control, verified in the loop.
+Project-URL: Homepage, https://github.com/munshi007/Aura-State
+Project-URL: Repository, https://github.com/munshi007/Aura-State
+Project-URL: Issues, https://github.com/munshi007/Aura-State/issues
+Author: Rohan Munshi
+License: MIT
+License-File: LICENSE
+Keywords: agent-framework,agents,ai-safety,conformal-prediction,ctl,formal-verification,llm,model-checking,prompt-injection,smt,state-machine,z3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: instructor>=1.3
+Requires-Dist: networkx>=3.0
+Requires-Dist: openai>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pymodelchecking>=1.3
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: z3-solver>=4.12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">Aura-State</h1>
+
+<p align="center"><b>Build LLM agents you can actually prove things about.</b></p>
+
+<p align="center">
+  Verification that runs <i>in the loop</i>, not the sidebar — Z3 proofs, CTL model checking, and conformal risk control gate every step. A value that can't be proven is never accepted.
+</p>
+
+<p align="center">
+  <img alt="CI" src="https://github.com/munshi007/Aura-State/actions/workflows/ci.yml/badge.svg">
+  <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-3d3aa8.svg">
+  <img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
+  <img alt="tests" src="https://img.shields.io/badge/tests-130%20passing-1c8a5b.svg">
+</p>
+
+```bash
+pip install aura-state
+```
+
+## See it in 10 seconds (no API key)
+
+Every guarantee ships as a runnable proof against the real solvers:
+
+| Demo | What it proves |
+|---|---|
+| `python examples/verified_loop_demo.py` | Z3 rejects a hallucinated extraction in the loop, retries, accepts |
+| `python examples/taint_proof_demo.py` | untrusted input provably can't reach a dangerous tool |
+| `python examples/risk_abstention_demo.py` | acts only within a calibrated risk budget, else escalates to a human |
+| `python examples/emit_contract_demo.py` | a portable contract compiled faithfully from the design |
+| `python examples/replan_demo.py` | the verifier *repairs* the plan until it's proven-safe |
+| `python examples/pasc_demo.py` | pipeline-aware conformal calibrates the end-to-end answer, not just each step |
+
+## What this is
+
+Most LLM frameworks let you chain API calls and hope for the best. Aura-State takes a different approach: you define your workflow as a typed graph of nodes, and **verification runs inside the loop** — every extraction must satisfy its formal contract before the workflow moves on.
+
+The key difference is what happens between nodes:
+
+- **Extractions** are checked against Z3 proof obligations, in the extract→verify→retry loop — a value that can't be proven is not accepted (fail-closed)
+- **Math** runs in a no-`exec` sandboxed interpreter, never hallucinated
+- **Uncertainty** is a real conformal interval over repeated runs, not a vibe
+- **Workflows** are model-checked (CTL) for reachability/completion/ordering *before* they run
+- **Routing** (when a node returns an ambiguous edge) is a Thompson-sampling bandit, not an LLM guess
+
+## Quick example
+
+```python
+from aura_state import AuraEngine, Node, CompiledTransition
+from pydantic import BaseModel, Field
+from openai import OpenAI
+
+# Define what you want to extract
+class LeadData(BaseModel):
+    name: str = Field(description="Full name")
+    budget: int = Field(description="Budget in USD")
+    timeline: str = Field(description="Buying timeline")
+
+# Define a node that extracts it — with a Z3 obligation the value must satisfy
+class ExtractLead(Node):
+    system_prompt = "Extract lead info from a sales call transcript."
+    extracts = LeadData
+    obligations = ["budget > 0"]   # proven in the loop; unprovable -> not accepted
+
+    def handle(self, user_text, extracted_data=None, memory=None):
+        return "QualifyBudget", extracted_data.model_dump()
+
+# Define a decision node that does deterministic math (no LLM). Its rule runs
+# even though the node does no extraction — it reads prior state from memory.
+class QualifyBudget(Node):
+    system_prompt = "Score the lead."
+    sandbox_rule = "result = budget > 100000"  # runs in the no-exec sandbox
+
+    def handle(self, user_text, extracted_data=None, memory=None):
+        return "END", memory
+
+# Wire it up
+engine = AuraEngine(llm_client=OpenAI())
+engine.register(ExtractLead, QualifyBudget)
+engine.connect([
+    CompiledTransition(from_node=ExtractLead, to_node=QualifyBudget),
+])
+
+# Run
+next_state, data = engine.process("ExtractLead", user_text="Hi, I'm Sarah. Budget is $450k.")
+```
+
+## What happens under the hood
+
+When you call `engine.process()`, it runs through these steps in order:
+
+```
+1. Few-shot injection      →  optional: inject similar past successes as examples.
+2. Verification loop       →  extract → check (sandbox rule + Z3 obligations) → retry.
+                              A value that fails its contract is not accepted (fail-closed).
+3. Conformal interval      →  with consensus > 1, build a real interval over the runs.
+4. Your handle() method    →  your routing / business logic runs here.
+5. Bandit router           →  if handle() returns an invalid edge, Thompson-sample a feasible one.
+6. State serialization     →  save state (JSON, tamper-evident) for time-travel debugging.
+```
+
+Graph-level properties (reachability, completion, ordering) are checked separately
+at **design time** with `engine.verify([...])` — CTL model checking over the whole
+graph, which per-transition checks can't do. Everything above happens *in the loop*;
+`engine.verification_reports()` returns the proof results and intervals per step.
+
+## Formal verification (the interesting part)
+
+This is what actually makes Aura-State different from other frameworks.
+
+### Verify your workflow graph before it runs
+
+Your node graph gets compiled into a [Kripke structure](https://en.wikipedia.org/wiki/Kripke_structure) and checked against temporal logic properties:
+
+```python
+from aura_state import verify_engine, reachability, mutual_exclusion, eventual_completion
+
+results = verify_engine(engine, [
+    {"description": "QualifyBudget is reachable", "formula": reachability("QualifyBudget")},
+    {"description": "All paths terminate", "formula": eventual_completion("QualifyBudget")},
+])
+# Result: PROVEN or VIOLATED, with the exact states that satisfy/violate
+```
+
+This is the same technique used to verify hardware circuits and flight control systems (CTL model checking, Clarke et al. 1986).
+
+### Prove that extracted data is correct
+
+After the LLM extracts values, Z3 (a theorem prover from Microsoft Research) can formally prove they satisfy your constraints:
+
+```python
+from aura_state import prove_extraction
+
+result = prove_extraction(
+    {"budget": 450000, "cost_per_sqft": 3, "total": 1350000},
+    obligations=["budget > 0", "total == budget * cost_per_sqft"],
+)
+# result.verified = True
+# If False, Z3 gives you a counterexample showing exactly what broke
+```
+
+It also proves your obligations aren't *self-contradictory*. `["x > 5", "x < 3"]`
+can never hold — Z3 catches that symbolically (variables ranging freely over the
+declared field bounds, not pinned to one value), and the design→contract compiler
+flags it per node before you ship.
+
+### Confidence intervals on extractions
+
+Run the extraction multiple times and get distribution-free confidence intervals:
+
+```python
+from aura_state import conformal_interval
+
+budgets = [450000, 452000, 448000, 450000, 451000]
+ci = conformal_interval(budgets, confidence=0.95)
+# ci.lower = 447800, ci.upper = 452200
+```
+
+This uses conformal prediction (Vovk et al., 2005) — no distributional assumptions required.
+
+**Pipeline-aware (PASC):** a 95% guarantee at each node is *not* 95% end-to-end —
+errors compound. `PipelineConformal` calibrates on the composed output so the
+guarantee holds for the final answer. In the demo, per-step conformal covers the
+end-to-end result only ~48%; PASC hits the nominal 90%. See
+`python examples/pasc_demo.py`.
+
+### Compile a runtime contract from the design
+
+The obligations, CTL verdicts, and confidence a workflow was proven against
+compile into a single portable, versioned contract. Because it's derived from
+the same typed design the engine runs, the specification is **faithful by
+construction** — spec and implementation are one artifact and can't drift.
+
+```python
+contract = engine.compile_contract(properties=[
+    {"description": "RouteLead is reachable", "formula": reachability("RouteLead")},
+])
+contract.to_json()                        # portable, content-addressable
+check_faithfulness(contract, "QualifyLead", extracted)   # contract agrees with the loop
+diff_contracts(old, contract)             # design-time regression gate
+```
+
+Every other assurance system *consumes* a behavioral contract it can't author —
+and hand-written policy drifts from the code (and is only 24–35% faithful when
+translated from prose). Here the contract is emitted from the design that was
+proven. See `python examples/emit_contract_demo.py`.
+
+### Prove untrusted data can't reach a dangerous tool (injection-proof)
+
+Label nodes with capability types and the compiler statically proves — over the
+typed graph — that no untrusted source can reach a dangerous sink without
+passing a sanitizer. It tracks *provenance, not content*, so it can't be fooled
+by the encodings that defeat runtime scanners. The verdict compiles into the
+contract, so a runtime can refuse to deploy a `VIOLATED` graph.
+
+```python
+class Ingest(Node):    untrusted_source = True     # LLM / external tool output
+class Review(Node):    sanitizer = True            # clears taint
+class SendEmail(Node): dangerous_sink = True       # irreversible action
+
+analyze_taint(engine)   # -> VIOLATED (Ingest -> SendEmail) unless Review is in the path
+```
+
+It's **field-level**: label individual fields, and a clean field passes a sink
+untouched while only a *tainted* field reaching it is a violation — with the exact
+field and its origin named. A field-specific sanitizer clears just its field.
+
+```python
+class Ingest(Node): untrusted_fields = ["note"]   # free text is untrusted
+class Send(Node):   sink_fields = ["account_id"]  # the action consumes account_id
+
+analyze_field_taint(engine)   # PROVEN — the tainted `note` never reaches the sink arg
+```
+
+Everyone else sells injection *detection* (probabilistic). This is
+*impossibility* over the design. See `python examples/taint_proof_demo.py`.
+
+### Act only if calibrated risk ≤ ε, otherwise escalate
+
+The "knows when it doesn't know" story made into an actual gate. Calibrate a
+controller on a labeled set and the agent auto-acts only when its false-action
+rate is provably within budget — everything below the threshold escalates to a
+human, never a silent guess.
+
+```python
+ctrl = RiskController(epsilon=0.05).calibrate(scores, correct)   # false-action rate ≤ 5%
+
+class Decide(Node):
+    risk_controller = ctrl
+    escalation_node = "HumanReview"
+    def risk_score(self, extracted_data=None, conformal=None, memory=None):
+        return confidence   # in [0,1]
+```
+
+Uses Conformal Risk Control (arXiv:2208.02814); Learn-Then-Test
+(arXiv:2110.01052) for tuning several thresholds. Abstention is a first-class
+engine outcome. See `python examples/risk_abstention_demo.py`.
+
+### Let the verifier repair the plan (counterexample-guided replanning)
+
+Verification is usually a gate that says VIOLATED and stops. Here the
+counterexample — a tainted path, a CTL violating state, a Z3 assignment — is fed
+back to a replanner, which edits the plan and re-verifies, until it's proven or a
+budget is hit. The plan is provably correct *because* the verifier drove it there.
+
+```python
+result = engine.repair()          # verify → counterexample → repair → re-verify
+result.verified                   # True: driven to PROVEN (e.g. a sanitizer inserted)
+result.unresolved                 # if it aborts: the explicit remaining violations
+```
+
+Never a silent pass — an unrepairable design aborts with the violation named.
+Refs: PAT-Agent (arXiv:2509.23675), VERIMAP (arXiv:2510.17109). See
+`python examples/replan_demo.py`.
+
+## Benchmark results
+
+We ran 10 real-estate sales transcripts through a 4-node pipeline using GPT-4o-mini (30 API calls total):
+
+```
+Field             Accuracy
+──────────────   ──────────
+name                  100%
+budget                100%
+bedrooms              100%
+pre_approved           90%
+timeline               90%
+city                   80%
+
+Temporal properties:       3/3 proven
+Z3 proof obligations:     20/20 passed
+Avg latency:              1.4s
+```
+
+```bash
+# See verification reject a hallucination in the loop — no API key needed
+python examples/verified_loop_demo.py
+
+# Full pipeline benchmark — no API key needed
+python examples/benchmark/run_benchmark.py
+
+# With real LLM calls (needs OPENAI_API_KEY in .env)
+python examples/benchmark/run_live.py --model gpt-4o-mini --runs 3
+```
+
+## Project structure
+
+```
+aura_state/
+├── core/
+│   ├── engine.py              # Main engine — verified process() loop + bandit router
+│   ├── adaptive_graph.py      # Node health metrics + per-edge Beta-Bernoulli posteriors
+│   ├── verification_loop.py   # Extract → verify (sandbox + Z3) → retry loop
+│   └── providers.py           # Multi-model routing + cost tracking
+├── verification/             # ← the core: correct, adversarially-tested primitives
+│   ├── proof_engine.py        # Z3 proofs (fail-closed AST→Z3 compiler, no eval)
+│   ├── conformal.py           # jackknife+ prediction intervals (order statistic)
+│   └── temporal_verifier.py   # Kripke + CTL model checking (init-state, structural deadlocks)
+├── execution/
+│   ├── sandbox.py             # No-exec allowlist AST evaluator (deny-by-default)
+│   └── tracer.py              # State serialization, tamper-evident JSON (time-travel debug)
+├── compiler/
+│   ├── schema_compiler.py     # JSON Schema → Node classes
+│   └── dspy_tuner.py          # KNN few-shot selection (real embedder required)
+├── memory/
+│   └── pruner.py              # Context window optimization
+└── consensus/
+    └── auto_vote.py           # Multi-run extraction with voting
+```
+
+## Installation
+
+```bash
+pip install aura-state
+```
+
+Or the latest from source:
+
+```bash
+pip install git+https://github.com/munshi007/Aura-State.git
+```
+
+Python 3.10+ required. Dependencies: `pydantic`, `instructor`, `openai`, `networkx`, `pyModelChecking`, `z3-solver`, `pyyaml`.
+
+## Tests
+
+```bash
+python -m pytest tests/ -v
+# 100 tests passing
+```
+
+## Docs
+
+- [Usage Guide](docs/GUIDE.md) — code examples for every feature
+- [Algorithm Reference](docs/ALGORITHMS.md) — deep-dive into CTL, Z3, Thompson sampling, conformal prediction
+- [Contributing](CONTRIBUTING.md) — architecture overview and how to contribute
+- [Benchmark](examples/benchmark/) — synthetic and live benchmarks
+
+## License
+
+MIT