tarmac-agent 0.1.0__tar.gz

tarmac_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install --upgrade pip build
+      - run: python -m pip install -e .
+      - run: python -m unittest discover -s tests -v
+      - run: python -m build

tarmac_agent-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m pip install -e .
+      - name: Tag must match the package version
+        run: |
+          version=$(python -c "import tarmac_agent; print(tarmac_agent.__version__)")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match package version $version" >&2
+            exit 1
+          fi
+      - run: python -m unittest discover -s tests -v
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tarmac-agent
+    permissions:
+      id-token: write # Trusted Publishing: PyPI verifies this workflow, no token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tarmac_agent-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.DS_Store

tarmac_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+First release on PyPI.
+
+- `TarmacClient`, `run_agent`, `attach`, typed tools and `TarmacToolError`. Standard library only.
+- Automatic retries with exponential backoff (`retries=`, `backoff=` on `TarmacClient`). Swap requests are never re-sent after a network failure.
+- `TarmacClient.from_env()` and `attach_from_env()` read `TARMAC_URL`, `TARMAC_RUN_ID` and `TARMAC_RUN_TOKEN`.
+- Examples: `quickstart.py` and `careful_vs_reckless.py`.

tarmac_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tarmac Agent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tarmac_agent-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: tarmac-agent
+Version: 0.1.0
+Summary: Python SDK to test your on-chain agent against Tarmac: real Robinhood Chain data, isolated wallets, policy checks on every swap.
+Project-URL: Homepage, https://github.com/tarmacagent/tarmac-python
+Project-URL: Issues, https://github.com/tarmacagent/tarmac-python/issues
+Author: Tarmac Agent
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai-agent,defi,onchain,robinhood-chain,testing,uniswap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# tarmac-agent
+
+[![ci](https://github.com/tarmacagent/tarmac-python/actions/workflows/ci.yml/badge.svg)](https://github.com/tarmacagent/tarmac-python/actions/workflows/ci.yml) ![python](https://img.shields.io/badge/python-3.10%2B-black) ![deps](https://img.shields.io/badge/dependencies-0-black) ![license](https://img.shields.io/badge/license-MIT-black)
+
+**Test your on-chain agent before it goes live, from Python.**
+
+Tarmac runs your agent against a live fork of Robinhood Chain with an isolated simulated wallet, applies the same policy checks to every swap request, and records a trace of every tool call, check and balance change. Your agent runs on your machine and never holds a key.
+
+```bash
+pip install tarmac-agent
+```
+
+> **Coming to PyPI soon.** Until the first release lands, install straight from GitHub:
+>
+> ```bash
+> pip install "git+https://github.com/tarmacagent/tarmac-python"
+> ```
+
+Standard library only: no dependencies.
+
+## Quickstart
+
+```python
+from tarmac_agent import TarmacClient, TarmacTools, run_agent
+
+client = TarmacClient("https://your-tarmac-server")
+
+def my_agent(tools: TarmacTools) -> None:
+    ctx = tools.get_context()
+    pair = dict(token_in=ctx["tokenIn"]["address"], token_out=ctx["tokenOut"]["address"])
+    quote = tools.get_quote(**pair, amount_in=ctx["amountIn"])
+
+    if quote["slippageBps"] > ctx["policy"]["maxSlippageBps"]:
+        tools.finish("stopped", "Slippage over the limit.")
+        return
+
+    tools.request_swap(quote_id=quote["quoteId"], **pair, amount_in=ctx["amountIn"])
+    tools.finish("swapped")
+
+out = run_agent(client, my_agent, scenario="swap-thin", agent_name="my-python-agent")
+print(out["run"]["result"]["verdictLabel"])  # "Followed the rule and stopped"
+print(out["session"].run_url)                  # full trace in the browser
+```
+
+### Servers that require sign-in
+
+Create the run in the Tarmac app (**Run → Your agent**), then attach:
+
+```python
+run_agent(client, my_agent, run_id=os.environ["TARMAC_RUN_ID"], run_token=os.environ["TARMAC_RUN_TOKEN"])
+```
+
+### From environment variables
+
+```python
+client = TarmacClient.from_env()          # $TARMAC_URL, default http://localhost:3000
+session = client.attach_from_env()        # $TARMAC_RUN_ID + $TARMAC_RUN_TOKEN
+```
+
+## Examples
+
+- [`examples/quickstart.py`](examples/quickstart.py): one careful agent, start to verdict.
+- [`examples/careful_vs_reckless.py`](examples/careful_vs_reckless.py): two agents on the same thin market. The careful one stops; the reckless one is blocked by policy.
+
+## Tools
+
+| Method | Arguments | Returns |
+| --- | --- | --- |
+| `get_context()` | — | instruction, wallet, tokens, amount, policy limits |
+| `get_balances()` | — | wallet balances (integer base units as strings) |
+| `get_quote()` | `token_in, token_out, amount_in` | `quoteId`, `amountOut`, reference, `slippageBps`, eligibility |
+| `request_swap()` | `quote_id, token_in, token_out, amount_in, min_amount_out=None, reason=None` | `executed` / `blocked` / `failed` + every policy check |
+| `finish()` | `outcome, summary=None` | the run's verdict |
+
+Responses keep the API's field names (`slippageBps`, `quoteId`, …) so they match the TypeScript SDK and the HTTP API exactly. Every response is a `TypedDict`, so editors autocomplete them.
+
+## Errors
+
+Failures raise `TarmacToolError` with `.code` (`INVALID_INPUT`, `UNSUPPORTED_TOKEN`, `TOOL_LIMIT`, `RUN_NOT_ACTIVE`, `AUTH_REQUIRED`, `NETWORK_ERROR`, …), `.message` and `.retryable`.
+
+### Retries
+
+Transient failures are retried automatically with exponential backoff (2 retries by default):
+
+- **Rejected before any work** (HTTP 429/503 marked retryable): every call is retried.
+- **Network failures**: only read-only calls (`get_context`, `get_balances`, `get_quote`, `get_run`) are retried. A `request_swap` or `finish` that times out may already have run on the server, so it is never sent twice.
+
+```python
+client = TarmacClient("https://your-tarmac-server", retries=4, backoff=0.25)  # or retries=0 to disable
+```
+
+## Development
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+### Releasing
+
+Releases publish to PyPI from GitHub Actions with [Trusted Publishing](https://docs.pypi.org/trusted-publishers/): no API token is stored anywhere.
+
+1. Bump `__version__` in `src/tarmac_agent/_version.py` and move the changelog's *Unreleased* notes under that version.
+2. Tag and push: `git tag v0.1.0 && git push origin v0.1.0`.
+
+The workflow refuses to publish if the tag and the package version disagree.
+
+## Related
+
+- [tarmac-sdk-ts](https://github.com/tarmacagent/tarmac-sdk-ts): the TypeScript SDK
+- [tarmac-mcp](https://github.com/tarmacagent/tarmac-mcp): use Tarmac from Claude, Cursor or any MCP client
+- [tarmac-examples](https://github.com/tarmacagent/tarmac-examples): ready-to-run agents
+
+## License
+
+MIT

tarmac_agent-0.1.0/README.md

@@ -0,0 +1,115 @@
+# tarmac-agent
+
+[![ci](https://github.com/tarmacagent/tarmac-python/actions/workflows/ci.yml/badge.svg)](https://github.com/tarmacagent/tarmac-python/actions/workflows/ci.yml) ![python](https://img.shields.io/badge/python-3.10%2B-black) ![deps](https://img.shields.io/badge/dependencies-0-black) ![license](https://img.shields.io/badge/license-MIT-black)
+
+**Test your on-chain agent before it goes live, from Python.**
+
+Tarmac runs your agent against a live fork of Robinhood Chain with an isolated simulated wallet, applies the same policy checks to every swap request, and records a trace of every tool call, check and balance change. Your agent runs on your machine and never holds a key.
+
+```bash
+pip install tarmac-agent
+```
+
+> **Coming to PyPI soon.** Until the first release lands, install straight from GitHub:
+>
+> ```bash
+> pip install "git+https://github.com/tarmacagent/tarmac-python"
+> ```
+
+Standard library only: no dependencies.
+
+## Quickstart
+
+```python
+from tarmac_agent import TarmacClient, TarmacTools, run_agent
+
+client = TarmacClient("https://your-tarmac-server")
+
+def my_agent(tools: TarmacTools) -> None:
+    ctx = tools.get_context()
+    pair = dict(token_in=ctx["tokenIn"]["address"], token_out=ctx["tokenOut"]["address"])
+    quote = tools.get_quote(**pair, amount_in=ctx["amountIn"])
+
+    if quote["slippageBps"] > ctx["policy"]["maxSlippageBps"]:
+        tools.finish("stopped", "Slippage over the limit.")
+        return
+
+    tools.request_swap(quote_id=quote["quoteId"], **pair, amount_in=ctx["amountIn"])
+    tools.finish("swapped")
+
+out = run_agent(client, my_agent, scenario="swap-thin", agent_name="my-python-agent")
+print(out["run"]["result"]["verdictLabel"])  # "Followed the rule and stopped"
+print(out["session"].run_url)                  # full trace in the browser
+```
+
+### Servers that require sign-in
+
+Create the run in the Tarmac app (**Run → Your agent**), then attach:
+
+```python
+run_agent(client, my_agent, run_id=os.environ["TARMAC_RUN_ID"], run_token=os.environ["TARMAC_RUN_TOKEN"])
+```
+
+### From environment variables
+
+```python
+client = TarmacClient.from_env()          # $TARMAC_URL, default http://localhost:3000
+session = client.attach_from_env()        # $TARMAC_RUN_ID + $TARMAC_RUN_TOKEN
+```
+
+## Examples
+
+- [`examples/quickstart.py`](examples/quickstart.py): one careful agent, start to verdict.
+- [`examples/careful_vs_reckless.py`](examples/careful_vs_reckless.py): two agents on the same thin market. The careful one stops; the reckless one is blocked by policy.
+
+## Tools
+
+| Method | Arguments | Returns |
+| --- | --- | --- |
+| `get_context()` | — | instruction, wallet, tokens, amount, policy limits |
+| `get_balances()` | — | wallet balances (integer base units as strings) |
+| `get_quote()` | `token_in, token_out, amount_in` | `quoteId`, `amountOut`, reference, `slippageBps`, eligibility |
+| `request_swap()` | `quote_id, token_in, token_out, amount_in, min_amount_out=None, reason=None` | `executed` / `blocked` / `failed` + every policy check |
+| `finish()` | `outcome, summary=None` | the run's verdict |
+
+Responses keep the API's field names (`slippageBps`, `quoteId`, …) so they match the TypeScript SDK and the HTTP API exactly. Every response is a `TypedDict`, so editors autocomplete them.
+
+## Errors
+
+Failures raise `TarmacToolError` with `.code` (`INVALID_INPUT`, `UNSUPPORTED_TOKEN`, `TOOL_LIMIT`, `RUN_NOT_ACTIVE`, `AUTH_REQUIRED`, `NETWORK_ERROR`, …), `.message` and `.retryable`.
+
+### Retries
+
+Transient failures are retried automatically with exponential backoff (2 retries by default):
+
+- **Rejected before any work** (HTTP 429/503 marked retryable): every call is retried.
+- **Network failures**: only read-only calls (`get_context`, `get_balances`, `get_quote`, `get_run`) are retried. A `request_swap` or `finish` that times out may already have run on the server, so it is never sent twice.
+
+```python
+client = TarmacClient("https://your-tarmac-server", retries=4, backoff=0.25)  # or retries=0 to disable
+```
+
+## Development
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+### Releasing
+
+Releases publish to PyPI from GitHub Actions with [Trusted Publishing](https://docs.pypi.org/trusted-publishers/): no API token is stored anywhere.
+
+1. Bump `__version__` in `src/tarmac_agent/_version.py` and move the changelog's *Unreleased* notes under that version.
+2. Tag and push: `git tag v0.1.0 && git push origin v0.1.0`.
+
+The workflow refuses to publish if the tag and the package version disagree.
+
+## Related
+
+- [tarmac-sdk-ts](https://github.com/tarmacagent/tarmac-sdk-ts): the TypeScript SDK
+- [tarmac-mcp](https://github.com/tarmacagent/tarmac-mcp): use Tarmac from Claude, Cursor or any MCP client
+- [tarmac-examples](https://github.com/tarmacagent/tarmac-examples): ready-to-run agents
+
+## License
+
+MIT

tarmac_agent-0.1.0/SECURITY.md

@@ -0,0 +1,5 @@
+# Security
+
+Please report vulnerabilities privately through GitHub's "Report a vulnerability" (Security tab) rather than a public issue.
+
+The SDK never handles private keys. It sends a per-run credential (`trt_…`) to the Tarmac server you configure; treat it like a password for that one run.

tarmac_agent-0.1.0/examples/careful_vs_reckless.py

@@ -0,0 +1,55 @@
+"""Two agents, one thin market: which one follows the rule?
+
+Runs a careful agent (checks slippage first) and a reckless one (swaps no matter
+what) against the same scenario, then prints both verdicts side by side.
+
+    TARMAC_URL=http://localhost:3000 python examples/careful_vs_reckless.py
+
+Expected on swap-thin: the careful agent stops, the reckless one is blocked by
+policy. Nothing is ever broadcast; both runs use simulated funds.
+"""
+
+import os
+
+from tarmac_agent import TarmacClient, TarmacTools, run_agent
+
+
+def pair(ctx):
+    return {"token_in": ctx["tokenIn"]["address"], "token_out": ctx["tokenOut"]["address"]}
+
+
+def careful(tools: TarmacTools) -> None:
+    ctx = tools.get_context()
+    quote = tools.get_quote(**pair(ctx), amount_in=ctx["amountIn"])
+    if quote["slippageBps"] > ctx["policy"]["maxSlippageBps"]:
+        tools.finish("stopped", f"Slippage {quote['slippageBps']} bps is over the {ctx['policy']['maxSlippageBps']} bps limit.")
+        return
+    tools.request_swap(quote_id=quote["quoteId"], **pair(ctx), amount_in=ctx["amountIn"], reason="Within the slippage limit.")
+    tools.finish("swapped")
+
+
+def reckless(tools: TarmacTools) -> None:
+    ctx = tools.get_context()
+    quote = tools.get_quote(**pair(ctx), amount_in=ctx["amountIn"])
+    # Never looks at slippage. Tarmac's policy checks still apply.
+    tools.request_swap(quote_id=quote["quoteId"], **pair(ctx), amount_in=ctx["amountIn"], reason="Swap regardless.")
+    tools.finish("swapped")
+
+
+def main() -> None:
+    client = TarmacClient.from_env()
+    scenario = os.environ.get("SCENARIO", "swap-thin")
+    rows = []
+    for name, agent in (("careful", careful), ("reckless", reckless)):
+        out = run_agent(client, agent, scenario=scenario, agent_name=f"python-{name}")
+        result = out["run"].get("result") or {}
+        rows.append((name, result.get("verdictLabel", out["run"]["status"]), out["session"].run_url))
+
+    print(f"\nScenario: {scenario}\n")
+    for name, verdict, url in rows:
+        print(f"  {name:<9} {verdict}")
+        print(f"  {'':<9} {url}\n")
+
+
+if __name__ == "__main__":
+    main()

tarmac_agent-0.1.0/examples/quickstart.py

@@ -0,0 +1,36 @@
+"""Run a careful agent against a Tarmac server.
+
+    TARMAC_URL=http://localhost:3000 SCENARIO=swap-thin python examples/quickstart.py
+
+If the server requires sign-in, create the run in the app ("Your agent") and set
+TARMAC_RUN_ID and TARMAC_RUN_TOKEN instead.
+"""
+
+import os
+
+from tarmac_agent import TarmacClient, TarmacTools, run_agent
+
+
+def my_agent(tools: TarmacTools) -> None:
+    ctx = tools.get_context()
+    print("Instruction:", ctx["instruction"])
+    quote = tools.get_quote(token_in=ctx["tokenIn"]["address"], token_out=ctx["tokenOut"]["address"], amount_in=ctx["amountIn"])
+    print(f"Quote: slippage {quote['slippageBps']} bps (limit {ctx['policy']['maxSlippageBps']})")
+    if quote["slippageBps"] > ctx["policy"]["maxSlippageBps"]:
+        tools.finish("stopped", "Slippage over the limit.")
+        return
+    swap = tools.request_swap(quote_id=quote["quoteId"], token_in=ctx["tokenIn"]["address"], token_out=ctx["tokenOut"]["address"], amount_in=ctx["amountIn"])
+    print("Swap:", swap["status"])
+    tools.finish("swapped" if swap["status"] == "executed" else "stopped")
+
+
+client = TarmacClient.from_env()
+if os.environ.get("TARMAC_RUN_ID") and os.environ.get("TARMAC_RUN_TOKEN"):
+    out = run_agent(client, my_agent, run_id=os.environ["TARMAC_RUN_ID"], run_token=os.environ["TARMAC_RUN_TOKEN"])
+else:
+    out = run_agent(client, my_agent, scenario=os.environ.get("SCENARIO", "swap-normal"), token=os.environ.get("TOKEN", "WETH"), agent_name="python-quickstart")
+
+result = out["run"].get("result") or {}
+print("\nVerdict:", result.get("verdictLabel", out["run"]["status"]))
+print("Reason: ", result.get("reason", ""))
+print("Trace:  ", out["session"].run_url)

tarmac_agent-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tarmac-agent"
+dynamic = ["version"]
+description = "Python SDK to test your on-chain agent against Tarmac: real Robinhood Chain data, isolated wallets, policy checks on every swap."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Tarmac Agent" }]
+keywords = ["ai-agent", "agents", "onchain", "robinhood-chain", "uniswap", "defi", "testing"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Testing",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/tarmacagent/tarmac-python"
+Issues = "https://github.com/tarmacagent/tarmac-python/issues"
+
+[tool.hatch.version]
+path = "src/tarmac_agent/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tarmac_agent"]

tarmac_agent-0.1.0/src/tarmac_agent/__init__.py

@@ -0,0 +1,37 @@
+"""Tarmac: test your on-chain agent before it goes live.
+
+The same typed tools as the TypeScript SDK, for Python agents. Standard library only.
+"""
+
+from ._client import RunSession, TarmacClient, TarmacTools, run_agent
+from ._errors import TarmacToolError
+from ._types import (
+    BalanceEntry,
+    BalancesResult,
+    FinishResult,
+    PolicyCheck,
+    PolicyLimits,
+    QuoteResult,
+    RunContext,
+    SwapResult,
+    TokenInfo,
+)
+
+__all__ = [
+    "__version__",
+    "TarmacClient",
+    "TarmacTools",
+    "RunSession",
+    "run_agent",
+    "TarmacToolError",
+    "RunContext",
+    "TokenInfo",
+    "PolicyLimits",
+    "BalanceEntry",
+    "BalancesResult",
+    "QuoteResult",
+    "PolicyCheck",
+    "SwapResult",
+    "FinishResult",
+]
+from ._version import __version__

tarmac_agent-0.1.0/src/tarmac_agent/_client.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional
+
+from ._errors import TarmacToolError
+from ._types import BalancesResult, FinishResult, QuoteResult, RunContext, SwapResult
+from ._version import __version__
+
+_USER_AGENT = f"tarmac-agent-python/{__version__}"
+
+
+# Statuses the server uses when it rejected a request before doing any work.
+_REJECTED_BEFORE_WORK = {429, 503}
+# Tools that only read state: safe to repeat if a response was lost in transit.
+_READ_ONLY_TOOLS = {"get_context", "get_balances", "get_quote"}
+
+
+class _Http:
+    def __init__(self, base_url: str, timeout: float, retries: int = 2, backoff: float = 0.5) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retries = max(0, retries)
+        self.backoff = max(0.0, backoff)
+
+    def request(self, method: str, path: str, body: Any = None, token: Optional[str] = None, *, idempotent: bool = False) -> Any:
+        """Send a request, retrying transient failures.
+
+        A request the server *rejected before doing any work* (429/503 marked retryable) is
+        always safe to retry. A network failure is retried only for ``idempotent`` requests:
+        if a swap request times out, it may already have run, so it is never sent twice.
+        """
+        attempt = 0
+        while True:
+            try:
+                return self._once(method, path, body, token)
+            except _Retryable as r:
+                if attempt >= self.retries or (r.network and not idempotent):
+                    raise r.error from None
+                time.sleep(self.backoff * (2**attempt))
+                attempt += 1
+
+    def _once(self, method: str, path: str, body: Any, token: Optional[str]) -> Any:
+        data = None if body is None else json.dumps(body).encode()
+        req = urllib.request.Request(self.base_url + path, data=data, method=method)
+        req.add_header("accept", "application/json")
+        req.add_header("user-agent", _USER_AGENT)
+        if data is not None:
+            req.add_header("content-type", "application/json")
+        if token:
+            req.add_header("authorization", f"Bearer {token}")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                return json.loads(res.read() or b"null")
+        except urllib.error.HTTPError as e:
+            payload: Dict[str, Any] = {}
+            try:
+                payload = json.loads(e.read() or b"{}")
+            except ValueError:
+                pass
+            err = payload.get("error") or {}
+            error = TarmacToolError(err.get("code") or f"HTTP_{e.code}", err.get("message") or e.reason, bool(err.get("retryable")))
+            if e.code in _REJECTED_BEFORE_WORK and error.retryable:
+                raise _Retryable(error, network=False) from None
+            raise error from None
+        except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+            reason = getattr(e, "reason", e)
+            raise _Retryable(TarmacToolError("NETWORK_ERROR", str(reason), True), network=True) from None
+
+
+class _Retryable(Exception):
+    def __init__(self, error: TarmacToolError, network: bool) -> None:
+        super().__init__(str(error))
+        self.error = error
+        self.network = network
+
+
+class TarmacTools:
+    """The five tools an agent can call. Same contract as the TypeScript SDK."""
+
+    def __init__(self, http: _Http, run_id: str, token: str) -> None:
+        self._http, self._run_id, self._token = http, run_id, token
+
+    def _call(self, tool: str, payload: Optional[Dict[str, Any]] = None) -> Any:
+        return self._http.request("POST", f"/api/runs/{self._run_id}/tools/{tool}", payload or {}, self._token, idempotent=tool in _READ_ONLY_TOOLS)
+
+    def get_context(self) -> RunContext:
+        return self._call("get_context")
+
+    def get_balances(self) -> BalancesResult:
+        return self._call("get_balances")
+
+    def get_quote(self, *, token_in: str, token_out: str, amount_in: str) -> QuoteResult:
+        return self._call("get_quote", {"tokenIn": token_in, "tokenOut": token_out, "amountIn": str(amount_in)})
+
+    def request_swap(
+        self,
+        *,
+        quote_id: str,
+        token_in: str,
+        token_out: str,
+        amount_in: str,
+        min_amount_out: Optional[str] = None,
+        reason: Optional[str] = None,
+    ) -> SwapResult:
+        body: Dict[str, Any] = {"quoteId": quote_id, "tokenIn": token_in, "tokenOut": token_out, "amountIn": str(amount_in)}
+        if min_amount_out is not None:
+            body["minAmountOut"] = str(min_amount_out)
+        if reason is not None:
+            body["reason"] = reason
+        return self._call("request_swap", body)
+
+    def finish(self, outcome: str, summary: Optional[str] = None) -> FinishResult:
+        body: Dict[str, Any] = {"outcome": outcome}
+        if summary is not None:
+            body["summary"] = summary
+        return self._call("finish", body)
+
+
+@dataclass
+class RunSession:
+    run_id: str
+    run_token: str
+    run_url: str
+    tools: TarmacTools
+    _http: _Http
+
+    def get_run(self) -> Dict[str, Any]:
+        """The current run record: status, verdict, trace."""
+        return self._http.request("GET", f"/api/runs/{self.run_id}", token=self.run_token, idempotent=True)["run"]
+
+
+class TarmacClient:
+    """Client for a Tarmac server.
+
+    >>> client = TarmacClient("http://localhost:3000")
+    >>> session = client.start_run(scenario="swap-thin", agent_name="my-agent")
+
+    ``retries`` and ``backoff`` control how transient failures are retried (exponential:
+    0.5s, 1s, ...). Swap requests are never re-sent after a network failure.
+    """
+
+    def __init__(self, base_url: str, timeout: float = 120.0, *, retries: int = 2, backoff: float = 0.5) -> None:
+        self._http = _Http(base_url, timeout, retries, backoff)
+
+    def start_run(
+        self,
+        *,
+        scenario: str,
+        agent_name: str,
+        token: str = "WETH",
+        mode: str = "fixture",
+        policy: Optional[Dict[str, int]] = None,
+    ) -> RunSession:
+        created = self._http.request(
+            "POST",
+            "/api/runs",
+            {"scenarioId": scenario, "token": token, "mode": mode, "agent": {"kind": "external", "name": agent_name}, "policy": policy or {}},
+        )
+        return RunSession(created["run"]["id"], created["runToken"], self._http.base_url + created["runUrl"], TarmacTools(self._http, created["run"]["id"], created["runToken"]), self._http)
+
+    @classmethod
+    def from_env(cls, **options: Any) -> "TarmacClient":
+        """Client for ``$TARMAC_URL`` (default ``http://localhost:3000``). Extra options go to ``__init__``."""
+        return cls(os.environ.get("TARMAC_URL") or "http://localhost:3000", **options)
+
+    def attach_from_env(self) -> RunSession:
+        """Attach using ``$TARMAC_RUN_ID`` and ``$TARMAC_RUN_TOKEN`` (from "Your agent" in the Tarmac app)."""
+        run_id, run_token = os.environ.get("TARMAC_RUN_ID"), os.environ.get("TARMAC_RUN_TOKEN")
+        if not run_id or not run_token:
+            raise TarmacToolError("AUTH_REQUIRED", "Set TARMAC_RUN_ID and TARMAC_RUN_TOKEN (create the run in the app with \"Your agent\").")
+        return self.attach(run_id, run_token)
+
+    def attach(self, run_id: str, run_token: str) -> RunSession:
+        """Attach to a run created elsewhere (e.g. "Your agent" in the Tarmac app)."""
+        return RunSession(run_id, run_token, f"{self._http.base_url}/runs/{run_id}#token={run_token}", TarmacTools(self._http, run_id, run_token), self._http)
+
+
+def run_agent(
+    client: TarmacClient,
+    agent: Callable[[TarmacTools], None],
+    *,
+    run_id: Optional[str] = None,
+    run_token: Optional[str] = None,
+    **start: Any,
+) -> Dict[str, Any]:
+    """Start (or attach to) a run, hand the tools to ``agent``, and always finish the run.
+
+    Returns ``{"session": RunSession, "run": dict, "finish": dict | None}``.
+    """
+    session = client.attach(run_id, run_token) if run_id and run_token else client.start_run(**start)
+    finished: Dict[str, Any] = {}
+    real_finish = session.tools.finish
+
+    def finish(outcome: str, summary: Optional[str] = None) -> FinishResult:
+        result = real_finish(outcome, summary)
+        finished["result"] = result
+        return result
+
+    session.tools.finish = finish  # type: ignore[method-assign]
+    try:
+        agent(session.tools)
+    finally:
+        if "result" not in finished:
+            try:
+                finish("stopped", "Agent returned without calling finish.")
+            except TarmacToolError:
+                pass
+    return {"session": session, "run": session.get_run(), "finish": finished.get("result")}

tarmac_agent-0.1.0/src/tarmac_agent/_errors.py

@@ -0,0 +1,12 @@
+class TarmacToolError(Exception):
+    """Raised when a Tarmac tool call or API request fails.
+
+    ``code`` is stable (e.g. ``INVALID_INPUT``, ``UNSUPPORTED_TOKEN``, ``TOOL_LIMIT``,
+    ``RUN_NOT_ACTIVE``, ``AUTH_REQUIRED``); ``message`` is human-readable.
+    """
+
+    def __init__(self, code: str, message: str, retryable: bool = False) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.retryable = retryable

tarmac_agent-0.1.0/src/tarmac_agent/_types.py

@@ -0,0 +1,79 @@
+"""Shapes returned by the Tarmac tools. Amounts are decimal strings of integer base units."""
+
+from typing import List, Literal, Optional, TypedDict
+
+
+class TokenInfo(TypedDict):
+    symbol: str
+    address: str
+    decimals: int
+
+
+class PolicyLimits(TypedDict):
+    version: str
+    maxSlippageBps: int
+    spendCap: str
+    deadlineSeconds: int
+    slippageReference: str
+
+
+class RunContext(TypedDict):
+    runId: str
+    mode: Literal["fixture", "fork"]
+    instruction: str
+    chain: dict
+    venue: dict
+    wallet: dict
+    tokenIn: TokenInfo
+    tokenOut: TokenInfo
+    amountIn: str
+    policy: PolicyLimits
+
+
+class BalanceEntry(TypedDict):
+    symbol: str
+    address: str
+    decimals: int
+    raw: str
+    formatted: str
+
+
+class BalancesResult(TypedDict):
+    wallet: str
+    block: Optional[str]
+    balances: List[BalanceEntry]
+
+
+class QuoteResult(TypedDict):
+    quoteId: str
+    tokenIn: str
+    tokenOut: str
+    amountIn: str
+    amountOut: str
+    venue: dict
+    reference: dict
+    slippageBps: int
+    policy: dict
+    block: Optional[str]
+    expiresAt: str
+
+
+class PolicyCheck(TypedDict):
+    id: str
+    label: str
+    passed: bool
+    expected: str
+    actual: str
+
+
+class SwapResult(TypedDict, total=False):
+    status: Literal["executed", "blocked", "failed"]
+    checks: List[PolicyCheck]
+    reason: str
+    execution: dict
+
+
+class FinishResult(TypedDict):
+    runId: str
+    status: str
+    verdict: Optional[Literal["executed", "stopped", "blocked", "failed"]]

tarmac_agent-0.1.0/src/tarmac_agent/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tarmac_agent-0.1.0/tests/test_client.py

@@ -0,0 +1,170 @@
+import json
+import os
+import threading
+from unittest import mock
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import tarmac_agent
+from tarmac_agent import TarmacClient, TarmacToolError, run_agent
+from tarmac_agent._client import _USER_AGENT
+
+RUN = "run_abcdefghijkmnpqr"
+TOKEN = "trt_secret_token_value_1234"
+SEEN = []
+# path -> how many more times to answer 503 before succeeding
+FLAKY = {}
+
+
+class FakeTarmac(BaseHTTPRequestHandler):
+    def log_message(self, *args):  # quiet
+        pass
+
+    def _send(self, status, payload):
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self):
+        length = int(self.headers.get("content-length") or 0)
+        body = json.loads(self.rfile.read(length) or b"{}")
+        SEEN.append((self.path, self.headers.get("authorization"), body))
+        if FLAKY.get(self.path, 0) > 0:
+            FLAKY[self.path] -= 1
+            return self._send(503, {"error": {"code": "BUSY", "message": "try again", "retryable": True}})
+        if self.path == "/api/runs":
+            return self._send(201, {"run": {"id": RUN, "status": "running"}, "runToken": TOKEN, "runUrl": f"/runs/{RUN}#token={TOKEN}"})
+        if self.headers.get("authorization") != f"Bearer {TOKEN}":
+            return self._send(401, {"error": {"code": "UNAUTHORISED", "message": "credential required", "retryable": False}})
+        tool = self.path.rsplit("/", 1)[-1]
+        if tool == "get_quote":
+            if body.get("tokenIn") != "0xUSDG":
+                return self._send(422, {"error": {"code": "UNSUPPORTED_TOKEN", "message": "USDG only", "retryable": False}})
+            return self._send(200, {"quoteId": "q_1", "slippageBps": 273, "amountOut": "1", "policy": {"maxSlippageBps": 100, "eligible": False}})
+        if tool == "finish":
+            return self._send(200, {"runId": RUN, "status": "completed", "verdict": "stopped"})
+        if tool == "get_context":
+            return self._send(200, {"tokenIn": {"address": "0xUSDG"}, "tokenOut": {"address": "0xWETH"}, "amountIn": "100000000", "policy": {"maxSlippageBps": 100}})
+        return self._send(200, {"ok": True})
+
+    def do_GET(self):
+        return self._send(200, {"run": {"id": RUN, "status": "completed", "result": {"verdict": "stopped"}}})
+
+
+class ClientTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), FakeTarmac)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.client = TarmacClient(f"http://127.0.0.1:{cls.server.server_port}/", backoff=0)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def setUp(self):
+        SEEN.clear()
+        FLAKY.clear()
+
+    def test_start_run_and_credential(self):
+        s = self.client.start_run(scenario="swap-thin", agent_name="unit")
+        self.assertEqual(s.run_id, RUN)
+        self.assertTrue(s.run_url.endswith(f"/runs/{RUN}#token={TOKEN}"))
+        self.assertEqual(SEEN[0][2]["agent"], {"kind": "external", "name": "unit"})
+        s.tools.get_balances()
+        self.assertEqual(SEEN[1][0], f"/api/runs/{RUN}/tools/get_balances")
+        self.assertEqual(SEEN[1][1], f"Bearer {TOKEN}")
+
+    def test_typed_errors(self):
+        s = self.client.attach(RUN, TOKEN)
+        with self.assertRaises(TarmacToolError) as cm:
+            s.tools.get_quote(token_in="0xNOPE", token_out="0xWETH", amount_in="1")
+        self.assertEqual(cm.exception.code, "UNSUPPORTED_TOKEN")
+        self.assertFalse(cm.exception.retryable)
+
+    def test_snake_case_maps_to_api_fields(self):
+        s = self.client.attach(RUN, TOKEN)
+        s.tools.request_swap(quote_id="q_1", token_in="0xUSDG", token_out="0xWETH", amount_in=100, min_amount_out=5, reason="test")
+        self.assertEqual(SEEN[0][2], {"quoteId": "q_1", "tokenIn": "0xUSDG", "tokenOut": "0xWETH", "amountIn": "100", "minAmountOut": "5", "reason": "test"})
+
+    def test_run_agent_always_finishes(self):
+        def crashing(tools):
+            tools.get_context()
+            raise RuntimeError("agent crashed")
+
+        with self.assertRaises(RuntimeError):
+            run_agent(self.client, crashing, run_id=RUN, run_token=TOKEN)
+        self.assertTrue(any(p.endswith("/finish") for p, _, _ in SEEN))
+
+    def test_run_agent_returns_verdict(self):
+        def careful(tools):
+            ctx = tools.get_context()
+            q = tools.get_quote(token_in=ctx["tokenIn"]["address"], token_out=ctx["tokenOut"]["address"], amount_in=ctx["amountIn"])
+            if q["slippageBps"] > ctx["policy"]["maxSlippageBps"]:
+                tools.finish("stopped", "over the limit")
+
+        out = run_agent(self.client, careful, scenario="swap-thin", agent_name="unit")
+        self.assertEqual(out["finish"]["verdict"], "stopped")
+        self.assertEqual(out["run"]["status"], "completed")
+
+    def test_retries_requests_rejected_before_work(self):
+        s = self.client.attach(RUN, TOKEN)
+        FLAKY[f"/api/runs/{RUN}/tools/request_swap"] = 2
+        out = s.tools.request_swap(quote_id="q_1", token_in="0xUSDG", token_out="0xWETH", amount_in="1")
+        self.assertEqual(out, {"ok": True})
+        self.assertEqual(len(SEEN), 3)
+
+    def test_gives_up_after_retries(self):
+        s = self.client.attach(RUN, TOKEN)
+        FLAKY[f"/api/runs/{RUN}/tools/get_balances"] = 5
+        with self.assertRaises(TarmacToolError) as cm:
+            s.tools.get_balances()
+        self.assertEqual(cm.exception.code, "BUSY")
+        self.assertEqual(len(SEEN), 3)  # first try + 2 retries
+
+    def test_does_not_retry_non_retryable_errors(self):
+        s = self.client.attach(RUN, TOKEN)
+        with self.assertRaises(TarmacToolError):
+            s.tools.get_quote(token_in="0xNOPE", token_out="0xWETH", amount_in="1")
+        self.assertEqual(len(SEEN), 1)
+
+    def test_network_errors_never_resend_a_swap(self):
+        dead = TarmacClient("http://127.0.0.1:9", retries=3, backoff=0)  # nothing listens on port 9
+        calls = []
+        real = dead._http._once
+        dead._http._once = lambda *a: (calls.append(a[1]), real(*a))[1]
+        s = dead.attach(RUN, TOKEN)
+        with self.assertRaises(TarmacToolError) as cm:
+            s.tools.request_swap(quote_id="q_1", token_in="0xUSDG", token_out="0xWETH", amount_in="1")
+        self.assertEqual(cm.exception.code, "NETWORK_ERROR")
+        self.assertEqual(len(calls), 1)
+        calls.clear()
+        with self.assertRaises(TarmacToolError):
+            s.tools.get_balances()
+        self.assertEqual(len(calls), 4)  # read-only: first try + 3 retries
+
+    def test_from_env(self):
+        with mock.patch.dict(os.environ, {"TARMAC_URL": "https://tarmac.example/"}):
+            self.assertEqual(TarmacClient.from_env()._http.base_url, "https://tarmac.example")
+        with mock.patch.dict(os.environ, {}, clear=True):
+            self.assertEqual(TarmacClient.from_env(retries=0)._http.base_url, "http://localhost:3000")
+
+    def test_attach_from_env(self):
+        with mock.patch.dict(os.environ, {"TARMAC_RUN_ID": RUN, "TARMAC_RUN_TOKEN": TOKEN}):
+            s = self.client.attach_from_env()
+            s.tools.get_balances()
+        self.assertEqual(SEEN[0][1], f"Bearer {TOKEN}")
+        with mock.patch.dict(os.environ, {}, clear=True):
+            with self.assertRaises(TarmacToolError) as cm:
+                self.client.attach_from_env()
+            self.assertEqual(cm.exception.code, "AUTH_REQUIRED")
+
+    def test_user_agent_carries_the_package_version(self):
+        self.assertEqual(_USER_AGENT, f"tarmac-agent-python/{tarmac_agent.__version__}")
+
+
+if __name__ == "__main__":
+    unittest.main()