pandaprobe 0.1.1__tar.gz

pandaprobe-0.1.1/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.vscode/
+.cursor/plans/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+!.env.example

pandaprobe-0.1.1/Makefile

@@ -0,0 +1,43 @@
+.PHONY: install install-langgraph install-google-adk install-claude-agent-sdk install-crewai install-openai-agents lock lint format format-check test test-cov build clean
+
+install:
+	uv sync --extra dev
+
+install-langgraph:
+	uv sync --extra dev --extra langgraph
+
+install-google-adk:
+	uv sync --extra dev --extra google-adk
+
+install-claude-agent-sdk:
+	uv sync --extra dev --extra claude-agent-sdk
+
+install-crewai:
+	uv sync --extra dev --extra crewai
+
+install-openai-agents:
+	uv sync --extra dev --extra openai-agents
+
+lock:
+	uv lock
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run ruff format .
+
+format-check:
+	uv run ruff format --check .
+
+test:
+	uv run pytest tests/ -v
+
+test-cov:
+	uv run pytest tests/ -v --cov=pandaprobe --cov-report=term-missing
+
+build:
+	uv build
+
+clean:
+	rm -rf dist/ build/ *.egg-info src/*.egg-info .pytest_cache .ruff_cache

pandaprobe-0.1.1/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: pandaprobe
+Version: 0.1.1
+Summary: Python SDK for PandaProbe — open-source agent tracing and evaluation
+Project-URL: Homepage, https://github.com/chirpz-ai/pandaprobe-sdk
+Project-URL: Documentation, https://github.com/chirpz-ai/pandaprobe-sdk
+Project-URL: Repository, https://github.com/chirpz-ai/pandaprobe-sdk
+Author-email: PandaProbe | Chirpz AI <support@chirpz.ai>
+License-Expression: MIT
+Keywords: agents,ai,evaluation,llm,observability,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.80.0; extra == 'anthropic'
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'claude-agent-sdk'
+Requires-Dist: wrapt>=1.14.0; extra == 'claude-agent-sdk'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.100.0; extra == 'crewai'
+Requires-Dist: wrapt>=1.14.0; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.80.0; extra == 'dev'
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: google-genai>=1.0.0; extra == 'dev'
+Requires-Dist: langchain-google-genai>=4.0.0; extra == 'dev'
+Requires-Dist: langchain-openai>=0.2.0; extra == 'dev'
+Requires-Dist: openai>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: twine>=6.0.0; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: anthropic>=0.80.0; extra == 'examples'
+Requires-Dist: google-genai>=1.0.0; extra == 'examples'
+Requires-Dist: langchain-google-genai>=4.0.0; extra == 'examples'
+Requires-Dist: langchain-openai>=0.2.0; extra == 'examples'
+Requires-Dist: openai>=1.0.0; extra == 'examples'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
+Provides-Extra: google-adk
+Requires-Dist: google-adk>=1.0.0; extra == 'google-adk'
+Requires-Dist: wrapt>=1.14.0; extra == 'google-adk'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3.0; extra == 'langgraph'
+Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.13.0; extra == 'openai-agents'
+Description-Content-Type: text/markdown
+
+# PandaProbe Python SDK
+
+Python SDK for [PandaProbe](https://github.com/chirpz-ai/pandaprobe-sdk) — open-source agent tracing and evaluation.
+
+## Installation
+
+```bash
+pip install pandaprobe
+```
+
+With optional integrations:
+
+```bash
+pip install pandaprobe[openai]       # OpenAI wrapper
+pip install pandaprobe[gemini]       # Google Gemini wrapper
+pip install pandaprobe[anthropic]    # Anthropic wrapper
+pip install pandaprobe[langgraph]    # LangGraph integration
+pip install pandaprobe[all]          # Everything
+```
+
+## Quick Start
+
+### 1. Set environment variables
+
+```bash
+export PANDAPROBE_API_KEY="sk_pp_..."
+export PANDAPROBE_PROJECT_NAME="my-project"
+export PANDAPROBE_ENDPOINT="my-pandaprobe-endpoint"
+export PANDAPROBE_ENVIRONMENT="production"   # optional
+export PANDAPROBE_RELEASE="v1.2.0"           # optional
+```
+
+The SDK auto-initializes from these environment variables on first use — no explicit `init()` call is needed. To disable tracing, set `PANDAPROBE_ENABLED=false`.
+
+You can still use `pandaprobe.init(...)` for programmatic configuration if preferred.
+
+### 2. Decorator-based tracing (custom agents)
+
+```python
+import pandaprobe
+
+@pandaprobe.trace(name="my-agent")
+def run_agent(query: str):
+    @pandaprobe.span(name="llm-call", kind="LLM")
+    def call_llm(prompt):
+        return openai_client.chat.completions.create(...)
+
+    @pandaprobe.span(name="search", kind="TOOL")
+    def search(q):
+        return search_engine.search(q)
+
+    context = search(query)
+    return call_llm(f"Context: {context}\nQuery: {query}")
+```
+
+### 3. OpenAI wrapper (automatic LLM tracing)
+
+```python
+from pandaprobe.wrappers import wrap_openai
+import openai
+
+client = wrap_openai(openai.OpenAI())
+
+# Chat Completions API — automatically traced:
+response = client.chat.completions.create(
+    model="gpt-5.4-nano",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+
+# Responses API — also automatically traced, including reasoning summaries
+# and built-in tool calls (web_search, function_call, etc.) as child spans:
+response = client.responses.create(
+    model="gpt-5.4-nano",
+    input="Explain recursion in one sentence.",
+    reasoning={"effort": "low", "summary": "auto"},
+)
+```
+
+### 4. Gemini wrapper (automatic LLM tracing)
+
+```python
+from pandaprobe.wrappers import wrap_gemini
+from google import genai
+
+client = wrap_gemini(genai.Client())
+
+response = client.models.generate_content(
+    model="gemini-2.5-flash",
+    contents="Explain recursion in one sentence.",
+)
+```
+
+### 5. Anthropic wrapper (automatic LLM tracing)
+
+```python
+from pandaprobe.wrappers import wrap_anthropic
+import anthropic
+
+client = wrap_anthropic(anthropic.Anthropic())
+
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=150,
+    system="You are a concise assistant.",
+    messages=[{"role": "user", "content": "Explain recursion in one sentence."}],
+)
+```
+
+### 6. LangGraph integration
+
+```python
+from pandaprobe.integrations.langgraph import LangGraphCallbackHandler
+
+handler = LangGraphCallbackHandler()
+result = graph.invoke(
+    {"messages": [HumanMessage(content="hello")]},
+    config={"callbacks": [handler]},
+)
+```
+
+### 7. Session and user tracking
+
+Group related traces under a session and/or user using the universal context API:
+
+```python
+import pandaprobe
+
+# Context managers — scoped to the block
+with pandaprobe.session("conversation-123"):
+    with pandaprobe.user("user-abc"):
+        run_agent("What is recursion?")
+        run_agent("Can you give me an example?")
+
+# Imperative — useful for dynamic switching
+pandaprobe.set_session("conversation-456")
+pandaprobe.set_user("user-xyz")
+run_agent("New topic")
+```
+
+Both propagate across all SDK layers (decorators, wrappers, integrations, context managers). Explicit parameters (`session_id=`, `user_id=`) take precedence over the context.
+
+### 8. Programmatic scoring
+
+```python
+pandaprobe.score(
+    trace_id="...",
+    name="user_satisfaction",
+    value="0.9",
+    data_type="NUMERIC",
+    reason="User clicked thumbs up",
+)
+```
+
+### 9. Flushing
+
+For short-lived scripts, call `pandaprobe.flush()` before exiting to ensure all traces are sent. For long-running processes, the SDK flushes automatically via a background thread and an `atexit` handler.
+
+```python
+pandaprobe.flush()
+pandaprobe.shutdown()
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| `PANDAPROBE_API_KEY` | *(required)* | API key |
+| `PANDAPROBE_PROJECT_NAME` | *(required)* | Project name |
+| `PANDAPROBE_ENDPOINT` | `http://localhost:8000` | Backend URL |
+| `PANDAPROBE_ENVIRONMENT` | `None` | Environment tag (e.g. `production`, `staging`) |
+| `PANDAPROBE_RELEASE` | `None` | Release/version tag (e.g. `v1.2.0`) |
+| `PANDAPROBE_ENABLED` | `true` | Enable/disable SDK |
+| `PANDAPROBE_BATCH_SIZE` | `10` | Traces per flush batch |
+| `PANDAPROBE_FLUSH_INTERVAL` | `5.0` | Seconds between flushes |
+| `PANDAPROBE_DEBUG` | `false` | Verbose logging |
+
+## Development
+
+```bash
+make py-install       # Install all deps (providers, examples, dev tools)
+make py-lint          # Run linter
+make py-format        # Auto-format
+make py-test          # Run tests
+make py-test-cov      # Tests with coverage
+```
+
+## License
+
+MIT

pandaprobe-0.1.1/README.md

@@ -0,0 +1,189 @@
+# PandaProbe Python SDK
+
+Python SDK for [PandaProbe](https://github.com/chirpz-ai/pandaprobe-sdk) — open-source agent tracing and evaluation.
+
+## Installation
+
+```bash
+pip install pandaprobe
+```
+
+With optional integrations:
+
+```bash
+pip install pandaprobe[openai]       # OpenAI wrapper
+pip install pandaprobe[gemini]       # Google Gemini wrapper
+pip install pandaprobe[anthropic]    # Anthropic wrapper
+pip install pandaprobe[langgraph]    # LangGraph integration
+pip install pandaprobe[all]          # Everything
+```
+
+## Quick Start
+
+### 1. Set environment variables
+
+```bash
+export PANDAPROBE_API_KEY="sk_pp_..."
+export PANDAPROBE_PROJECT_NAME="my-project"
+export PANDAPROBE_ENDPOINT="my-pandaprobe-endpoint"
+export PANDAPROBE_ENVIRONMENT="production"   # optional
+export PANDAPROBE_RELEASE="v1.2.0"           # optional
+```
+
+The SDK auto-initializes from these environment variables on first use — no explicit `init()` call is needed. To disable tracing, set `PANDAPROBE_ENABLED=false`.
+
+You can still use `pandaprobe.init(...)` for programmatic configuration if preferred.
+
+### 2. Decorator-based tracing (custom agents)
+
+```python
+import pandaprobe
+
+@pandaprobe.trace(name="my-agent")
+def run_agent(query: str):
+    @pandaprobe.span(name="llm-call", kind="LLM")
+    def call_llm(prompt):
+        return openai_client.chat.completions.create(...)
+
+    @pandaprobe.span(name="search", kind="TOOL")
+    def search(q):
+        return search_engine.search(q)
+
+    context = search(query)
+    return call_llm(f"Context: {context}\nQuery: {query}")
+```
+
+### 3. OpenAI wrapper (automatic LLM tracing)
+
+```python
+from pandaprobe.wrappers import wrap_openai
+import openai
+
+client = wrap_openai(openai.OpenAI())
+
+# Chat Completions API — automatically traced:
+response = client.chat.completions.create(
+    model="gpt-5.4-nano",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+
+# Responses API — also automatically traced, including reasoning summaries
+# and built-in tool calls (web_search, function_call, etc.) as child spans:
+response = client.responses.create(
+    model="gpt-5.4-nano",
+    input="Explain recursion in one sentence.",
+    reasoning={"effort": "low", "summary": "auto"},
+)
+```
+
+### 4. Gemini wrapper (automatic LLM tracing)
+
+```python
+from pandaprobe.wrappers import wrap_gemini
+from google import genai
+
+client = wrap_gemini(genai.Client())
+
+response = client.models.generate_content(
+    model="gemini-2.5-flash",
+    contents="Explain recursion in one sentence.",
+)
+```
+
+### 5. Anthropic wrapper (automatic LLM tracing)
+
+```python
+from pandaprobe.wrappers import wrap_anthropic
+import anthropic
+
+client = wrap_anthropic(anthropic.Anthropic())
+
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=150,
+    system="You are a concise assistant.",
+    messages=[{"role": "user", "content": "Explain recursion in one sentence."}],
+)
+```
+
+### 6. LangGraph integration
+
+```python
+from pandaprobe.integrations.langgraph import LangGraphCallbackHandler
+
+handler = LangGraphCallbackHandler()
+result = graph.invoke(
+    {"messages": [HumanMessage(content="hello")]},
+    config={"callbacks": [handler]},
+)
+```
+
+### 7. Session and user tracking
+
+Group related traces under a session and/or user using the universal context API:
+
+```python
+import pandaprobe
+
+# Context managers — scoped to the block
+with pandaprobe.session("conversation-123"):
+    with pandaprobe.user("user-abc"):
+        run_agent("What is recursion?")
+        run_agent("Can you give me an example?")
+
+# Imperative — useful for dynamic switching
+pandaprobe.set_session("conversation-456")
+pandaprobe.set_user("user-xyz")
+run_agent("New topic")
+```
+
+Both propagate across all SDK layers (decorators, wrappers, integrations, context managers). Explicit parameters (`session_id=`, `user_id=`) take precedence over the context.
+
+### 8. Programmatic scoring
+
+```python
+pandaprobe.score(
+    trace_id="...",
+    name="user_satisfaction",
+    value="0.9",
+    data_type="NUMERIC",
+    reason="User clicked thumbs up",
+)
+```
+
+### 9. Flushing
+
+For short-lived scripts, call `pandaprobe.flush()` before exiting to ensure all traces are sent. For long-running processes, the SDK flushes automatically via a background thread and an `atexit` handler.
+
+```python
+pandaprobe.flush()
+pandaprobe.shutdown()
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| `PANDAPROBE_API_KEY` | *(required)* | API key |
+| `PANDAPROBE_PROJECT_NAME` | *(required)* | Project name |
+| `PANDAPROBE_ENDPOINT` | `http://localhost:8000` | Backend URL |
+| `PANDAPROBE_ENVIRONMENT` | `None` | Environment tag (e.g. `production`, `staging`) |
+| `PANDAPROBE_RELEASE` | `None` | Release/version tag (e.g. `v1.2.0`) |
+| `PANDAPROBE_ENABLED` | `true` | Enable/disable SDK |
+| `PANDAPROBE_BATCH_SIZE` | `10` | Traces per flush batch |
+| `PANDAPROBE_FLUSH_INTERVAL` | `5.0` | Seconds between flushes |
+| `PANDAPROBE_DEBUG` | `false` | Verbose logging |
+
+## Development
+
+```bash
+make py-install       # Install all deps (providers, examples, dev tools)
+make py-lint          # Run linter
+make py-format        # Auto-format
+make py-test          # Run tests
+make py-test-cov      # Tests with coverage
+```
+
+## License
+
+MIT

pandaprobe-0.1.1/examples/README.md

@@ -0,0 +1,166 @@
+# PandaProbe SDK Examples
+
+Real end-to-end examples that call live services and send traces to the PandaProbe backend. Use these to validate SDK integrations during development.
+
+## Setup
+
+### 1. Install the SDK with all dependencies
+
+From the repo root:
+
+```bash
+make py-install
+```
+
+### 2. Export environment variables
+
+All examples require:
+
+```bash
+export PANDAPROBE_API_KEY="sk_pp_..."
+export PANDAPROBE_PROJECT_NAME="my-project"
+export PANDAPROBE_ENDPOINT="http://localhost:8000"
+
+# Provider keys (set whichever you need):
+export OPENAI_API_KEY="sk-..."
+export GOOGLE_API_KEY="..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+The SDK auto-initializes from these environment variables — no `pandaprobe.init()` call is needed.
+
+
+To enable debug logging:
+
+```bash
+export PANDAPROBE_DEBUG=true
+```
+
+To disable tracing:
+
+```bash
+export PANDAPROBE_ENABLED=false
+```
+
+### 3. Run any example
+
+```bash
+cd libraries/python
+uv run python examples/openai/01_chat_completion.py
+```
+
+## Examples
+
+### Context Managers
+
+| Example | Description |
+|---|---|
+| `context_managers/01_rag_pipeline.py` | RAG pipeline with retrieval + LLM generation + scoring via `pandaprobe.start_trace()` and `trace.span()` |
+| `context_managers/02_multi_turn.py` | Multi-turn tutoring agent with session grouping via `pandaprobe.session()` |
+
+### Decorators
+
+| Example | Description |
+|---|---|
+| `decorators/01_support_agent.py` | Customer support agent with retrieval + LLM via `@pandaprobe.trace` and `@pandaprobe.span` |
+| `decorators/02_multi_turn.py` | Multi-turn topic assistant with session grouping via `pandaprobe.session()` + `@pandaprobe.trace` |
+
+### OpenAI Wrapper
+
+| Example | Description |
+|---|---|
+| `openai/01_chat_completion.py` | Chat Completions API with automatic tracing via `wrap_openai` |
+| `openai/02_streaming.py` | Streaming chat completion with automatic tracing via `wrap_openai` |
+| `openai/03_multi_turn.py` | Multi-turn conversation with session grouping via `pandaprobe.session()` + `wrap_openai` |
+| `openai/04_responses_api.py` | Responses API with reasoning summaries and automatic tracing via `wrap_openai` |
+
+### Gemini Wrapper
+
+| Example | Description |
+|---|---|
+| `gemini/01_chat_completion.py` | generate_content with automatic tracing via `wrap_gemini` |
+| `gemini/02_multi_turn.py` | Multi-turn conversation with session grouping via `pandaprobe.session()` + `wrap_gemini` |
+
+### Anthropic Wrapper
+
+| Example | Description |
+|---|---|
+| `anthropic/01_chat_completion.py` | messages.create with extended thinking and automatic tracing via `wrap_anthropic` |
+| `anthropic/02_multi_turn.py` | Multi-turn conversation with extended thinking and session grouping via `pandaprobe.session()` + `wrap_anthropic` |
+
+### LangGraph
+
+| Example | Description |
+|---|---|
+| `langgraph/01_chatbot.py` | Simple chatbot with `LangGraphCallbackHandler` |
+| `langgraph/02_tool_agent.py` | ReAct agent with weather + population tools via `LangGraphCallbackHandler` |
+| `langgraph/03_multi_turn.py` | Multi-turn travel advisor with session grouping via `pandaprobe.session()` + `LangGraphCallbackHandler` |
+
+### Google ADK
+
+| Example | Description |
+|---|---|
+| `google_adk/01_simple_agent.py` | Simple chatbot agent with automatic tracing via `GoogleADKAdapter` |
+| `google_adk/02_tool_agent.py` | Agent with weather + population tools via `GoogleADKAdapter` |
+| `google_adk/03_multi_turn.py` | Multi-turn travel advisor with session grouping via `pandaprobe.session()` + `GoogleADKAdapter` |
+
+### Claude Agent SDK
+
+| Example | Description |
+|---|---|
+| `claude_agent_sdk/01_simple_agent.py` | Simple chatbot with automatic tracing via `ClaudeAgentSDKAdapter` |
+| `claude_agent_sdk/02_tool_agent.py` | Agent with custom tools (weather + population) via `ClaudeAgentSDKAdapter` |
+| `claude_agent_sdk/03_multi_turn.py` | Multi-turn travel advisor with session grouping via `pandaprobe.session()` + `ClaudeAgentSDKAdapter` |
+
+### CrewAI
+
+| Example | Description |
+|---|---|
+| `crewai/01_simple_crew.py` | Simple crew with a single agent and task via `CrewAIAdapter` |
+| `crewai/02_tool_crew.py` | Crew with tool-calling agent (weather + population) via `CrewAIAdapter` |
+| `crewai/03_multi_agent.py` | Multi-agent crew with sequential task execution via `CrewAIAdapter` |
+
+### OpenAI Agents SDK
+
+| Example | Description |
+|---|---|
+| `openai_agents/01_simple_agent.py` | Simple agent with automatic tracing via `OpenAIAgentsAdapter` |
+| `openai_agents/02_tool_agent.py` | Agent with function tools (weather + population) via `OpenAIAgentsAdapter` |
+| `openai_agents/03_multi_turn.py` | Multi-turn conversation with session grouping via `pandaprobe.session()` + `OpenAIAgentsAdapter` |
+
+
+## Session API
+
+The SDK provides a universal `session_id` propagation mechanism that works across all layers:
+
+```python
+import uuid
+import pandaprobe
+
+session_id = str(uuid.uuid4())
+
+# Option 1: Context manager (recommended for scoped usage)
+with pandaprobe.session(session_id):
+    # All traces created here inherit the session_id
+    run_agent(query)
+
+# Option 2: Imperative setter (for dynamic switching)
+pandaprobe.set_session(str(uuid.uuid4()))
+run_agent(query)
+```
+
+Session precedence (highest to lowest):
+1. Explicit parameter (`session_id="..."` passed directly)
+2. Context var (`pandaprobe.session()` / `pandaprobe.set_session()`)
+3. None
+
+## What to Look For
+
+After running an example, check your PandaProbe backend to verify:
+
+- **Traces** appear with the correct name and project
+- **Spans** show proper parent-child hierarchy
+- **LLM spans** capture model name, token usage, and input/output
+- **Tool spans** (LangGraph examples) capture tool name and results
+- **Scores** are attached to the correct traces
+- **Sessions** group related traces together (multi-turn examples)