agentlens-py 0.1.0__tar.gz

agentlens_py-0.1.0/.gitignore

@@ -0,0 +1,170 @@
+# ============================================================
+# Python
+# ============================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+.env
+.env.local
+.env.*.local
+
+# pytest / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.hypothesis/
+
+# mypy / pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyright/
+
+# ruff / flake8
+.ruff_cache/
+
+# Distribution / packaging
+MANIFEST
+
+# ============================================================
+# Node / Next.js
+# ============================================================
+node_modules/
+.next/
+out/
+.nuxt/
+.cache/
+.parcel-cache/
+.turbo/
+
+# Build output
+dist/
+build/
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+
+# ============================================================
+# Docker
+# ============================================================
+.dockerignore
+
+# ============================================================
+# OS / Editor
+# ============================================================
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+*.sublime-project
+*.sublime-workspace
+
+# ============================================================
+# Secrets / credentials (never commit these)
+# ============================================================
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+*.pem
+*.key
+secrets/
+
+# ============================================================
+# Alembic
+# ============================================================
+# Keep migrations tracked; ignore only generated artefacts
+apps/api/migrations/__pycache__/
+apps/api/migrations/versions/__pycache__/
+
+# ============================================================
+# Misc
+# ============================================================
+*.log
+*.tmp
+*.bak
+
+# ============================================================
+# Pre-launch release cleanup additions
+# ============================================================
+.Python
+downloads/
+wheels/
+*.pyo
+.env/
+apps/api/.env
+apps/web/.env
+apps/web/.env.local
+secrets.txt
+apps/web/.next/
+apps/web/out/
+apps/web/node_modules/
+*.code-workspace
+*.tar
+logs/
+scratch_test.py
+ws_test_delay.py
+test_trace.py
+
+# Internal planning documents
+ANTIGRAVITY_PROMPT.md
+agentlens_project_handover_summary.md
+*_handover_*.md
+
+# Manual test scripts
+test_agent.py
+verify_dashboard_data.py
+test_trace.py
+
+# Kiro AI IDE specs (internal)
+.kiro/
+
+# Editor
+.vscode/
+
+# Hypothesis test data
+apps/api/.hypothesis/
+apps/api/tmp/
+apps/api/unicode_data/
+

agentlens_py-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,120 @@
+# AgentLens Python SDK
+
+The official Python client for AgentLens. Easily trace agent execution steps, nested tool calls, and LLM completions with non-blocking, asynchronous ingestion.
+
+## Key Features
+
+- **Micro-Batched Background Ingestion**: Uses a thread-safe daemon worker (`SpanQueue` wrapping a safe `queue.Queue`) to buffer and flush spans concurrently without delaying agent execution.
+- **Zero-Dependency Exception Guard**: The SDK never propagates internal networking or API exceptions, ensuring your production agent runs remain robust.
+- **Automatic Cost & Token Estimation**: Immediate calculations of token consumption and pricing for popular OpenAI and Anthropic models.
+- **Auto-Instrumentation**: Monkey-patches OpenAI and Anthropic clients to capture inputs, outputs, tokens, and streaming responses out-of-the-box.
+
+---
+
+## Installation
+
+Install the package via `pip` (or `uv` / `poetry`):
+
+```bash
+pip install agentlens-py
+```
+
+> [!NOTE]
+> Note that the package is installed via `agentlens-py`, but the Python import name remains `import agentlens as al`.
+
+---
+
+## Quick Start (2-Line Integration)
+
+Instrument your application to capture all OpenAI completions automatically:
+
+```python
+import agentlens as al
+
+# Initialize the global client and instrument the OpenAI SDK
+al.init(api_key="al_live_YOUR_API_KEY_HERE", base_url="http://localhost:8000")
+al.instrument_openai()
+```
+
+---
+
+## Detailed Usage
+
+### Decorators & Context Managers
+
+Trace custom Python functions or specific logical blocks inside your agents:
+
+```python
+import agentlens as al
+
+# 1. Trace a high-level agent loop
+@al.trace(name="Customer Assistant Agent")
+def run_assistant(user_query: str):
+    print("Agent started...")
+    
+    # 2. Trace tool calls or sub-steps using context managers
+    with al.span(name="Database Lookup", span_type="tool") as s:
+        s.set_metadata("query", user_query)
+        result = db_search(user_query)
+        s.set_output({"results_count": len(result)})
+        
+    return result
+```
+
+### Auto-Instrumentation Examples
+
+#### OpenAI (Both Streaming & Non-Streaming)
+
+```python
+import openai
+import agentlens as al
+
+al.init(api_key="al_live_...")
+al.instrument_openai()
+
+client = openai.OpenAI()
+
+# Spans are automatically created for completions, including token counts and costs
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Explain quantizing neural networks."}]
+)
+```
+
+#### Anthropic (Both Streaming & Non-Streaming)
+
+```python
+import anthropic
+import agentlens as al
+
+al.init(api_key="al_live_...")
+al.instrument_anthropic()
+
+client = anthropic.Anthropic()
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=1000,
+    messages=[{"role": "user", "content": "What is reinforcement learning?"}]
+)
+```
+
+---
+
+## Public API Reference
+
+### `al.init(api_key: str, base_url: str = "http://localhost:8000", debug: bool = False, enabled: bool = True) -> None`
+Configures the global AgentLens client, spins up the thread-safe background ingestion worker, and registers an `atexit` hook to flush remaining spans on application termination.
+- `api_key`: Your active AgentLens project API key (prefixed with `al_live_`).
+- `base_url`: Endpoint of your FastAPI backend.
+- `debug`: Enable internal logging for SDK debugging.
+- `enabled`: If set to `False`, all tracing operations, monkey-patches, and decorators gracefully fallback to no-ops.
+
+### `al.trace(name: str | None = None, tags: list[str] | None = None)`
+Decorator to declare a new root trace context. Propagates the trace context down the execution tree.
+
+### `al.span(name: str, span_type: str = "custom")`
+Context manager to record a logical sub-step inside an active trace context. Supports updating metadata and final outputs.
+
+### `al.flush(timeout: float = 5.0) -> None`
+Manually blocks and flushes any enqueued spans to the API backend up to the specified timeout. Excellent for short-running serverless function environments.

agentlens_py-0.1.0/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_py-0.1.0/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_py-0.1.0/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)