agentreplay 0.1.2__tar.gz → 0.1.3__tar.gz

agentreplay-0.1.3/PKG-INFO

@@ -0,0 +1,1138 @@
+Metadata-Version: 2.4
+Name: agentreplay
+Version: 0.1.3
+Summary: Agentreplay is a high-performance observability and tracing platform for LLM agents and AI apps, combining semantic search, specialized evals (RAGAS, G-Eval, toxicity), and Git-like versioning of prompts and responses.
+Author-email: Sushanth <sushanth@agentreplay.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://agentreplay.dev
+Project-URL: Documentation, https://agentreplay.dev
+Project-URL: Repository, https://github.com/agentreplay/agentreplay
+Project-URL: Issues, https://github.com/agentreplay/agentreplay/issues
+Project-URL: Changelog, https://github.com/agentreplay/agentreplay/blob/main/CHANGELOG.md
+Keywords: llm,agents,tracing,observability,ai,opentelemetry,ragas,evaluation,prompts,semantic-search,langchain,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "otel"
+Requires-Dist: opentelemetry-instrumentation>=0.41b0; extra == "otel"
+Requires-Dist: opentelemetry-instrumentation-openai>=0.48.0; extra == "otel"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: bandit>=1.7.0; extra == "dev"
+Requires-Dist: types-requests>=2.31.0; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.3.0; extra == "langchain"
+Requires-Dist: langchain-openai>=0.2.0; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
+Requires-Dist: langchain>=0.3.0; extra == "langgraph"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index>=0.11.0; extra == "llamaindex"
+Requires-Dist: llama-index-core>=0.11.0; extra == "llamaindex"
+Provides-Extra: llamaindex-workflows
+Requires-Dist: llama-index>=0.11.0; extra == "llamaindex-workflows"
+Requires-Dist: llama-index-workflows>=0.2.0; extra == "llamaindex-workflows"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.5.0; extra == "openai-agents"
+Provides-Extra: autogen
+Requires-Dist: autogen-agentchat>=0.4.0; extra == "autogen"
+Requires-Dist: autogen-core>=0.4.0; extra == "autogen"
+Provides-Extra: semantic-kernel
+Requires-Dist: semantic-kernel>=1.0.0; extra == "semantic-kernel"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Provides-Extra: smolagents
+Requires-Dist: smolagents>=1.0.0; extra == "smolagents"
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai>=1.0.0; extra == "pydantic-ai"
+Provides-Extra: strands
+Requires-Dist: strands-sdk>=1.0.0; extra == "strands"
+Provides-Extra: google-adk
+Requires-Dist: google-adk>=1.0.0; extra == "google-adk"
+Provides-Extra: all-frameworks
+Requires-Dist: langchain>=0.3.0; extra == "all-frameworks"
+Requires-Dist: langchain-openai>=0.2.0; extra == "all-frameworks"
+Requires-Dist: langgraph>=0.2.0; extra == "all-frameworks"
+Requires-Dist: llama-index>=0.11.0; extra == "all-frameworks"
+Requires-Dist: openai-agents>=0.5.0; extra == "all-frameworks"
+Requires-Dist: autogen-agentchat>=0.4.0; extra == "all-frameworks"
+Requires-Dist: semantic-kernel>=1.0.0; extra == "all-frameworks"
+Requires-Dist: crewai>=0.1.0; extra == "all-frameworks"
+Requires-Dist: smolagents>=1.0.0; extra == "all-frameworks"
+Requires-Dist: pydantic-ai>=1.0.0; extra == "all-frameworks"
+Provides-Extra: all
+Requires-Dist: langchain>=0.3.0; extra == "all"
+Requires-Dist: langchain-openai>=0.2.0; extra == "all"
+Requires-Dist: langgraph>=0.2.0; extra == "all"
+Requires-Dist: llama-index>=0.11.0; extra == "all"
+Requires-Dist: openai-agents>=0.5.0; extra == "all"
+Requires-Dist: autogen-agentchat>=0.4.0; extra == "all"
+Requires-Dist: semantic-kernel>=1.0.0; extra == "all"
+Requires-Dist: crewai>=0.1.0; extra == "all"
+Requires-Dist: smolagents>=1.0.0; extra == "all"
+Requires-Dist: pydantic-ai>=1.0.0; extra == "all"
+Requires-Dist: pytest>=7.0.0; extra == "all"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
+Dynamic: license-file
+
+# Agentreplay Python SDK
+
+[![PyPI version](https://badge.fury.io/py/agentreplay.svg)](https://badge.fury.io/py/agentreplay)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![CI](https://github.com/agentreplay/agentreplay/actions/workflows/ci-python.yaml/badge.svg)](https://github.com/agentreplay/agentreplay/actions/workflows/ci-python.yaml)
+
+**The observability platform for LLM agents and AI applications.** Trace every LLM call, tool invocation, and agent step with minimal code changes.
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 🚀 **Zero-Config Setup** | Works out of the box with environment variables |
+| 🎯 **One-Liner Instrumentation** | Wrap OpenAI/Anthropic clients in one line |
+| 🔧 **Decorator-Based Tracing** | `@traceable` for any function |
+| 🔄 **Async Native** | Full support for async/await patterns |
+| 🔒 **Privacy First** | Built-in PII redaction and scrubbing |
+| 📊 **Token Tracking** | Automatic token usage capture |
+| 🌐 **Framework Agnostic** | Works with LangChain, LlamaIndex, CrewAI, etc. |
+| ⚡ **Batched Transport** | Efficient background sending with retry |
+
+---
+
+## 📦 Installation
+
+```bash
+# Basic installation (minimal dependencies)
+pip install agentreplay
+
+# With OpenTelemetry support
+pip install agentreplay[otel]
+
+# With LangChain integration
+pip install agentreplay[langchain]
+
+# With LangGraph integration
+pip install agentreplay[langgraph]
+
+# With LlamaIndex integration
+pip install agentreplay[llamaindex]
+
+# Full installation (all integrations)
+pip install agentreplay[otel,langchain,langgraph,llamaindex]
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Set Environment Variables
+
+```bash
+export AGENTREPLAY_API_KEY="your-api-key"
+export AGENTREPLAY_PROJECT_ID="my-project"
+# Optional
+export AGENTREPLAY_BASE_URL="https://api.agentreplay.io"
+```
+
+### 2. Enable Auto-Instrumentation
+
+After installing the package, run the install command to enable zero-code auto-instrumentation:
+
+```bash
+# Run this once after pip install
+agentreplay-install
+```
+
+This installs a `.pth` file that automatically initializes Agentreplay when Python starts, enabling automatic tracing of OpenAI, Anthropic, and other LLM libraries **without any code changes**.
+
+#### Option A: Zero-Code (after running agentreplay-install)
+
+```bash
+# Just run your script - instrumentation happens automatically!
+python my_app.py
+```
+
+#### Option B: Code-Based Initialization
+
+Add these two lines at the **very beginning** of your main file, before any other imports:
+
+```python
+import agentreplay
+agentreplay.init()  # Must be called before importing OpenAI, Anthropic, etc.
+
+# Now import your LLM clients - they're automatically traced!
+from openai import OpenAI
+
+client = OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+# All OpenAI calls are automatically traced!
+
+# Ensure traces are sent before exit
+agentreplay.flush()
+```
+
+> ⚠️ **Important**: `agentreplay.init()` must be called **before** importing OpenAI, Anthropic, or other LLM libraries for auto-instrumentation to work.
+
+#### Managing Auto-Instrumentation
+
+```bash
+# Install auto-instrumentation (run once after pip install)
+agentreplay-install
+
+# Check if installed
+agentreplay-install --check
+
+# Uninstall auto-instrumentation
+agentreplay-install --uninstall
+```
+
+### 3. Manual Tracing with Decorators
+
+```python
+import agentreplay
+
+# Initialize (reads from env vars automatically)
+agentreplay.init()
+
+# Trace any function with a simple decorator
+@agentreplay.traceable
+def my_ai_function(query: str) -> str:
+    # Your AI logic here
+    return f"Response to: {query}"
+
+# Call your function - it's automatically traced!
+result = my_ai_function("What is the capital of France?")
+
+# Ensure all traces are sent before exit
+agentreplay.flush()
+```
+
+That's it! Your function calls are now being traced and sent to Agentreplay.
+
+---
+
+## 🔧 Core API Reference
+
+### Initialization
+
+```python
+import agentreplay
+
+# Option 1: Environment variables (recommended for production)
+agentreplay.init()
+
+# Option 2: Explicit configuration
+agentreplay.init(
+    api_key="your-api-key",
+    project_id="my-project",
+    base_url="https://api.agentreplay.io",
+    
+    # Optional settings
+    tenant_id="default",       # Multi-tenant identifier
+    agent_id="default",        # Default agent ID
+    enabled=True,              # Set False to disable in tests
+    capture_input=True,        # Capture function inputs
+    capture_output=True,       # Capture function outputs
+    batch_size=100,            # Batch size before sending
+    flush_interval=5.0,        # Auto-flush interval in seconds
+    debug=False,               # Enable debug logging
+)
+
+# Check if SDK is initialized
+from agentreplay.sdk import is_initialized
+if is_initialized():
+    print("SDK is ready!")
+
+# Get current configuration
+config = agentreplay.sdk.get_config()
+print(f"Project: {config.project_id}")
+```
+
+---
+
+## 🎯 The `@traceable` Decorator
+
+The primary and most Pythonic way to instrument your code:
+
+### Basic Usage
+
+```python
+from agentreplay import traceable
+
+# Just add the decorator - that's it!
+@traceable
+def process_query(query: str) -> str:
+    return call_llm(query)
+
+# Works with any function signature
+@traceable
+def complex_function(data: dict, *, optional_param: str = "default") -> list:
+    return process(data, optional_param)
+```
+
+### With Options
+
+```python
+from agentreplay import traceable, SpanKind
+
+# Custom span name and kind
+@traceable(name="openai_chat", kind=SpanKind.LLM)
+def call_openai(messages: list) -> str:
+    return openai_client.chat.completions.create(
+        model="gpt-4",
+        messages=messages
+    )
+
+# Disable input capture for sensitive data
+@traceable(capture_input=False)
+def authenticate(password: str) -> bool:
+    return verify_password(password)
+
+# Disable output capture
+@traceable(capture_output=False)
+def get_secret() -> str:
+    return fetch_secret_from_vault()
+
+# Add static metadata
+@traceable(metadata={"version": "2.0", "model": "gpt-4", "team": "ml"})
+def enhanced_query(query: str) -> str:
+    return process(query)
+```
+
+### Async Functions
+
+Full async/await support - no changes needed:
+
+```python
+import asyncio
+from agentreplay import traceable, SpanKind
+
+@traceable(kind=SpanKind.LLM)
+async def async_llm_call(prompt: str) -> str:
+    response = await openai_client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response.choices[0].message.content
+
+@traceable
+async def process_batch(queries: list[str]) -> list[str]:
+    # All concurrent calls are traced with proper parent-child relationships
+    tasks = [async_llm_call(q) for q in queries]
+    return await asyncio.gather(*tasks)
+
+# Run
+results = asyncio.run(process_batch(["query1", "query2", "query3"]))
+```
+
+---
+
+## 📐 Context Manager: `trace()`
+
+For more control over span attributes and timing:
+
+```python
+from agentreplay import trace, SpanKind
+
+def complex_operation(query: str) -> dict:
+    with trace("process_query", kind=SpanKind.CHAIN) as span:
+        # Set input data
+        span.set_input({"query": query, "timestamp": time.time()})
+        
+        # Nested span for document retrieval
+        with trace("retrieve_documents", kind=SpanKind.RETRIEVER) as retriever_span:
+            docs = vector_db.search(query, top_k=5)
+            retriever_span.set_output({"document_count": len(docs)})
+            retriever_span.set_attribute("vector_db", "pinecone")
+        
+        # Nested span for LLM generation
+        with trace("generate_response", kind=SpanKind.LLM) as llm_span:
+            llm_span.set_model("gpt-4", provider="openai")
+            response = generate_response(query, docs)
+            llm_span.set_token_usage(
+                prompt_tokens=150,
+                completion_tokens=200,
+                total_tokens=350
+            )
+            llm_span.set_output({"response_length": len(response)})
+        
+        # Add events for debugging
+        span.add_event("processing_complete", {"doc_count": len(docs)})
+        
+        # Set final output
+        span.set_output({"response": response, "sources": len(docs)})
+        
+        return {"response": response, "sources": docs}
+```
+
+### Manual Span Control
+
+For cases where you need explicit control:
+
+```python
+from agentreplay import start_span, SpanKind
+
+def long_running_operation():
+    span = start_span("background_job", kind=SpanKind.TOOL)
+    span.set_input({"job_type": "data_sync"})
+    
+    try:
+        # Long running work...
+        for i in range(100):
+            process_item(i)
+            if i % 10 == 0:
+                span.add_event("progress", {"completed": i})
+        
+        span.set_output({"items_processed": 100})
+        
+    except Exception as e:
+        span.set_error(e)
+        raise
+        
+    finally:
+        span.end()  # Always call end()
+```
+
+---
+
+## 🔌 LLM Client Wrappers
+
+### OpenAI (Recommended)
+
+One line to instrument all OpenAI calls:
+
+```python
+from openai import OpenAI
+from agentreplay import init, wrap_openai, flush
+
+init()
+
+# Wrap the client - all calls are now traced automatically!
+client = wrap_openai(OpenAI())
+
+# Use normally - tracing happens in the background
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Explain quantum computing in simple terms."}
+    ],
+    temperature=0.7,
+)
+
+print(response.choices[0].message.content)
+
+# Embeddings are traced too
+embedding = client.embeddings.create(
+    model="text-embedding-ada-002",
+    input="Hello world"
+)
+
+flush()
+```
+
+### Async OpenAI
+
+```python
+from openai import AsyncOpenAI
+from agentreplay import init, wrap_openai
+
+init()
+
+# Works with async client too
+async_client = wrap_openai(AsyncOpenAI())
+
+async def main():
+    response = await async_client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+    return response.choices[0].message.content
+```
+
+### Anthropic
+
+```python
+from anthropic import Anthropic
+from agentreplay import init, wrap_anthropic, flush
+
+init()
+
+# Wrap the Anthropic client
+client = wrap_anthropic(Anthropic())
+
+# Use normally
+message = client.messages.create(
+    model="claude-3-opus-20240229",
+    max_tokens=1024,
+    messages=[
+        {"role": "user", "content": "Explain the theory of relativity."}
+    ]
+)
+
+print(message.content[0].text)
+flush()
+```
+
+### Disable Content Capture
+
+For privacy-sensitive applications:
+
+```python
+# Don't capture message content, only metadata
+client = wrap_openai(OpenAI(), capture_content=False)
+
+# Traces will still include:
+# - Model name
+# - Token counts
+# - Latency
+# - Error information
+# But NOT the actual messages or responses
+```
+
+---
+
+## 🏷️ Context Management
+
+### Global Context
+
+Set context that applies to ALL subsequent traces:
+
+```python
+from agentreplay import set_context, get_global_context, clear_context
+
+# Set user context (persists until cleared)
+set_context(
+    user_id="user-123",
+    session_id="session-456",
+    agent_id="support-bot",
+)
+
+# Add more context later
+set_context(
+    environment="production",
+    version="1.2.0",
+    region="us-west-2",
+)
+
+# Get current global context
+context = get_global_context()
+print(context)  # {'user_id': 'user-123', 'session_id': 'session-456', ...}
+
+# Clear all context
+clear_context()
+```
+
+### Request-Scoped Context
+
+For web applications with per-request context:
+
+```python
+from agentreplay import with_context
+
+async def handle_api_request(request):
+    # Context only applies within this block
+    with with_context(
+        user_id=request.user_id,
+        request_id=request.headers.get("X-Request-ID"),
+        ip_address=request.client_ip,
+    ):
+        # All traces here include this context
+        result = await process_request(request)
+        
+    # Context automatically cleared after block
+    return result
+
+# Async version works too
+async def async_handler(request):
+    async with with_context(user_id=request.user_id):
+        return await async_process(request)
+```
+
+### Multi-Agent Context
+
+For multi-agent systems like CrewAI or AutoGen:
+
+```python
+from agentreplay import AgentContext
+
+def run_multi_agent_workflow():
+    # Each agent gets its own context
+    with AgentContext(
+        agent_id="researcher",
+        session_id="workflow-123",
+        workflow_id="content-creation",
+    ):
+        # All LLM calls here are tagged with agent_id="researcher"
+        research_results = researcher_agent.run()
+    
+    with AgentContext(
+        agent_id="writer",
+        session_id="workflow-123",  # Same session
+        workflow_id="content-creation",
+    ):
+        # These calls are tagged with agent_id="writer"
+        article = writer_agent.run(research_results)
+    
+    with AgentContext(
+        agent_id="editor",
+        session_id="workflow-123",
+        workflow_id="content-creation",
+    ):
+        final_article = editor_agent.run(article)
+    
+    return final_article
+```
+
+---
+
+## 🔒 Privacy & Data Redaction
+
+### Configure Privacy Settings
+
+```python
+from agentreplay import configure_privacy
+
+configure_privacy(
+    # Enable built-in patterns for common PII
+    use_builtin_patterns=True,  # Emails, credit cards, SSNs, phones, API keys
+    
+    # Add custom regex patterns
+    redact_patterns=[
+        r"secret-\w+",           # Custom secret format
+        r"internal-id-\d+",      # Internal IDs
+        r"password:\s*\S+",      # Password fields
+    ],
+    
+    # Completely scrub these JSON paths
+    scrub_paths=[
+        "input.password",
+        "input.credentials.api_key",
+        "output.user.ssn",
+        "metadata.internal_token",
+    ],
+    
+    # Hash PII instead of replacing with [REDACTED]
+    # Allows tracking unique values without exposing data
+    hash_pii=True,
+    hash_salt="your-secret-salt-here",
+    
+    # Custom replacement text
+    redacted_text="[SENSITIVE]",
+)
+```
+
+### Built-in Redaction Patterns
+
+The SDK includes patterns for:
+
+| Type | Example | Redacted As |
+|------|---------|-------------|
+| Email | user@example.com | [REDACTED] |
+| Credit Card | 4111-1111-1111-1111 | [REDACTED] |
+| SSN | 123-45-6789 | [REDACTED] |
+| Phone (US) | +1-555-123-4567 | [REDACTED] |
+| Phone (Intl) | +44-20-1234-5678 | [REDACTED] |
+| API Key | sk-proj-abc123... | [REDACTED] |
+| Bearer Token | Bearer eyJ... | [REDACTED] |
+| JWT | eyJhbG... | [REDACTED] |
+| IP Address | 192.168.1.1 | [REDACTED] |
+
+### Manual Redaction
+
+```python
+from agentreplay import redact_payload, redact_string, hash_pii
+
+# Redact an entire payload
+data = {
+    "user": {
+        "email": "john@example.com",
+        "phone": "+1-555-123-4567",
+    },
+    "message": "My credit card is 4111-1111-1111-1111",
+    "api_key": "sk-proj-abcdefghijk",
+}
+
+safe_data = redact_payload(data)
+# Result:
+# {
+#     "user": {
+#         "email": "[REDACTED]",
+#         "phone": "[REDACTED]",
+#     },
+#     "message": "My credit card is [REDACTED]",
+#     "api_key": "[REDACTED]",
+# }
+
+# Redact a single string
+safe_message = redact_string("Contact me at user@example.com")
+# "Contact me at [REDACTED]"
+
+# Hash for consistent anonymization (same input = same hash)
+user_hash = hash_pii("user@example.com")
+# "[HASH:a1b2c3d4]"
+
+# Useful for analytics without exposing PII
+print(f"User {user_hash} performed action")
+```
+
+### Temporary Privacy Context
+
+```python
+from agentreplay.privacy import privacy_context
+
+# Add extra redaction rules for a specific block
+with privacy_context(
+    redact_patterns=[r"internal-token-\w+"],
+    scrub_paths=["metadata.debug_info"],
+):
+    # These rules only apply within this block
+    result = process_sensitive_data(data)
+
+# Original rules restored after block
+```
+
+---
+
+## 📊 Span Kinds
+
+Use semantic span kinds for better visualization and filtering:
+
+```python
+from agentreplay import SpanKind
+
+# Available span kinds
+SpanKind.CHAIN       # Orchestration, workflows, pipelines
+SpanKind.LLM         # LLM API calls (OpenAI, Anthropic, etc.)
+SpanKind.TOOL        # Tool/function calls, actions
+SpanKind.RETRIEVER   # Vector DB search, document retrieval
+SpanKind.EMBEDDING   # Embedding generation
+SpanKind.GUARDRAIL   # Safety checks, content filtering
+SpanKind.CACHE       # Cache operations
+SpanKind.HTTP        # HTTP requests
+SpanKind.DB          # Database queries
+```
+
+Example usage:
+
+```python
+from agentreplay import traceable, SpanKind
+
+@traceable(kind=SpanKind.RETRIEVER)
+def search_documents(query: str) -> list:
+    return vector_db.similarity_search(query, k=5)
+
+@traceable(kind=SpanKind.LLM)
+def generate_answer(query: str, docs: list) -> str:
+    return llm.generate(query, context=docs)
+
+@traceable(kind=SpanKind.CHAIN)
+def rag_pipeline(query: str) -> str:
+    docs = search_documents(query)
+    return generate_answer(query, docs)
+```
+
+---
+
+## ⚙️ Lifecycle Management
+
+### Flushing Traces
+
+Always ensure traces are sent before your application exits:
+
+```python
+import agentreplay
+
+agentreplay.init()
+
+# Your application code...
+
+# Option 1: Manual flush with timeout
+agentreplay.flush(timeout=10.0)  # Wait up to 10 seconds
+
+# Option 2: Full graceful shutdown
+agentreplay.shutdown(timeout=30.0)  # Flush and cleanup
+
+# Option 3: Auto-registered (init() registers atexit handler automatically)
+# Traces are flushed on normal program exit
+```
+
+### Serverless / AWS Lambda
+
+**Critical**: Always flush explicitly before the function returns!
+
+```python
+import agentreplay
+
+agentreplay.init()
+
+@agentreplay.traceable
+def process_event(event):
+    # Your logic here
+    return {"processed": True}
+
+def lambda_handler(event, context):
+    try:
+        result = process_event(event)
+        return {
+            "statusCode": 200,
+            "body": json.dumps(result)
+        }
+    finally:
+        # CRITICAL: Flush before Lambda freezes
+        agentreplay.flush(timeout=5.0)
+```
+
+### FastAPI / Starlette
+
+```python
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+import agentreplay
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    agentreplay.init()
+    yield
+    # Shutdown
+    agentreplay.shutdown(timeout=10.0)
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/chat")
+async def chat(request: ChatRequest):
+    # Traces are sent automatically in background
+    return await process_chat(request)
+```
+
+### Diagnostics
+
+```python
+import agentreplay
+
+# Get SDK statistics
+stats = agentreplay.get_stats()
+print(f"Spans sent: {stats.get('spans_sent', 0)}")
+print(f"Spans pending: {stats.get('spans_pending', 0)}")
+print(f"Errors: {stats.get('errors', 0)}")
+print(f"Batches sent: {stats.get('batches_sent', 0)}")
+
+# Health check - verify backend connectivity
+if agentreplay.ping():
+    print("✅ Backend is reachable")
+else:
+    print("❌ Cannot reach backend")
+```
+
+---
+
+## 🔗 Framework Integrations
+
+### LangChain
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.schema import HumanMessage
+import agentreplay
+
+agentreplay.init()
+
+@agentreplay.traceable(name="langchain_qa", kind=agentreplay.SpanKind.CHAIN)
+def answer_question(question: str) -> str:
+    llm = ChatOpenAI(model="gpt-4", temperature=0)
+    response = llm.invoke([HumanMessage(content=question)])
+    return response.content
+
+result = answer_question("What is machine learning?")
+agentreplay.flush()
+```
+
+### LangGraph
+
+```python
+from langgraph.graph import StateGraph, END
+import agentreplay
+
+agentreplay.init()
+
+@agentreplay.traceable(name="agent_node", kind=agentreplay.SpanKind.LLM)
+def agent_node(state):
+    # Agent logic
+    response = llm.invoke(state["messages"])
+    return {"messages": state["messages"] + [response]}
+
+@agentreplay.traceable(name="tool_node", kind=agentreplay.SpanKind.TOOL)
+def tool_node(state):
+    # Tool execution
+    result = execute_tool(state["tool_call"])
+    return {"messages": state["messages"] + [result]}
+
+# Build graph with traced nodes
+workflow = StateGraph(State)
+workflow.add_node("agent", agent_node)
+workflow.add_node("tools", tool_node)
+# ... rest of graph definition
+```
+
+### CrewAI
+
+```python
+from crewai import Agent, Task, Crew
+import agentreplay
+
+agentreplay.init()
+
+# Wrap the LLM client
+wrapped_llm = agentreplay.wrap_openai(OpenAI())
+
+# Track each agent with context
+with agentreplay.AgentContext(agent_id="researcher", workflow_id="article-creation"):
+    researcher = Agent(
+        role="Senior Researcher",
+        goal="Find comprehensive information",
+        llm=wrapped_llm,
+    )
+
+with agentreplay.AgentContext(agent_id="writer", workflow_id="article-creation"):
+    writer = Agent(
+        role="Content Writer",
+        goal="Write engaging articles",
+        llm=wrapped_llm,
+    )
+
+# Run the crew
+crew = Crew(agents=[researcher, writer], tasks=[research_task, write_task])
+result = crew.kickoff()
+
+agentreplay.flush()
+```
+
+### LlamaIndex
+
+```python
+from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
+import agentreplay
+
+agentreplay.init()
+
+@agentreplay.traceable(name="index_documents", kind=agentreplay.SpanKind.EMBEDDING)
+def build_index(directory: str):
+    documents = SimpleDirectoryReader(directory).load_data()
+    return VectorStoreIndex.from_documents(documents)
+
+@agentreplay.traceable(name="query_index", kind=agentreplay.SpanKind.RETRIEVER)
+def query(index, question: str):
+    query_engine = index.as_query_engine()
+    return query_engine.query(question)
+
+index = build_index("./documents")
+response = query(index, "What is the main topic?")
+agentreplay.flush()
+```
+
+---
+
+## 🌐 Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AGENTREPLAY_API_KEY` | API key for authentication | **Required** |
+| `AGENTREPLAY_PROJECT_ID` | Project identifier | **Required** |
+| `AGENTREPLAY_BASE_URL` | API base URL | `https://api.agentreplay.io` |
+| `AGENTREPLAY_TENANT_ID` | Tenant identifier | `default` |
+| `AGENTREPLAY_AGENT_ID` | Default agent ID | `default` |
+| `AGENTREPLAY_ENABLED` | Enable/disable tracing | `true` |
+| `AGENTREPLAY_DEBUG` | Enable debug logging | `false` |
+| `AGENTREPLAY_BATCH_SIZE` | Spans per batch | `100` |
+| `AGENTREPLAY_FLUSH_INTERVAL` | Auto-flush interval (seconds) | `5.0` |
+| `AGENTREPLAY_CAPTURE_INPUT` | Capture function inputs | `true` |
+| `AGENTREPLAY_CAPTURE_OUTPUT` | Capture function outputs | `true` |
+
+---
+
+## 🧪 Testing
+
+### Disable Tracing in Tests
+
+```python
+import agentreplay
+import pytest
+
+@pytest.fixture(autouse=True)
+def disable_tracing():
+    """Disable tracing for all tests."""
+    agentreplay.init(enabled=False)
+    yield
+    agentreplay.reset()
+
+def test_my_function():
+    # Tracing is disabled, no network calls
+    result = my_traced_function("test")
+    assert result == expected
+```
+
+Or use environment variable:
+
+```bash
+AGENTREPLAY_ENABLED=false pytest
+```
+
+### Mock the SDK
+
+```python
+from unittest.mock import patch
+
+def test_with_mock():
+    with patch('agentreplay.flush'):
+        # flush() won't actually send data
+        result = my_function()
+```
+
+---
+
+## 📚 Complete API Reference
+
+### Top-Level Functions
+
+| Function | Description |
+|----------|-------------|
+| `init(**config)` | Initialize the SDK with configuration |
+| `flush(timeout=None)` | Send all pending traces |
+| `shutdown(timeout=None)` | Graceful shutdown with flush |
+| `reset()` | Reset SDK state completely |
+| `get_stats()` | Get diagnostic statistics |
+| `ping()` | Check backend connectivity |
+
+### Decorators & Tracing
+
+| Function | Description |
+|----------|-------------|
+| `@traceable` | Decorator for function tracing |
+| `@observe` | Alias for `@traceable` (Langfuse-style) |
+| `trace(name, **opts)` | Context manager for creating spans |
+| `start_span(name, **opts)` | Create a manual span |
+| `get_current_span()` | Get the currently active span |
+
+### Client Wrappers
+
+| Function | Description |
+|----------|-------------|
+| `wrap_openai(client, **opts)` | Wrap OpenAI client |
+| `wrap_anthropic(client, **opts)` | Wrap Anthropic client |
+| `wrap_method(obj, method, **opts)` | Wrap any method |
+
+### Context Management
+
+| Function | Description |
+|----------|-------------|
+| `set_context(**ctx)` | Set global context |
+| `get_global_context()` | Get current global context |
+| `clear_context()` | Clear all global context |
+| `with_context(**ctx)` | Scoped context manager |
+| `AgentContext(...)` | Class-based agent context |
+
+### Privacy
+
+| Function | Description |
+|----------|-------------|
+| `configure_privacy(**opts)` | Configure redaction settings |
+| `redact_payload(data)` | Redact sensitive data from dict |
+| `redact_string(text)` | Redact patterns from string |
+| `hash_pii(value, salt=None)` | Hash PII for anonymization |
+| `add_pattern(regex)` | Add redaction pattern at runtime |
+| `add_scrub_path(path)` | Add scrub path at runtime |
+
+### ActiveSpan Methods
+
+| Method | Description |
+|--------|-------------|
+| `set_input(data)` | Set span input data |
+| `set_output(data)` | Set span output data |
+| `set_attribute(key, value)` | Set a single attribute |
+| `set_attributes(dict)` | Set multiple attributes |
+| `add_event(name, attrs)` | Add a timestamped event |
+| `set_error(exception)` | Record an error |
+| `set_token_usage(...)` | Set LLM token counts |
+| `set_model(model, provider)` | Set model information |
+| `end()` | End the span |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+```bash
+# Clone the repository
+git clone https://github.com/agentreplay/agentreplay.git
+cd agentreplay/sdks/python
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run linter
+ruff check src/
+
+# Run type checker
+mypy src/agentreplay
+
+# Run formatter
+ruff format src/
+```
+
+---
+
+## 📄 License
+
+Apache 2.0 - see [LICENSE](../../LICENSE) for details.
+
+---
+
+## 🔗 Links
+
+- 📖 [Documentation](https://docs.agentreplay.io)
+- 💻 [GitHub Repository](https://github.com/agentreplay/agentreplay)
+- 📦 [PyPI Package](https://pypi.org/project/agentreplay/)
+- 💬 [Discord Community](https://discord.gg/agentreplay)
+- 🐦 [Twitter](https://twitter.com/agentreplay)
+
+---
+
+<p align="center">
+  Made with ❤️ by the Agentreplay team
+</p>