traccia 0.1.2__tar.gz → 0.1.6__tar.gz

{traccia-0.1.2 → traccia-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traccia
-Version: 0.1.2
+Version: 0.1.6
 Summary: Production-ready distributed tracing SDK for AI agents and LLM applications
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/traccia-ai/traccia
@@ -32,6 +32,8 @@ Requires-Dist: opentelemetry-semantic-conventions>=0.40b0
 Requires-Dist: tomli>=2.0.0; python_version < "3.11"
 Requires-Dist: toml>=0.10.0
 Requires-Dist: pydantic>=2.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
 Dynamic: license-file
 
 # Traccia
@@ -43,6 +45,7 @@ Traccia is a lightweight, high-performance Python SDK for observability and trac
 ## ✨ Features
 
 - **🔍 Automatic Instrumentation**: Auto-patch OpenAI, Anthropic, requests, and HTTP libraries
+- **🤖 Framework Integrations**: Support for LangChain and OpenAI Agents SDK
 - **📊 LLM-Aware Tracing**: Track tokens, costs, prompts, and completions automatically
 - **⚡ Zero-Config Start**: Simple `init()` call with automatic config discovery
 - **🎯 Decorator-Based**: Trace any function with `@observe` decorator
@@ -101,6 +104,59 @@ def generate_text(prompt: str) -> str:
 text = generate_text("Write a haiku about Python")
 ```
 
+### LangChain
+
+Create a callback handler and pass it to `config={"callbacks": [traccia_handler]}`. Install the optional extra: `pip install traccia[langchain]`.
+
+```python
+from traccia import init
+from traccia.integrations.langchain import CallbackHandler  # or TracciaCallbackHandler
+from langchain_openai import ChatOpenAI
+
+init()
+
+# Create Traccia handler (no args)
+traccia_handler = CallbackHandler()
+
+# Use with any LangChain runnable
+llm = ChatOpenAI(model="gpt-4o-mini")
+result = llm.invoke(
+    "Tell me a joke",
+    config={"callbacks": [traccia_handler]}
+)
+```
+
+Spans for LLM/chat model runs are created automatically with the same attributes as direct OpenAI instrumentation (model, prompt, usage, cost).
+
+**Note:** `pip install traccia[langchain]` installs traccia plus `langchain-core`; you need this extra to use the callback handler. If you already have `langchain-core` (e.g. from `langchain` or `langchain-openai`), base `pip install traccia` may be enough at runtime, but `traccia[langchain]` is the supported way to get a compatible dependency.
+
+### OpenAI Agents SDK
+
+Traccia **automatically** detects and instruments the OpenAI Agents SDK when installed. No extra code needed:
+
+```python
+from traccia import init
+from agents import Agent, Runner
+
+init()  # Automatically enables Agents SDK tracing
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant"
+)
+result = Runner.run_sync(agent, "Write a haiku about recursion")
+```
+
+**Configuration**: Auto-enabled by default when `openai-agents` is installed. To disable:
+
+```python
+init(openai_agents=False)  # Explicit parameter
+# OR set environment variable: TRACCIA_OPENAI_AGENTS=false
+# OR in traccia.toml under [instrumentation]: openai_agents = false
+```
+
+**Compatibility**: If you have `openai-agents` installed but don't use it (e.g., using LangChain or pure OpenAI instead), the integration is registered but never invoked—no overhead or extra spans.
+
 ---
 
 ## 📖 Configuration
@@ -141,6 +197,7 @@ reset_trace_file = false      # Reset file on initialization
 enable_patching = true          # Auto-patch libraries (OpenAI, Anthropic, requests)
 enable_token_counting = true    # Count tokens for LLM calls
 enable_costs = true             # Calculate costs
+openai_agents = true            # Auto-enable OpenAI Agents SDK integration
 auto_instrument_tools = false   # Auto-instrument tool calls (experimental)
 max_tool_spans = 100            # Max tool spans to create
 max_span_depth = 10             # Max nested span depth
@@ -470,18 +527,6 @@ init(debug=True)
 - Increase `max_queue_size` if spans are queued
 - Check `traccia doctor` output
 
-#### **Import errors after upgrade**
-
-If you're migrating from `traccia_sdk`:
-
-```python
-# OLD (will raise helpful error)
-from traccia_sdk import init  # ❌ ImportError with migration guide
-
-# NEW
-from traccia import init  # ✅ Correct
-```
-
 ---
 
 ## 📚 API Reference
@@ -537,13 +582,14 @@ Create a span context manager.
 
 ### Decorator
 
-#### `@observe(name=None, *, attributes=None, as_type="span", skip_args=None, skip_result=False)`
+#### `@observe(name=None, *, attributes=None, tags=None, as_type="span", skip_args=None, skip_result=False)`
 
 Decorate a function to create spans automatically.
 
 **Parameters**:
 - `name` (str, optional): Span name (default: function name)
 - `attributes` (dict, optional): Initial attributes
+- `tags` (list[str], optional): User-defined identifiers for the observed method
 - `as_type` (str): Span type (`"span"`, `"llm"`, `"tool"`)
 - `skip_args` (list, optional): Arguments to skip capturing
 - `skip_result` (bool): Skip capturing return value
@@ -590,6 +636,17 @@ Application Code (@observe)
    Backend (Grafana Tempo / Jaeger / Zipkin / etc.)
 ```
 
+### Instrumentation vs Integrations
+
+- **`traccia.instrumentation.*`**: Infrastructure and vendor instrumentation.
+  - HTTP client/server helpers (including FastAPI middleware).
+  - Vendor SDK hooks and monkey patching (e.g., OpenAI, Anthropic, `requests`).
+  - Decorators and utilities used for auto-instrumenting arbitrary functions.
+
+- **`traccia.integrations.*`**: AI/agent framework integrations.
+  - Adapters that plug into higher-level frameworks via their official extension points (e.g., LangChain callbacks).
+  - Work at the level of chains, tools, agents, and workflows rather than raw HTTP or SDK calls.
+
 ---
 
 ## 🤝 Contributing
@@ -649,7 +706,7 @@ pytest traccia/tests/ --cov=traccia --cov-report=html
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) for details
+Apache License 2.0 - see [LICENSE](LICENSE) for full terms and conditions.
 
 ---
 

{traccia-0.1.2 → traccia-0.1.6}/README.md

@@ -7,6 +7,7 @@ Traccia is a lightweight, high-performance Python SDK for observability and trac
 ## ✨ Features
 
 - **🔍 Automatic Instrumentation**: Auto-patch OpenAI, Anthropic, requests, and HTTP libraries
+- **🤖 Framework Integrations**: Support for LangChain and OpenAI Agents SDK
 - **📊 LLM-Aware Tracing**: Track tokens, costs, prompts, and completions automatically
 - **⚡ Zero-Config Start**: Simple `init()` call with automatic config discovery
 - **🎯 Decorator-Based**: Trace any function with `@observe` decorator
@@ -65,6 +66,59 @@ def generate_text(prompt: str) -> str:
 text = generate_text("Write a haiku about Python")
 ```
 
+### LangChain
+
+Create a callback handler and pass it to `config={"callbacks": [traccia_handler]}`. Install the optional extra: `pip install traccia[langchain]`.
+
+```python
+from traccia import init
+from traccia.integrations.langchain import CallbackHandler  # or TracciaCallbackHandler
+from langchain_openai import ChatOpenAI
+
+init()
+
+# Create Traccia handler (no args)
+traccia_handler = CallbackHandler()
+
+# Use with any LangChain runnable
+llm = ChatOpenAI(model="gpt-4o-mini")
+result = llm.invoke(
+    "Tell me a joke",
+    config={"callbacks": [traccia_handler]}
+)
+```
+
+Spans for LLM/chat model runs are created automatically with the same attributes as direct OpenAI instrumentation (model, prompt, usage, cost).
+
+**Note:** `pip install traccia[langchain]` installs traccia plus `langchain-core`; you need this extra to use the callback handler. If you already have `langchain-core` (e.g. from `langchain` or `langchain-openai`), base `pip install traccia` may be enough at runtime, but `traccia[langchain]` is the supported way to get a compatible dependency.
+
+### OpenAI Agents SDK
+
+Traccia **automatically** detects and instruments the OpenAI Agents SDK when installed. No extra code needed:
+
+```python
+from traccia import init
+from agents import Agent, Runner
+
+init()  # Automatically enables Agents SDK tracing
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant"
+)
+result = Runner.run_sync(agent, "Write a haiku about recursion")
+```
+
+**Configuration**: Auto-enabled by default when `openai-agents` is installed. To disable:
+
+```python
+init(openai_agents=False)  # Explicit parameter
+# OR set environment variable: TRACCIA_OPENAI_AGENTS=false
+# OR in traccia.toml under [instrumentation]: openai_agents = false
+```
+
+**Compatibility**: If you have `openai-agents` installed but don't use it (e.g., using LangChain or pure OpenAI instead), the integration is registered but never invoked—no overhead or extra spans.
+
 ---
 
 ## 📖 Configuration
@@ -105,6 +159,7 @@ reset_trace_file = false      # Reset file on initialization
 enable_patching = true          # Auto-patch libraries (OpenAI, Anthropic, requests)
 enable_token_counting = true    # Count tokens for LLM calls
 enable_costs = true             # Calculate costs
+openai_agents = true            # Auto-enable OpenAI Agents SDK integration
 auto_instrument_tools = false   # Auto-instrument tool calls (experimental)
 max_tool_spans = 100            # Max tool spans to create
 max_span_depth = 10             # Max nested span depth
@@ -434,18 +489,6 @@ init(debug=True)
 - Increase `max_queue_size` if spans are queued
 - Check `traccia doctor` output
 
-#### **Import errors after upgrade**
-
-If you're migrating from `traccia_sdk`:
-
-```python
-# OLD (will raise helpful error)
-from traccia_sdk import init  # ❌ ImportError with migration guide
-
-# NEW
-from traccia import init  # ✅ Correct
-```
-
 ---
 
 ## 📚 API Reference
@@ -501,13 +544,14 @@ Create a span context manager.
 
 ### Decorator
 
-#### `@observe(name=None, *, attributes=None, as_type="span", skip_args=None, skip_result=False)`
+#### `@observe(name=None, *, attributes=None, tags=None, as_type="span", skip_args=None, skip_result=False)`
 
 Decorate a function to create spans automatically.
 
 **Parameters**:
 - `name` (str, optional): Span name (default: function name)
 - `attributes` (dict, optional): Initial attributes
+- `tags` (list[str], optional): User-defined identifiers for the observed method
 - `as_type` (str): Span type (`"span"`, `"llm"`, `"tool"`)
 - `skip_args` (list, optional): Arguments to skip capturing
 - `skip_result` (bool): Skip capturing return value
@@ -554,6 +598,17 @@ Application Code (@observe)
    Backend (Grafana Tempo / Jaeger / Zipkin / etc.)
 ```
 
+### Instrumentation vs Integrations
+
+- **`traccia.instrumentation.*`**: Infrastructure and vendor instrumentation.
+  - HTTP client/server helpers (including FastAPI middleware).
+  - Vendor SDK hooks and monkey patching (e.g., OpenAI, Anthropic, `requests`).
+  - Decorators and utilities used for auto-instrumenting arbitrary functions.
+
+- **`traccia.integrations.*`**: AI/agent framework integrations.
+  - Adapters that plug into higher-level frameworks via their official extension points (e.g., LangChain callbacks).
+  - Work at the level of chains, tools, agents, and workflows rather than raw HTTP or SDK calls.
+
 ---
 
 ## 🤝 Contributing
@@ -613,7 +668,7 @@ pytest traccia/tests/ --cov=traccia --cov-report=html
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) for details
+Apache License 2.0 - see [LICENSE](LICENSE) for full terms and conditions.
 
 ---
 

traccia-0.1.6/__init__.py

@@ -0,0 +1,73 @@
+"""Python SDK entrypoint for the agent tracing library."""
+
+from traccia.auto import start_tracing, stop_tracing, init, trace, end_auto_trace
+from traccia.tracer import TracerProvider
+from traccia.instrumentation.decorator import observe
+
+# Version exposure
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    try:
+        __version__ = version("traccia")
+    except PackageNotFoundError:
+        __version__ = "0.1.0"  # Fallback version
+except ImportError:
+    __version__ = "0.1.0"  # Fallback for Python < 3.8
+
+# Initialize global tracer provider (now uses OpenTelemetry directly)
+_global_tracer_provider = TracerProvider()
+
+
+def get_tracer(name: str = "default"):
+    """Fetch a tracer from the global provider."""
+    return _global_tracer_provider.get_tracer(name)
+
+
+def span(name: str, attributes: dict = None):
+    """
+    Convenience function to create a span using the default tracer.
+    
+    This is a simpler alternative to:
+        tracer = get_tracer("name")
+        with tracer.start_as_current_span("span_name") as span:
+    
+    Usage:
+        from traccia import span
+        
+        with span("my_operation"):
+            # Your code here
+            pass
+        
+        # With attributes
+        with span("my_operation", {"key": "value"}) as s:
+            s.set_attribute("another", "attr")
+            # Your code here
+    """
+    tracer = get_tracer()
+    return tracer.start_as_current_span(name, attributes=attributes)
+
+
+def set_tracer_provider(provider: TracerProvider) -> None:
+    """Override the global tracer provider (primarily for tests or customization)."""
+    global _global_tracer_provider
+    _global_tracer_provider = provider
+
+
+def get_tracer_provider() -> TracerProvider:
+    return _global_tracer_provider
+
+
+__all__ = [
+    "__version__",
+    "get_tracer",
+    "get_tracer_provider",
+    "set_tracer_provider",
+    "start_tracing",
+    "stop_tracing",
+    "init",
+    "trace",
+    "end_auto_trace",
+    "span",
+    "observe",
+]
+