Sinew

A model-agnostic cognitive harness: any muscle, same sinew.

Sinew wraps any base LLM in the structural behaviors that make frontier agentic models effective — deep verification loops, long-horizon planning, automated self-correction, and persistent state — implemented outside the model, in a deterministic kernel the model cannot corrupt.

The model proposes. The kernel disposes.

pip: zero dependencies (core) · Python 3.10+ · state: SQLite + files

The idea in four sentences

1. The context window is a render target, not a log. Every turn, a context compiler renders a fresh, budgeted view of externalized state; the model holds no hidden conversational memory, so context is bounded by construction and every call is fresh-context.
2. Claims are quarantined until bound to evidence. Model assertions never become load-bearing facts without a mechanical receipt (exit code, file hash, tool output) — this kills compounding hallucination, the dominant failure mode of weak-model agents.
3. Plans are falsifiable data. Every task node carries machine-checkable acceptance criteria and only completes through a fail-closed verification gate: mechanical checks first, adversarial fresh-context LLM judge last.
4. Failure is a typed signal. The kernel classifies failures, detects loops by action-fingerprint, enforces budgets, and can escalate a stuck node to a stronger model tier — cost-tiered cognition.

Quickstart

No install needed from this directory (pip install -e . optional). On locked-down Windows machines use the module form — it is first-class:

# 1. Offline demo — no API keys, no network. A scripted "model" lies once,
#    ships a bug, gets caught by the gate, fixes it, and finishes verified:
python -m sinew demo

# 2. Real run on a local model (Ollama, vLLM, LM Studio — anything
#    OpenAI-compatible):
python -m sinew run \
  --driver openai-compat --base-url http://localhost:11434/v1 --model llama3.1 \
  --workspace ./myproj \
  --goal "Implement fizzbuzz in fizzbuzz.py with tests in test_fizzbuzz.py" \
  --accept-cmd "python -m unittest test_fizzbuzz -v"

# 3. Real run on Claude (pip install anthropic; auth via ANTHROPIC_API_KEY
#    or `ant auth login`):
python -m sinew run --driver anthropic \
  --workspace ./myproj \
  --goal "..." --accept-cmd "python -m unittest"

# Kill the process at any point; state survives in <workspace>/.sinew:
python -m sinew resume --driver anthropic --workspace ./myproj
python -m sinew status --workspace ./myproj

# Measure a model's protocol fidelity (calibrates repair patience):
python -m sinew probe --driver openai-compat --base-url ... --model ...

Mixed fleets are the intended shape — cheap local model as the generator, a stronger model only where it pays:

python -m sinew run --driver openai-compat --base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:7b \
  --escalation-model qwen2.5-coder:32b \
  --verifier-model llama3.1:70b \
  --goal "..." --accept-cmd "..."

How a turn works (Propose–Verify–Commit)

            ┌────────────────────────────────────────────────┐
            │                    KERNEL                      │
            │  (deterministic; owns all control flow)        │
            │                                                │
 Ledger ───►│ 1. frontier()  — pick the next workable node   │
 (SQLite,   │ 2. render()    — compile budgeted context      │──► Driver
  append-   │ 3. parse()     — raw text → typed Action       │◄── (any LLM,
  only)  ◄──│ 4. dispatch()  — plan / do / claim / conclude  │    stateless)
            │ 5. gate()      — mechanical checks, judge      │
            │ 6. policy()    — loops, budgets, escalation    │
            └────────────────────────────────────────────────┘

• plan — decompose the current node; every child must carry at least one falsifiable check or the kernel rejects the plan.
• do — touch the world through allowlisted, workspace-rooted tools; results are recorded as evidence with provenance.
• claim — assert a fact citing evidence ids; uncited claims are rendered to all future turns as UNVERIFIED … treat as rumors.
• conclude — request completion; the kernel runs the node's acceptance checks. Pass → the summary becomes a verified fact. Fail → a failure brief (the diff of failure, not the failed reasoning — anti-anchoring) is rendered on the next attempt.

Every transition is one append to the ledger. kill -9 at any boundary and resume re-folds to the identical state.

What lives where

sinew/kernel.py	the Propose–Verify–Commit control loop
sinew/state.py	append-only ledger, task tree, claims, evidence, fold
sinew/context.py	the context compiler (render target, not a log)
sinew/verify.py	fail-closed gate: cmd / file checks + adversarial judge
sinew/policy.py	failure classes, loop detection, budgets, escalation
sinew/protocol.py	one-action-per-turn protocol + bounded repair loop
sinew/tools.py	fs + allowlisted shell, everything becomes evidence
sinew/drivers/	mock / OpenAI-compatible / Anthropic; stateless per turn
tests/	40 tests — the executable spec of the guarantees

Run the suite: python -m unittest discover -v

Project documents

Document	Role
docs/BLUEPRINT.md	Strategy: mission, falsifiable bets, phase arc, 1.0 success criteria, non-goals
docs/PRD.md	Requirements: numbered, testable, prioritized, with live status
docs/SDP.md	Development plan: milestones M0–M5 with falsifiable exits, process rules, risk register
docs/TEST_QA_PLAN.md	Quality: guarantee coverage map, test taxonomy, the eval instrument, release gates
docs/DECISIONS.md	ADR log D-001…D-012; settled decisions and how to supersede them
docs/GLOSSARY.md	Shared vocabulary
ARCHITECTURE.md	Design rationale and roadmap narrative
CHANGELOG.md	Release history
PROJECT_EXPLAINED.md	Plain-language explainer of the whole project for non-technical readers
SINEW_ATLAS.html	Self-contained visual atlas — diagrams of the idea, the machine, the docs, and the roadmap (open in a browser)

Traceability: Blueprint bet → milestone → PRD requirement → QA guarantee → metric → threshold. The PRD status column is the source of truth for what is real.

Honest status

v0. The guarantees that are tested and real: claim quarantine, fail-closed gating, mechanical-first verification, loop suppression, budget blocking, driver escalation, protocol repair for weak models, and kill-anywhere resumability. What it is not yet: parallel branch exploration, semantic memory recall, a sandbox that resists a malicious model (the allowlist and path guards contain accidents; run untrusted workloads in a VM). See ARCHITECTURE.md for the full design rationale and roadmap.