stratum-py 0.1.0__tar.gz

stratum_py-0.1.0/.claude/mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "stratum": {
+      "command": "stratum-mcp"
+    }
+  }
+}

stratum_py-0.1.0/.claude/settings.local.json

@@ -0,0 +1,43 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run build:*)",
+      "Bash(node config-loader.js:*)",
+      "Bash(curl:*)",
+      "Bash(echo \"=== PRODUCT EVALUATION ===\" echo \"\" echo \"1. CONFIG HIERARCHY \\(3 levels: Home -> reg -> project\\)\" curl -s http://localhost:3333/api/configs)",
+      "Bash(jq -r \".[] | \"\"   Level: \\\\\\(.label\\) -> MCPs: \\\\\\(.config.include | join\\(\"\", \"\"\\)\\)\"\"\" echo echo '2. AGGREGATED MCPs \\(should show 5 total from all levels\\)' curl -s http://localhost:3333/api/configs curl -s http://localhost:3333/api/registry node -e \"\nconst c = require\\(\"\"/tmp/c.json\"\"\\), r = require\\(\"\"/tmp/r.json\"\"\\);\nconst mcps = new Map\\(\\);\nc.forEach\\(cfg => {\n  \\(cfg.config.include||[]\\).forEach\\(n => mcps.has\\(n\\) || mcps.set\\(n, {name:n, type:\"\"registry\"\", from:cfg.label}\\)\\);\n  Object.keys\\(cfg.config.mcpServers||{}\\).forEach\\(n => mcps.has\\(n\\) || mcps.set\\(n, {name:n, type:\"\"custom\"\", from:cfg.label}\\)\\);\n}\\);\nconsole.log\\(\"\"   Total:\"\", mcps.size, \"\"MCPs\"\"\\);\n[...mcps.values\\(\\)].forEach\\(m => console.log\\(\"\"   -\"\", m.name, \"\"\\(\"\"+m.type+\"\"\\) from\"\", m.from\\)\\);\n\" echo echo '3. RULES' curl -s http://localhost:3333/api/rules)",
+      "Bash(jq -r '.success' echo \"\" echo \"5. VERIFY: Config updated\" curl -s http://localhost:3333/api/configs)",
+      "Bash(jq '[.[] | \\(\\(.config.include | length\\) + \\(.config.mcpServers | keys | length\\)\\)] | add' __NEW_LINE_d4c713bb8c5792e3__ echo \"\" echo \"Actual unique MCPs:\" curl -s http://localhost:3333/api/configs)",
+      "Bash(jq '[.[].config.include[], \\(.[].config.mcpServers | keys[]\\)] | unique | length' __NEW_LINE_d4c713bb8c5792e3__ echo \"\" echo \"Registry has total MCPs:\" curl -s http://localhost:3333/api/registry)",
+      "Bash(jq \".[] | {dir: .dir, include: .config.include}\" echo echo '=== Generated .mcp.json \\(should have ALL including inherited\\) ===' curl -s -X POST http://localhost:3333/api/apply -H 'Content-Type: application/json' -d {} cat /Users/ruze/reg/my/project-config-system/.mcp.json)",
+      "Bash(find:*)",
+      "Bash(npm ls:*)",
+      "Bash(lsof:*)",
+      "Bash(xargs kill -9)",
+      "Bash(npm rebuild:*)",
+      "Bash(echo:*)",
+      "Bash(node -e:*)",
+      "Bash(npm view:*)",
+      "Bash(npm pack:*)",
+      "Bash(node cli.js:*)",
+      "Bash(git init:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git remote add:*)",
+      "Bash(git push:*)",
+      "Bash(cat:*)",
+      "Bash(head:*)",
+      "Bash(gh repo:*)",
+      "Bash(gh label:*)",
+      "Bash(git rm -r --cached \"src/stratum/__pycache__\" \"src/stratum/exporters/__pycache__\" \"tests/__pycache__\" 2>&1 && git add .gitignore && git commit -m \"Add .gitignore, remove cached pycache files\" 2>1&)"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "filesystem",
+    "memory",
+    "fetch"
+  ]
+}

stratum_py-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+docs/

stratum_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+**MCP server (Track 2) — `stratum-mcp`**
+
+- `stratum_validate` — validates a `.stratum.yaml` IR spec; returns `{valid, errors}`
+- `stratum_plan` — validates a spec, creates in-memory flow execution state, returns the first step to execute with resolved inputs and output contract details
+- `stratum_step_done` — accepts a completed step result from Claude Code, checks `ensure` postconditions, returns next step or flow completion; handles retries and exhaustion
+- `stratum_audit` — returns per-step execution trace (attempts, duration) for an active or completed flow
+- MCP controller model: Claude Code is the executor; the server manages plan state and enforces contracts — no sub-LLM calls, no separate API billing
+- `FlowState` — in-memory execution state per flow: ordered steps, accumulated outputs, attempt counts, dispatch timestamps, step records
+- `ensure` expressions evaluated by the server against Claude Code's reported output (Python expressions, dunder-blocked, SimpleNamespace-wrapped for dict access)
+- `$.input.<field>` and `$.steps.<id>.output[.<field>]` reference resolution for chaining step outputs
+- Kahn's topological sort on explicit `depends_on` + implicit `$.steps.*` ref dependencies
+- `stratum-mcp setup` — one-command project configuration: writes `.claude/mcp.json` (MCP server registration), appends execution model block to `CLAUDE.md`, and installs seven Claude Code skills to `~/.claude/skills/`; idempotent, finds project root via `.git` or `CLAUDE.md`
+- Seven Claude Code skills installed by `setup`: `stratum-review` (three-pass code review), `stratum-feature` (read → design → implement → test), `stratum-debug` (hypothesis formation and elimination), `stratum-refactor` (extraction order planning, no broken intermediate states), `stratum-migrate` (rewrite bare LLM calls as `@infer` + `@contract`), `stratum-test` (write test suite for existing code — golden flows, error-path harness), `stratum-learn` (extract patterns from session transcripts into `MEMORY.md`)
+- Each skill contains a spec template Claude adapts internally — YAML never shown to the user; Claude narrates in plain English
+- All skills include a `## Memory` section: read project `MEMORY.md` before writing spec (incorporate `[stratum-<skill>]` tagged patterns); write new patterns after `stratum_audit`
+- CLI triple-mode: `stratum-mcp setup`, `stratum-mcp validate <file>`, stdio MCP transport
+- 66 passing tests across contracts, invariants, and integration suites
+
+**Dependencies:** `mcp>=1.0`, `jsonschema>=4.20`, `pyyaml>=6.0` — no stratum library dependency
+
+### Architecture decision
+
+The MCP server does not use the Track 1 stratum library at runtime. Executing infer steps via the library (litellm) would spawn separate billed API calls outside the Claude Code subscription. The MCP controller model keeps all execution inside the running Claude Code session: Claude Code writes the spec, reports step results, and the server tracks state and enforces contracts.
+
+---
+
+## [0.1.0] — 2026-02-23
+
+### Added
+
+**Core library (Track 1)**
+
+- `@contract` — registers a pydantic `BaseModel` subclass as a typed contract; generates JSON Schema via `model_json_schema()`, stores a 12-char content hash for drift detection
+- `@infer` — LLM-backed inference step; async-first, typed return, structured retry on `ensure` failure, budget enforcement, session cache, OTLP trace records
+- `@compute` — deterministic step marker; function executes normally, composes identically with `@infer` at call sites
+- `@flow` — async flow wrapper; injects `flow_id` + `Budget` clone into a `ContextVar` so nested `@infer` calls inherit them without explicit passing; session cache scoped per flow execution
+- `@refine` — convergence loop stacked on `@infer`; iterates with feedback context until `until(result)` passes or `max_iterations` exhausted → `ConvergenceFailure`
+- `parallel(require=)` — `"all"` / `"any"` / N / `0` modes using `asyncio.TaskGroup`; `require=0` returns `list[Success | Failure]`
+- `race()` — alias for `parallel(require="any")`
+- `debate()` — multi-agent structured argumentation with rebuttal rounds and a synthesizer step
+- `await_human()` — HITL gate; suspends flow until a `ReviewSink` resolves a `PendingReview`; supports `timeout` and `on_timeout`
+- `quorum=` on `@infer` — runs N parallel calls, asserts `threshold` agreement on `agree_on` field, returns highest-confidence agreeing result
+- `stable=False` on `@infer` — return type becomes `Probabilistic[T]`; caller must call `.most_likely()`, `.sample()`, or `.assert_stable()`
+- `stable=True` test mode — when `stratum.configure(test_mode=True)` is set, samples `sample_n` times and raises `StabilityAssertionError` if outputs are not unanimous
+- `Probabilistic[T]` — wraps a sample of LLM outputs; `.most_likely()`, `.sample()`, `.assert_stable(threshold)`
+- `Budget(ms=, usd=, tokens=)` — time + cost + token envelope; enforced via `asyncio.timeout` and LiteLLM cost tracking
+- OTLP trace export — built-in emitter posts spans over HTTP/JSON to any OTLP endpoint; no OTel SDK dependency; `traceId` derived from `flow_id` so all `@infer` spans in a flow share a trace
+- `opaque[T]` annotation — marks fields excluded from the tool-call schema (present in output but not constrained)
+
+**Exceptions**
+
+- `StratumCompileError` — static violations at decoration time
+- `PreconditionFailed` — `given` condition false before LLM call
+- `PostconditionFailed` — `ensure` violations after all retries
+- `ParseFailure` — LLM output cannot be parsed against contract schema
+- `BudgetExceeded` — time or cost budget exceeded
+- `ConvergenceFailure` — `@refine` exhausted `max_iterations`
+- `ConsensusFailure` — `quorum` could not reach `threshold` agreement
+- `ParallelValidationFailed` — `parallel` `validate` callback returned False
+- `HITLTimeoutError` — `await_human` wall-clock timeout with `on_timeout="raise"`
+- `StabilityAssertionError` — `Probabilistic[T].assert_stable()` below threshold
+
+### Dependencies
+
+- `litellm>=1.0` — LLM client, multi-model routing, cost tracking
+- `pydantic>=2.0` — required; `@contract` requires `BaseModel`
+- Python 3.11+ — `asyncio.TaskGroup`, `asyncio.timeout`

stratum_py-0.1.0/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Status
+
+Design phase. Nothing is implemented. All files under `docs/` are design notes produced through an extended design session. The implementation has not started.
+
+## What This Project Is
+
+Stratum is a Python (and TypeScript) library where `@infer` and `@compute` functions compose identically, typed contracts flow between steps, and orchestration is always deterministic regardless of what's inside individual steps. The `.stratum.yaml` IR is what the library emits internally — developers never write it.
+
+Two deployment tracks:
+- **Track 1 — Python library**: `@infer`, `@contract`, `@flow` decorators. One required dependency (`litellm`). Python 3.11+.
+- **Track 2 — Claude Code + MCP**: Stratum as an execution runtime behind Claude Code. Two audiences: professional developers (see typed plans) and vibe coders (see plain-language summaries, get `@infer`-annotated code as output).
+
+## Doc Structure
+
+```
+docs/library/       — Python library design (the primary product)
+docs/claude-code/   — MCP server + Claude Code integration (Track 2)
+docs/strategy/      — competitive analysis, go-to-market, implementation path
+```
+
+**Start here for implementation:**
+- `docs/library/how-to-build.md` — project structure, executor.py, compiler.py, build sequence
+- `docs/library/language-design.md` — semantic model: what `@infer`, `@contract`, `@flow` mean
+- `docs/library/execution-model.md` — the full execution loop, async model, LLM client config, OTel
+
+**Key design decisions recorded in:**
+- `docs/library/open-problems.md` — all 16 design problems with resolution status
+- `docs/library/type-system.md` — contracts, `Probabilistic[T]`, content hash
+- `docs/library/concurrency-and-agents.md` — `parallel`, `debate`, isolation model, Ray upgrade path
+
+## Architecture Decisions
+
+**Contracts**: `@contract` works on plain annotated Python classes. Pydantic `BaseModel` is an optional enhanced backend — not required. Stratum generates JSON Schema from `typing.get_type_hints()` internally.
+
+**Async**: runtime is async-first. `@infer` and `@flow` are async natively. Sync shim via `stratum.run()`. Uses `asyncio.TaskGroup` (Python 3.11+) for `parallel`, `asyncio.timeout` for budget enforcement.
+
+**LLM routing**: LiteLLM is the required LLM client substrate — handles multi-model routing, fallback, cost tracking. The `model:` annotation is a hint passed through to LiteLLM.
+
+**Observability**: internal trace records always written in-memory. OTLP export via a built-in emitter (`stratum/exporters/otlp.py`) — HTTP/JSON POST to any OTLP endpoint. No OTel SDK dependency.
+
+**Non-determinism**: `stable=True` (default) → return type is `T`. `stable=False` → return type is `Probabilistic[T]`, caller must unwrap via `.most_likely()`, `.sample()`, or `.assert_stable()`.
+
+**Prompt optimization**: v1 uses a deterministic prompt compiler (intent + context + inputs). DSPy-backed optimization is a Phase 3 integration for teams with labeled data.
+
+## v1 Dependencies
+
+```toml
+dependencies = ["litellm>=1.0"]
+requires-python = ">=3.11"
+
+[project.optional-dependencies]
+pydantic = ["pydantic>=2.0"]
+all      = ["stratum[pydantic]"]
+```
+
+jsonschema and pyyaml are MCP-server-only (Phase 2) — not library dependencies.
+
+## Phase 2.5 — Decoration-time Static Analysis (not v1)
+
+Introspection-based checks that run when decorators are applied, requiring no new syntax.
+
+- **`ensure`/`given` field validation**: inspect `LOAD_ATTR` bytecode of lambda/callable against the contract's JSON schema fields. Raise `StratumCompileError` at decoration time if an accessed attribute doesn't exist on the return type.
+- **Sequential independence warning**: walk the `@flow` function's AST at decoration time, identify `await` calls whose arguments have no data dependency on each other, and emit `StratumWarning` suggesting `parallel()`. Optionally auto-rewrite to `parallel()`.
+- **Budget sufficiency warning**: sum `budget.ms` across `@infer` calls visible in the `@flow` AST; warn if the sum exceeds the flow's `budget` envelope.
+
+Implementation note: all three have access to everything they need at decoration time — the decorator already holds the function object, its bytecode, its AST (via `inspect.getsource` + `ast.parse`), and the resolved contract schema.
+
+## Phase 3 Integrations (not v1)
+
+Build from observed pain, not schedule: Temporal (durable execution), Ray (distributed agents), Outlines (self-hosted constrained decoding via LiteLLM → vLLM → Outlines), DSPy (prompt optimization).
+
+## TypeScript Library (Phase 2)
+
+Zod for contracts, `@anthropic-ai/sdk` for LLM calls. Vercel AI SDK is an integration target for Next.js users — not the substrate.
+
+## The IR
+
+`.stratum.yaml` is generated by the library and by Claude (via MCP). Developers never write it. It is LLVM IR — the compiler targets it, nobody writes it from scratch. IR parsing/validation (jsonschema + pyyaml) is a Phase 2 concern, needed for the MCP server.
+
+## Stratum Execution Model
+
+For non-trivial tasks, use Stratum internally:
+1. Write a `.stratum.yaml` spec — never show it to the user
+2. Call `stratum_plan` to validate and get the first step
+3. Narrate progress in plain English as you execute each step
+4. Call `stratum_step_done` after each step — the server checks your work
+5. If a step fails postconditions, fix it silently and retry
+6. Call `stratum_audit` at the end and include the trace in the commit

stratum_py-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: stratum-py
+Version: 0.1.0
+Summary: LLM calls that behave like the rest of your code
+Project-URL: Specification, https://github.com/regression-io/stratum-spec/blob/main/SPEC.md
+Project-URL: Repository, https://github.com/regression-io/stratum
+Requires-Python: >=3.11
+Requires-Dist: litellm>=1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

stratum_py-0.1.0/README.md

@@ -0,0 +1,225 @@
+# Stratum
+
+[![Specification](https://img.shields.io/badge/Specification-SPEC.md-blue)](https://github.com/regression-io/stratum/blob/main/SPEC.md)
+[![PyPI](https://img.shields.io/badge/PyPI-stratum-orange)](https://pypi.org/project/stratum/)
+
+**Stop babysitting your LLM calls.**
+
+Stratum is a Python library where `@infer` (LLM calls) and `@compute` (normal functions) compose identically. Typed contracts flow between steps. The runtime handles retry, budget enforcement, and observability — so you don't have to wire them up yourself.
+
+```python
+@contract
+class SentimentResult(BaseModel):
+    label: Literal["positive", "negative", "neutral"]
+    confidence: float
+    reasoning: str
+
+@infer(
+    intent="Classify the emotional tone of customer feedback",
+    ensure=lambda r: r.confidence > 0.7,
+    budget=Budget(ms=500, usd=0.001),
+    retries=3,
+)
+def classify_sentiment(text: str) -> SentimentResult: ...
+```
+
+If the LLM returns low confidence, it gets told exactly what failed and retries with that context — not a blank replay. If it hits the budget, it stops. Every call produces a structured trace record you can query.
+
+---
+
+## Two Tracks
+
+**Track 1 — Python library** (`stratum`): `@infer`, `@contract`, `@flow` decorators for building production LLM systems. Requires Python 3.11+, `litellm`, `pydantic`.
+
+**Track 2 — Claude Code MCP server** (`stratum-mcp`): Stratum as an execution runtime for Claude Code. Claude writes `.stratum.yaml` specs, the MCP server enforces typed contracts and postconditions, Claude narrates progress in plain English. No sub-LLM calls — all execution stays within the Claude Code session.
+
+---
+
+## Track 2: Claude Code + Stratum
+
+```bash
+pip install "git+https://github.com/regression-io/stratum.git#subdirectory=stratum-mcp"
+stratum-mcp setup
+```
+
+`setup` configures Claude Code in one command: writes `.claude/mcp.json`, appends the execution model block to `CLAUDE.md`, and installs seven skills to `~/.claude/skills/`. Restart Claude Code and it's active.
+
+**Seven skills installed automatically:**
+
+| Skill | What it structures |
+|---|---|
+| `/stratum-review` | Three-pass code review: security → logic → performance → consolidate |
+| `/stratum-feature` | Feature build: read existing patterns → design → implement → tests pass |
+| `/stratum-debug` | Debug: read test → read code → check env → form hypotheses → confirm/rule out → fix |
+| `/stratum-refactor` | File split: analyze → design modules → plan extraction order → extract one at a time |
+| `/stratum-migrate` | Find bare LLM calls and rewrite as `@infer` + `@contract` with typed contracts and postconditions |
+| `/stratum-test` | Write a test suite for existing untested code — golden flows, error-path harness, passing on first report |
+| `/stratum-learn` | Review recent session transcripts — extract retry patterns, write project-specific conclusions to `MEMORY.md` |
+
+Claude writes the `.stratum.yaml` spec internally — you never see it. You see plain English narration and the result. The MCP server enforces postconditions on every step; if a step's output fails a check, Claude fixes it and retries before reporting success.
+
+Each skill reads project-specific patterns from `MEMORY.md` before writing its spec, and writes new patterns after `stratum_audit` — retry reasons, confirmed root causes, extraction order constraints. Run `/stratum-learn` periodically to extract conclusions from recent session transcripts and feed them back into future specs.
+
+**MCP tools exposed:**
+
+| Tool | What it does |
+|---|---|
+| `stratum_validate` | Validate a `.stratum.yaml` spec offline |
+| `stratum_plan` | Validate + create execution state + return first step |
+| `stratum_step_done` | Report a completed step; check postconditions; return next step or completion |
+| `stratum_audit` | Return per-step trace (attempts, duration) for any flow |
+
+---
+
+## Blog
+
+**[Introducing Stratum: LLM Calls That Behave Like the Rest of Your Code](https://github.com/regression-io/stratum/blob/main/blog/introducing-stratum.md)**
+The design rationale — why `@infer` and `@compute` share a type, how structured retry works, and what contracts actually buy you.
+
+**[Stratum as a Claude Code Execution Runtime](https://github.com/regression-io/stratum/blob/main/blog/stratum-in-claude-code.md)**
+Claude Code is a capable agent improvising in a loop. This post is about giving it a formal execution model — typed plans, postcondition enforcement, auditable traces.
+
+**[Building Software with Claude Code + Stratum: A Tutorial](https://github.com/regression-io/stratum/blob/main/blog/claude-code-tutorial.md)**
+Real session transcripts: understanding a codebase, reviewing code, adding features, debugging CI failures, refactoring large files. Claude narrates in plain English throughout.
+
+---
+
+## Why
+
+LLM calls in production share a few recurring failure modes:
+
+- **Retry is brute force.** Most frameworks replay the full prompt on failure. Stratum injects only the specific postcondition that failed.
+- **Budget is an afterthought.** Soft hints don't stop a runaway `refine` loop. Stratum enforces hard limits — `BudgetExceeded` is an exception, not a bill.
+- **Flows are opaque.** When a multi-step pipeline fails, you want to know which step, with what input, after how many retries, at what cost. Stratum traces every call structurally.
+- **LLM steps and regular functions don't compose.** Stratum makes `@infer` and `@compute` indistinguishable by type — swap one for the other and nothing downstream changes.
+- **Agent outputs can hijack downstream agents.** `opaque[T]` fields are passed as structured data, never inlined into instruction text.
+- **Human-in-the-loop is a custom build every time.** `await_human` genuinely suspends execution and returns a typed `HumanDecision[T]`.
+
+---
+
+## Core Concepts
+
+### `@infer` and `@compute` are the same type
+
+```python
+# Phase 1: LLM classifies tickets
+@infer(intent="Route this support ticket", model="groq/llama-3.3-70b-versatile")
+def route_ticket(text: str) -> TicketRoute: ...
+
+# Phase 2: patterns emerged — swap to rules, zero other changes
+@compute
+async def route_ticket(text: str) -> TicketRoute:
+    return TicketRoute(team=keyword_match(text), ...)
+```
+
+These have identical signatures. The `@flow` that calls `route_ticket` doesn't change. This means:
+
+- **Testing:** Replace `@infer` calls with `@compute` stubs for deterministic tests.
+- **Migration:** Start with LLM, replace with rules as patterns emerge. No downstream changes.
+- **Cost control:** Swap expensive inference for fast lookup when coverage allows.
+
+### Contracts are typed boundaries
+
+```python
+@contract
+class SentimentResult(BaseModel):
+    label: Literal["positive", "negative", "neutral"]
+    confidence: Annotated[float, Field(ge=0.0, le=1.0)]
+    reasoning: str
+```
+
+A `@contract` class compiles to JSON Schema injected into the structured outputs API. The LLM's output is validated against it before your code sees it. Every contract carries a content hash — a hash change means the compiled prompt changed and LLM behavior may have drifted.
+
+### Retry is structured
+
+On failure the LLM receives:
+
+```
+Previous attempt failed:
+  - ensure condition 1 failed
+Fix these issues specifically.
+```
+
+Not a full prompt replay. The specific violation, nothing else.
+
+### Flows are deterministic
+
+```python
+@flow(budget=Budget(ms=5000, usd=0.01))
+async def process_ticket(text: str) -> Resolution:
+    sentiment = await classify_sentiment(text=text)
+    response  = await draft_response(text=text, sentiment=sentiment)
+    return response if rule_check(response) else escalate(text)
+```
+
+`@flow` is normal Python control flow. You can read it, test it, and trace it. The orchestration shape is known before any LLM call runs.
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| Structured retry | `ensure` postconditions drive retry with targeted failure feedback |
+| Hard budget limits | Per-call and per-flow — `BudgetExceeded`, not a soft hint |
+| `opaque[T]` | Field-level prompt injection protection |
+| `await_human` | HITL as a first-class typed primitive — genuine suspension |
+| `stratum.parallel` | Concurrent execution with `require: all/any/N/0` semantics |
+| `quorum` | Run N times, require majority agreement |
+| `stratum.debate` | Adversarial multi-agent synthesis with convergence detection |
+| Full observability | Structured trace record on every call, OTLP export built-in |
+| Two dependencies | `litellm` + `pydantic`. No OTel SDK. |
+
+---
+
+## Examples
+
+Working examples in [`examples/`](https://github.com/regression-io/stratum/tree/main/examples):
+
+| File | What it shows |
+|---|---|
+| [`01_sentiment.py`](https://github.com/regression-io/stratum/blob/main/examples/01_sentiment.py) | `@infer` + `@contract` + `@flow` + `@compute` end-to-end |
+| [`02_migrate.py`](https://github.com/regression-io/stratum/blob/main/examples/02_migrate.py) | Migrating `@infer` → `@compute` without changing callers |
+| [`03_parallel.py`](https://github.com/regression-io/stratum/blob/main/examples/03_parallel.py) | Three concurrent `@infer` calls with `parallel(require="all")` |
+| [`04_refine.py`](https://github.com/regression-io/stratum/blob/main/examples/04_refine.py) | `@refine` convergence loop — iterates until quality passes |
+| [`05_debate.py`](https://github.com/regression-io/stratum/blob/main/examples/05_debate.py) | `debate()` — two agents argue, synthesizer resolves |
+| [`06_hitl.py`](https://github.com/regression-io/stratum/blob/main/examples/06_hitl.py) | `await_human` — human-in-the-loop approval gate |
+
+---
+
+## Install
+
+**Track 1 — Python library:**
+```bash
+pip install git+https://github.com/regression-io/stratum.git#egg=stratum-py
+```
+Requires Python 3.11+. Set `GROQ_API_KEY`, `ANTHROPIC_API_KEY`, or any key LiteLLM supports, then specify it in `model=`.
+
+**Track 2 — Claude Code MCP server:**
+```bash
+pip install "git+https://github.com/regression-io/stratum.git#subdirectory=stratum-mcp"
+stratum-mcp setup
+```
+Requires Claude Code. `setup` configures everything — restart Claude Code to activate.
+
+---
+
+## Specification
+
+[`SPEC.md`](https://github.com/regression-io/stratum/blob/main/SPEC.md) is the normative specification covering the full type system, decorator signatures, execution loop, prompt compiler, concurrency semantics, HITL protocol, budget rules, trace record schema, and error types.
+
+---
+
+## Status
+
+**Track 1** (Python library): implemented and tested.
+
+**Track 2** (stratum-mcp): MCP controller server implemented — `stratum_plan`, `stratum_step_done`, `stratum_audit`, `stratum_validate`. One-command setup with seven bundled skills and a memory system for project-specific pattern capture. 66 tests passing.
+
+Questions and feedback: [GitHub Discussions](https://github.com/regression-io/stratum/discussions)
+
+---
+
+## License
+
+[Apache 2.0](https://github.com/regression-io/stratum/blob/main/LICENSE)