agentlens-py 0.1.0__py3-none-any.whl

agentlens/__init__.py

@@ -0,0 +1,62 @@
+"""AgentLens Python SDK — zero-overhead observability for AI agents.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+from typing import Optional
+
+from agentlens.client import AgentLensClient
+from agentlens.decorators import span, trace
+from agentlens.instruments.anthropic import instrument_anthropic
+from agentlens.instruments.openai import instrument_openai
+
+__all__ = [
+    "init",
+    "instrument_openai",
+    "instrument_anthropic",
+    "trace",
+    "span",
+    "flush",
+]
+
+_global_client: Optional[AgentLensClient] = None
+logger = logging.getLogger("agentlens")
+
+
+def init(
+    api_key: str,
+    base_url: str = "http://localhost:8000",
+    debug: bool = False,
+    enabled: bool = True,
+) -> AgentLensClient:
+    """Initialize the global AgentLens client."""
+    global _global_client
+
+    if _global_client is not None:
+        _global_client.stop()
+
+    _global_client = AgentLensClient(
+        api_key=api_key,
+        base_url=base_url,
+        debug=debug,
+        enabled=enabled,
+    )
+
+    # Register exit handler to flush queue on shutdown
+    if enabled:
+        atexit.register(flush)
+
+    return _global_client
+
+
+def flush(timeout: float = 5.0) -> None:
+    """Flush all currently buffered spans in the global client."""
+    global _global_client
+    if _global_client is not None and _global_client.enabled:
+        try:
+            _global_client.flush(timeout=timeout)
+        except Exception as e:
+            if _global_client.debug:
+                logger.debug(f"Failed to flush spans: {e}", exc_info=True)

agentlens/client.py

@@ -0,0 +1,137 @@
+"""AgentLens SDK Client for background batch span ingestion.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import queue
+import threading
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+logger = logging.getLogger("agentlens")
+
+
+class AgentLensClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://localhost:8000",
+        debug: bool = False,
+        enabled: bool = True,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.debug = debug
+        self.enabled = enabled
+
+        self._queue: queue.Queue[Dict[str, Any]] = queue.Queue(maxsize=10000)
+        self._stop_event = threading.Event()
+        self._worker_thread: Optional[threading.Thread] = None
+
+        if self.enabled:
+            self.start()
+
+    def start(self):
+        if self._worker_thread is not None and self._worker_thread.is_alive():
+            return
+        self._stop_event.clear()
+        self._worker_thread = threading.Thread(target=self._worker, daemon=True)
+        self._worker_thread.start()
+
+    def enqueue(self, item: Dict[str, Any]):
+        if not self.enabled:
+            return
+        try:
+            self._queue.put_nowait(item)
+        except queue.Full:
+            logger.warning("AgentLens queue full. Draining one item to make space.")
+            try:
+                self._queue.get_nowait()
+                self._queue.task_done()
+            except (queue.Empty, ValueError):
+                pass
+            try:
+                self._queue.put_nowait(item)
+            except queue.Full:
+                pass  # Fail-safe
+
+    def _safe_enqueue(self, item: Dict[str, Any]):
+        try:
+            self.enqueue(item)
+        except Exception as e:
+            if self.debug:
+                logger.debug(f"Failed to enqueue span: {e}", exc_info=True)
+
+    def _send_batch(self, batch: List[Dict[str, Any]]):
+        if not batch:
+            return
+        try:
+            url = f"{self.base_url}/v1/ingest"
+            headers = {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            }
+            payload = {"spans": batch}
+
+            # Sync request since we are on background worker thread
+            with httpx.Client(timeout=10.0) as client:
+                resp = client.post(url, json=payload, headers=headers)
+                if resp.status_code != 200:
+                    if self.debug:
+                        logger.debug(
+                            f"Ingest failed with status {resp.status_code}: {resp.text}"
+                        )
+        except Exception as e:
+            if self.debug:
+                logger.debug(f"Error sending batch to AgentLens: {e}", exc_info=True)
+
+    def _worker(self):
+        while not self._stop_event.is_set():
+            batch = []
+            start_time = time.time()
+            while len(batch) < 100:
+                elapsed = time.time() - start_time
+                if elapsed >= 0.5:
+                    break
+                timeout = 0.5 - elapsed
+                try:
+                    item = self._queue.get(timeout=timeout)
+                    batch.append(item)
+                except queue.Empty:
+                    break
+
+            if batch:
+                self._send_batch(batch)
+                for _ in range(len(batch)):
+                    self._queue.task_done()
+            else:
+                time.sleep(0.05)
+
+    def flush(self, timeout: float = 5.0):
+        start_time = time.time()
+        while not self._queue.empty():
+            if time.time() - start_time > timeout:
+                break
+            batch = []
+            while len(batch) < 100:
+                try:
+                    item = self._queue.get_nowait()
+                    batch.append(item)
+                except queue.Empty:
+                    break
+            if batch:
+                self._send_batch(batch)
+                for _ in range(len(batch)):
+                    self._queue.task_done()
+            else:
+                break
+
+    def stop(self, timeout: float = 5.0):
+        self._stop_event.set()
+        self.flush(timeout=timeout)
+        if self._worker_thread is not None:
+            self._worker_thread.join(timeout=timeout)

agentlens/context.py

@@ -0,0 +1,30 @@
+"""ContextVar-based trace/span ID propagation.
+
+These vars are set by the @trace decorator and span() context manager so that
+nested calls automatically inherit the current trace and span context without
+any explicit passing.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Optional
+
+_current_trace_id: ContextVar[Optional[str]] = ContextVar("_current_trace_id", default=None)
+_current_span_id: ContextVar[Optional[str]] = ContextVar("_current_span_id", default=None)
+
+
+def get_trace_id() -> Optional[str]:
+    return _current_trace_id.get()
+
+
+def get_span_id() -> Optional[str]:
+    return _current_span_id.get()
+
+
+def set_trace_id(value: Optional[str]):
+    return _current_trace_id.set(value)
+
+
+def set_span_id(value: Optional[str]):
+    return _current_span_id.set(value)

agentlens/decorators.py

@@ -0,0 +1,208 @@
+"""Decorators and context managers for AgentLens instrumentation.
+"""
+
+from __future__ import annotations
+
+import traceback
+import uuid
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from functools import wraps
+from typing import Any, Callable, List, Optional
+
+from agentlens.context import (
+    _current_span_id,
+    _current_trace_id,
+    get_span_id,
+    get_trace_id,
+    set_span_id,
+    set_trace_id,
+)
+
+
+def trace(name: Optional[str] = None, tags: Optional[List[str]] = None) -> Callable[..., Any]:
+    """Decorator to mark a function as a trace root."""
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            import agentlens
+            if agentlens._global_client is None or not agentlens._global_client.enabled:
+                return func(*args, **kwargs)
+
+            trace_id = str(uuid.uuid4())
+            span_id = str(uuid.uuid4())
+
+            trace_token = set_trace_id(trace_id)
+            span_token = set_span_id(span_id)
+
+            span_name = name or func.__name__
+            started_at = datetime.now(timezone.utc)
+            start_time = time.time()
+
+            status = "success"
+            error_type = None
+            error_message = None
+            error_stack = None
+
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                status = "error"
+                error_type = type(e).__name__
+                error_message = str(e)
+                error_stack = traceback.format_exc()
+                raise e
+            finally:
+                ended_at = datetime.now(timezone.utc)
+                duration_ms = int((time.time() - start_time) * 1000)
+
+                span_payload = {
+                    "id": span_id,
+                    "trace_id": trace_id,
+                    "parent_span_id": None,
+                    "name": span_name,
+                    "span_type": "custom",
+                    "status": status,
+                    "started_at": started_at.isoformat(),
+                    "ended_at": ended_at.isoformat(),
+                    "duration_ms": duration_ms,
+                    "tags": tags or [],
+                }
+                if error_type:
+                    span_payload.update({
+                        "error_type": error_type,
+                        "error_message": error_message,
+                        "error_stack": error_stack,
+                    })
+
+                agentlens._global_client._safe_enqueue(span_payload)
+
+                _current_trace_id.reset(trace_token)
+                _current_span_id.reset(span_token)
+
+        return wrapper
+    return decorator
+
+
+class Span:
+    def __init__(self, id: str, trace_id: str, parent_span_id: Optional[str] = None):
+        self.id = id
+        self.trace_id = trace_id
+        self.parent_span_id = parent_span_id
+        self.metadata = {}
+        self.input = None
+        self.output = None
+        self.input_tokens = None
+        self.output_tokens = None
+        self.model = None
+        self.provider = None
+
+    def set_metadata(self, key_or_dict: Any, value: Any = None):
+        if isinstance(key_or_dict, dict):
+            for k, v in key_or_dict.items():
+                self._set_key(k, v)
+        else:
+            self._set_key(key_or_dict, value)
+
+    def _set_key(self, key: str, value: Any):
+        if key == "input_tokens":
+            self.input_tokens = value
+        elif key == "output_tokens":
+            self.output_tokens = value
+        elif key == "model":
+            self.model = value
+        elif key == "provider":
+            self.provider = value
+        else:
+            self.metadata[key] = value
+
+    def set_output(self, output: Any):
+        self.output = output
+
+    def set_input(self, input_val: Any):
+        self.input = input_val
+
+
+@contextmanager
+def span(name: str, span_type: str = "custom", tags: Optional[List[str]] = None):
+    """Context manager to mark a block of code as a span."""
+    import agentlens
+    if agentlens._global_client is None or not agentlens._global_client.enabled:
+        yield Span(id="", trace_id="")
+        return
+
+    # Check or generate a root trace context if none exists
+    trace_id = get_trace_id()
+    trace_token = None
+    if not trace_id:
+        trace_id = str(uuid.uuid4())
+        trace_token = set_trace_id(trace_id)
+
+    parent_span_id = get_span_id()
+    span_id = str(uuid.uuid4())
+
+    span_token = set_span_id(span_id)
+
+    started_at = datetime.now(timezone.utc)
+    start_time = time.time()
+
+    status = "success"
+    error_type = None
+    error_message = None
+    error_stack = None
+
+    s = Span(id=span_id, trace_id=trace_id, parent_span_id=parent_span_id)
+
+    try:
+        yield s
+    except Exception as e:
+        status = "error"
+        error_type = type(e).__name__
+        error_message = str(e)
+        error_stack = traceback.format_exc()
+        raise e
+    finally:
+        ended_at = datetime.now(timezone.utc)
+        duration_ms = int((time.time() - start_time) * 1000)
+
+        span_payload = {
+            "id": span_id,
+            "trace_id": trace_id,
+            "parent_span_id": parent_span_id,
+            "name": name,
+            "span_type": span_type,
+            "status": status,
+            "started_at": started_at.isoformat(),
+            "ended_at": ended_at.isoformat(),
+            "duration_ms": duration_ms,
+            "tags": tags or [],
+        }
+        if error_type:
+            span_payload.update({
+                "error_type": error_type,
+                "error_message": error_message,
+                "error_stack": error_stack,
+            })
+
+        if s.input is not None:
+            span_payload["input"] = s.input
+        if s.output is not None:
+            span_payload["output"] = s.output
+        if s.metadata:
+            span_payload["metadata"] = s.metadata
+        if s.input_tokens is not None:
+            span_payload["input_tokens"] = s.input_tokens
+        if s.output_tokens is not None:
+            span_payload["output_tokens"] = s.output_tokens
+        if s.model is not None:
+            span_payload["model"] = s.model
+        if s.provider is not None:
+            span_payload["provider"] = s.provider
+
+        agentlens._global_client._safe_enqueue(span_payload)
+
+        _current_span_id.reset(span_token)
+        if trace_token:
+            _current_trace_id.reset(trace_token)

agentlens/instruments/anthropic.py

@@ -0,0 +1,359 @@
+"""Anthropic client instrumentation monkey-patch.
+"""
+
+from __future__ import annotations
+
+import time
+import traceback
+import uuid
+from datetime import datetime, timezone
+
+from agentlens.context import get_span_id, get_trace_id
+from agentlens.pricing import calculate_cost
+
+
+def instrument_anthropic():
+    """Monkey-patch Anthropic messages client to automatically record spans."""
+    try:
+        from anthropic.resources.messages import Messages
+    except ImportError:
+        return
+
+    if getattr(Messages, "_agentlens_instrumented", False):
+        return
+    Messages._agentlens_instrumented = True
+
+    original_create = Messages.create
+
+    def patched_create(self, *args, **kwargs):
+        import agentlens
+        if agentlens._global_client is None or not agentlens._global_client.enabled:
+            return original_create(self, *args, **kwargs)
+
+        trace_id = get_trace_id()
+        if not trace_id:
+            return original_create(self, *args, **kwargs)
+
+        parent_span_id = get_span_id()
+        span_id = str(uuid.uuid4())
+
+        model = kwargs.get("model", "unknown")
+        provider = "anthropic"
+        started_at = datetime.now(timezone.utc)
+        start_time = time.time()
+        messages = kwargs.get("messages", [])
+        is_stream = kwargs.get("stream", False)
+
+        if is_stream:
+            try:
+                response = original_create(self, *args, **kwargs)
+            except Exception as e:
+                ended_at = datetime.now(timezone.utc)
+                duration_ms = int((time.time() - start_time) * 1000)
+                span_payload = {
+                    "id": span_id,
+                    "trace_id": trace_id,
+                    "parent_span_id": parent_span_id,
+                    "name": f"anthropic.messages.create ({model})",
+                    "span_type": "llm",
+                    "status": "error",
+                    "started_at": started_at.isoformat(),
+                    "ended_at": ended_at.isoformat(),
+                    "duration_ms": duration_ms,
+                    "model": model,
+                    "provider": provider,
+                    "input": {"messages": messages},
+                    "error_type": type(e).__name__,
+                    "error_message": str(e),
+                    "error_stack": traceback.format_exc(),
+                }
+                agentlens._global_client._safe_enqueue(span_payload)
+                raise e
+
+            def stream_wrapper(stream_resp):
+                accumulated_content = []
+                input_tokens = 0
+                output_tokens = 0
+                try:
+                    for event in stream_resp:
+                        yield event
+                        event_type = getattr(event, "type", None)
+                        if event_type == "content_block_delta":
+                            delta = getattr(event, "delta", None)
+                            if delta and getattr(delta, "type", None) == "text_delta":
+                                text = getattr(delta, "text", "")
+                                accumulated_content.append(text)
+                        elif event_type == "message_start":
+                            message = getattr(event, "message", None)
+                            if message and hasattr(message, "usage") and message.usage:
+                                input_tokens = getattr(message.usage, "input_tokens", 0) or 0
+                        elif event_type == "message_delta":
+                            usage = getattr(event, "usage", None)
+                            if usage:
+                                output_tokens = getattr(usage, "output_tokens", 0) or 0
+                finally:
+                    ended_at = datetime.now(timezone.utc)
+                    duration_ms = int((time.time() - start_time) * 1000)
+                    cost_usd = calculate_cost(model, input_tokens, output_tokens)
+                    full_output = "".join(accumulated_content)
+
+                    span_payload = {
+                        "id": span_id,
+                        "trace_id": trace_id,
+                        "parent_span_id": parent_span_id,
+                        "name": f"anthropic.messages.create ({model})",
+                        "span_type": "llm",
+                        "status": "success",
+                        "started_at": started_at.isoformat(),
+                        "ended_at": ended_at.isoformat(),
+                        "duration_ms": duration_ms,
+                        "model": model,
+                        "provider": provider,
+                        "input_tokens": input_tokens,
+                        "output_tokens": output_tokens,
+                        "cost_usd": cost_usd,
+                        "input": {"messages": messages},
+                        "output": {"content": [{"type": "text", "text": full_output}]},
+                    }
+                    agentlens._global_client._safe_enqueue(span_payload)
+
+            return stream_wrapper(response)
+        else:
+            try:
+                response = original_create(self, *args, **kwargs)
+                ended_at = datetime.now(timezone.utc)
+                duration_ms = int((time.time() - start_time) * 1000)
+
+                input_tokens = 0
+                output_tokens = 0
+                output_content = []
+
+                if hasattr(response, "usage") and response.usage:
+                    input_tokens = getattr(response.usage, "input_tokens", 0) or 0
+                    output_tokens = getattr(response.usage, "output_tokens", 0) or 0
+
+                if hasattr(response, "content") and response.content:
+                    for block in response.content:
+                        block_type = getattr(block, "type", "text")
+                        if block_type == "text":
+                            output_content.append({
+                                "type": "text",
+                                "text": getattr(block, "text", "")
+                            })
+
+                cost_usd = calculate_cost(model, input_tokens, output_tokens)
+
+                span_payload = {
+                    "id": span_id,
+                    "trace_id": trace_id,
+                    "parent_span_id": parent_span_id,
+                    "name": f"anthropic.messages.create ({model})",
+                    "span_type": "llm",
+                    "status": "success",
+                    "started_at": started_at.isoformat(),
+                    "ended_at": ended_at.isoformat(),
+                    "duration_ms": duration_ms,
+                    "model": model,
+                    "provider": provider,
+                    "input_tokens": input_tokens,
+                    "output_tokens": output_tokens,
+                    "cost_usd": cost_usd,
+                    "input": {"messages": messages},
+                    "output": {"content": output_content},
+                }
+                agentlens._global_client._safe_enqueue(span_payload)
+                return response
+            except Exception as e:
+                ended_at = datetime.now(timezone.utc)
+                duration_ms = int((time.time() - start_time) * 1000)
+                span_payload = {
+                    "id": span_id,
+                    "trace_id": trace_id,
+                    "parent_span_id": parent_span_id,
+                    "name": f"anthropic.messages.create ({model})",
+                    "span_type": "llm",
+                    "status": "error",
+                    "started_at": started_at.isoformat(),
+                    "ended_at": ended_at.isoformat(),
+                    "duration_ms": duration_ms,
+                    "model": model,
+                    "provider": provider,
+                    "input": {"messages": messages},
+                    "error_type": type(e).__name__,
+                    "error_message": str(e),
+                    "error_stack": traceback.format_exc(),
+                }
+                agentlens._global_client._safe_enqueue(span_payload)
+                raise e
+
+    Messages.create = patched_create
+
+    try:
+        from anthropic.resources.messages import AsyncMessages
+
+        original_async_create = AsyncMessages.create
+
+        async def patched_async_create(self, *args, **kwargs):
+            import agentlens
+            if agentlens._global_client is None or not agentlens._global_client.enabled:
+                return await original_async_create(self, *args, **kwargs)
+
+            trace_id = get_trace_id()
+            if not trace_id:
+                return await original_async_create(self, *args, **kwargs)
+
+            parent_span_id = get_span_id()
+            span_id = str(uuid.uuid4())
+
+            model = kwargs.get("model", "unknown")
+            provider = "anthropic"
+            started_at = datetime.now(timezone.utc)
+            start_time = time.time()
+            messages = kwargs.get("messages", [])
+            is_stream = kwargs.get("stream", False)
+
+            if is_stream:
+                try:
+                    response = await original_async_create(self, *args, **kwargs)
+                except Exception as e:
+                    ended_at = datetime.now(timezone.utc)
+                    duration_ms = int((time.time() - start_time) * 1000)
+                    span_payload = {
+                        "id": span_id,
+                        "trace_id": trace_id,
+                        "parent_span_id": parent_span_id,
+                        "name": f"anthropic.messages.create ({model})",
+                        "span_type": "llm",
+                        "status": "error",
+                        "started_at": started_at.isoformat(),
+                        "ended_at": ended_at.isoformat(),
+                        "duration_ms": duration_ms,
+                        "model": model,
+                        "provider": provider,
+                        "input": {"messages": messages},
+                        "error_type": type(e).__name__,
+                        "error_message": str(e),
+                        "error_stack": traceback.format_exc(),
+                    }
+                    agentlens._global_client._safe_enqueue(span_payload)
+                    raise e
+
+                async def async_stream_wrapper(stream_resp):
+                    accumulated_content = []
+                    input_tokens = 0
+                    output_tokens = 0
+                    try:
+                        async for event in stream_resp:
+                            yield event
+                            event_type = getattr(event, "type", None)
+                            if event_type == "content_block_delta":
+                                delta = getattr(event, "delta", None)
+                                if delta and getattr(delta, "type", None) == "text_delta":
+                                    text = getattr(delta, "text", "")
+                                    accumulated_content.append(text)
+                            elif event_type == "message_start":
+                                message = getattr(event, "message", None)
+                                if message and hasattr(message, "usage") and message.usage:
+                                    input_tokens = getattr(message.usage, "input_tokens", 0) or 0
+                            elif event_type == "message_delta":
+                                usage = getattr(event, "usage", None)
+                                if usage:
+                                    output_tokens = getattr(usage, "output_tokens", 0) or 0
+                    finally:
+                        ended_at = datetime.now(timezone.utc)
+                        duration_ms = int((time.time() - start_time) * 1000)
+                        cost_usd = calculate_cost(model, input_tokens, output_tokens)
+                        full_output = "".join(accumulated_content)
+
+                        span_payload = {
+                            "id": span_id,
+                            "trace_id": trace_id,
+                            "parent_span_id": parent_span_id,
+                            "name": f"anthropic.messages.create ({model})",
+                            "span_type": "llm",
+                            "status": "success",
+                            "started_at": started_at.isoformat(),
+                            "ended_at": ended_at.isoformat(),
+                            "duration_ms": duration_ms,
+                            "model": model,
+                            "provider": provider,
+                            "input_tokens": input_tokens,
+                            "output_tokens": output_tokens,
+                            "cost_usd": cost_usd,
+                            "input": {"messages": messages},
+                            "output": {"content": [{"type": "text", "text": full_output}]},
+                        }
+                        agentlens._global_client._safe_enqueue(span_payload)
+
+                return async_stream_wrapper(response)
+            else:
+                try:
+                    response = await original_async_create(self, *args, **kwargs)
+                    ended_at = datetime.now(timezone.utc)
+                    duration_ms = int((time.time() - start_time) * 1000)
+
+                    input_tokens = 0
+                    output_tokens = 0
+                    output_content = []
+
+                    if hasattr(response, "usage") and response.usage:
+                        input_tokens = getattr(response.usage, "input_tokens", 0) or 0
+                        output_tokens = getattr(response.usage, "output_tokens", 0) or 0
+
+                    if hasattr(response, "content") and response.content:
+                        for block in response.content:
+                            block_type = getattr(block, "type", "text")
+                            if block_type == "text":
+                                output_content.append({
+                                    "type": "text",
+                                    "text": getattr(block, "text", "")
+                                })
+
+                    cost_usd = calculate_cost(model, input_tokens, output_tokens)
+
+                    span_payload = {
+                        "id": span_id,
+                        "trace_id": trace_id,
+                        "parent_span_id": parent_span_id,
+                        "name": f"anthropic.messages.create ({model})",
+                        "span_type": "llm",
+                        "status": "success",
+                        "started_at": started_at.isoformat(),
+                        "ended_at": ended_at.isoformat(),
+                        "duration_ms": duration_ms,
+                        "model": model,
+                        "provider": provider,
+                        "input_tokens": input_tokens,
+                        "output_tokens": output_tokens,
+                        "cost_usd": cost_usd,
+                        "input": {"messages": messages},
+                        "output": {"content": output_content},
+                    }
+                    agentlens._global_client._safe_enqueue(span_payload)
+                    return response
+                except Exception as e:
+                    ended_at = datetime.now(timezone.utc)
+                    duration_ms = int((time.time() - start_time) * 1000)
+                    span_payload = {
+                        "id": span_id,
+                        "trace_id": trace_id,
+                        "parent_span_id": parent_span_id,
+                        "name": f"anthropic.messages.create ({model})",
+                        "span_type": "llm",
+                        "status": "error",
+                        "started_at": started_at.isoformat(),
+                        "ended_at": ended_at.isoformat(),
+                        "duration_ms": duration_ms,
+                        "model": model,
+                        "provider": provider,
+                        "input": {"messages": messages},
+                        "error_type": type(e).__name__,
+                        "error_message": str(e),
+                        "error_stack": traceback.format_exc(),
+                    }
+                    agentlens._global_client._safe_enqueue(span_payload)
+                    raise e
+
+        AsyncMessages.create = patched_async_create
+    except Exception:
+        pass

agentlens/instruments/openai.py

@@ -0,0 +1,367 @@
+"""OpenAI client instrumentation monkey-patch.
+"""
+
+from __future__ import annotations
+
+import time
+import traceback
+import uuid
+from datetime import datetime, timezone
+
+from agentlens.context import get_span_id, get_trace_id
+from agentlens.pricing import calculate_cost
+
+
+def instrument_openai():
+    """Monkey-patch OpenAI chat completions to automatically record spans."""
+    try:
+        from openai.resources.chat.completions import Completions
+    except ImportError:
+        return
+
+    if getattr(Completions, "_agentlens_instrumented", False):
+        return
+    Completions._agentlens_instrumented = True
+
+    original_create = Completions.create
+
+    def patched_create(self, *args, **kwargs):
+        import agentlens
+        if agentlens._global_client is None or not agentlens._global_client.enabled:
+            return original_create(self, *args, **kwargs)
+
+        trace_id = get_trace_id()
+        if not trace_id:
+            return original_create(self, *args, **kwargs)
+
+        parent_span_id = get_span_id()
+        span_id = str(uuid.uuid4())
+
+        model = kwargs.get("model", "unknown")
+        provider = "openai"
+        started_at = datetime.now(timezone.utc)
+        start_time = time.time()
+        messages = kwargs.get("messages", [])
+        is_stream = kwargs.get("stream", False)
+
+        if is_stream:
+            stream_options = kwargs.get("stream_options", {}) or {}
+            stream_options["include_usage"] = True
+            kwargs["stream_options"] = stream_options
+
+            try:
+                response = original_create(self, *args, **kwargs)
+            except Exception as e:
+                ended_at = datetime.now(timezone.utc)
+                duration_ms = int((time.time() - start_time) * 1000)
+                span_payload = {
+                    "id": span_id,
+                    "trace_id": trace_id,
+                    "parent_span_id": parent_span_id,
+                    "name": f"openai.chat.completions.create ({model})",
+                    "span_type": "llm",
+                    "status": "error",
+                    "started_at": started_at.isoformat(),
+                    "ended_at": ended_at.isoformat(),
+                    "duration_ms": duration_ms,
+                    "model": model,
+                    "provider": provider,
+                    "input": {"messages": messages},
+                    "error_type": type(e).__name__,
+                    "error_message": str(e),
+                    "error_stack": traceback.format_exc(),
+                }
+                agentlens._global_client._safe_enqueue(span_payload)
+                raise e
+
+            def stream_wrapper(stream_resp):
+                accumulated_content = []
+                prompt_tokens = 0
+                completion_tokens = 0
+                try:
+                    for chunk in stream_resp:
+                        yield chunk
+                        if hasattr(chunk, "choices") and chunk.choices:
+                            choice = chunk.choices[0]
+                            if hasattr(choice, "delta") and choice.delta:
+                                if hasattr(choice.delta, "content") and choice.delta.content:
+                                    accumulated_content.append(choice.delta.content)
+                        if hasattr(chunk, "usage") and chunk.usage:
+                            prompt_tokens = getattr(chunk.usage, "prompt_tokens", 0) or 0
+                            completion_tokens = getattr(chunk.usage, "completion_tokens", 0) or 0
+                finally:
+                    ended_at = datetime.now(timezone.utc)
+                    duration_ms = int((time.time() - start_time) * 1000)
+                    cost_usd = calculate_cost(model, prompt_tokens, completion_tokens)
+                    full_output = "".join(accumulated_content)
+
+                    span_payload = {
+                        "id": span_id,
+                        "trace_id": trace_id,
+                        "parent_span_id": parent_span_id,
+                        "name": f"openai.chat.completions.create ({model})",
+                        "span_type": "llm",
+                        "status": "success",
+                        "started_at": started_at.isoformat(),
+                        "ended_at": ended_at.isoformat(),
+                        "duration_ms": duration_ms,
+                        "model": model,
+                        "provider": provider,
+                        "input_tokens": prompt_tokens,
+                        "output_tokens": completion_tokens,
+                        "cost_usd": cost_usd,
+                        "input": {"messages": messages},
+                        "output": {
+                            "choices": [
+                                {
+                                    "message": {
+                                        "role": "assistant",
+                                        "content": full_output,
+                                    }
+                                }
+                            ]
+                        },
+                    }
+                    agentlens._global_client._safe_enqueue(span_payload)
+
+            return stream_wrapper(response)
+        else:
+            try:
+                response = original_create(self, *args, **kwargs)
+                ended_at = datetime.now(timezone.utc)
+                duration_ms = int((time.time() - start_time) * 1000)
+
+                prompt_tokens = 0
+                completion_tokens = 0
+                output_message = {}
+                if hasattr(response, "usage") and response.usage:
+                    prompt_tokens = getattr(response.usage, "prompt_tokens", 0) or 0
+                    completion_tokens = getattr(response.usage, "completion_tokens", 0) or 0
+                if hasattr(response, "choices") and response.choices:
+                    choice = response.choices[0]
+                    if hasattr(choice, "message") and choice.message:
+                        output_message = {
+                            "role": getattr(choice.message, "role", "assistant"),
+                            "content": getattr(choice.message, "content", ""),
+                        }
+
+                cost_usd = calculate_cost(model, prompt_tokens, completion_tokens)
+
+                span_payload = {
+                    "id": span_id,
+                    "trace_id": trace_id,
+                    "parent_span_id": parent_span_id,
+                    "name": f"openai.chat.completions.create ({model})",
+                    "span_type": "llm",
+                    "status": "success",
+                    "started_at": started_at.isoformat(),
+                    "ended_at": ended_at.isoformat(),
+                    "duration_ms": duration_ms,
+                    "model": model,
+                    "provider": provider,
+                    "input_tokens": prompt_tokens,
+                    "output_tokens": completion_tokens,
+                    "cost_usd": cost_usd,
+                    "input": {"messages": messages},
+                    "output": {"choices": [{"message": output_message}]},
+                }
+                agentlens._global_client._safe_enqueue(span_payload)
+                return response
+            except Exception as e:
+                ended_at = datetime.now(timezone.utc)
+                duration_ms = int((time.time() - start_time) * 1000)
+                span_payload = {
+                    "id": span_id,
+                    "trace_id": trace_id,
+                    "parent_span_id": parent_span_id,
+                    "name": f"openai.chat.completions.create ({model})",
+                    "span_type": "llm",
+                    "status": "error",
+                    "started_at": started_at.isoformat(),
+                    "ended_at": ended_at.isoformat(),
+                    "duration_ms": duration_ms,
+                    "model": model,
+                    "provider": provider,
+                    "input": {"messages": messages},
+                    "error_type": type(e).__name__,
+                    "error_message": str(e),
+                    "error_stack": traceback.format_exc(),
+                }
+                agentlens._global_client._safe_enqueue(span_payload)
+                raise e
+
+    Completions.create = patched_create
+
+    try:
+        from openai.resources.chat.completions import AsyncCompletions
+
+        original_async_create = AsyncCompletions.create
+
+        async def patched_async_create(self, *args, **kwargs):
+            import agentlens
+            if agentlens._global_client is None or not agentlens._global_client.enabled:
+                return await original_async_create(self, *args, **kwargs)
+
+            trace_id = get_trace_id()
+            if not trace_id:
+                return await original_async_create(self, *args, **kwargs)
+
+            parent_span_id = get_span_id()
+            span_id = str(uuid.uuid4())
+
+            model = kwargs.get("model", "unknown")
+            provider = "openai"
+            started_at = datetime.now(timezone.utc)
+            start_time = time.time()
+            messages = kwargs.get("messages", [])
+            is_stream = kwargs.get("stream", False)
+
+            if is_stream:
+                stream_options = kwargs.get("stream_options", {}) or {}
+                stream_options["include_usage"] = True
+                kwargs["stream_options"] = stream_options
+
+                try:
+                    response = await original_async_create(self, *args, **kwargs)
+                except Exception as e:
+                    ended_at = datetime.now(timezone.utc)
+                    duration_ms = int((time.time() - start_time) * 1000)
+                    span_payload = {
+                        "id": span_id,
+                        "trace_id": trace_id,
+                        "parent_span_id": parent_span_id,
+                        "name": f"openai.chat.completions.create ({model})",
+                        "span_type": "llm",
+                        "status": "error",
+                        "started_at": started_at.isoformat(),
+                        "ended_at": ended_at.isoformat(),
+                        "duration_ms": duration_ms,
+                        "model": model,
+                        "provider": provider,
+                        "input": {"messages": messages},
+                        "error_type": type(e).__name__,
+                        "error_message": str(e),
+                        "error_stack": traceback.format_exc(),
+                    }
+                    agentlens._global_client._safe_enqueue(span_payload)
+                    raise e
+
+                async def async_stream_wrapper(stream_resp):
+                    accumulated_content = []
+                    prompt_tokens = 0
+                    completion_tokens = 0
+                    try:
+                        async for chunk in stream_resp:
+                            yield chunk
+                            if hasattr(chunk, "choices") and chunk.choices:
+                                choice = chunk.choices[0]
+                                if hasattr(choice, "delta") and choice.delta:
+                                    if hasattr(choice.delta, "content") and choice.delta.content:
+                                        accumulated_content.append(choice.delta.content)
+                            if hasattr(chunk, "usage") and chunk.usage:
+                                prompt_tokens = getattr(chunk.usage, "prompt_tokens", 0) or 0
+                                completion_tokens = getattr(chunk.usage, "completion_tokens", 0) or 0
+                    finally:
+                        ended_at = datetime.now(timezone.utc)
+                        duration_ms = int((time.time() - start_time) * 1000)
+                        cost_usd = calculate_cost(model, prompt_tokens, completion_tokens)
+                        full_output = "".join(accumulated_content)
+
+                        span_payload = {
+                            "id": span_id,
+                            "trace_id": trace_id,
+                            "parent_span_id": parent_span_id,
+                            "name": f"openai.chat.completions.create ({model})",
+                            "span_type": "llm",
+                            "status": "success",
+                            "started_at": started_at.isoformat(),
+                            "ended_at": ended_at.isoformat(),
+                            "duration_ms": duration_ms,
+                            "model": model,
+                            "provider": provider,
+                            "input_tokens": prompt_tokens,
+                            "output_tokens": completion_tokens,
+                            "cost_usd": cost_usd,
+                            "input": {"messages": messages},
+                            "output": {
+                                "choices": [
+                                    {
+                                        "message": {
+                                            "role": "assistant",
+                                            "content": full_output,
+                                        }
+                                    }
+                                ]
+                            },
+                        }
+                        agentlens._global_client._safe_enqueue(span_payload)
+
+                return async_stream_wrapper(response)
+            else:
+                try:
+                    response = await original_async_create(self, *args, **kwargs)
+                    ended_at = datetime.now(timezone.utc)
+                    duration_ms = int((time.time() - start_time) * 1000)
+
+                    prompt_tokens = 0
+                    completion_tokens = 0
+                    output_message = {}
+                    if hasattr(response, "usage") and response.usage:
+                        prompt_tokens = getattr(response.usage, "prompt_tokens", 0) or 0
+                        completion_tokens = getattr(response.usage, "completion_tokens", 0) or 0
+                    if hasattr(response, "choices") and response.choices:
+                        choice = response.choices[0]
+                        if hasattr(choice, "message") and choice.message:
+                            output_message = {
+                                "role": getattr(choice.message, "role", "assistant"),
+                                "content": getattr(choice.message, "content", ""),
+                            }
+
+                    cost_usd = calculate_cost(model, prompt_tokens, completion_tokens)
+
+                    span_payload = {
+                        "id": span_id,
+                        "trace_id": trace_id,
+                        "parent_span_id": parent_span_id,
+                        "name": f"openai.chat.completions.create ({model})",
+                        "span_type": "llm",
+                        "status": "success",
+                        "started_at": started_at.isoformat(),
+                        "ended_at": ended_at.isoformat(),
+                        "duration_ms": duration_ms,
+                        "model": model,
+                        "provider": provider,
+                        "input_tokens": prompt_tokens,
+                        "output_tokens": completion_tokens,
+                        "cost_usd": cost_usd,
+                        "input": {"messages": messages},
+                        "output": {"choices": [{"message": output_message}]},
+                    }
+                    agentlens._global_client._safe_enqueue(span_payload)
+                    return response
+                except Exception as e:
+                    ended_at = datetime.now(timezone.utc)
+                    duration_ms = int((time.time() - start_time) * 1000)
+                    span_payload = {
+                        "id": span_id,
+                        "trace_id": trace_id,
+                        "parent_span_id": parent_span_id,
+                        "name": f"openai.chat.completions.create ({model})",
+                        "span_type": "llm",
+                        "status": "error",
+                        "started_at": started_at.isoformat(),
+                        "ended_at": ended_at.isoformat(),
+                        "duration_ms": duration_ms,
+                        "model": model,
+                        "provider": provider,
+                        "input": {"messages": messages},
+                        "error_type": type(e).__name__,
+                        "error_message": str(e),
+                        "error_stack": traceback.format_exc(),
+                    }
+                    agentlens._global_client._safe_enqueue(span_payload)
+                    raise e
+
+        AsyncCompletions.create = patched_async_create
+    except Exception:
+        pass

agentlens/pricing.py

@@ -0,0 +1,37 @@
+"""Token cost lookup and calculation for LLM spans.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("agentlens")
+
+PRICING = {
+    "gpt-4o": {"input": 5.0 / 1_000_000, "output": 15.0 / 1_000_000},
+    "gpt-4o-mini": {"input": 0.15 / 1_000_000, "output": 0.60 / 1_000_000},
+    "gpt-4-turbo": {"input": 10.0 / 1_000_000, "output": 30.0 / 1_000_000},
+    "gpt-4": {"input": 30.0 / 1_000_000, "output": 60.0 / 1_000_000},
+    "gpt-3.5-turbo": {"input": 0.50 / 1_000_000, "output": 1.50 / 1_000_000},
+    "gpt-3.5-turbo-0125": {"input": 0.50 / 1_000_000, "output": 1.50 / 1_000_000},
+    "claude-3-5-sonnet-20241022": {"input": 3.0 / 1_000_000, "output": 15.0 / 1_000_000},
+    "claude-3-5-haiku-20241022": {"input": 0.80 / 1_000_000, "output": 4.0 / 1_000_000},
+    "claude-3-opus-20240229": {"input": 15.0 / 1_000_000, "output": 75.0 / 1_000_000},
+    "claude-3-sonnet-20240229": {"input": 3.0 / 1_000_000, "output": 15.0 / 1_000_000},
+    "claude-3-haiku-20240307": {"input": 0.25 / 1_000_000, "output": 1.25 / 1_000_000},
+    # Verified from cometapi.com/models on 2026-06-27 — re-check periodically,
+    # CometAPI pricing can change.
+    "glm-5.2": {"input": 1.12 / 1_000_000, "output": 3.528 / 1_000_000},
+}
+
+
+def calculate_cost(model: str, input_tokens: int, output_tokens: int) -> float:
+    """Calculate the cost in USD for a given model and token count."""
+    rates = PRICING.get(model)
+    if not rates:
+        logger.debug(f"Unknown model name for cost calculation: {model}")
+        return 0.0
+
+    in_cost = input_tokens * rates["input"]
+    out_cost = output_tokens * rates["output"]
+    return in_cost + out_cost

agentlens_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: agentlens-py
+Version: 0.1.0
+Summary: AgentLens Python SDK — zero-overhead observability for AI agents
+Requires-Python: >=3.9
+Requires-Dist: httpx==0.28.1
+Requires-Dist: structlog==25.5.0
+Provides-Extra: dev
+Requires-Dist: hypothesis==6.152.9; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'

agentlens_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agentlens/__init__.py,sha256=qA3mXgZnimMnis_Nzce6oMrBoE77MPF5OUe_D93P_Ns,1621
+agentlens/client.py,sha256=0BuNl7MStYr0xhbJ_lWrXRSwA3mGgXDN1X6KGaT_mxM,4466
+agentlens/context.py,sha256=-8OGFgS7tQ8HbOiRogRl5YLEEMAsfDFBUXkMhOWdQLA,853
+agentlens/decorators.py,sha256=9batbDAXMhqqB_4VCJcLEKGnXtKKN2FVd5q9XUiXGO4,6740
+agentlens/pricing.py,sha256=7z4KZeIYGn4_wbP9YGd8qBj6gmQPB76xSTWHJhOR598,1702
+agentlens/instruments/anthropic.py,sha256=ZVM48PQyGd0AqPJSfY-uRMPxP23P_JbKwk3ssg4zLXo,16743
+agentlens/instruments/openai.py,sha256=u4hqZ4XWQLSl4q0ZW3TA_SRO3m1GePgWB33OGWpHUSQ,17217
+agentlens_py-0.1.0.dist-info/METADATA,sha256=YlI6w6Vrd8jmU7LxJgYiysJ-pDN7cPRDzdk5iFNkh20,386
+agentlens_py-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentlens_py-0.1.0.dist-info/RECORD,,

agentlens_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any