Metadata-Version: 2.4
Name: heap-ai
Version: 0.1.0a0
Summary: A Python harness for AI agents. Spec-driven, approval-gated, MCP-native.
Project-URL: Homepage, https://github.com/vicente-r-junior/heap-ai
Project-URL: Repository, https://github.com/vicente-r-junior/heap-ai
Project-URL: Issues, https://github.com/vicente-r-junior/heap-ai/issues
Author-email: Vicente Rosa Junior <vicenteaff@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,approval-gated,harness,litellm,llm,mcp,spec-driven
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click<9.0,>=8.1
Requires-Dist: litellm<2.0,>=1.50
Requires-Dist: mcp<2.0,>=0.9
Requires-Dist: pydantic<3.0,>=2.6
Requires-Dist: python-dotenv<2.0,>=1.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<14.0,>=13.7
Provides-Extra: dev
Requires-Dist: ruff<1.0,>=0.4; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio<2.0,>=0.23; extra == 'test'
Requires-Dist: pytest-cov<6.0,>=4.1; extra == 'test'
Requires-Dist: pytest<9.0,>=7.4; extra == 'test'
Description-Content-Type: text/markdown

# HEAP

**Harness for Execution, Approvals & Plans.** A Python harness for AI agents.
Spec-driven, approval-gated, MCP-native. Model-agnostic via [LiteLLM][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.

[litellm]: https://github.com/BerriAI/litellm

---

## Quick start

```bash
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:

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

The full HEAP loop, against a real bug:

```bash
.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`](examples/hello_gateway.py) | Layer 1 — one Anthropic call through the gateway, with cost reporting |
| [`examples/weather_agent.py`](examples/weather_agent.py) | Layer 4 — `Agent` class with PEV loop, hooks firing, a `@tool` executing |
| [`examples/csv-bom/`](examples/csv-bom/README.md) | 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](tests/test_s7_smoke.py) 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](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](LICENSE).

## Author

[Vicente Rosa Junior](https://github.com/vicente-r-junior) — built in
the open as Brazilian-led OSS.
