spyllm 0.2.0__tar.gz

spyllm-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+.pytest_cache/
+.venv/
+*.pyc
+*.pyo
+*.pyd
+
+node_modules/
+dist/
+coverage/
+.vite/
+
+.env
+.env.*
+!.env.example
+
+.DS_Store
+Thumbs.db
+
+.idea/
+.vscode/
+
+backend/.mypy_cache/
+backend/.ruff_cache/
+frontend/.eslintcache

spyllm-0.2.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: spyllm
+Version: 0.2.0
+Summary: Two-line automatic LLM tracing. Works with OpenAI, Anthropic, and more.
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: wrapt>=1.14.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'

spyllm-0.2.0/README.md

@@ -0,0 +1,82 @@
+# SpyLLM Python SDK
+
+Automatic LLM tracing in two lines. Works with OpenAI, Anthropic, and more.
+
+## Quick Start
+
+```python
+import spyllm
+
+spyllm.init(api_key="sk-...")
+
+# That's it. Every OpenAI and Anthropic call is now automatically traced.
+from openai import OpenAI
+
+client = OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+# Prompt, response, tokens, cost, and latency are captured automatically.
+```
+
+## Install
+
+```bash
+pip install spyllm
+```
+
+## What Gets Captured
+
+Every LLM call automatically records:
+
+- **Prompt** — full message history sent to the model
+- **Response** — the model's output
+- **Token count** — input + output tokens
+- **Cost** — estimated USD cost based on model pricing
+- **Latency** — wall-clock time for the API call
+- **Tool calls** — if the model invoked tools/functions
+- **Errors** — failed calls with the exception message
+
+## Supported Providers
+
+| Provider   | Auto-instrumented |
+|------------|-------------------|
+| OpenAI     | Yes               |
+| Anthropic  | Yes               |
+
+## Advanced Usage
+
+### Manual Tracing
+
+```python
+from spyllm import SpyLLMClient
+
+client = SpyLLMClient(api_key="sk-...", base_url="https://api.spyllm.com")
+client.trace(
+    agent_name="my-agent",
+    prompt="What is 2+2?",
+    response="4",
+    token_count=15,
+    cost_usd=0.001,
+)
+```
+
+### Decorator
+
+```python
+from spyllm import agent_trace, init
+
+init(api_key="sk-...")
+
+@agent_trace("my-pipeline")
+def run_pipeline(query: str) -> str:
+    # your code here
+    return result
+```
+
+### Disable Auto-instrumentation
+
+```python
+spyllm.init(api_key="sk-...", instrument=False)
+```

spyllm-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "spyllm"
+version = "0.2.0"
+description = "Two-line automatic LLM tracing. Works with OpenAI, Anthropic, and more."
+requires-python = ">=3.9"
+dependencies = [
+  "httpx>=0.24.0",
+  "wrapt>=1.14.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.18.0"]
+otel = [
+  "opentelemetry-api>=1.20.0",
+  "opentelemetry-sdk>=1.20.0",
+  "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["spyllm"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

spyllm-0.2.0/spyllm/__init__.py

@@ -0,0 +1,64 @@
+"""SpyLLM Python SDK — two-line automatic LLM tracing.
+
+Usage::
+
+    import spyllm
+    spyllm.init(api_key="sk-...")
+
+    # Every OpenAI / Anthropic call is now auto-traced.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .client import SpyLLMClient, agent_trace
+
+__all__ = [
+    "init",
+    "shutdown",
+    "SpyLLMClient",
+    "agent_trace",
+]
+
+_client: Optional[SpyLLMClient] = None
+
+
+def init(
+    api_key: str,
+    *,
+    base_url: str = "https://api.spyllm.dev",
+    instrument: bool = True,
+) -> SpyLLMClient:
+    """Initialise the SpyLLM SDK.
+
+    This creates a background batcher, monkey-patches supported LLM providers,
+    and returns a client instance for manual tracing if needed.
+
+    Args:
+        api_key: Your SpyLLM API key.
+        base_url: Override the API endpoint (useful for self-hosted).
+        instrument: If True (default), auto-patch OpenAI and Anthropic.
+    """
+    global _client
+
+    from .batcher import TraceBatcher
+    from . import instrumentor
+
+    batcher = TraceBatcher(api_key=api_key, base_url=base_url)
+    instrumentor._batcher = batcher
+
+    _client = SpyLLMClient(api_key=api_key, base_url=base_url)
+
+    if instrument:
+        instrumentor.patch_all()
+
+    return _client
+
+
+def shutdown() -> None:
+    """Flush pending traces and shut down the background thread."""
+    from . import instrumentor
+
+    if instrumentor._batcher is not None:
+        instrumentor._batcher.shutdown()

spyllm-0.2.0/spyllm/batcher.py

@@ -0,0 +1,85 @@
+"""Background trace batcher.
+
+Collects traces in a thread-safe queue and flushes them to the SpyLLM API in
+a daemon thread so instrumented calls never block on network I/O.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import queue
+import threading
+from typing import Any, Optional
+
+import httpx
+
+logger = logging.getLogger("spyllm")
+
+_MAX_BATCH = 50
+_FLUSH_INTERVAL = 2.0  # seconds
+
+
+class TraceBatcher:
+    def __init__(self, api_key: str, base_url: str) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._queue: queue.Queue[dict[str, Any]] = queue.Queue()
+        self._shutdown = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        atexit.register(self.flush)
+
+    def enqueue(self, trace: dict[str, Any]) -> None:
+        self._queue.put(trace)
+
+    def flush(self) -> None:
+        """Drain the queue and send everything. Called at exit or manually."""
+        batch: list[dict[str, Any]] = []
+        while True:
+            try:
+                batch.append(self._queue.get_nowait())
+            except queue.Empty:
+                break
+        if batch:
+            self._send(batch)
+
+    def shutdown(self) -> None:
+        self._shutdown.set()
+        self.flush()
+
+    def _run(self) -> None:
+        while not self._shutdown.is_set():
+            batch: list[dict[str, Any]] = []
+            try:
+                batch.append(self._queue.get(timeout=_FLUSH_INTERVAL))
+            except queue.Empty:
+                continue
+
+            while len(batch) < _MAX_BATCH:
+                try:
+                    batch.append(self._queue.get_nowait())
+                except queue.Empty:
+                    break
+
+            self._send(batch)
+
+    def _send(self, batch: list[dict[str, Any]]) -> None:
+        if not batch:
+            return
+        try:
+            with httpx.Client(timeout=10.0) as client:
+                if len(batch) == 1:
+                    client.post(
+                        f"{self._base_url}/v1/traces",
+                        json=batch[0],
+                        headers={"X-API-Key": self._api_key},
+                    )
+                else:
+                    client.post(
+                        f"{self._base_url}/v1/traces/batch",
+                        json=batch,
+                        headers={"X-API-Key": self._api_key},
+                    )
+        except Exception:
+            logger.debug("spyllm: failed to send %d traces", len(batch), exc_info=True)

spyllm-0.2.0/spyllm/client.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import functools
+import threading
+import time
+from typing import Any, Optional
+
+import httpx
+
+
+class SpyLLMClient:
+    """Low-level client for the SpyLLM REST API.
+
+    Most users should use ``spyllm.init()`` instead, which sets up automatic
+    instrumentation.  This class is useful for manual tracing or advanced use.
+    """
+
+    def __init__(self, api_key: str, base_url: str = "https://api.spyllm.com") -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"X-API-Key": self.api_key},
+            timeout=30.0,
+        )
+
+    def trace(
+        self,
+        agent_name: str,
+        prompt: str,
+        response: str,
+        *,
+        trace_type: str = "llm_call",
+        status: str = "success",
+        latency_ms: Optional[float] = None,
+        token_count: Optional[int] = None,
+        cost_usd: Optional[float] = None,
+        session_id: Optional[str] = None,
+        metadata: Optional[str] = None,
+        tool_calls: Optional[str] = None,
+    ) -> str:
+        payload: dict[str, Any] = {
+            "agent_name": agent_name,
+            "prompt": prompt,
+            "response": response,
+            "trace_type": trace_type,
+            "status": status,
+        }
+        for key, val in [
+            ("latency_ms", latency_ms),
+            ("token_count", token_count),
+            ("cost_usd", cost_usd),
+            ("session_id", session_id),
+            ("metadata", metadata),
+            ("tool_calls", tool_calls),
+        ]:
+            if val is not None:
+                payload[key] = val
+
+        resp = self._http.post("/v1/traces", json=payload)
+        resp.raise_for_status()
+        return resp.json()["id"]
+
+    def search(self, query: str, *, top_k: int = 20, status: Optional[str] = None) -> list[dict[str, Any]]:
+        payload: dict[str, Any] = {"query": query, "top_k": top_k}
+        if status:
+            payload["status"] = status
+        resp = self._http.post("/v1/search", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def agent_trace(agent_name: str, client: Optional[SpyLLMClient] = None) -> Any:
+    """Decorator that automatically traces a function call."""
+    def decorator(func: Any) -> Any:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            start = time.time()
+            result = None
+            call_status = "success"
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as exc:
+                call_status = "error"
+                result = str(exc)
+                raise
+            finally:
+                sdk_client = client or _get_default_client()
+                if sdk_client:
+                    threading.Thread(
+                        target=sdk_client.trace,
+                        kwargs={
+                            "agent_name": agent_name,
+                            "prompt": str(args) + str(kwargs),
+                            "response": str(result),
+                            "status": call_status,
+                            "latency_ms": (time.time() - start) * 1000,
+                        },
+                        daemon=True,
+                    ).start()
+        return wrapper
+    return decorator
+
+
+def _get_default_client() -> Optional[SpyLLMClient]:
+    from . import _client
+    return _client

spyllm-0.2.0/spyllm/decorators.py

@@ -0,0 +1,3 @@
+from .client import agent_trace
+
+__all__ = ["agent_trace"]

spyllm-0.2.0/spyllm/instrumentor.py

@@ -0,0 +1,459 @@
+"""Auto-instrumentation for OpenAI and Anthropic Python SDKs.
+
+When `patch_openai()` or `patch_anthropic()` is called, the respective SDK's
+`create` methods are monkey-patched via `wrapt` so every LLM call is
+automatically traced — zero code changes required for the end user.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import types
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from wrapt import wrap_function_wrapper
+
+from .pricing import estimate_cost
+
+logger = logging.getLogger("spyllm")
+
+# Will be set by `init()` in __init__.py
+_batcher: Any = None
+
+
+@dataclass
+class _PatchTarget:
+    module: str
+    cls: str
+    method: str
+    provider: str
+    is_async: bool
+
+
+# ---------------------------------------------------------------------------
+# OpenAI targets
+# ---------------------------------------------------------------------------
+
+_OPENAI_TARGETS: list[_PatchTarget] = [
+    _PatchTarget("openai.resources.chat.completions", "Completions", "create", "openai", False),
+    _PatchTarget("openai.resources.chat.completions", "AsyncCompletions", "create", "openai", True),
+    _PatchTarget("openai.resources.completions", "Completions", "create", "openai", False),
+    _PatchTarget("openai.resources.completions", "AsyncCompletions", "create", "openai", True),
+]
+
+# ---------------------------------------------------------------------------
+# Anthropic targets
+# ---------------------------------------------------------------------------
+
+_ANTHROPIC_TARGETS: list[_PatchTarget] = [
+    _PatchTarget("anthropic.resources.messages", "Messages", "create", "anthropic", False),
+    _PatchTarget("anthropic.resources.messages", "AsyncMessages", "create", "anthropic", True),
+]
+
+
+# ---------------------------------------------------------------------------
+# Extraction helpers
+# ---------------------------------------------------------------------------
+
+def _safe_json(obj: Any) -> str:
+    try:
+        return json.dumps(obj, default=str)
+    except Exception:
+        return str(obj)
+
+
+def _extract_openai_data(kwargs: dict[str, Any], response: Any) -> dict[str, Any]:
+    """Pull trace fields from an OpenAI chat/completion response."""
+    resp_dict = response.__dict__ if hasattr(response, "__dict__") else {}
+    usage = getattr(response, "usage", None)
+
+    model = getattr(response, "model", None) or kwargs.get("model", "unknown")
+    input_tokens = getattr(usage, "prompt_tokens", 0) or 0
+    output_tokens = getattr(usage, "completion_tokens", 0) or 0
+
+    messages = kwargs.get("messages", [])
+    prompt_str = _safe_json(messages) if messages else kwargs.get("prompt", "")
+
+    choices = getattr(response, "choices", [])
+    response_text = ""
+    tool_calls_data = None
+    if choices:
+        choice = choices[0]
+        msg = getattr(choice, "message", None)
+        if msg:
+            response_text = getattr(msg, "content", "") or ""
+            tc = getattr(msg, "tool_calls", None)
+            if tc:
+                tool_calls_data = _safe_json([t.__dict__ for t in tc] if hasattr(tc[0], "__dict__") else tc)
+        elif hasattr(choice, "text"):
+            response_text = getattr(choice, "text", "")
+
+    cost = estimate_cost(model, input_tokens, output_tokens)
+
+    return {
+        "agent_name": model,
+        "prompt": prompt_str if isinstance(prompt_str, str) else _safe_json(prompt_str),
+        "response": response_text,
+        "trace_type": "llm_call",
+        "status": "success",
+        "token_count": input_tokens + output_tokens,
+        "cost_usd": cost,
+        "tool_calls": tool_calls_data,
+        "metadata": _safe_json({
+            "provider": "openai",
+            "model": model,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+        }),
+    }
+
+
+def _extract_anthropic_data(kwargs: dict[str, Any], response: Any) -> dict[str, Any]:
+    """Pull trace fields from an Anthropic messages response."""
+    model = getattr(response, "model", None) or kwargs.get("model", "unknown")
+    usage = getattr(response, "usage", None)
+    input_tokens = getattr(usage, "input_tokens", 0) or 0
+    output_tokens = getattr(usage, "output_tokens", 0) or 0
+
+    messages = kwargs.get("messages", [])
+    system = kwargs.get("system", "")
+    prompt_parts = []
+    if system:
+        prompt_parts.append({"role": "system", "content": system})
+    prompt_parts.extend(messages)
+    prompt_str = _safe_json(prompt_parts)
+
+    content_blocks = getattr(response, "content", [])
+    response_text = ""
+    tool_calls_data = None
+    tool_uses = []
+    for block in content_blocks:
+        block_type = getattr(block, "type", "")
+        if block_type == "text":
+            response_text += getattr(block, "text", "")
+        elif block_type == "tool_use":
+            tool_uses.append({
+                "id": getattr(block, "id", ""),
+                "name": getattr(block, "name", ""),
+                "input": getattr(block, "input", {}),
+            })
+    if tool_uses:
+        tool_calls_data = _safe_json(tool_uses)
+
+    cost = estimate_cost(model, input_tokens, output_tokens)
+
+    return {
+        "agent_name": model,
+        "prompt": prompt_str,
+        "response": response_text,
+        "trace_type": "llm_call",
+        "status": "success",
+        "token_count": input_tokens + output_tokens,
+        "cost_usd": cost,
+        "tool_calls": tool_calls_data,
+        "metadata": _safe_json({
+            "provider": "anthropic",
+            "model": model,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+        }),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Streaming wrappers
+# ---------------------------------------------------------------------------
+
+class _OpenAIStreamProxy:
+    """Wraps an OpenAI sync Stream to capture chunks, then sends the trace
+    when the stream is exhausted."""
+
+    def __init__(self, stream: Any, kwargs: dict[str, Any], start_time: float) -> None:
+        self._stream = stream
+        self._kwargs = kwargs
+        self._start_time = start_time
+        self._chunks: list[Any] = []
+
+    def __iter__(self) -> Any:
+        try:
+            for chunk in self._stream:
+                self._chunks.append(chunk)
+                yield chunk
+        finally:
+            self._finalize()
+
+    def __next__(self) -> Any:
+        try:
+            chunk = next(self._stream)
+            self._chunks.append(chunk)
+            return chunk
+        except StopIteration:
+            self._finalize()
+            raise
+
+    def __enter__(self) -> "_OpenAIStreamProxy":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self._finalize()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._stream, name)
+
+    def _finalize(self) -> None:
+        if not self._chunks or _batcher is None:
+            return
+        latency_ms = (time.time() - self._start_time) * 1000
+        model, content, usage, tool_calls = _reassemble_openai_stream(self._chunks)
+        input_tokens = 0
+        output_tokens = 0
+        if usage:
+            input_tokens = getattr(usage, "prompt_tokens", 0) or 0
+            output_tokens = getattr(usage, "completion_tokens", 0) or 0
+
+        cost = estimate_cost(model or self._kwargs.get("model", "unknown"), input_tokens, output_tokens)
+        messages = self._kwargs.get("messages", [])
+        trace = {
+            "agent_name": model or self._kwargs.get("model", "unknown"),
+            "prompt": _safe_json(messages),
+            "response": content or "",
+            "trace_type": "llm_call",
+            "status": "success",
+            "latency_ms": latency_ms,
+            "token_count": input_tokens + output_tokens,
+            "cost_usd": cost,
+            "tool_calls": _safe_json(tool_calls) if tool_calls else None,
+            "metadata": _safe_json({"provider": "openai", "model": model, "streamed": True}),
+        }
+        _batcher.enqueue({k: v for k, v in trace.items() if v is not None})
+        self._chunks = []
+
+
+class _OpenAIAsyncStreamProxy:
+    """Async variant of the stream proxy."""
+
+    def __init__(self, stream: Any, kwargs: dict[str, Any], start_time: float) -> None:
+        self._stream = stream
+        self._kwargs = kwargs
+        self._start_time = start_time
+        self._chunks: list[Any] = []
+
+    async def __aiter__(self) -> Any:
+        try:
+            async for chunk in self._stream:
+                self._chunks.append(chunk)
+                yield chunk
+        finally:
+            self._finalize()
+
+    async def __anext__(self) -> Any:
+        try:
+            chunk = await self._stream.__anext__()
+            self._chunks.append(chunk)
+            return chunk
+        except StopAsyncIteration:
+            self._finalize()
+            raise
+
+    async def __aenter__(self) -> "_OpenAIAsyncStreamProxy":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        self._finalize()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._stream, name)
+
+    def _finalize(self) -> None:
+        if not self._chunks or _batcher is None:
+            return
+        latency_ms = (time.time() - self._start_time) * 1000
+        model, content, usage, tool_calls = _reassemble_openai_stream(self._chunks)
+        input_tokens = 0
+        output_tokens = 0
+        if usage:
+            input_tokens = getattr(usage, "prompt_tokens", 0) or 0
+            output_tokens = getattr(usage, "completion_tokens", 0) or 0
+
+        cost = estimate_cost(model or self._kwargs.get("model", "unknown"), input_tokens, output_tokens)
+        messages = self._kwargs.get("messages", [])
+        trace = {
+            "agent_name": model or self._kwargs.get("model", "unknown"),
+            "prompt": _safe_json(messages),
+            "response": content or "",
+            "trace_type": "llm_call",
+            "status": "success",
+            "latency_ms": latency_ms,
+            "token_count": input_tokens + output_tokens,
+            "cost_usd": cost,
+            "tool_calls": _safe_json(tool_calls) if tool_calls else None,
+            "metadata": _safe_json({"provider": "openai", "model": model, "streamed": True}),
+        }
+        _batcher.enqueue({k: v for k, v in trace.items() if v is not None})
+        self._chunks = []
+
+
+def _reassemble_openai_stream(chunks: list[Any]) -> tuple[Optional[str], str, Any, Optional[list[Any]]]:
+    """Reassemble streamed OpenAI chunks into (model, content, usage, tool_calls)."""
+    model: Optional[str] = None
+    content_parts: list[str] = []
+    usage = None
+    tool_calls: dict[int, dict[str, str]] = {}
+
+    for chunk in chunks:
+        c = chunk if isinstance(chunk, dict) else chunk.__dict__
+        model = model or c.get("model")
+        usage = c.get("usage") or usage
+        for choice in c.get("choices", []):
+            ch = choice if isinstance(choice, dict) else choice.__dict__
+            delta = ch.get("delta")
+            if delta is None:
+                continue
+            d = delta if isinstance(delta, dict) else delta.__dict__
+            if d.get("content"):
+                content_parts.append(d["content"])
+            if d.get("tool_calls"):
+                for tc in d["tool_calls"]:
+                    tc_d = tc if isinstance(tc, dict) else tc.__dict__
+                    idx = tc_d.get("index", 0)
+                    if idx not in tool_calls:
+                        func = tc_d.get("function", {})
+                        func_d = func if isinstance(func, dict) else func.__dict__
+                        tool_calls[idx] = {"name": func_d.get("name", ""), "arguments": func_d.get("arguments", "")}
+                    else:
+                        func = tc_d.get("function", {})
+                        func_d = func if isinstance(func, dict) else func.__dict__
+                        tool_calls[idx]["name"] = tool_calls[idx]["name"] or func_d.get("name", "")
+                        tool_calls[idx]["arguments"] += func_d.get("arguments", "")
+
+    tc_list = list(tool_calls.values()) if tool_calls else None
+    return model, "".join(content_parts), usage, tc_list
+
+
+# ---------------------------------------------------------------------------
+# Wrapper factories
+# ---------------------------------------------------------------------------
+
+def _make_sync_wrapper(target: _PatchTarget) -> Any:
+    extractor = _extract_openai_data if target.provider == "openai" else _extract_anthropic_data
+
+    def wrapper(wrapped: Any, instance: Any, args: Any, kwargs: Any) -> Any:
+        if _batcher is None:
+            return wrapped(*args, **kwargs)
+
+        start = time.time()
+        try:
+            response = wrapped(*args, **kwargs)
+        except Exception as exc:
+            latency_ms = (time.time() - start) * 1000
+            trace = {
+                "agent_name": kwargs.get("model", "unknown"),
+                "prompt": _safe_json(kwargs.get("messages", [])),
+                "response": str(exc),
+                "trace_type": "llm_call",
+                "status": "error",
+                "latency_ms": latency_ms,
+                "metadata": _safe_json({"provider": target.provider, "error": str(exc)}),
+            }
+            _batcher.enqueue(trace)
+            raise
+
+        if _is_stream(response):
+            return _OpenAIStreamProxy(response, kwargs, start)
+
+        latency_ms = (time.time() - start) * 1000
+        trace = extractor(kwargs, response)
+        trace["latency_ms"] = latency_ms
+        _batcher.enqueue({k: v for k, v in trace.items() if v is not None})
+        return response
+
+    return wrapper
+
+
+def _make_async_wrapper(target: _PatchTarget) -> Any:
+    extractor = _extract_openai_data if target.provider == "openai" else _extract_anthropic_data
+
+    async def wrapper(wrapped: Any, instance: Any, args: Any, kwargs: Any) -> Any:
+        if _batcher is None:
+            return await wrapped(*args, **kwargs)
+
+        start = time.time()
+        try:
+            response = await wrapped(*args, **kwargs)
+        except Exception as exc:
+            latency_ms = (time.time() - start) * 1000
+            trace = {
+                "agent_name": kwargs.get("model", "unknown"),
+                "prompt": _safe_json(kwargs.get("messages", [])),
+                "response": str(exc),
+                "trace_type": "llm_call",
+                "status": "error",
+                "latency_ms": latency_ms,
+                "metadata": _safe_json({"provider": target.provider, "error": str(exc)}),
+            }
+            _batcher.enqueue(trace)
+            raise
+
+        if _is_stream(response):
+            return _OpenAIAsyncStreamProxy(response, kwargs, start)
+
+        latency_ms = (time.time() - start) * 1000
+        trace = extractor(kwargs, response)
+        trace["latency_ms"] = latency_ms
+        _batcher.enqueue({k: v for k, v in trace.items() if v is not None})
+        return response
+
+    return wrapper
+
+
+def _is_stream(obj: Any) -> bool:
+    return (
+        isinstance(obj, types.GeneratorType)
+        or isinstance(obj, types.AsyncGeneratorType)
+        or type(obj).__name__ in ("Stream", "AsyncStream")
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public patching API
+# ---------------------------------------------------------------------------
+
+def patch_openai() -> None:
+    """Monkey-patch the OpenAI Python SDK so all calls are auto-traced."""
+    try:
+        import openai  # noqa: F401
+    except ImportError:
+        logger.debug("openai not installed, skipping instrumentation")
+        return
+
+    for target in _OPENAI_TARGETS:
+        try:
+            wrapper = _make_async_wrapper(target) if target.is_async else _make_sync_wrapper(target)
+            wrap_function_wrapper(target.module, f"{target.cls}.{target.method}", wrapper)
+        except Exception:
+            logger.debug("Failed to patch %s.%s.%s", target.module, target.cls, target.method, exc_info=True)
+
+
+def patch_anthropic() -> None:
+    """Monkey-patch the Anthropic Python SDK so all calls are auto-traced."""
+    try:
+        import anthropic  # noqa: F401
+    except ImportError:
+        logger.debug("anthropic not installed, skipping instrumentation")
+        return
+
+    for target in _ANTHROPIC_TARGETS:
+        try:
+            wrapper = _make_async_wrapper(target) if target.is_async else _make_sync_wrapper(target)
+            wrap_function_wrapper(target.module, f"{target.cls}.{target.method}", wrapper)
+        except Exception:
+            logger.debug("Failed to patch %s.%s.%s", target.module, target.cls, target.method, exc_info=True)
+
+
+def patch_all() -> None:
+    """Patch all supported providers."""
+    patch_openai()
+    patch_anthropic()

spyllm-0.2.0/spyllm/otel.py

@@ -0,0 +1,20 @@
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+
+def init_otel(
+    api_key: str,
+    endpoint: str = "https://api.spyllm.com",
+    service_name: str = "my-agent",
+):
+    provider = TracerProvider(resource=Resource.create({"service.name": service_name}))
+    exporter = OTLPSpanExporter(
+        endpoint=f"{endpoint}/v1/traces/otlp",
+        headers={"X-API-Key": api_key},
+    )
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+    return provider

spyllm-0.2.0/spyllm/pricing.py

@@ -0,0 +1,81 @@
+"""Built-in model pricing table.
+
+Costs are in USD per token (not per 1K tokens). We maintain this table so the
+SDK can estimate `cost_usd` without any user configuration.  Prices should be
+updated periodically as providers change their rates.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+# fmt: off
+MODEL_COSTS: dict[str, dict[str, float]] = {
+    # OpenAI
+    "gpt-4o":                {"input": 2.50  / 1_000_000, "output": 10.00 / 1_000_000},
+    "gpt-4o-2024-11-20":     {"input": 2.50  / 1_000_000, "output": 10.00 / 1_000_000},
+    "gpt-4o-2024-08-06":     {"input": 2.50  / 1_000_000, "output": 10.00 / 1_000_000},
+    "gpt-4o-2024-05-13":     {"input": 5.00  / 1_000_000, "output": 15.00 / 1_000_000},
+    "gpt-4o-mini":           {"input": 0.15  / 1_000_000, "output": 0.60  / 1_000_000},
+    "gpt-4o-mini-2024-07-18":{"input": 0.15  / 1_000_000, "output": 0.60  / 1_000_000},
+    "gpt-4-turbo":           {"input": 10.00 / 1_000_000, "output": 30.00 / 1_000_000},
+    "gpt-4":                 {"input": 30.00 / 1_000_000, "output": 60.00 / 1_000_000},
+    "gpt-3.5-turbo":         {"input": 0.50  / 1_000_000, "output": 1.50  / 1_000_000},
+    "o1":                    {"input": 15.00 / 1_000_000, "output": 60.00 / 1_000_000},
+    "o1-mini":               {"input": 3.00  / 1_000_000, "output": 12.00 / 1_000_000},
+    "o1-preview":            {"input": 15.00 / 1_000_000, "output": 60.00 / 1_000_000},
+    "o3-mini":               {"input": 1.10  / 1_000_000, "output": 4.40  / 1_000_000},
+
+    # Anthropic
+    "claude-3-5-sonnet-20241022": {"input": 3.00 / 1_000_000, "output": 15.00 / 1_000_000},
+    "claude-3-5-sonnet-20240620": {"input": 3.00 / 1_000_000, "output": 15.00 / 1_000_000},
+    "claude-3-5-haiku-20241022":  {"input": 0.80 / 1_000_000, "output": 4.00  / 1_000_000},
+    "claude-3-opus-20240229":     {"input": 15.00/ 1_000_000, "output": 75.00 / 1_000_000},
+    "claude-3-sonnet-20240229":   {"input": 3.00 / 1_000_000, "output": 15.00 / 1_000_000},
+    "claude-3-haiku-20240307":    {"input": 0.25 / 1_000_000, "output": 1.25  / 1_000_000},
+    "claude-sonnet-4-20250514":   {"input": 3.00 / 1_000_000, "output": 15.00 / 1_000_000},
+    "claude-haiku-4-20250514":    {"input": 0.80 / 1_000_000, "output": 4.00  / 1_000_000},
+}
+# fmt: on
+
+# Prefix aliases so "gpt-4o-2024-*" matches even if the exact snapshot isn't listed.
+_PREFIX_MAP: dict[str, str] = {
+    "gpt-4o-mini": "gpt-4o-mini",
+    "gpt-4o": "gpt-4o",
+    "gpt-4-turbo": "gpt-4-turbo",
+    "gpt-4": "gpt-4",
+    "gpt-3.5-turbo": "gpt-3.5-turbo",
+    "o3-mini": "o3-mini",
+    "o1-mini": "o1-mini",
+    "o1-preview": "o1-preview",
+    "o1": "o1",
+    "claude-3-5-sonnet": "claude-3-5-sonnet-20241022",
+    "claude-3-5-haiku": "claude-3-5-haiku-20241022",
+    "claude-3-opus": "claude-3-opus-20240229",
+    "claude-3-sonnet": "claude-3-sonnet-20240229",
+    "claude-3-haiku": "claude-3-haiku-20240307",
+    "claude-sonnet-4": "claude-sonnet-4-20250514",
+    "claude-haiku-4": "claude-haiku-4-20250514",
+}
+
+
+def _resolve_model(model: str) -> Optional[str]:
+    if model in MODEL_COSTS:
+        return model
+    for prefix, canonical in _PREFIX_MAP.items():
+        if model.startswith(prefix):
+            return canonical
+    return None
+
+
+def estimate_cost(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+) -> Optional[float]:
+    """Return estimated USD cost, or None if the model is unknown."""
+    resolved = _resolve_model(model)
+    if resolved is None:
+        return None
+    costs = MODEL_COSTS[resolved]
+    return input_tokens * costs["input"] + output_tokens * costs["output"]