taprun 0.14.0__py3-none-any.whl

taprun/__init__.py

@@ -0,0 +1,59 @@
+"""Taprun — compile your AI agent's browser-acting trajectory into a
+deterministic program that replays at zero LLM tokens.
+
+Two surfaces in one package:
+
+1. **CLI**. After `pip install taprun` the `tap` command becomes
+   available; first invocation downloads the platform binary from npm
+   and exec's it. Equivalent to `brew install LeonTing1010/tap/tap` for
+   Python users on Linux/Windows where Homebrew isn't standard.
+
+2. **SDK**. `from taprun import forge, run, doctor` shells out to the
+   same `tap` CLI. Each call is one process spawn (~30-100 ms warm);
+   for hot loops use `tap mcp start` and call via MCP.
+
+Quick start
+-----------
+
+>>> from taprun import run, doctor
+>>> rows = run("hn/top")              # execute a Tap-compiled plan
+>>> verdict = doctor("hn/top")        # cross-validate vs authoritative
+
+>>> from browser_use import Agent
+>>> from taprun import forge
+>>> agent = Agent(task="...", llm=...)
+>>> result = await agent.run()
+>>> forge(trajectory=result.model_dump(),
+...       site="example", name="dashboard")
+
+See: https://taprun.dev/docs
+"""
+
+from __future__ import annotations
+
+from .api import (
+    forge,
+    run,
+    doctor,
+    verify,
+    list_taps,
+    show,
+    stats,
+    TapError,
+    TapNotFoundError,
+)
+
+__version__ = "0.14.0"
+
+__all__ = [
+    "forge",
+    "run",
+    "doctor",
+    "verify",
+    "list_taps",
+    "show",
+    "stats",
+    "TapError",
+    "TapNotFoundError",
+    "__version__",
+]

taprun/api.py

@@ -0,0 +1,222 @@
+"""Subprocess wrapper around the `tap` CLI.
+
+Each public function shells out to the binary located via
+`TAPRUN_BIN` env var or `tap` on PATH. Output is parsed as JSON
+where the CLI supports `--json`; raw stdout otherwise.
+
+Errors:
+- `TapNotFoundError` when the `tap` binary cannot be located.
+- `TapError` (non-zero exit) carrying stderr + the failed argv.
+
+Latency note: each call is one process spawn (~30-100 ms on a
+warm machine). Acceptable for batch agent jobs; for hot loops
+prefer `tap mcp start` and call via MCP.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from typing import Any, Optional, Union
+
+
+class TapError(RuntimeError):
+    """Raised when the `tap` CLI exits non-zero."""
+
+    def __init__(self, argv: list[str], returncode: int, stderr: str) -> None:
+        self.argv = argv
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(
+            f"tap {' '.join(argv[1:])} exited {returncode}: {stderr.strip() or '(no stderr)'}"
+        )
+
+
+class TapNotFoundError(RuntimeError):
+    """Raised when the `tap` binary cannot be located. Install via brew
+    or set TAPRUN_BIN to the path."""
+
+
+def _resolve_bin() -> str:
+    explicit = os.environ.get("TAPRUN_BIN")
+    if explicit:
+        if not os.path.isfile(explicit):
+            raise TapNotFoundError(f"TAPRUN_BIN={explicit} does not exist")
+        return explicit
+    found = shutil.which("tap")
+    if not found:
+        raise TapNotFoundError(
+            "`tap` not found on PATH. Install with `brew install LeonTing1010/tap/tap` "
+            "or set TAPRUN_BIN to the binary path."
+        )
+    return found
+
+
+def _run_cli(args: list[str], *, parse_json: bool = True) -> Any:
+    """Spawn the `tap` CLI with the given args. Returns parsed JSON
+    when `parse_json=True` and the output is parsable, else raw text.
+    Raises `TapError` on non-zero exit."""
+    bin_path = _resolve_bin()
+    argv = [bin_path] + args
+    proc = subprocess.run(
+        argv,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        raise TapError(argv, proc.returncode, proc.stderr)
+    out = proc.stdout
+    if not parse_json:
+        return out
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError:
+        # Some CLI commands print a mix of progress text + a JSON tail.
+        # Best-effort: return raw text and let the caller parse.
+        return out
+
+
+def run(tap_id: str, *, args: Optional[dict[str, Any]] = None) -> Any:
+    """Execute a compiled tap by `<site>/<name>` id. Returns parsed
+    rows (typically a list of dicts).
+
+    >>> rows = run("hn/top")
+    >>> len(rows) > 0
+    True
+    """
+    cli_args = ["run", tap_id, "--json"]
+    if args:
+        for k, v in args.items():
+            cli_args.extend([f"--{k}", str(v)])
+    return _run_cli(cli_args)
+
+
+def doctor(tap_id: str) -> Any:
+    """Run health + drift verification on a tap. Returns the doctor
+    verdict (status + details).
+
+    >>> v = doctor("hn/top")
+    >>> v["status"] in ("ok", "broken", "stale")
+    True
+    """
+    return _run_cli(["doctor", tap_id, "--json"])
+
+
+# `verify` is an alias for `doctor` — both names appear in the
+# three-plane refactor ADR. SDK exposes both for ergonomic choice.
+verify = doctor
+
+
+def forge(
+    target: Optional[str] = None,
+    *,
+    desc: Optional[str] = None,
+    intent: str = "read",
+    trajectory: Union[str, dict, list, None] = None,
+    site: Optional[str] = None,
+    name: Optional[str] = None,
+) -> Any:
+    """Compile a tap from a URL, natural-language description, OR a
+    browser-use AgentHistoryList trajectory.
+
+    Three modes:
+
+    1. URL — Tier 0 deterministic compile, no AI:
+
+       >>> forge("https://news.ycombinator.com")
+
+    2. Description (BYOK AI loop):
+
+       >>> forge("get github trending repos")
+
+    3. Trajectory — compile a recorded agent run into a deterministic
+       plan that replays at zero LLM tokens:
+
+       >>> from browser_use import Agent
+       >>> agent = Agent(task="...", llm=...)
+       >>> result = await agent.run()
+       >>> forge(trajectory=result.model_dump(),
+       ...      site="ycombinator", name="homepage")
+
+       Pass either a parsed dict / AgentHistoryList JSON, or a path
+       to a JSON file. `site` and `name` are required.
+    """
+    if trajectory is not None:
+        if not site or not name:
+            raise ValueError("forge(trajectory=...) requires both site= and name=")
+        if isinstance(trajectory, str) and os.path.isfile(trajectory):
+            traj_path = trajectory
+            cleanup_path: Optional[str] = None
+        else:
+            payload = trajectory if isinstance(trajectory, str) else json.dumps(trajectory)
+            fd, traj_path = tempfile.mkstemp(suffix=".trajectory.json")
+            try:
+                with os.fdopen(fd, "w") as f:
+                    f.write(payload)
+            except BaseException:
+                os.unlink(traj_path)
+                raise
+            cleanup_path = traj_path
+        try:
+            return _run_cli(
+                ["forge", "--from-trajectory", traj_path, "--site", site, "--name", name],
+                parse_json=False,
+            )
+        finally:
+            if cleanup_path:
+                try:
+                    os.unlink(cleanup_path)
+                except OSError:
+                    pass
+
+    if target is None:
+        raise ValueError("forge() requires `target` (URL or description) or `trajectory=`")
+    args = ["forge", target]
+    if desc:
+        args.extend(["--desc", desc])
+    if intent != "read":
+        args.extend(["--intent", intent])
+    return _run_cli(args, parse_json=False)
+
+
+def list_taps(site: Optional[str] = None) -> Any:
+    """List installed taps. Optional site filter.
+
+    >>> taps = list_taps("hn")
+    """
+    args = ["list"]
+    if site:
+        args.append(site)
+    args.append("--json")
+    return _run_cli(args)
+
+
+def show(tap_id: str) -> Any:
+    """Inspect a tap (source + manifest + fingerprint).
+
+    >>> info = show("hn/top")
+    """
+    return _run_cli(["show", tap_id])
+
+
+def stats() -> Any:
+    """K(t) telemetry — token cost per capability accumulated across
+    runs. Returns the stats snapshot in the same shape as
+    `tap stats --json`.
+
+    >>> s = stats()
+    """
+    return _run_cli(["stats", "--json"])
+
+
+def _which() -> Union[str, None]:
+    """Diagnostic — return the `tap` binary path that would be used,
+    or None if not found. Public for users debugging install paths."""
+    try:
+        return _resolve_bin()
+    except TapNotFoundError:
+        return None

taprun/cli.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Tap CLI - Python wrapper for the tap binary."""
+
+import os
+import sys
+import platform
+import subprocess
+import urllib.request
+import urllib.error
+import json
+from pathlib import Path
+
+VERSION = "0.14.0"
+GITHUB_REPO = "LeonTing1010/tap"
+NPM_REGISTRY = "https://registry.npmjs.org/@taprun/cli"
+CACHE_DIR = Path.home() / ".tap" / "bin"
+
+
+def get_platform_package():
+    """Determine the correct npm package name for the current platform."""
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    
+    if system == "darwin":
+        if machine in ("arm64", "aarch64"):
+            return "cli-darwin-arm64"
+        else:
+            return "cli-darwin-x64"
+    elif system == "linux":
+        return "cli-linux-x64"
+    elif system == "windows":
+        return "cli-win32-x64"
+    else:
+        raise RuntimeError(f"Unsupported platform: {system} {machine}")
+
+
+def get_binary_name():
+    """Get the binary name for the current platform."""
+    system = platform.system().lower()
+    if system == "windows":
+        return "tap.exe"
+    return "tap"
+
+
+def download_from_npm():
+    """Download the tap binary from npm registry."""
+    package = get_platform_package()
+    binary_name = get_binary_name()
+    
+    # Get package metadata from npm
+    npm_url = f"https://registry.npmjs.org/@taprun/{package}"
+    
+    try:
+        with urllib.request.urlopen(npm_url, timeout=30) as response:
+            data = json.loads(response.read().decode('utf-8'))
+        
+        # Get the latest version's tarball URL
+        latest_version = data.get('dist-tags', {}).get('latest', VERSION)
+        version_data = data.get('versions', {}).get(latest_version, {})
+        tarball_url = version_data.get('dist', {}).get('tarball', '')
+        
+        if not tarball_url:
+            raise RuntimeError(f"Could not find tarball URL for {package}@{latest_version}")
+        
+        print(f"Downloading tap {latest_version} for your platform...")
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        
+        # Download tarball
+        import tarfile
+        import tempfile
+        
+        with tempfile.NamedTemporaryFile(suffix='.tgz', delete=False) as tmp:
+            urllib.request.urlretrieve(tarball_url, tmp.name)
+            
+            # Extract the binary
+            with tarfile.open(tmp.name, 'r:gz') as tar:
+                # Find the binary in the package
+                for member in tar.getmembers():
+                    if member.name.endswith(f'bin/{binary_name}') or member.name.endswith(binary_name):
+                        # Extract to cache dir
+                        extracted = tar.extract(member, CACHE_DIR)
+                        # Get the actual file path
+                        extracted_path = CACHE_DIR / member.name
+                        final_path = CACHE_DIR / binary_name
+                        
+                        # Move to final location if needed
+                        if extracted_path != final_path:
+                            extracted_path.rename(final_path)
+                        
+                        # Make executable on Unix systems
+                        if platform.system() != "Windows":
+                            final_path.chmod(0o755)
+                        
+                        # Cleanup temp files
+                        os.unlink(tmp.name)
+                        # Cleanup extracted directory structure
+                        import shutil
+                        pkg_dir = CACHE_DIR / "package"
+                        if pkg_dir.exists():
+                            shutil.rmtree(pkg_dir)
+                        
+                        print(f"Downloaded to {final_path}")
+                        return final_path
+        
+        raise RuntimeError(f"Binary not found in package {package}")
+        
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"Failed to download tap binary: HTTP {e.code}")
+    except Exception as e:
+        raise RuntimeError(f"Failed to download tap binary: {e}")
+
+
+def get_binary_path():
+    """Get the path to the tap binary, downloading if necessary.
+
+    Resolution order (matches taprun.api._resolve_bin):
+      1. TAPRUN_BIN env var (explicit override; e.g. brew-installed tap)
+      2. ~/.tap/bin/tap (cached download from npm)
+      3. Download from @taprun/cli-* npm registry → ~/.tap/bin/tap
+    """
+    explicit = os.environ.get("TAPRUN_BIN")
+    if explicit:
+        explicit_path = Path(explicit)
+        if not explicit_path.is_file():
+            raise RuntimeError(f"TAPRUN_BIN={explicit} does not exist")
+        return explicit_path
+
+    binary_name = get_binary_name()
+    binary_path = CACHE_DIR / binary_name
+
+    # Check if binary already exists
+    if binary_path.exists():
+        return binary_path
+
+    # Download the binary from npm
+    return download_from_npm()
+
+
+def main():
+    """Main entry point - proxy to the tap binary."""
+    try:
+        binary_path = get_binary_path()
+        
+        # Pass all arguments to the tap binary
+        args = [str(binary_path)] + sys.argv[1:]
+        
+        # Execute the binary
+        result = subprocess.run(args, check=False)
+        sys.exit(result.returncode)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

taprun-0.14.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: taprun
+Version: 0.14.0
+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
+
+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/tap` 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).

taprun-0.14.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+taprun/__init__.py,sha256=ap_6LfA7g4JBvlQwlt9Zg1Oor7N0ouEVB2s0wMFXpyg,1444
+taprun/api.py,sha256=x6hh2kpRDY829ma5QP61pRSoe4G_XV_tMq8hxNQOk30,6668
+taprun/cli.py,sha256=PLqljEQCCdIcwPYEpsL8G7ykULyhYJ5yC_Lc0_Tc6Us,5415
+taprun-0.14.0.dist-info/METADATA,sha256=mImzLZTS92-W-ZGSYnRWTPv-Z9VZ9g-mmVfvYO9rXBM,4859
+taprun-0.14.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+taprun-0.14.0.dist-info/entry_points.txt,sha256=EDv1lC5SPd2gAd_fdKYjjciCN7dUDlF1Dk9DYdKDCN0,40
+taprun-0.14.0.dist-info/top_level.txt,sha256=TSeKX7hcsBArtKs0llrN5B5sZ-BJ0rxAON2PHQhZGHU,7
+taprun-0.14.0.dist-info/RECORD,,

taprun-0.14.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

taprun-0.14.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tap = taprun.cli:main

taprun-0.14.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+taprun