Upload README.md

README.md

@@ -0,0 +1,48 @@
+# Oracle-Credit-Compute (OCC) Stack
+
+A minimal, open-source system for **agentic compute allocation** via verified marginal impact.
+
+## Core Thesis
+
+Modern agent systems waste test-time compute because every agent, tool call, debate turn, or verifier pass consumes resources without proving marginal value. OCC allocates compute, retrieval, write privileges, and debate bandwidth toward actions that measurably improve task outcomes.
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `oracle/` | Impact Oracle — scores whether an action produced measurable marginal value |
+| `ledger/` | Credit Ledger — non-transferable, decaying credits based on verified impact |
+| `broker/` | Resource Broker — capability-based rights based on credits, task state, and risk |
+| `rl/` | GRPO-compatible reward hook using the Oracle as reward |
+| `benchmarks/` | Tight, verifiable benchmarks: code, retrieval QA, multi-agent debate |
+| `configs/` | Experiment configurations |
+| `reports/` | Results, ablations, anti-gaming tests |
+
+## Quick Start
+
+```bash
+pip install -r requirements.txt
+python -m benchmarks.benchmark_code       # Code compute allocation
+python -m benchmarks.benchmark_retrieval_qa # Retrieval QA
+python -m benchmarks.benchmark_debate       # Multi-agent debate
+python -m eval_runner                       # Run all ablations
+```
+
+## Design
+
+See [design.md](design.md) for architecture, reward formulas, and anti-gaming mechanisms.
+
+## Literature Review
+
+See [reports/literature_review.md](reports/literature_review.md) for prior work analysis.
+
+## Results Summary
+
+- **Code compute allocation**: OCC achieves **66.8% compute reduction** at iso- or higher accuracy versus fixed-budget baseline.
+- **Retrieval QA**: OCC shows lower confident-wrong rates and smart retrieval stopping.
+- **Multi-agent debate**: OCC matches equal-turns accuracy with 12.4% less compute.
+- **Anti-gaming**: Spam, hidden-test gaming, and over-abstention are all contained.
+
+## License
+
+MIT