useagentledger 0.1.0__py3-none-any.whl

agentledger/__init__.py

@@ -0,0 +1,418 @@
+"""AgentLedger Python SDK.
+
+Track, attribute, and govern AI agent spend across OpenAI, Anthropic, and
+Gemini. Mirrors the TypeScript SDK:
+
+- ``run()`` wraps an LLM call with a pre-call kill-switch check and
+  fire-and-forget usage tracking (cost is computed server-side from
+  AgentLedger's authoritative pricing table — the SDK carries no pricing copy).
+- Control-plane calls (block checks, tracking, sessions) always fail open:
+  a network error on AgentLedger's side never breaks your LLM call.
+
+Zero dependencies — stdlib only.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Generator, Iterable, List, Optional
+
+__all__ = ["AgentLedger", "AgentLedgerBlockError"]
+
+_BLOCK_CACHE_TTL = 5.0  # seconds, matches the TS SDK and proxy cache
+_CONTROL_PLANE_TIMEOUT = 10.0
+_LLM_TIMEOUT = 600.0
+
+_ENV_VARS = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "gemini": "GOOGLE_API_KEY",
+}
+
+
+class AgentLedgerBlockError(Exception):
+    """Raised when the AgentLedger kill switch blocks a call before it is made."""
+
+    def __init__(self, message: str, dimension: str, dimension_value: str):
+        super().__init__(message)
+        self.dimension = dimension
+        self.dimension_value = dimension_value
+
+
+def _post_json(url: str, body: Dict[str, Any], headers: Dict[str, str], timeout: float) -> Dict[str, Any]:
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(url, data=data, method="POST")
+    req.add_header("Content-Type", "application/json")
+    for k, v in headers.items():
+        req.add_header(k, v)
+    with urllib.request.urlopen(req, timeout=timeout) as res:
+        return json.loads(res.read().decode("utf-8"))
+
+
+def _iter_sse(res: Any) -> Generator[Dict[str, Any], None, None]:
+    """Parse a text/event-stream response into JSON event dicts."""
+    for raw_line in res:
+        line = raw_line.decode("utf-8").rstrip("\r\n")
+        if not line.startswith("data:"):
+            continue
+        payload = line[5:].strip()
+        if payload == "[DONE]":
+            return
+        try:
+            yield json.loads(payload)
+        except (ValueError, TypeError):
+            continue  # skip malformed event data
+
+
+class AgentLedger:
+    """Client for tracking and governing LLM calls through AgentLedger.
+
+    Args:
+        api_key: Your AgentLedger API key (``al_live_...``).
+        base_url: AgentLedger API base URL. Defaults to the hosted service.
+        provider_keys: Optional dict with ``anthropic`` / ``openai`` / ``gemini``
+            API keys. Falls back to ``ANTHROPIC_API_KEY`` / ``OPENAI_API_KEY`` /
+            ``GOOGLE_API_KEY`` environment variables.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.useagentledger.com",
+        provider_keys: Optional[Dict[str, str]] = None,
+    ):
+        import os
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        keys = provider_keys or {}
+        self._provider_keys = {
+            provider: keys.get(provider) or os.environ.get(env_var, "")
+            for provider, env_var in _ENV_VARS.items()
+        }
+        self._block_cache: Dict[str, Dict[str, Any]] = {}
+        self._block_cache_lock = threading.Lock()
+
+    # ── Control plane ─────────────────────────────────────────────────────────
+
+    def _auth_headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    def _check_blocks(
+        self,
+        agent: str,
+        task: Optional[str],
+        user: Optional[str],
+        customer: Optional[str],
+    ) -> None:
+        cache_key = f"{agent}:{task or ''}:{user or ''}:{customer or ''}"
+        now = time.monotonic()
+
+        with self._block_cache_lock:
+            cached = self._block_cache.get(cache_key)
+            if cached and now < cached["expires_at"]:
+                if cached["isBlocked"]:
+                    raise AgentLedgerBlockError(
+                        f"AgentLedger kill switch: {cached['reason']}",
+                        cached["dimension"],
+                        cached["dimension_value"],
+                    )
+                return
+            if cached:
+                del self._block_cache[cache_key]
+
+        try:
+            status = _post_json(
+                f"{self._base_url}/api/v1/blocks/check",
+                {"agent": agent, "task": task, "user_id": user, "customer_id": customer},
+                self._auth_headers(),
+                _CONTROL_PLANE_TIMEOUT,
+            )
+        except Exception:
+            return  # fail open — AgentLedger being unreachable never blocks the call
+
+        with self._block_cache_lock:
+            self._block_cache[cache_key] = {**status, "expires_at": now + _BLOCK_CACHE_TTL}
+
+        if status.get("isBlocked"):
+            raise AgentLedgerBlockError(
+                f"AgentLedger kill switch: {status.get('reason', '')}",
+                status.get("dimension", ""),
+                status.get("dimension_value", ""),
+            )
+
+    def track(
+        self,
+        agent: str,
+        provider: str,
+        model: str,
+        input_tokens: int,
+        output_tokens: int,
+        task: Optional[str] = None,
+        user_id: Optional[str] = None,
+        customer_id: Optional[str] = None,
+        cost_usd: Optional[float] = None,
+        latency_ms: Optional[int] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+        input_hash: Optional[str] = None,
+        background: bool = True,
+    ) -> None:
+        """Record an LLM call. Cost is computed server-side when ``cost_usd`` is omitted.
+
+        With ``background=True`` (default) the HTTP call runs on a daemon thread
+        so tracking adds no latency to your agent. Errors are always swallowed.
+        """
+        body = {
+            "agent": agent,
+            "task": task,
+            "user_id": user_id,
+            "customer_id": customer_id,
+            "provider": provider,
+            "model": model,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "session_id": session_id,
+            "input_hash": input_hash,
+        }
+        if cost_usd is not None:
+            body["cost_usd"] = cost_usd
+        if latency_ms is not None:
+            body["latency_ms"] = latency_ms
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        def send() -> None:
+            try:
+                _post_json(f"{self._base_url}/api/v1/track", body, self._auth_headers(), _CONTROL_PLANE_TIMEOUT)
+            except Exception:
+                pass  # tracking failures never surface
+
+        if background:
+            threading.Thread(target=send, daemon=True).start()
+        else:
+            send()
+
+    def start_session(
+        self,
+        agent: str,
+        task: Optional[str] = None,
+        user: Optional[str] = None,
+        customer: Optional[str] = None,
+    ) -> Optional[str]:
+        """Create an explicit session for grouping multi-step agent work. Returns the session ID, or None on failure."""
+        try:
+            res = _post_json(
+                f"{self._base_url}/api/v1/track/sessions",
+                {"agent": agent, "task": task, "user_id": user, "customer_id": customer},
+                self._auth_headers(),
+                _CONTROL_PLANE_TIMEOUT,
+            )
+            return res.get("session_id")
+        except Exception:
+            return None
+
+    def end_session(self, session_id: str, success: bool = True) -> None:
+        try:
+            data = json.dumps({"success": success}).encode("utf-8")
+            req = urllib.request.Request(
+                f"{self._base_url}/api/v1/track/sessions/{session_id}", data=data, method="PATCH"
+            )
+            req.add_header("Content-Type", "application/json")
+            req.add_header("Authorization", f"Bearer {self._api_key}")
+            urllib.request.urlopen(req, timeout=_CONTROL_PLANE_TIMEOUT).close()
+        except Exception:
+            pass  # session errors never surface
+
+    def record_unit(
+        self,
+        agent: str,
+        session_id: Optional[str] = None,
+        unit_count: int = 1,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Record a completed business unit (for ROI reporting with custom_event counting)."""
+        try:
+            _post_json(
+                f"{self._base_url}/api/v1/roi/events",
+                {"agent": agent, "session_id": session_id, "unit_count": unit_count, "metadata": metadata},
+                self._auth_headers(),
+                _CONTROL_PLANE_TIMEOUT,
+            )
+        except Exception:
+            pass  # never surface recording errors
+
+    # ── LLM execution ─────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _hash_messages(messages: Iterable[Any]) -> Optional[str]:
+        try:
+            s = json.dumps(list(messages), separators=(",", ":"), default=str)[:4000]
+            return hashlib.sha256(s.encode("utf-8")).hexdigest()[:16]
+        except Exception:
+            return None
+
+    def _require_key(self, provider: str) -> str:
+        key = self._provider_keys.get(provider, "")
+        if not key:
+            raise ValueError(
+                f"{provider} API key not set. Pass provider_keys={{'{provider}': ...}} or set {_ENV_VARS[provider]}."
+            )
+        return key
+
+    def _provider_request(
+        self, provider: str, model: str, messages: List[Any], options: Dict[str, Any], stream: bool
+    ) -> urllib.request.Request:
+        if provider == "anthropic":
+            key = self._require_key("anthropic")
+            body = {"model": model, "messages": messages, **options}
+            if stream:
+                body["stream"] = True
+            req = urllib.request.Request(
+                "https://api.anthropic.com/v1/messages",
+                data=json.dumps(body).encode("utf-8"),
+                method="POST",
+            )
+            req.add_header("x-api-key", key)
+            req.add_header("anthropic-version", "2023-06-01")
+        elif provider == "openai":
+            key = self._require_key("openai")
+            body = {"model": model, "messages": messages, **options}
+            if stream:
+                body["stream"] = True
+                # include_usage makes OpenAI emit a final chunk carrying token usage
+                body.setdefault("stream_options", {"include_usage": True})
+            req = urllib.request.Request(
+                "https://api.openai.com/v1/chat/completions",
+                data=json.dumps(body).encode("utf-8"),
+                method="POST",
+            )
+            req.add_header("Authorization", f"Bearer {key}")
+        elif provider == "gemini":
+            key = self._require_key("gemini")
+            action = "streamGenerateContent?alt=sse" if stream else "generateContent"
+            body = {"contents": messages, **options}
+            req = urllib.request.Request(
+                f"https://generativelanguage.googleapis.com/v1beta/models/{model}:{action}",
+                data=json.dumps(body).encode("utf-8"),
+                method="POST",
+            )
+            req.add_header("x-goog-api-key", key)
+        else:
+            raise ValueError(f"Unsupported provider: {provider}. Use 'anthropic', 'openai', or 'gemini'.")
+
+        req.add_header("Content-Type", "application/json")
+        return req
+
+    def run(
+        self,
+        agent: str,
+        llm: Dict[str, Any],
+        task: Optional[str] = None,
+        user: Optional[str] = None,
+        customer: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> Any:
+        """Run an LLM call with kill-switch enforcement and automatic tracking.
+
+        ``llm`` must contain ``provider`` ('anthropic' | 'openai' | 'gemini'),
+        ``model``, and ``messages``; any other keys are passed through to the
+        provider (e.g. ``max_tokens``, ``temperature``).
+
+        Non-streaming (default): returns the provider's JSON response as a dict.
+        Streaming (``stream=True`` in ``llm``): returns a generator of parsed
+        stream events. Usage is tracked when the stream ends, including early
+        termination by the consumer.
+
+        Raises:
+            AgentLedgerBlockError: if an active kill-switch block matches this call.
+        """
+        llm = dict(llm)
+        provider = llm.pop("provider")
+        model = llm.pop("model")
+        messages = llm.pop("messages")
+        stream = bool(llm.pop("stream", False))
+
+        self._check_blocks(agent, task, user, customer)
+
+        start = time.monotonic()
+        req = self._provider_request(provider, model, messages, llm, stream)
+
+        def track_usage(input_tokens: int, output_tokens: int) -> None:
+            self.track(
+                agent=agent,
+                task=task,
+                user_id=user,
+                customer_id=customer,
+                provider=provider,
+                model=model,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                latency_ms=int((time.monotonic() - start) * 1000),
+                session_id=session_id,
+                input_hash=self._hash_messages(messages),
+            )
+
+        if stream:
+            try:
+                res = urllib.request.urlopen(req, timeout=_LLM_TIMEOUT)
+            except urllib.error.HTTPError as err:
+                detail = err.read().decode("utf-8", errors="replace")[:500]
+                raise RuntimeError(f"{provider} streaming request failed ({err.code}): {detail}") from err
+
+            def event_stream() -> Generator[Dict[str, Any], None, None]:
+                input_tokens = 0
+                output_tokens = 0
+                try:
+                    for event in _iter_sse(res):
+                        if provider == "anthropic":
+                            if event.get("type") == "message_start":
+                                input_tokens = event.get("message", {}).get("usage", {}).get("input_tokens", 0)
+                            elif event.get("type") == "message_delta":
+                                usage = event.get("usage") or {}
+                                if isinstance(usage.get("output_tokens"), int):
+                                    output_tokens = usage["output_tokens"]
+                        elif provider == "openai":
+                            usage = event.get("usage") or {}
+                            if isinstance(usage.get("prompt_tokens"), int):
+                                input_tokens = usage["prompt_tokens"]
+                                output_tokens = usage.get("completion_tokens", 0)
+                        elif provider == "gemini":
+                            usage = event.get("usageMetadata") or {}
+                            if isinstance(usage.get("promptTokenCount"), int):
+                                input_tokens = usage["promptTokenCount"]
+                                output_tokens = usage.get("candidatesTokenCount", 0)
+                        yield event
+                finally:
+                    res.close()
+                    # tracks whatever usage was observed, even on early termination
+                    track_usage(input_tokens, output_tokens)
+
+            return event_stream()
+
+        try:
+            with urllib.request.urlopen(req, timeout=_LLM_TIMEOUT) as res:
+                response = json.loads(res.read().decode("utf-8"))
+        except urllib.error.HTTPError as err:
+            # Provider returned an error body — surface it as the response, like the TS SDK
+            try:
+                response = json.loads(err.read().decode("utf-8"))
+            except Exception:
+                raise RuntimeError(f"{provider} request failed ({err.code})") from err
+
+        if provider == "anthropic":
+            usage = response.get("usage") or {}
+            track_usage(usage.get("input_tokens", 0), usage.get("output_tokens", 0))
+        elif provider == "openai":
+            usage = response.get("usage") or {}
+            track_usage(usage.get("prompt_tokens", 0), usage.get("completion_tokens", 0))
+        else:  # gemini
+            usage = response.get("usageMetadata") or {}
+            track_usage(usage.get("promptTokenCount", 0), usage.get("candidatesTokenCount", 0))
+
+        return response

useagentledger-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: useagentledger
+Version: 0.1.0
+Summary: AgentLedger Python SDK — track, attribute, and govern AI agent spend across OpenAI, Anthropic, and Gemini.
+License: MIT
+Project-URL: Homepage, https://useagentledger.com
+Project-URL: Documentation, https://useagentledger.com/blog
+Keywords: llm,cost-tracking,ai-agents,openai,anthropic,gemini,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# AgentLedger Python SDK
+
+Track, attribute, and govern AI agent spend across OpenAI, Anthropic, and Gemini — with per-agent / per-task / per-user / per-customer cost attribution, kill switches, loop detection, and ROI reporting.
+
+Zero dependencies. Python 3.9+.
+
+```bash
+pip install useagentledger
+```
+
+(The import name is `agentledger`: `from agentledger import AgentLedger`.)
+
+## Quick start
+
+```python
+from agentledger import AgentLedger
+
+al = AgentLedger(api_key="al_live_...")  # provider keys read from env by default
+
+response = al.run(
+    agent="invoice-processor",
+    task="extraction",
+    customer="acme-corp",
+    llm={
+        "provider": "anthropic",
+        "model": "claude-sonnet-4-6",
+        "max_tokens": 1024,
+        "messages": [{"role": "user", "content": "Extract line items from this invoice: ..."}],
+    },
+)
+print(response["content"][0]["text"])
+```
+
+Every call is tracked automatically — token counts, latency, and attribution dimensions. Cost is computed server-side from AgentLedger's pricing table (134+ models), so the SDK never goes stale.
+
+## Kill switch
+
+`run()` checks AgentLedger's block list before every call (cached 5 seconds). If an alert rule has blocked this agent, task, user, or customer, the call raises **before** any provider spend happens:
+
+```python
+from agentledger import AgentLedger, AgentLedgerBlockError
+
+try:
+    al.run(agent="support-bot", customer="acme-corp", llm={...})
+except AgentLedgerBlockError as e:
+    print(f"Blocked: {e} (dimension={e.dimension}, value={e.dimension_value})")
+```
+
+The check **fails open** — if AgentLedger is unreachable, your LLM call proceeds normally. Governance never becomes a point of failure.
+
+## Streaming
+
+Pass `stream=True` and iterate the returned generator. Usage is captured from the stream's own events and tracked when the stream ends (even if you stop early):
+
+```python
+stream = al.run(
+    agent="chat-assistant",
+    user="user-42",
+    llm={
+        "provider": "openai",
+        "model": "gpt-4o",
+        "stream": True,
+        "messages": [{"role": "user", "content": "Hello!"}],
+    },
+)
+for event in stream:
+    delta = event.get("choices", [{}])[0].get("delta", {}).get("content")
+    if delta:
+        print(delta, end="", flush=True)
+```
+
+Works for all three providers (Anthropic `message_start`/`message_delta` events, OpenAI usage chunk, Gemini `usageMetadata`).
+
+## Sessions (multi-step agents)
+
+Group a multi-step task into one session so loop detection and per-session cost work across steps:
+
+```python
+session_id = al.start_session(agent="research-bot", task="report")
+for step in plan:
+    al.run(agent="research-bot", session_id=session_id, llm={...})
+al.end_session(session_id, success=True)
+```
+
+Calls without an explicit session are auto-grouped server-side (same agent + task within a 10-minute window).
+
+## Track calls you make yourself
+
+Already using the official `openai` / `anthropic` clients? Just report usage:
+
+```python
+result = openai_client.chat.completions.create(model="gpt-4o-mini", messages=msgs)
+
+al.track(
+    agent="summarizer",
+    customer="acme-corp",
+    provider="openai",
+    model="gpt-4o-mini",
+    input_tokens=result.usage.prompt_tokens,
+    output_tokens=result.usage.completion_tokens,
+)
+```
+
+`track()` runs on a background thread by default (zero added latency) and swallows all errors. Pass `background=False` to send synchronously.
+
+## ROI units
+
+Record completed business outcomes for cost-per-outcome reporting (`custom_event` count method):
+
+```python
+al.record_unit(agent="invoice-processor", unit_count=1)
+```
+
+## Configuration
+
+```python
+al = AgentLedger(
+    api_key="al_live_...",
+    base_url="https://api.useagentledger.com",   # or your self-hosted proxy
+    provider_keys={                               # optional — env vars used otherwise
+        "anthropic": "...",   # ANTHROPIC_API_KEY
+        "openai": "...",      # OPENAI_API_KEY
+        "gemini": "...",      # GOOGLE_API_KEY
+    },
+)
+```

useagentledger-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+agentledger/__init__.py,sha256=UqAcYFbiWZH8kyvjWPA8E-nsO7QwB7dRdXfm_tdM4io,16703
+useagentledger-0.1.0.dist-info/METADATA,sha256=UiCLId9DVzPAClaSN2rlis_Oqw2OrkR67g1biBj97qw,4751
+useagentledger-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+useagentledger-0.1.0.dist-info/top_level.txt,sha256=5yo3cw8VcXmvosSKHloeSGsojarwfgP12L4B1EoL74A,12
+useagentledger-0.1.0.dist-info/RECORD,,

useagentledger-0.1.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
+

useagentledger-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentledger