tollgateai 0.1.0__tar.gz

tollgateai-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# v0 sandbox internal files
+__v0_runtime_loader.js
+__v0_devtools.tsx
+__v0_jsx-dev-runtime.ts
+.snowflake/
+.v0-trash/
+.vercel/
+
+# Environment variables
+.env*.local
+
+# Common ignores
+node_modules
+.next/
+.DS_Store
+
+# Lambda build artifacts
+dist/
+# Claude Code runtime artifacts
+.claude/
+
+.vercel

tollgateai-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: tollgateai
+Version: 0.1.0
+Summary: Track real LLM model usage and compute live gross margin with Tollgate.
+Project-URL: Homepage, https://tollgateapp.vercel.app
+Author: Tollgate
+License: Proprietary
+Keywords: anthropic,cost,llm,margin,observability,openai,tokens,tollgate
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# tollgateai (Python SDK)
+
+Track **real** LLM model usage and compute live gross margin with
+[Tollgate](https://tollgateapp.vercel.app). The SDK reads the actual usage off
+each provider response — you never hand-count tokens. Zero dependencies.
+
+```bash
+pip install tollgateai
+```
+
+Create an API key in **Tollgate → Integrations**, then set:
+
+```bash
+export TOLLGATE_API_KEY=tg_live_xxx
+# optional, defaults to the hosted app:
+export TOLLGATE_BASE_URL=https://tollgateapp.vercel.app
+```
+
+## Auto-instrumentation (recommended)
+
+Wrap your provider client once; every call reports real usage in the background.
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from tollgate import create_tollgate_client, wrap_anthropic
+
+tollgate = create_tollgate_client()  # reads TOLLGATE_API_KEY
+anthropic = wrap_anthropic(
+    Anthropic(), tollgate,
+    customer_id="cust_A",     # your end customer
+    revenue_unit_cents=50,    # what you charge for this unit ($0.50)
+)
+
+# Use the client normally — usage is tracked automatically.
+anthropic.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=[{"role": "user", "content": "Summarize this ticket…"}],
+)
+```
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from tollgate import create_tollgate_client, wrap_openai
+
+tollgate = create_tollgate_client()
+openai = wrap_openai(OpenAI(), tollgate, customer_id="cust_A")
+
+openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+`revenue_unit_cents` can also be a callable of the response, e.g.
+`revenue_unit_cents=lambda res: 50 if res.something else 0`.
+
+## Manual tracking
+
+For providers without a wrapper (Bedrock, custom gateways) or full control:
+
+```python
+from tollgate import create_tollgate_client
+
+tollgate = create_tollgate_client()
+
+tollgate.track({
+    "customerId": "cust_A",
+    "runId": "run_12345",
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "tokensIn": 1200,
+    "tokensOut": 450,
+    "reasoningTokens": 0,
+    "cachedTokens": 0,
+    "revenueUnitCents": 50,
+    "idempotencyKey": "run_12345#step_1",  # exactly-once: safe to retry
+})
+```
+
+## Notes
+
+- **Idempotent.** Events dedupe on `idempotencyKey` (auto-set to the provider
+  response id by the wrappers), so retries never double-count.
+- **No prompt content is ever sent** — only token counts and metadata.
+- **Streaming** responses are not auto-tracked yet (the wrappers only report when
+  a non-streaming `usage` is present). Track those manually for now.
+- **Non-blocking.** Auto-instrumented tracking runs on a background thread;
+  failures go to `on_error` (default: log a warning) and never break your call.
+
+Licensed for use with Tollgate. Not open source.

tollgateai-0.1.0/README.md

@@ -0,0 +1,95 @@
+# tollgateai (Python SDK)
+
+Track **real** LLM model usage and compute live gross margin with
+[Tollgate](https://tollgateapp.vercel.app). The SDK reads the actual usage off
+each provider response — you never hand-count tokens. Zero dependencies.
+
+```bash
+pip install tollgateai
+```
+
+Create an API key in **Tollgate → Integrations**, then set:
+
+```bash
+export TOLLGATE_API_KEY=tg_live_xxx
+# optional, defaults to the hosted app:
+export TOLLGATE_BASE_URL=https://tollgateapp.vercel.app
+```
+
+## Auto-instrumentation (recommended)
+
+Wrap your provider client once; every call reports real usage in the background.
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from tollgate import create_tollgate_client, wrap_anthropic
+
+tollgate = create_tollgate_client()  # reads TOLLGATE_API_KEY
+anthropic = wrap_anthropic(
+    Anthropic(), tollgate,
+    customer_id="cust_A",     # your end customer
+    revenue_unit_cents=50,    # what you charge for this unit ($0.50)
+)
+
+# Use the client normally — usage is tracked automatically.
+anthropic.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=[{"role": "user", "content": "Summarize this ticket…"}],
+)
+```
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from tollgate import create_tollgate_client, wrap_openai
+
+tollgate = create_tollgate_client()
+openai = wrap_openai(OpenAI(), tollgate, customer_id="cust_A")
+
+openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+`revenue_unit_cents` can also be a callable of the response, e.g.
+`revenue_unit_cents=lambda res: 50 if res.something else 0`.
+
+## Manual tracking
+
+For providers without a wrapper (Bedrock, custom gateways) or full control:
+
+```python
+from tollgate import create_tollgate_client
+
+tollgate = create_tollgate_client()
+
+tollgate.track({
+    "customerId": "cust_A",
+    "runId": "run_12345",
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "tokensIn": 1200,
+    "tokensOut": 450,
+    "reasoningTokens": 0,
+    "cachedTokens": 0,
+    "revenueUnitCents": 50,
+    "idempotencyKey": "run_12345#step_1",  # exactly-once: safe to retry
+})
+```
+
+## Notes
+
+- **Idempotent.** Events dedupe on `idempotencyKey` (auto-set to the provider
+  response id by the wrappers), so retries never double-count.
+- **No prompt content is ever sent** — only token counts and metadata.
+- **Streaming** responses are not auto-tracked yet (the wrappers only report when
+  a non-streaming `usage` is present). Track those manually for now.
+- **Non-blocking.** Auto-instrumented tracking runs on a background thread;
+  failures go to `on_error` (default: log a warning) and never break your call.
+
+Licensed for use with Tollgate. Not open source.

tollgateai-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tollgateai"
+version = "0.1.0"
+description = "Track real LLM model usage and compute live gross margin with Tollgate."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "Proprietary" }
+authors = [{ name = "Tollgate" }]
+keywords = ["llm", "tokens", "cost", "margin", "observability", "anthropic", "openai", "tollgate"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://tollgateapp.vercel.app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tollgate"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tollgate", "README.md"]

tollgateai-0.1.0/src/tollgate/__init__.py

@@ -0,0 +1,26 @@
+"""Tollgate Python SDK — track real LLM usage and compute live gross margin."""
+
+from .client import (
+    TollgateClient,
+    TollgateError,
+    create_tollgate_client,
+)
+from .instrument import (
+    anthropic_event_from,
+    openai_event_from,
+    wrap_anthropic,
+    wrap_openai,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TollgateClient",
+    "TollgateError",
+    "create_tollgate_client",
+    "wrap_anthropic",
+    "wrap_openai",
+    "anthropic_event_from",
+    "openai_event_from",
+    "__version__",
+]

tollgateai-0.1.0/src/tollgate/client.py

@@ -0,0 +1,82 @@
+"""Tollgate ingest client. Zero dependencies — uses urllib from the stdlib."""
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional
+
+DEFAULT_BASE_URL = "https://tollgateapp.vercel.app"
+
+
+class TollgateError(Exception):
+    def __init__(self, message: str, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class TollgateClient:
+    """Reports usage events to ``POST /api/track``. Idempotent on ``idempotencyKey``."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 10.0,
+        max_retries: int = 2,
+    ):
+        self.api_key = api_key or os.environ.get("TOLLGATE_API_KEY")
+        self.base_url = (
+            base_url or os.environ.get("TOLLGATE_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    def track(self, event: Dict[str, Any]) -> Dict[str, Any]:
+        if not self.api_key:
+            raise TollgateError("Missing API key — pass api_key or set TOLLGATE_API_KEY.")
+
+        # Drop None values so server defaults apply.
+        payload = json.dumps({k: v for k, v in event.items() if v is not None}).encode("utf-8")
+        url = self.base_url + "/api/track"
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": "Bearer " + self.api_key,
+        }
+
+        last_err: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            req = urllib.request.Request(url, data=payload, method="POST", headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    # 200 (duplicate) and 201 (created) both succeed here.
+                    return json.loads(resp.read().decode("utf-8") or "{}")
+            except urllib.error.HTTPError as e:
+                status = e.code
+                if status >= 500 or status == 429:
+                    last_err = TollgateError("Tollgate track failed (%d)" % status, status)
+                else:
+                    body = None
+                    try:
+                        body = json.loads(e.read().decode("utf-8") or "{}")
+                    except Exception:
+                        pass
+                    raise TollgateError("Tollgate track failed (%d)" % status, status, body)
+            except urllib.error.URLError as e:
+                last_err = e
+
+            if attempt < self.max_retries:
+                time.sleep(0.2 * (2 ** attempt))  # 0.2s, 0.4s, …
+
+        raise last_err or TollgateError("Tollgate track failed after retries")
+
+
+def create_tollgate_client(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    timeout: float = 10.0,
+    max_retries: int = 2,
+) -> TollgateClient:
+    return TollgateClient(api_key=api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)

tollgateai-0.1.0/src/tollgate/instrument.py

@@ -0,0 +1,173 @@
+"""Auto-instrumentation: wrap a provider client so every completion reports its
+REAL usage to Tollgate — no manual token counting. Structurally typed, so this
+package never has to depend on the provider SDKs."""
+
+import logging
+import threading
+import uuid
+from typing import Any, Callable, Dict, Optional, Union
+
+from .client import TollgateClient
+
+logger = logging.getLogger("tollgate")
+
+Revenue = Union[int, Callable[[Any], Optional[int]], None]
+RunId = Union[str, Callable[[], str], None]
+
+
+def _attr(obj: Any, *path: str, default: Any = None) -> Any:
+    """Read a nested attribute or dict key path, tolerant of either."""
+    cur = obj
+    for p in path:
+        if cur is None:
+            return default
+        cur = cur.get(p) if isinstance(cur, dict) else getattr(cur, p, None)
+    return cur if cur is not None else default
+
+
+def _resolve_run_id(run_id: RunId, response_id: Optional[str]) -> str:
+    if callable(run_id):
+        return run_id()
+    return run_id or response_id or str(uuid.uuid4())
+
+
+def _resolve_revenue(revenue: Revenue, response: Any) -> Optional[int]:
+    return revenue(response) if callable(revenue) else revenue
+
+
+def _fire(tollgate: TollgateClient, event: Dict[str, Any], on_error: Optional[Callable[[Exception], None]]) -> None:
+    def run() -> None:
+        try:
+            tollgate.track(event)
+        except Exception as err:  # noqa: BLE001 - report, never raise into caller
+            (on_error or (lambda e: logger.warning("[tollgate] track failed: %s", e)))(err)
+
+    threading.Thread(target=run, daemon=True).start()
+
+
+# --- Anthropic ------------------------------------------------------------
+
+def anthropic_event_from(
+    msg: Any,
+    customer_id: str,
+    agent_id: Optional[str] = None,
+    run_id: RunId = None,
+    revenue_unit_cents: Revenue = None,
+) -> Optional[Dict[str, Any]]:
+    usage = _attr(msg, "usage")
+    if usage is None:
+        return None
+    rid = _resolve_run_id(run_id, _attr(msg, "id"))
+    return {
+        "customerId": customer_id,
+        "agentId": agent_id,
+        "runId": rid,
+        "provider": "anthropic",
+        "model": _attr(msg, "model", default="unknown"),
+        "tokensIn": _attr(usage, "input_tokens", default=0),
+        "tokensOut": _attr(usage, "output_tokens", default=0),
+        "cachedTokens": _attr(usage, "cache_read_input_tokens", default=0),
+        "revenueUnitCents": _resolve_revenue(revenue_unit_cents, msg),
+        "idempotencyKey": _attr(msg, "id") or rid,
+    }
+
+
+# --- OpenAI ---------------------------------------------------------------
+
+def openai_event_from(
+    completion: Any,
+    customer_id: str,
+    agent_id: Optional[str] = None,
+    run_id: RunId = None,
+    revenue_unit_cents: Revenue = None,
+) -> Optional[Dict[str, Any]]:
+    usage = _attr(completion, "usage")
+    if usage is None:
+        return None
+    rid = _resolve_run_id(run_id, _attr(completion, "id"))
+    return {
+        "customerId": customer_id,
+        "agentId": agent_id,
+        "runId": rid,
+        "provider": "openai",
+        "model": _attr(completion, "model", default="unknown"),
+        "tokensIn": _attr(usage, "prompt_tokens", default=0),
+        "tokensOut": _attr(usage, "completion_tokens", default=0),
+        "reasoningTokens": _attr(usage, "completion_tokens_details", "reasoning_tokens", default=0),
+        "cachedTokens": _attr(usage, "prompt_tokens_details", "cached_tokens", default=0),
+        "revenueUnitCents": _resolve_revenue(revenue_unit_cents, completion),
+        "idempotencyKey": _attr(completion, "id") or rid,
+    }
+
+
+# --- Proxy plumbing -------------------------------------------------------
+
+class _CreateInterceptor:
+    """Wraps an object exposing ``create(...)`` and reports the response."""
+
+    def __init__(self, inner: Any, hook: Callable[[Any], None]):
+        self._inner = inner
+        self._hook = hook
+
+    def create(self, *args: Any, **kwargs: Any) -> Any:
+        result = self._inner.create(*args, **kwargs)
+        self._hook(result)
+        return result
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._inner, name)
+
+
+class _Proxy:
+    """Forwards everything to ``target`` except the keys in ``overrides``."""
+
+    def __init__(self, target: Any, overrides: Dict[str, Any]):
+        object.__setattr__(self, "_target", target)
+        object.__setattr__(self, "_overrides", overrides)
+
+    def __getattr__(self, name: str) -> Any:
+        overrides = object.__getattribute__(self, "_overrides")
+        if name in overrides:
+            return overrides[name]
+        return getattr(object.__getattribute__(self, "_target"), name)
+
+
+def wrap_anthropic(
+    client: Any,
+    tollgate: TollgateClient,
+    customer_id: str,
+    agent_id: Optional[str] = None,
+    run_id: RunId = None,
+    revenue_unit_cents: Revenue = None,
+    on_error: Optional[Callable[[Exception], None]] = None,
+) -> Any:
+    """Wrap an Anthropic client so ``messages.create`` auto-reports real usage."""
+
+    def hook(result: Any) -> None:
+        event = anthropic_event_from(result, customer_id, agent_id, run_id, revenue_unit_cents)
+        if event:
+            _fire(tollgate, event, on_error)
+
+    messages = _CreateInterceptor(client.messages, hook)
+    return _Proxy(client, {"messages": messages})
+
+
+def wrap_openai(
+    client: Any,
+    tollgate: TollgateClient,
+    customer_id: str,
+    agent_id: Optional[str] = None,
+    run_id: RunId = None,
+    revenue_unit_cents: Revenue = None,
+    on_error: Optional[Callable[[Exception], None]] = None,
+) -> Any:
+    """Wrap an OpenAI client so ``chat.completions.create`` auto-reports usage."""
+
+    def hook(result: Any) -> None:
+        event = openai_event_from(result, customer_id, agent_id, run_id, revenue_unit_cents)
+        if event:
+            _fire(tollgate, event, on_error)
+
+    completions = _CreateInterceptor(client.chat.completions, hook)
+    chat = _Proxy(client.chat, {"completions": completions})
+    return _Proxy(client, {"chat": chat})