pip install git+https://github.com/munshi007/Aura-State.git

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
class ExtractLead(Node):
    system_prompt = "Extract lead info from a sales call transcript."
    extracts = LeadData

    def handle(self, user_text, extracted_data=None, memory=None):
        return "QualifyBudget", extracted_data.model_dump()

# Define a node that does deterministic math (no LLM)
class QualifyBudget(Node):
    system_prompt = "Score the lead."
    sandbox_rule = "result = budget > 100000"  # runs in sandboxed AST, not LLM

    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.")

1. Adaptive DAG health check     →  Should this node be skipped or retried?
2. GraphRAG cache lookup          →  Have we seen this exact input before? Skip the LLM.
3. Few-shot injection             →  Find similar past successes, inject as examples.
4. LLM extraction + verification  →  Extract data, verify with Z3, retry if wrong.
5. Your node's handle() method    →  Your business logic runs here.
6. MCTS Routing (UCB1)        →  Score branches using UCB1 + AdaptiveDAG metrics.
7. State serialization            →  Save state for time-travel debugging.
8. Speculative execution          →  Pre-compute likely next nodes in parallel.

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

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

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

फ़ील्ड              सटीकता
──────────────   ──────────
नाम                  100%
बजट                100%
बेडरूम              100%
पूर्व-अनुमोदित       90%
समयरेखा              90%
शहर                   80%

टेम्पोरल गुण:       3/3 साबित
Z3 प्रूफ दायित्व:    20/20 पास
रूटिंग सटीकता:        90%
औसत विलंबता:       1.4s

# Try it yourself — 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

aura_state/
├── core/
│   ├── engine.py              # Main engine — process() + MCTS/UCB1 routing
│   ├── adaptive_graph.py      # Node health monitoring
│   ├── verification_loop.py   # Extract → verify → retry loop
│   └── providers.py           # Multi-model routing + cost tracking
├── compiler/
│   ├── schema_compiler.py     # JSON Schema → Node classes
│   └── dspy_tuner.py          # KNN few-shot selection
├── verification/
│   ├── temporal_verifier.py   # Kripke + CTL model checking
│   ├── conformal.py           # Conformal prediction intervals
│   └── proof_engine.py        # Z3 proofs
├── execution/
│   ├── tracer.py              # State serialization (time-travel debug)
│   └── sandbox.py             # Safe math execution (AST validated)
├── memory/
│   ├── trajectory_cache.py    # Subgraph isomorphism cache
│   └── pruner.py              # Context window optimization
└── consensus/
    └── auto_vote.py           # Multi-run extraction with voting

pip install git+https://github.com/munshi007/Aura-State.git

python -m pytest tests/ -v
# 65 tests passing