Metadata-Version: 2.4
Name: etchplan
Version: 0.1.1
Summary: Compile an AI agent's repeated workflows into deterministic, auditable routines that replay at $0, with a fallback to the agent.
Project-URL: Homepage, https://github.com/Egoist-Machines/etchplan
Project-URL: Source, https://github.com/Egoist-Machines/etchplan
Project-URL: Issues, https://github.com/Egoist-Machines/etchplan/issues
Author: Egoist Machines, Inc.
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-traces,ai-agents,compiler,llm,tool-use,trace-mining
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: typer>=0.12.0
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == 'browser'
Provides-Extra: desktop
Requires-Dist: pyobjc-framework-applicationservices>=10.0; (sys_platform == 'darwin') and extra == 'desktop'
Requires-Dist: pyobjc-framework-cocoa>=10.0; (sys_platform == 'darwin') and extra == 'desktop'
Requires-Dist: pyobjc-framework-quartz>=10.0; (sys_platform == 'darwin') and extra == 'desktop'
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: llm
Requires-Dist: openai>=1.2.0; extra == 'llm'
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; extra == 'mcp'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/etchplan-logo.svg" alt="etchplan logo" width="100">
</p>

<h1 align="center"><em>etchplan</em></h1>

**Your agent solves the same shape of task again and again. _etchplan_ turns the repeatable parts into validated routines that can replay without model calls, with fallback to the agent whenever a guard does not hold.**

*Built by [Egoist Machines, Inc.](https://egoistmachines.com/) - efficient full-stack infrastructure for reliable AI systems.*

_etchplan_ watches local agent traces, mines recurring workflows, and compiles the safe ones into deterministic `ExecutionPlan`s. A routine runs only after validation. If the input drifts, a guard fails, or a tool is unbound, the agent handles the request.

- Zero model calls on a fully compiled replay.
- Guards, static checks, validation, and mutation gates before any served result.
- Local capture for Claude Code, Codex, and opencode; traces write to `~/.etchplan/`.
- Shadow, approval, canary, and drift kill-switch before live serving.
- Append-only audit log for routine decisions, tool calls, and fallbacks.
- CLI, MCP server, and runnable [BYO](examples/byo/README.md), [MCP](examples/mcp/README.md), and [real-API](examples/real_traces/README.md) examples.

## What It Is

**etchplan** removes repeat model calls when a validated tool workflow can replay directly, with the agent still behind the fallback. This is _not_ prompt caching, response caching, observability, or a workflow builder you hand-author. Those are all valid techniques that one can use in combination with etchplan to make model calls cheaper, skip near-duplicates, or help you watch the agent. 

**etchplan** is built for structured tool-call workflows: API/MCP integrations, browser actions, and repeated multi-step work where arguments bind to inputs or earlier tool outputs. Free-text coding churn is mined and usually refused because the arguments are code, shell, or prose instead of stable parameters.

Reference points: [Agent JIT Compilation](https://arxiv.org/abs/2605.21470) and [Agent Workflow Optimization / meta-tools](https://arxiv.org/abs/2601.22037). The comparison notes are in [RELATED_WORK.md](RELATED_WORK.md).

## Install

Apache-2.0, local-first, Python >= 3.11.

```bash
pip install etchplan        # or: uv tool install etchplan, pipx install etchplan
etch demo                   # the whole offline loop: import, mine, compile, validate, run. No agent, no keys.
etch doctor                 # confirm capture wiring and that etch is on your PATH
```

Try it with no install at all: `uvx etchplan demo`. Extras for the parts that need them: `etchplan[mcp]` (MCP server), `etchplan[browser]` (Playwright replay), `etchplan[desktop]` (macOS GUI capture). From source: `git clone https://github.com/Egoist-Machines/etchplan && cd etchplan && uv run etch demo`.

## Use it on your agent

Install capture once and use your agent normally. `etch setup` runs the [Quickstart](#quickstart) discovery loop for you: an auto-pipeline captures, mines, and compiles draft routines on every session and turn end, so you never run those steps by hand.

```bash
uv run etch setup claude-code --write     # also: codex | opencode
# use your agent; sessions capture to ~/.etchplan/ and the auto-pipeline keeps routines fresh

uv run etch report                        # money and time saved, read from the store the pipeline fills
uv run etch report --format html --open
```

That auto-pipeline is Quickstart steps 1-3 (import, mine, compile drafts) on a schedule; `etch report` and `etch yield` just read what it found. `etch doctor` checks that capture is installed and events are flowing. `etch mcp install` registers the MCP server for Claude Code, Claude Desktop, Cursor, Codex, or all supported clients. The full command surface, dry-run behavior, serving modes, and MCP proxy details are in [docs/cli.md](docs/cli.md).

Only serving stays manual, by design (Quickstart steps 4-5): gather agreement with `etch run --shadow`, approve once the evidence clears your bar, then canary an approved routine. Guard failure, missing binding, runtime error, or drift routes back to the agent.

## Example results

Per recurring solve on AppWorld (gpt-5.5), after one agent solve to seed and one compile:

| | agent, every time | _etchplan_ |
|---|--:|--:|
| latency | ~116 s | ~0.2 s (~580x faster) |
| cost | ~$0.47 | $0 (zero model calls) |
| reuse economics | pays full price every time | break-even after ~1.07 reuses; ~9x cheaper by the 10th reuse |

The heavy live-agent harness behind those numbers is not in this repo. The compact benchmark artifacts are, and each number is labeled `measured`, `recorded`, `estimated`, or `assumed`. See [docs/results.md](docs/results.md) and [docs/benchmark-methodology.md](docs/benchmark-methodology.md).

The real-API corpora show the same shape on flows:

| domain | workflow | traces | result |
|---|---|---:|---|
| `weather_brief` | geocode(city) -> forecast -> air_quality | 30 | 3-node, 0 model |
| `ip_weather` | geoip(ip) -> forecast | 18 | 2-node, 0 model |
| `zip_weather` | postal(zip) -> forecast | 18 | 2-node, 0 model |
| `github_repo` | get_repo(slug) -> get_branch | 18 | 2-node, 0 model |
| `word_assoc` | related(word) -> related(top) | 18 | 2-node, 0 model |
| `pokemon` | get_pokemon(name) -> get_ability(url) | 18 | 2-node, 0 model |

All six compile in the local yield check: 120 traces, 6 recurring workflows, 6 compiled. The traces and scope notes are in [examples/real_traces](examples/real_traces/README.md).

## Quickstart

The real flow finds the workflows an agent repeats, compiles and validates the safe ones, then serves them behind the agent. Steps 1-3 run as-is on a real public-API corpus shipped in the repo; steps 4-5 bind your own tools and earn a routine the right to serve live.

**1. Get traces.** The traces can be your agent's (`etch setup <harness> --write` captures sessions to `~/.etchplan/`, see above). To run every step now, import a shipped real-API corpus into the same store:

```bash
db=.etchplan.sqlite
uv run etch import jsonl examples/real_traces/weather_brief/traces.jsonl --db $db
```

**2. See what recurs and compiles.** `etch yield` mines the recurring workflows and reports which compile and why the rest refuse. It measures only, it never serves:

```bash
uv run etch yield --db $db --min-support 5
#  recurring: 1  ->  compiled: 1   (weather_brief: geocode -> forecast -> air_quality, 0 model calls)
```

On captured agent traces, `etch report` turns the same store into money and time saved.

**3. Compile and validate a routine.** `--pattern-id top` takes the highest-support pattern that compiles; validation executes the routine over trace-derived cases (measured, not estimated):

```bash
uv run etch compile pattern --db $db --pattern-id top --out weather_brief.yaml
uv run etch validate plan weather_brief.yaml --db $db
```

**4. Run it behind your tools, with the agent as fallback.** `--registry` binds the plan's tool names to your callables; any guard failure, unbound tool, or runtime error routes to `--fallback`, and every call lands in the audit log:

```bash
uv run etch run weather_brief.yaml --input in.json \
  --registry your_tools:registry --fallback your_tools:agent --audit audit.jsonl
```

Runnable end to end with real bindings in [examples/byo](examples/byo/README.md) (plain callables) and [examples/mcp](examples/mcp/README.md) (MCP tools plus a policy-gated live mutation).

**5. Earn trust before serving live.** Nothing serves on day one. Accumulate agreement in shadow, approve once the evidence clears your bar, then canary in; the drift kill-switch pulls a routine whose fallback rate climbs:

```bash
uv run etch run weather_brief.yaml --input in.json --registry your_tools:registry --shadow   # serves the agent, records match/mismatch
uv run etch plans approve weather_brief.yaml --min-matches 20 --max-mismatch-rate 0.0
uv run etch run weather_brief.yaml --input in.json --registry your_tools:registry --require-approval --canary --canary-pct 10
```

Just want to watch the loop once? `uv run etch demo` runs all of it offline on a bundled example, no agent and no keys.

## How It Works

```
agent traces
    |
    v
 normalize      clean, redact, slot
    |
    v
   mine         find repeats, verify parameter flow, learn guards
    |
    v
  compile       synthesize a guarded ExecutionPlan
    |
    v
  validate      execute on trace-derived replay cases
    |
    v
   run ------>  guards hold: replay with zero model calls
    |
    +  ------>  guard fails: fall back to the agent
```

The trust loop is `draft -> shadow -> approved -> canary -> served`. Mutating steps stay behind idempotency and mutation gates, and a routine that fails validation is never run. The package map, guard implementation notes, and deeper diagrams are in [docs/architecture.md](docs/architecture.md) and [docs/security-model.md](docs/security-model.md).

## Workload Fit

| Workload | Fit | Why |
|---|---|---|
| Repeated API / MCP tool workflows | Excellent | bindable arguments, data flow between steps, learnable guards |
| Browser / desktop action loops | Preview | semantic actions can replay behind the same trust loop |
| Coding-agent edit loops | Refuses by design | free-text step arguments do not bind to deterministic routines |
| One-off tasks | No | one seed solve plus one compile does not amortize |

For natural compile-yield checks on your own traces, see [docs/measuring-yield.md](docs/measuring-yield.md). Active forward edges are tracked in [docs/roadmap.md](docs/roadmap.md).

## Docs

- Results: [docs/results.md](docs/results.md), [docs/benchmark-methodology.md](docs/benchmark-methodology.md)
- Build/run: [docs/cli.md](docs/cli.md), [docs/architecture.md](docs/architecture.md), [docs/security-model.md](docs/security-model.md)
- Project: [docs/development.md](docs/development.md), [docs/roadmap.md](docs/roadmap.md), [RELATED_WORK.md](RELATED_WORK.md), [CHANGELOG.md](CHANGELOG.md), [CITATION.cff](CITATION.cff)

## License & Security

Apache-2.0, see [LICENSE](LICENSE) and [NOTICE](NOTICE). The open-source code is free to use, including commercially; the "Etchplan" name and logo are trademarks ([TRADEMARKS.md](TRADEMARKS.md)), and Apache-2.0 grants no trademark rights. _etchplan_ is local-first: nothing leaves your machine by default.

Enterprise licensing and commercial support are available from [Egoist Machines, Inc.](https://egoistmachines.com/): hosted/managed serving, SSO/RBAC, a multi-tenant plan registry, and on-prem / BYOC deployment. Contact [sales@egoistmachines.com](mailto:sales@egoistmachines.com).

PRs welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) (commits need a DCO sign-off: `git commit -s`). Report security issues privately per [SECURITY.md](SECURITY.md), not in public issues. Other bugs and feature requests go to the [issue tracker](https://github.com/Egoist-Machines/etchplan/issues).
