heap-ai 0.1.0a0

A Python harness for AI agents. Spec-driven, approval-gated, MCP-native.

HEAP

Harness for Execution, Approvals & Plans. A Python harness for AI agents. Spec-driven, approval-gated, MCP-native. Model-agnostic via LiteLLM.

Status: v0.1 alpha. APIs are unstable. Not yet on PyPI; install from source. 331 tests, MIT-licensed, Brazilian-led OSS.

---

What is HEAP?

HEAP wraps any LLM with a spec-driven, approval-gated lifecycle:

spec  →  test scenarios  →  plan  →  run  →  verify
        ↑               ↑       ↑       ↑
   human-approved   human-approved   gate   gate

You write a spec. HEAP turns it into scenarios you approve, a plan you approve, and then runs it phase-by-phase, halting at every sprint gate for explicit human approval. State persists on every transition so a crashed run resumes cleanly. Auto-retry catches a single flaky phase; harder failures escalate.

The model never silently expands scope, never modifies the spec, and never skips a gate. The thesis: in 2026 model performance has stabilized; differentiation comes from the harness layer that wraps the model. HEAP is that layer — and it's designed to be deleted as models improve.

---

Quick start

git clone https://github.com/vicente-r-junior/heap-ai
cd heap-ai
make install                      # creates .venv + editable install
cp .env.example .env              # add your ANTHROPIC_API_KEY
.venv/bin/heap --help

Sanity check:

.venv/bin/python examples/hello_gateway.py   # one Anthropic call, prints cost
make test                                    # 331 tests

The full HEAP loop, against a real bug:

.venv/bin/heap spec new --mode bug --audience developer --name csv-bom
.venv/bin/heap scenarios generate csv-bom
.venv/bin/heap scenarios review csv-bom
.venv/bin/heap plan generate csv-bom
.venv/bin/heap plan show csv-bom
.venv/bin/heap plan approve csv-bom --by you
.venv/bin/heap run start csv-bom
# in another terminal:
.venv/bin/heap watch <run-id>
.venv/bin/heap status

---

Examples

Example	What it shows
examples/hello_gateway.py	Layer 1 — one Anthropic call through the gateway, with cost reporting
examples/weather_agent.py	Layer 4 — Agent class with PEV loop, hooks firing, a @tool executing
examples/csv-bom/	End-to-end smoke — drive the entire HEAP loop on a real UTF-8 BOM bug

The csv-bom example is the canonical walkthrough. Its deterministic counterpart drives the full chain offline through real HEAP modules and proves the example's tests go red → green when an executor applies the fix.

---

Architecture (v0.1)

Layer	Status	What
L5 Orchestration	v0.2+	Multi-agent patterns, A2A protocol
L4 Agent Runtime	v0.1	PEV loop, hooks (Block/Warn/Retry/Continue), contracts
L3 Capability	v0.1	@tool decorator, skills, MCP client
L2 Safety	v0.2+	Sandbox, policy engine, lethal-trifecta detection
L1 Model Gateway	v0.1	LiteLLM wrapper, role routing, cost, budget, fallback

Cross-cutting modules in v0.1: spec/ (interactive interrogator with three modes), scenarios.py (generation + gap detection + bidirectional spec amendment), plan.py (§10 ASCII renderer + estimate/risk heuristics + amendment audit log), run.py (state machine + persistence + §9.3 retry), status.py / watch.py (live observability), cli.py (the heap command).

---

CLI surface

heap spec       new / show / list / amend
heap scenarios  generate / show / review
heap plan       generate / show / list / amend / approve
heap run        start / resume / approve / show / list
heap status     [name]
heap watch      <run-id>

Every command persists artifacts to specs/ and .heap/runs/<run_id>/. State is durable across crashes; heap run resume <id> picks up at the last persisted phase boundary.

---

Models

Defaults are the reasoning sandwich pattern: heavy reasoning at the edges, fast generation in the middle.

Role	Default	Used for
planner	anthropic/claude-opus-4-7	Plan generation, verification, spec interrogation, code review
worker	anthropic/claude-sonnet-4-6	Code generation, file writes, routine execution
fast	anthropic/claude-haiku-4-5-20251001	Cheap classification, log parsing, routing

Override via HEAP_PLANNER_MODEL, HEAP_WORKER_MODEL, HEAP_FAST_MODEL env vars. Any LiteLLM-supported model works (OpenAI, Groq, Ollama, etc.). Fallback chain on errors is configurable.

---

Roadmap

• v0.1 (this) — Gateway, agent runtime, spec/scenarios/plan/run end-to-end, three runnable examples, deterministic smoke against a real bug.
• v0.2+ — L2 sandbox/policy, L5 multi-agent orchestration, headless mode (VPS, async, WhatsApp/Slack), knowledge connectors, web dashboard, drift detection in CI, auto-graduation of memory tiers.

---

Contributing

See CONTRIBUTING.md. Issues and pull requests welcome. HEAP is intentionally small in v0.1 (~5k LOC of source); contributions that keep that property are easier to land.

License

MIT — see LICENSE.

Author

Vicente Rosa Junior — built in the open as Brazilian-led OSS.