Rewrite README with why/where/how narrative + PyPI v0.1.0 release

README.md

@@ -17,6 +17,7 @@ pinned: false
 
 # ⚛️ QSVAPS — Quantum Superposition Verification for Agent Plan Safety
 
+[![PyPI](https://img.shields.io/pypi/v/qsvaps.svg)](https://pypi.org/project/qsvaps/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
 [![Tests](https://img.shields.io/badge/tests-52%20passed-brightgreen.svg)](#running-tests)
@@ -24,56 +25,107 @@ pinned: false
 
 **The first framework to use Grover's quantum search as a verification oracle for AI agent plans.**
 
-Classical generation → Quantum verification → Classical refinement.
+```
+Classical Generation  →  Quantum Verification  →  Classical Repair
+     (LLM agent)         (Grover's algorithm)       (LLM agent)
+```
 
 ---
 
-## What is QSVAPS?
+## 🔴 The Problem: AI Agents Fly Blind
+
+AI agents (LangChain, AutoGen, CrewAI) generate multi-step plans every day — chaining API calls, orchestrating tools, executing code. But here's the uncomfortable truth:
+
+> **Nobody verifies these plans before execution.**
+
+A plan that looks correct step-by-step can fail catastrophically due to **emergent interactions** between steps:
+- 🔥 **Race conditions** — two steps hit the same rate-limited API simultaneously
+- 💥 **Cascading failures** — step 3 depends on step 2, which silently failed
+- 🔒 **Resource deadlocks** — competing steps lock each other out
+- 🕳️ **Missing fallbacks** — a critical step fails with no recovery path
+
+Classical verification requires checking every possible execution scenario. For a plan with 20 decision points, that's **2²⁰ = 1,048,576 scenarios.** Exhaustive checking is too slow.
 
-AI agents (LangChain, AutoGen, CrewAI) generate multi-step plans — tool calls, API sequences, code execution chains. But **nobody verifies these plans before execution.** A plan that looks correct step-by-step can fail due to emergent interactions: race conditions, resource conflicts, cascading failures.
+## 🟢 The Solution: Quantum Verification
 
-QSVAPS solves this by encoding plan constraints as a **quantum oracle** and using **Grover's algorithm** to search for failure modes with a provable **quadratic speedup** over classical brute-force verification.
+QSVAPS uses **Grover's quantum search algorithm** — a provably optimal quantum algorithm — to search the space of potential failures **quadratically faster** than any classical approach:
 
-| Aspect | Classical | Quantum (Grover) |
+| Scenario | Classical Brute Force | QSVAPS (Grover) |
 |---|---|---|
-| Finding one failure in N states | O(N) | O(√N) |
-| Certifying no failures | O(N) exhaustive | O(√N) high-probability |
-| 2²⁰ state space | ~1M checks | ~1000 iterations |
+| 20 decision points (2²⁰ states) | ~1,000,000 checks | ~1,000 iterations |
+| 30 decision points (2³⁰ states) | ~1,000,000,000 checks | ~31,623 iterations |
+| Speedup | O(N) | O(√N) — **provably optimal** |
+
+This isn't quantum for the sake of quantum. Grover's speedup is **information-theoretically optimal** — no classical algorithm can do better for unstructured search.
+
+## 🧭 Where QSVAPS Fits
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                      AI Agent Architecture                          │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐  │
+│  │             │     │                  │     │                  │  │
+│  │  LLM Agent  │────▶│     QSVAPS       │────▶│  Safe Execution  │  │
+│  │  generates  │     │  verifies plan   │     │  with confidence │  │
+│  │  plan       │     │  using quantum   │     │                  │  │
+│  │             │     │  search          │     │                  │  │
+│  └─────────────┘     └────────┬─────────┘     └──────────────────┘  │
+│         ▲                     │                                      │
+│         │              If violations found                           │
+│         │                     │                                      │
+│         └─────────────────────┘                                      │
+│              LLM repairs plan                                        │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
 
-## Quick Start
+**QSVAPS sits between plan generation and execution.** It's the safety layer that catches failures before they happen — using quantum computing as a verification co-processor.
+
+### What Makes This Novel
+
+| Existing Approach | QSVAPS Difference |
+|---|---|
+| Quantum Neural Networks | Uses quantum for **verification**, not model training |
+| LLM generates quantum code | Quantum code enhances the **agent itself** |
+| Quantum hyperparameter tuning | Quantum solves a **core agent bottleneck** |
+| Classical plan verification | Provable **quadratic speedup** via Grover's algorithm |
+
+## ⚡ Quick Start
 
 ### Install
 
 ```bash
-pip install -r requirements.txt
+pip install qsvaps
 ```
 
 ### Run the Demo
 
 ```bash
-python demo.py
+python -m qsvaps.demo
 ```
 
-No API keys needed — uses the Qiskit Aer simulator and a mock LLM.
+No API keys needed — uses the Qiskit Aer simulator and a built-in mock LLM.
 
 ### Use in Your Code
 
 ```python
 from qsvaps import Plan, PlanAction, ResourceConstraint, PlanVerifier
 
-# Define a plan
+# Define your agent's plan
 plan = Plan(
-    name="My Agent Plan",
+    name="Data Pipeline",
     actions=[
-        PlanAction(name="fetch", description="Fetch data", resources=["api"]),
-        PlanAction(name="process", description="Process data"),
-        PlanAction(name="save", description="Save results", can_fail=False),
+        PlanAction(name="fetch_data", description="Fetch from API", resources=["api_quota"]),
+        PlanAction(name="transform", description="Transform dataset"),
+        PlanAction(name="save", description="Write to database", can_fail=False),
     ],
-    dependencies=[("fetch", "process"), ("process", "save")],
-    resource_constraints=[ResourceConstraint("api", max_concurrent=1)],
+    dependencies=[("fetch_data", "transform"), ("transform", "save")],
+    resource_constraints=[ResourceConstraint("api_quota", max_concurrent=1)],
 )
 
-# Verify
+# Quantum verification
 verifier = PlanVerifier(shots=2048)
 result = verifier.verify(plan, verbose=True)
 
@@ -83,100 +135,163 @@ if not result.is_safe:
         print(witness.explanation)
 ```
 
-### Verify & Repair with LLM
+### Verify & Auto-Repair with LLM
 
 ```python
 from qsvaps import PlanVerifier, LLMInterface
 
+# Connect to any OpenAI-compatible API
 llm = LLMInterface(api_key="sk-...", model="gpt-4")
-# or: llm = LLMInterface(mock=True)  # for testing
+
+# Or use the built-in mock for testing
+# llm = LLMInterface(mock=True)
 
 verifier = PlanVerifier(llm=llm, max_repair_iterations=3)
 results = verifier.verify_and_repair(plan, verbose=True)
+
+# The repaired plan is in results[-1].plan
 ```
 
-## Architecture
+## 🔬 How It Works
+
+### Step 1: Constraint Extraction
+
+Your plan's structure is automatically analyzed to extract boolean constraints:
 
 ```
-┌─────────────┐     ┌──────────────────┐     ┌───────────────┐
-│  LLM Agent  │────▶│  Constraint      │────▶│  Oracle       │
-│  generates  │     │  Engine extracts │     │  Builder      │
-│  Plan       │     │  boolean         │     │  creates      │
-│             │     │  constraints     │     │  quantum      │
-│             │     │                  │     │  circuit      │
-└─────────────┘     └──────────────────┘     └───────┬───────┘
-       ▲                                             │
-       │                                             ▼
-┌──────┴──────┐     ┌──────────────────┐     ┌───────────────┐
-│  LLM        │◀────│  Failure         │◀────│  Grover       │
-│  repairs    │     │  Witnesses       │     │  Search       │
-│  plan       │     │  decoded from    │     │  finds        │
-│             │     │  measurements    │     │  violations   │
-└─────────────┘     └──────────────────┘     └───────────────┘
+Plan: fetch_data → transform → save
+
+Constraints extracted:
+  C1 [DEPENDENCY]: 'transform' requires 'fetch_data' to succeed first
+     Formula: (¬x₁) ∨ x₀
+  C2 [DEPENDENCY]: 'save' requires 'transform' to succeed first
+     Formula: (¬x₂) ∨ x₁
+  C3 [COMPLETION]: 'save' must succeed
+     Formula: x₂
 ```
 
-## Project Structure
+Supported constraint types:
+- **Dependency** — if B depends on A, B succeeding implies A succeeded
+- **Resource** — actions sharing rate-limited resources can't both run in parallel
+- **Completion** — actions marked `can_fail=False` must succeed
+- **Fallback** — if an action has a fallback, at least one must succeed
+- **Custom** — any boolean expression you define
+
+### Step 2: Quantum Oracle Construction
+
+Constraints are encoded as a **quantum phase oracle** — a circuit that flips the phase of states where any constraint is violated:
 
 ```
-qsvaps/
-├── models.py             # Plan, Action, Constraint, Witness dataclasses
-├── constraint_engine.py  # Boolean constraint extraction from plans
-├── oracle_builder.py     # Quantum phase oracle + Grover diffuser
-├── grover_search.py      # Grover's algorithm execution engine
-├── verifier.py           # Main verification pipeline
-├── llm_interface.py      # LLM integration (OpenAI + mock mode)
-└── visualization.py      # ASCII diagrams + matplotlib plots
+|valid⟩    →   |valid⟩     (no phase change)
+|violation⟩ → -|violation⟩  (phase flipped)
 ```
 
-## How It Works
+### Step 3: Grover's Search
 
-1. **Plan Formalization** — Your agent's plan is parsed into structured `PlanAction` objects with preconditions, effects, and resource constraints.
+Grover's algorithm amplifies the probability of measuring violation states:
 
-2. **Constraint Extraction** — The `ConstraintEngine` automatically generates boolean constraints:
-   - **Dependency**: If B depends on A, then B succeeding implies A succeeded
-   - **Resource**: Actions sharing rate-limited resources can't both succeed in parallel
-   - **Completion**: Actions marked `can_fail=False` must succeed
-   - **Fallback**: If an action has a fallback, at least one must succeed
+```
+                    ┌──────────┐  ┌──────────┐
+|0⟩⊗ⁿ ── H⊗ⁿ ──┤  Oracle  ├──┤ Diffuser ├── × k iterations ── Measure
+                    └──────────┘  └──────────┘
+
+k = ⌊π/4 × √(N/M)⌋  where N = total states, M = violations
+```
+
+### Step 4: Witness Decoding
+
+Measured bitstrings are decoded into human-readable **failure witnesses**:
 
-3. **Oracle Construction** — Constraints are encoded as a quantum phase oracle: a circuit that flips the phase of states where any constraint is violated.
+```
+Witness #1 (measured 272 times):
+  ✅ Action 'fetch_data' succeeds
+  ✅ Action 'transform' succeeds  
+  ❌ Action 'save' FAILS
+  
+  Violated: 'save' must succeed
+  
+  → This scenario means the pipeline completes processing
+    but fails to persist results — silent data loss.
+```
+
+### Step 5: LLM Repair Loop
 
-4. **Grover Search** — Grover's algorithm amplifies violation states, making them overwhelmingly likely to be measured. With k = π/4 × √(N/M) iterations, violations are found quadratically faster than classical search.
+Witnesses are fed to an LLM that revises the plan:
+
+```
+Agent: "Your plan fails when 'save' fails with no fallback.
+        Add a retry mechanism or fallback storage."
 
-5. **Witness Extraction** — Measured bitstrings are decoded into human-readable `FailureWitness` objects showing exactly which actions failed and which constraints were violated.
+→ Repaired plan adds: save_fallback (write to local disk)
+→ Re-verification confirms the fix
+```
 
-6. **LLM Repair** — Witnesses are fed to an LLM that revises the plan, and verification repeats until the plan is safe.
+## 📦 Project Structure
 
-## The Quantum Advantage
+```
+qsvaps/
+├── models.py              # Plan, Action, Constraint, Witness dataclasses
+├── constraint_engine.py   # Boolean constraint extraction from plans
+├── oracle_builder.py      # Quantum phase oracle + Grover diffuser
+├── grover_search.py       # Grover's algorithm execution engine
+├── verifier.py            # Main verification pipeline
+├── llm_interface.py       # LLM integration (OpenAI + mock mode)
+└── visualization.py       # ASCII diagrams + matplotlib plots
+```
 
-QSVAPS uses Grover's algorithm — a provably optimal quantum search algorithm — to find plan failures quadratically faster than any classical approach:
+## 📊 Verified Results
 
-- **7-qubit circuit** verifies a 6-action pipeline with 128 possible states
-- **127/128 violations** detected in a single Grover iteration
-- **128× theoretical speedup** over exhaustive classical verification
-- Scales to **15+ qubits** on Qiskit Aer simulator, **127 qubits** on IBM Quantum hardware
+Demo verification of a 6-action API orchestration pipeline:
 
-This is not quantum for the sake of quantum — Grover's speedup is **information-theoretically optimal** for unstructured search.
+| Metric | Value |
+|---|---|
+| Qubits | 7 |
+| State space | 128 |
+| Violations found | 127 / 128 |
+| Grover iterations | 1 |
+| Circuit depth | 516 |
+| Circuit gates | 1,320 |
+| Theoretical speedup | 128× |
 
-## Running Tests
+## 🧪 Running Tests
 
 ```bash
 pip install pytest
 python -m pytest tests/ -v
 ```
 
-52 tests covering all components: models, constraints, oracle correctness, Grover search, and end-to-end verification.
+52 tests covering: models, constraint extraction, oracle correctness (statevector verified), Grover amplification, end-to-end verification, and repair loops.
+
+## 🛣️ Roadmap
 
-## Dependencies
+- [ ] **IBM Quantum integration** — run on real 127-qubit Eagle processors
+- [ ] **LangChain plugin** — drop-in verification for LangChain agents
+- [ ] **AutoGen middleware** — intercept plans before execution
+- [ ] **Scalable oracles** — CNF-based oracle construction for 20+ qubit plans
+- [ ] **Benchmark suite** — standardized plan verification benchmarks
 
-- `qiskit >= 1.0.0`
-- `qiskit-aer >= 0.13.0`
-- `numpy >= 1.24.0`
-- `matplotlib >= 3.7.0`
-- `openai >= 1.0.0` (optional, for LLM integration)
+## 📖 Research Background
 
-## Citation
+QSVAPS introduces a new architectural pattern: **"Generate classically, verify quantumly."** While quantum computing research typically focuses on replacing classical components (QNNs, VQCs), QSVAPS uses quantum algorithms in a fundamentally different role — as a verification oracle that checks classical output.
+
+This builds on:
+- **Grover's algorithm** (1996) — optimal O(√N) unstructured search
+- **PDDL-based planning** — formal plan representation with preconditions/effects
+- **Agent safety research** — the growing need to verify autonomous AI behavior
+
+The novelty lies in the bridge: encoding agent plan constraints as quantum oracles, enabling quantum speedup for a real-world AI safety problem.
+
+## 📦 Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `qiskit` | ≥ 1.0.0 | Quantum circuit construction |
+| `qiskit-aer` | ≥ 0.13.0 | Local quantum simulation |
+| `numpy` | ≥ 1.24.0 | Numerical operations |
+| `matplotlib` | ≥ 3.7.0 | Result visualization |
+| `openai` | ≥ 1.0.0 | *Optional* — LLM integration |
 
-If you use QSVAPS in your research, please cite:
+## 📄 Citation
 
 ```bibtex
 @software{qsvaps2025,
@@ -187,10 +302,10 @@ If you use QSVAPS in your research, please cite:
 }
 ```
 
-## Contributing
+## 🤝 Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-## License
+## 📜 License
 
 [MIT](LICENSE)