Metadata-Version: 2.4
Name: taprun
Version: 0.15.14
Summary: Compile your AI agent's browser-acting trajectory into a deterministic program that replays at zero LLM tokens. CLI + Python SDK.
Author-email: Leon Ting <leonting1010@gmail.com>
License: MIT
Project-URL: Homepage, https://taprun.dev
Project-URL: Documentation, https://taprun.dev/docs
Project-URL: Repository, https://github.com/LeonTing1010/tap
Project-URL: Issues, https://github.com/LeonTing1010/tap/issues
Keywords: ai-agent,browser-automation,web-scraping,mcp,claude,cursor,browser-use,stagehand,deterministic,trajectory-compile
Classifier: Development Status :: 4 - Beta
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# taprun

<!-- mcp-name: io.github.LeonTing1010/tap -->

Compile your AI agent's browser-acting trajectory into a deterministic
program that replays at **zero LLM tokens**, with built-in drift
verification.

```bash
pip install taprun
```

After install you get **two surfaces in one package**:

## 1 · CLI

The `tap` command. First invocation downloads the platform binary from
the npm `@taprun/cli-*` packages; subsequent calls exec the cached
binary. Equivalent to `brew install LeonTing1010/tap/taprun` for Python
users on Linux/Windows where Homebrew isn't standard.

```bash
tap forge https://news.ycombinator.com/        # compile a tap (Tier 0, no AI)
tap run hackernews/top                         # zero LLM tokens
tap doctor hackernews/top                      # cross-validate vs authoritative
tap mcp start                                  # MCP server for Claude Code / Cursor / Cline
```

## 2 · Python SDK

`from taprun import forge, run, doctor`. Each call shells out to the
same `tap` CLI; ~30-100 ms warm spawn cost. For hot loops use
`tap mcp start` and call via MCP instead.

```python
from taprun import run, doctor

rows = run("hackernews/top")              # execute a compiled tap
print(rows[0]["title"])

verdict = doctor("hackernews/top")        # 'ok' / 'broken' / 'stale'
```

### Compile from a browser-use trajectory

```python
from browser_use import Agent
from taprun import forge

agent = Agent(task="...", llm=...)
result = await agent.run()

forge(
    trajectory=result.model_dump(),       # AgentHistoryList dict, JSON string, or path
    site="example",
    name="dashboard",
)
# writes ~/.tap/taps/example/dashboard.tap.json
# replay with: tap run example/dashboard
```

v1 trajectory compile covers the navigation skeleton (`go_to_url`,
`click_element`, `input_text`, `scroll`, `wait`, `done`). Navigation
steps replay at 0 LLM tokens. For destination pages exposing a Tier 0
source (RSS / JSON-LD / agents.json / OpenAPI), pair with `tap forge
<url>` to compile the extraction half — that combination delivers
end-to-end zero-token replay. Stagehand and raw Anthropic tool-use
formats land in a follow-up.

## How it works

1. **Forge**: inspect the site → compile a deterministic `.tap.json`
   plan (one-time cost; free for pages with a Layer 1 source).
2. **Run**: replay the plan, no LLM in the loop.
3. **Doctor**: independently fetch the authoritative source and diff.
   Catches drift the agent would miss on a self-replay.
4. **Heal**: cached patches replay at 0 tokens; LLM only invoked when
   the patch cache misses (Pro tier).

## Configuration

```bash
# Override the binary path (e.g. to use a brew-installed `tap`)
export TAPRUN_BIN=/opt/homebrew/bin/tap

# AI key for the forge pipeline (BYOK; Hacker tier and above)
tap config set ai.key sk-ant-...
```

## Pricing

- **Free**: 65+ community taps, run, doctor, Tier 0 forge (the
  deterministic compile path when Layer 1 is available).
- **Hacker ($9/mo, BYOK)**: full forge pipeline with Layer 4 AI fallback.
- **Pro ($29/mo)**: heal + refresh + scheduling. 100% local.

The MCP server / CLI / forge / doctor binary is closed-source. The
public Chrome extension runtime
(<https://github.com/LeonTing1010/tap>) is MIT.

## Links

- Homepage: <https://taprun.dev/?utm_source=pypi&utm_medium=package&utm_campaign=taprun>
- Docs: <https://taprun.dev/docs?utm_source=pypi&utm_medium=package&utm_campaign=taprun-docs>
- Issues: <https://github.com/LeonTing1010/tap/issues>
- Skills: <https://github.com/LeonTing1010/tap-skills>

MIT License (the public extension; the `tap` binary distributed by this
package is proprietary).
