tollgate-sdk 0.1.0__tar.gz

tollgate_sdk-0.1.0/.gitignore

@@ -0,0 +1,115 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Alembic
+*.db
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+# Node / TypeScript
+node_modules/
+dist/
+build/
+*.tsbuildinfo
+.turbo/
+.next/
+.vercel/
+out/
+
+# Package manager files
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Environment files (already partially covered — extending)
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Logs
+*.log
+logs/
+
+# Test outputs
+coverage/
+.nyc_output/
+
+# Python tooling
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+
+# Build / distribution artifacts
+*.pyc
+*.pyo
+
+# Local scratch files
+/tmp/
+*.local

tollgate_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: tollgate-sdk
+Version: 0.1.0
+Summary: Python SDK for the Tollgate agent control plane
+Project-URL: Homepage, https://tollgate.dev
+Project-URL: Repository, https://github.com/tollgate/tollgate
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# tollgate-sdk
+
+Python SDK for [Tollgate](https://tollgate.dev) — the policy and approval layer for AI agents.
+
+## Install
+
+```bash
+pip install tollgate-sdk
+```
+
+## 5-minute quickstart
+
+```python
+from tollgate import Tollgate
+
+tg = Tollgate(
+    api_key="tg_live_...",
+    base_url="http://localhost:8000",  # your Tollgate API
+)
+
+@tg.guard("issue_refund")
+def issue_refund(amount: float, customer_id: str) -> dict:
+    # Your actual refund logic here
+    return {"refunded": amount, "customer": customer_id}
+
+# Safe to call — Tollgate checks policy before executing
+result = issue_refund(amount=50.0, customer_id="c_123")
+```
+
+When the policy says `require_approval`, the decorator blocks until a human approves or rejects in Slack.
+
+## Usage patterns
+
+### Decorator (recommended)
+
+```python
+@tg.guard("issue_refund")
+def issue_refund(amount: float, customer_id: str) -> dict:
+    return stripe.refund(amount=amount, customer=customer_id)
+```
+
+### Context manager
+
+```python
+with tg.check("issue_refund", {"amount": 500, "customer_id": "c_123"}):
+    stripe.refund(amount=500, customer="c_123")
+```
+
+### Explicit
+
+```python
+decision = tg.check_action("issue_refund", {"amount": 500})
+if decision.allowed:
+    stripe.refund(...)
+```
+
+## Error handling
+
+| Exception | When | How to handle |
+|-----------|------|---------------|
+| `ActionDenied` | Policy denied or human rejected | Abort the action, inform the user |
+| `ActionPending` | Approval timed out | Retry later or escalate |
+| `TollgateAuthError` | Invalid API key | Check your `api_key` |
+| `TollgateConnectionError` | Can't reach Tollgate API | Check network; consider `fail_open=True` |
+
+```python
+from tollgate import ActionDenied, ActionPending, TollgateConnectionError
+
+try:
+    result = issue_refund(amount=500, customer_id="c_123")
+except ActionDenied as e:
+    print(f"Refund not allowed: {e.reason}")
+except ActionPending as e:
+    print(f"Timed out waiting for approval: {e.action_id}")
+except TollgateConnectionError:
+    print("Tollgate unreachable")
+```
+
+## fail_open
+
+By default, if Tollgate is unreachable the SDK raises `TollgateConnectionError` (safe — nothing proceeds). Set `fail_open=True` to allow actions through when Tollgate is down:
+
+```python
+tg = Tollgate(api_key="...", fail_open=True)
+```
+
+**Risk:** If Tollgate is down, all actions proceed without policy checks. Only use `fail_open=True` when availability matters more than safety for your use case.
+
+## Async usage
+
+```python
+from tollgate import AsyncTollgate
+
+tg = AsyncTollgate(api_key="tg_live_...")
+
+@tg.aguard("issue_refund")
+async def issue_refund(amount: float, customer_id: str) -> dict:
+    return await stripe_async.refund(amount=amount)
+
+# In an async context:
+result = await issue_refund(amount=50.0, customer_id="c_123")
+```
+
+## Configuration
+
+```python
+tg = Tollgate(
+    api_key="tg_live_...",
+    base_url="https://api.tollgate.dev",  # override for local dev
+    poll_interval=2.0,   # seconds between approval polls
+    max_wait=300.0,      # max seconds to wait for approval
+    on_pending=lambda action_id: print(f"Waiting for approval: {action_id}"),
+    fail_open=False,     # raise on network errors (default)
+    timeout=10.0,        # HTTP request timeout
+)
+```
+
+## Links
+
+- [Dashboard](https://tollgate.dev)
+- [Docs](https://docs.tollgate.dev)
+- [API Reference](https://api.tollgate.dev/v1/docs)

tollgate_sdk-0.1.0/README.md

@@ -0,0 +1,122 @@
+# tollgate-sdk
+
+Python SDK for [Tollgate](https://tollgate.dev) — the policy and approval layer for AI agents.
+
+## Install
+
+```bash
+pip install tollgate-sdk
+```
+
+## 5-minute quickstart
+
+```python
+from tollgate import Tollgate
+
+tg = Tollgate(
+    api_key="tg_live_...",
+    base_url="http://localhost:8000",  # your Tollgate API
+)
+
+@tg.guard("issue_refund")
+def issue_refund(amount: float, customer_id: str) -> dict:
+    # Your actual refund logic here
+    return {"refunded": amount, "customer": customer_id}
+
+# Safe to call — Tollgate checks policy before executing
+result = issue_refund(amount=50.0, customer_id="c_123")
+```
+
+When the policy says `require_approval`, the decorator blocks until a human approves or rejects in Slack.
+
+## Usage patterns
+
+### Decorator (recommended)
+
+```python
+@tg.guard("issue_refund")
+def issue_refund(amount: float, customer_id: str) -> dict:
+    return stripe.refund(amount=amount, customer=customer_id)
+```
+
+### Context manager
+
+```python
+with tg.check("issue_refund", {"amount": 500, "customer_id": "c_123"}):
+    stripe.refund(amount=500, customer="c_123")
+```
+
+### Explicit
+
+```python
+decision = tg.check_action("issue_refund", {"amount": 500})
+if decision.allowed:
+    stripe.refund(...)
+```
+
+## Error handling
+
+| Exception | When | How to handle |
+|-----------|------|---------------|
+| `ActionDenied` | Policy denied or human rejected | Abort the action, inform the user |
+| `ActionPending` | Approval timed out | Retry later or escalate |
+| `TollgateAuthError` | Invalid API key | Check your `api_key` |
+| `TollgateConnectionError` | Can't reach Tollgate API | Check network; consider `fail_open=True` |
+
+```python
+from tollgate import ActionDenied, ActionPending, TollgateConnectionError
+
+try:
+    result = issue_refund(amount=500, customer_id="c_123")
+except ActionDenied as e:
+    print(f"Refund not allowed: {e.reason}")
+except ActionPending as e:
+    print(f"Timed out waiting for approval: {e.action_id}")
+except TollgateConnectionError:
+    print("Tollgate unreachable")
+```
+
+## fail_open
+
+By default, if Tollgate is unreachable the SDK raises `TollgateConnectionError` (safe — nothing proceeds). Set `fail_open=True` to allow actions through when Tollgate is down:
+
+```python
+tg = Tollgate(api_key="...", fail_open=True)
+```
+
+**Risk:** If Tollgate is down, all actions proceed without policy checks. Only use `fail_open=True` when availability matters more than safety for your use case.
+
+## Async usage
+
+```python
+from tollgate import AsyncTollgate
+
+tg = AsyncTollgate(api_key="tg_live_...")
+
+@tg.aguard("issue_refund")
+async def issue_refund(amount: float, customer_id: str) -> dict:
+    return await stripe_async.refund(amount=amount)
+
+# In an async context:
+result = await issue_refund(amount=50.0, customer_id="c_123")
+```
+
+## Configuration
+
+```python
+tg = Tollgate(
+    api_key="tg_live_...",
+    base_url="https://api.tollgate.dev",  # override for local dev
+    poll_interval=2.0,   # seconds between approval polls
+    max_wait=300.0,      # max seconds to wait for approval
+    on_pending=lambda action_id: print(f"Waiting for approval: {action_id}"),
+    fail_open=False,     # raise on network errors (default)
+    timeout=10.0,        # HTTP request timeout
+)
+```
+
+## Links
+
+- [Dashboard](https://tollgate.dev)
+- [Docs](https://docs.tollgate.dev)
+- [API Reference](https://api.tollgate.dev/v1/docs)

tollgate_sdk-0.1.0/examples/README.md

@@ -0,0 +1,75 @@
+# Support Agent Example
+
+A customer support agent powered by Claude that uses Tollgate to gate risky actions.
+
+## Prerequisites
+
+- Tollgate API running locally (`uvicorn tollgate.main:app --reload --port 8000` from `apps/api/`)
+- Docker running (Postgres + Redis via `docker-compose up -d` from repo root)
+- Slack workspace connected (see `apps/api/README.md` → Slack setup)
+- ngrok tunnel active (`ngrok http 8000`)
+
+## Step 1: Create an agent
+
+```bash
+# Sign up and get a JWT
+JWT=$(curl -s -X POST http://localhost:8000/auth/signup \
+  -H "Content-Type: application/json" \
+  -d '{"email":"demo@example.com","password":"demo-pw-123","org_name":"Demo Org"}' \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
+
+# Create the agent
+curl -s -X POST http://localhost:8000/agents \
+  -H "Authorization: Bearer $JWT" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"support-agent-demo"}'
+# Save the api_key from the response — you won't see it again
+```
+
+## Step 2: Upload the sample policy
+
+```bash
+AGENT_ID="<your-agent-id>"
+POLICY=$(cat sample_policy.yaml)
+
+curl -s -X POST "http://localhost:8000/agents/$AGENT_ID/policies" \
+  -H "Authorization: Bearer $JWT" \
+  -H "Content-Type: application/json" \
+  -d "{\"source_yaml\": $(python3 -c "import sys,json; print(json.dumps(open('sample_policy.yaml').read()))")}"
+```
+
+The policy allows refunds ≤ $100 automatically, requires Slack approval for refunds > $100, denies `delete_account`, and allows everything else.
+
+## Step 3: Set environment variables
+
+```bash
+export TOLLGATE_API_KEY="tg_live_..."   # from Step 1
+export TOLLGATE_BASE_URL="http://localhost:8000"
+export ANTHROPIC_API_KEY="sk-ant-..."  # your Anthropic API key
+```
+
+## Step 4: Run the agent
+
+```bash
+pip install -r requirements.txt
+python support_agent.py
+```
+
+## Step 5: Try it
+
+Ask the agent to perform actions:
+
+```
+You: Issue a $50 refund for customer c_001
+```
+→ Allowed immediately (under $100 threshold)
+
+```
+You: Issue a $500 refund for customer c_002
+```
+→ Pauses and posts to your Slack `#approvals` channel. Check Slack, click Approve or Reject.
+
+```
+You: Delete account for customer c_003
+```
+→ Denied immediately by policy.

tollgate_sdk-0.1.0/examples/requirements.txt

@@ -0,0 +1,2 @@
+tollgate-sdk
+anthropic

tollgate_sdk-0.1.0/examples/sample_policy.yaml

@@ -0,0 +1,15 @@
+version: 1
+rules:
+  - action: issue_refund
+    when:
+      amount: { lte: 100 }
+    decide: allow
+  - action: issue_refund
+    when:
+      amount: { gt: 100 }
+    decide: require_approval
+    approvers: ["#approvals"]
+  - action: delete_account
+    decide: deny
+    reason: "Account deletion is not permitted via agent"
+default: allow

tollgate_sdk-0.1.0/examples/support_agent.py

@@ -0,0 +1,193 @@
+"""
+Tollgate Example: AI Support Agent
+
+A support agent backed by Claude that uses Tollgate to gate risky actions.
+Three tools are protected: issue_refund, update_account, escalate_to_human.
+
+Run: python support_agent.py
+"""
+
+import os
+import sys
+
+import anthropic
+
+from tollgate import ActionDenied, ActionPending, Tollgate
+
+TOLLGATE_API_KEY = os.environ.get("TOLLGATE_API_KEY", "")
+TOLLGATE_BASE_URL = os.environ.get("TOLLGATE_BASE_URL", "http://localhost:8000")
+ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY", "")
+
+if not TOLLGATE_API_KEY:
+    print("Error: TOLLGATE_API_KEY is not set.")
+    sys.exit(1)
+if not ANTHROPIC_API_KEY:
+    print("Error: ANTHROPIC_API_KEY is not set.")
+    sys.exit(1)
+
+tg = Tollgate(
+    api_key=TOLLGATE_API_KEY,
+    base_url=TOLLGATE_BASE_URL,
+    on_pending=lambda action_id: print(f"\n[Tollgate] Waiting for approval in Slack... (action_id={action_id})"),
+    poll_interval=3.0,
+    max_wait=300.0,
+)
+
+client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)
+
+TOOLS = [
+    {
+        "name": "issue_refund",
+        "description": "Issue a refund to a customer for a specified amount.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "amount": {"type": "number", "description": "Refund amount in USD"},
+                "customer_id": {"type": "string", "description": "Customer identifier"},
+                "reason": {"type": "string", "description": "Reason for the refund"},
+            },
+            "required": ["amount", "customer_id"],
+        },
+    },
+    {
+        "name": "update_account",
+        "description": "Update a customer's account information.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "customer_id": {"type": "string", "description": "Customer identifier"},
+                "field": {"type": "string", "description": "Field to update (email, plan, etc.)"},
+                "value": {"type": "string", "description": "New value for the field"},
+            },
+            "required": ["customer_id", "field", "value"],
+        },
+    },
+    {
+        "name": "escalate_to_human",
+        "description": "Escalate this support case to a human agent.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "customer_id": {"type": "string", "description": "Customer identifier"},
+                "reason": {"type": "string", "description": "Reason for escalation"},
+                "priority": {"type": "string", "enum": ["low", "medium", "high"], "description": "Priority level"},
+            },
+            "required": ["customer_id", "reason"],
+        },
+    },
+]
+
+
+@tg.guard("issue_refund")
+def issue_refund(amount: float, customer_id: str, reason: str = "") -> dict:  # type: ignore[return]
+    """Execute the refund (would call Stripe in production)."""
+    print(f"[Tool] Issuing refund: ${amount} to {customer_id}")
+    return {"status": "refunded", "amount": amount, "customer_id": customer_id}
+
+
+@tg.guard("update_account")
+def update_account(customer_id: str, field: str, value: str) -> dict:  # type: ignore[return]
+    """Execute the account update (would call your DB in production)."""
+    print(f"[Tool] Updating {field}={value} for {customer_id}")
+    return {"status": "updated", "customer_id": customer_id, "field": field, "value": value}
+
+
+@tg.guard("escalate_to_human")
+def escalate_to_human(customer_id: str, reason: str, priority: str = "medium") -> dict:  # type: ignore[return]
+    """Escalate to a human agent."""
+    print(f"[Tool] Escalating {customer_id} — {reason} (priority={priority})")
+    return {"status": "escalated", "customer_id": customer_id, "ticket_id": "TKT-001"}
+
+
+def run_tool(name: str, inputs: dict) -> str:  # type: ignore[type-arg]
+    """Dispatch a tool call, catching Tollgate exceptions."""
+    try:
+        if name == "issue_refund":
+            result = issue_refund(**inputs)
+        elif name == "update_account":
+            result = update_account(**inputs)
+        elif name == "escalate_to_human":
+            result = escalate_to_human(**inputs)
+        else:
+            return f"Unknown tool: {name}"
+        return str(result)
+    except ActionDenied as e:
+        return f"[Tollgate] Action denied: {e.reason}"
+    except ActionPending as e:
+        return f"[Tollgate] Approval timed out after {e.timeout_seconds}s for action {e.action_id}"
+
+
+def chat_loop() -> None:
+    """Run the support agent loop."""
+    print("Tollgate Support Agent — type 'quit' to exit")
+    print(f"Connected to Tollgate at {TOLLGATE_BASE_URL}\n")
+    messages: list[dict] = []  # type: ignore[type-arg]
+
+    while True:
+        try:
+            user_input = input("You: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nGoodbye.")
+            break
+
+        if user_input.lower() in ("quit", "exit", "q"):
+            print("Goodbye.")
+            break
+        if not user_input:
+            continue
+
+        messages.append({"role": "user", "content": user_input})
+
+        response = client.messages.create(
+            model="claude-haiku-4-5-20251001",
+            max_tokens=1024,
+            system=(
+                "You are a helpful customer support agent. "
+                "Use the available tools to help customers with refunds, account updates, and escalations. "
+                "Always confirm the customer_id before taking actions."
+            ),
+            tools=TOOLS,  # type: ignore[arg-type]
+            messages=messages,  # type: ignore[arg-type]
+        )
+
+        while response.stop_reason == "tool_use":
+            tool_results = []
+            assistant_content = []
+
+            for block in response.content:
+                assistant_content.append(block)
+                if block.type == "tool_use":
+                    print(f"\n[Agent] Calling {block.name}({block.input})")
+                    result = run_tool(block.name, block.input)  # type: ignore[arg-type]
+                    tool_results.append({
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": result,
+                    })
+
+            messages.append({"role": "assistant", "content": assistant_content})
+            messages.append({"role": "user", "content": tool_results})
+
+            response = client.messages.create(
+                model="claude-haiku-4-5-20251001",
+                max_tokens=1024,
+                system=(
+                    "You are a helpful customer support agent. "
+                    "Use the available tools to help customers with refunds, account updates, and escalations."
+                ),
+                tools=TOOLS,  # type: ignore[arg-type]
+                messages=messages,  # type: ignore[arg-type]
+            )
+
+        # Extract final text response
+        reply = ""
+        for block in response.content:
+            if hasattr(block, "text"):
+                reply += block.text
+
+        messages.append({"role": "assistant", "content": response.content})
+        print(f"\nAgent: {reply}\n")
+
+
+if __name__ == "__main__":
+    chat_loop()

tollgate_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tollgate-sdk"
+version = "0.1.0"
+description = "Python SDK for the Tollgate agent control plane"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://tollgate.dev"
+Repository = "https://github.com/tollgate/tollgate"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tollgate"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.8",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "anyio>=4.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+mypy_path = "src"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]