fiddler-langgraph 0.1.0rc1__tar.gz → 1.0.0__tar.gz

{fiddler_langgraph-0.1.0rc1 → fiddler_langgraph-1.0.0}/MANIFEST.in

@@ -1,5 +1,5 @@
 include LICENSE
-include README.md
+include PUBLIC.md
 include fiddler_langgraph/VERSION
 recursive-include fiddler_langgraph *.py
 recursive-exclude tests *

{fiddler_langgraph-0.1.0rc1 → fiddler_langgraph-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiddler-langgraph
-Version: 0.1.0rc1
+Version: 1.0.0
 Summary: Python SDK for instrumenting GenAI Applications with Fiddler
 Home-page: https://fiddler.ai
 Author: Fiddler AI
@@ -87,7 +87,7 @@ from fiddler_langgraph import FiddlerClient
 
 # Initialize the FiddlerClient with basic configuration
 client = FiddlerClient(
-    url="https://api.fiddler.ai",
+    url="https://your-instance.fiddler.ai",
     api_key="fdl_api_key",
     application_id="fdl_application_id"  # Must be a valid UUID4
 )
@@ -152,7 +152,7 @@ The Fiddler SDK provides flexible configuration options for OpenTelemetry integr
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",  # Must be a valid UUID4
-    url="https://api.fiddler.ai"
+    url="https://your-instance.fiddler.ai"
 )
 ```
 
@@ -178,6 +178,7 @@ sampler = sampling.TraceIdRatioBased(0.1)  # Sample 10% of traces
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
     span_limits=custom_limits,
     sampler=sampler,
     console_tracer=False,  # Set to True for debugging
@@ -196,6 +197,7 @@ from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
     compression=Compression.Gzip,
 )
 
@@ -203,6 +205,7 @@ client = FiddlerClient(
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
     compression=Compression.NoCompression,
 )
 
@@ -210,6 +213,7 @@ client = FiddlerClient(
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
     compression=Compression.Deflate,
 )
 ```
@@ -229,7 +233,8 @@ os.environ['OTEL_BSP_EXPORT_TIMEOUT'] = '10000'
 
 client = FiddlerClient(
     api_key="your-api-key",
-    application_id="your-app-id"
+    application_id="your-app-id",
+    url="https://your-instance.fiddler.ai"
 )
 ```
 

fiddler_langgraph-1.0.0/PUBLIC.md

@@ -0,0 +1,169 @@
+# fiddler-langgraph
+
+[![Python Version](https://img.shields.io/pypi/pyversions/fiddler-langgraph.svg)](https://pypi.org/project/fiddler-langgraph/)
+
+[![PyPI Version](https://img.shields.io/pypi/v/fiddler-langgraph.svg)](https://pypi.org/project/fiddler-langgraph/)
+
+[![License](https://img.shields.io/pypi/l/fiddler-langgraph.svg)](https://pypi.org/project/fiddler-langgraph/)
+
+The official Python SDK for instrumenting GenAI Applications with [Fiddler](https://www.fiddler.ai) using OpenTelemetry and LangGraph. Monitor, analyze, and protect your LangGraph workflows, LLMs, and AI Agents in production.
+
+## Platform Features
+
+- 🚀 **Easy Integration** - Simple Python API for LangGraph application instrumentation
+- 📊 **OpenTelemetry Tracing** - Full distributed tracing support with configurable span limits
+- 🔍 **Automatic Instrumentation** - Zero-config tracing for LangGraph workflows, chains, and tools
+- 🎯 **LLM Context Management** - Set additional context for LLM processing with `set_llm_context()`
+- 💬 **Conversation Tracking** - Track multi-turn conversations with `set_conversation_id()`
+- 📈 **Performance Metrics** - Automatic tracking of timing, token usage, and model information
+- 🛡️ **Error Handling** - Comprehensive error tracking with detailed stack traces
+- 🔄 **Flexible Configuration** - Custom span limits, sampling strategies, and batch processing
+- 📊 **Resource Management** - Conservative defaults to prevent resource exhaustion
+- 🎨 **Message Serialization** - Smart handling of complex message content (lists, dicts)
+- 🔔 **Attribute Truncation** - Automatic truncation of long attribute values to prevent oversized spans
+
+## Installation
+
+```bash
+pip install fiddler-langgraph
+```
+
+## Requirements
+
+- Python 3.10, 3.11, 3.12, or 3.13
+- LangGraph >= 0.3.28 and <= 1.0.2 or Langchain >= 0.3.28 and <= 1.0.2
+
+### With Example Dependencies
+
+To run the example scripts:
+
+```bash
+pip install fiddler-langgraph[examples]
+```
+
+## Quick Start
+
+```python
+from fiddler_langgraph import FiddlerClient
+from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor, set_llm_context, set_conversation_id
+
+# Initialize the FiddlerClient
+client = FiddlerClient(
+    url="https://your-instance.fiddler.ai",
+    api_key="your-api-key",
+    application_id="your-application-id"  # Must be a valid UUID4
+)
+
+# Instrument LangGraph applications
+LangGraphInstrumentor(client).instrument()
+
+# Set additional context for LLM processing
+from langchain_openai import ChatOpenAI
+model = ChatOpenAI(model='gpt-4o-mini')
+set_llm_context(model, "Previous conversation context")
+
+# Set conversation ID for multi-turn conversations
+from langgraph.graph import StateGraph
+workflow = StateGraph(state_schema=State)
+app = workflow.compile()
+set_conversation_id("conversation_123")
+app.invoke({"messages": [{"role": "user", "content": "Write a novel"}]})
+```
+
+## Documentation
+
+* 📚 [Complete Documentation](https://docs.fiddler.ai/)
+* 🚀 [LangGraph Quick Start Guide](https://docs.fiddler.ai/developers/tutorials/llm-monitoring/langgraph-sdk-quick-start)
+* 📖 [API Reference](https://docs.fiddler.ai/api/fiddler-langgraph-sdk/langgraph)
+
+## Example Usage
+
+### Basic Instrumentation
+
+```python
+from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor
+
+# Initialize and instrument
+instrumentor = LangGraphInstrumentor(client)
+instrumentor.instrument()
+```
+
+### Setting LLM Context
+
+```python
+from fiddler_langgraph.tracing.instrumentation import set_llm_context
+from langchain_openai import ChatOpenAI
+
+model = ChatOpenAI(model='gpt-4o-mini')
+set_llm_context(model, "User prefers concise responses")
+```
+
+### Conversation Tracking
+
+```python
+from fiddler_langgraph.tracing.instrumentation import set_conversation_id
+import uuid
+
+# Set conversation ID for tracking multi-turn conversations
+conversation_id = str(uuid.uuid4())
+set_conversation_id(conversation_id)
+```
+
+### Advanced Configuration
+
+```python
+from opentelemetry.sdk.trace import SpanLimits, sampling
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
+
+# Custom span limits for high-volume applications
+custom_limits = SpanLimits(
+    max_events=64,
+    max_links=64,
+    max_span_attributes=64,
+    max_event_attributes=64,
+    max_link_attributes=64,
+    max_span_attribute_length=4096,
+)
+
+# Sampling strategy for production
+sampler = sampling.TraceIdRatioBased(0.1)  # Sample 10% of traces
+
+client = FiddlerClient(
+    api_key="your-api-key",
+    application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
+    span_limits=custom_limits,
+    sampler=sampler,
+    console_tracer=False,  # Set to True for debugging
+    compression=Compression.Gzip,  # Enable gzip compression (default)
+)
+```
+
+## Example Notebooks
+
+Check out our [GitHub repository](https://github.com/fiddler-labs/fiddler-sdk/tree/main/examples) for example scripts demonstrating:
+
+- Basic LangGraph instrumentation
+- LLM context management
+- Conversation tracking
+- Multi-agent workflows
+- Travel agent applications
+- Chatbot implementations
+
+## Version History
+
+See our [release notes](https://docs.fiddler.ai/history/python-client-history) for detailed version history.
+
+## Support
+
+- 📧 Email: [support@fiddler.ai](mailto:support@fiddler.ai)
+- 💬 Community: [Join our Slack](https://www.fiddler.ai/slack)
+- 🐛 Issues: [GitHub Issues](https://github.com/fiddler-labs/fiddler-sdk/issues)
+
+## License
+
+Apache License 2.0 - see LICENSE file for details
+
+---
+
+**Want to see Fiddler in action?** [Request a demo](https://www.fiddler.ai/demo)

{fiddler_langgraph-0.1.0rc1 → fiddler_langgraph-1.0.0}/README.md

@@ -33,7 +33,7 @@ from fiddler_langgraph import FiddlerClient
 
 # Initialize the FiddlerClient with basic configuration
 client = FiddlerClient(
-    url="https://api.fiddler.ai",
+    url="https://your-instance.fiddler.ai",
     api_key="fdl_api_key",
     application_id="fdl_application_id"  # Must be a valid UUID4
 )
@@ -98,7 +98,7 @@ The Fiddler SDK provides flexible configuration options for OpenTelemetry integr
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",  # Must be a valid UUID4
-    url="https://api.fiddler.ai"
+    url="https://your-instance.fiddler.ai"
 )
 ```
 
@@ -124,6 +124,7 @@ sampler = sampling.TraceIdRatioBased(0.1)  # Sample 10% of traces
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
     span_limits=custom_limits,
     sampler=sampler,
     console_tracer=False,  # Set to True for debugging
@@ -142,6 +143,7 @@ from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
     compression=Compression.Gzip,
 )
 
@@ -149,6 +151,7 @@ client = FiddlerClient(
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
     compression=Compression.NoCompression,
 )
 
@@ -156,6 +159,7 @@ client = FiddlerClient(
 client = FiddlerClient(
     api_key="your-api-key",
     application_id="your-app-id",
+    url="https://your-instance.fiddler.ai",
     compression=Compression.Deflate,
 )
 ```
@@ -175,7 +179,8 @@ os.environ['OTEL_BSP_EXPORT_TIMEOUT'] = '10000'
 
 client = FiddlerClient(
     api_key="your-api-key",
-    application_id="your-app-id"
+    application_id="your-app-id",
+    url="https://your-instance.fiddler.ai"
 )
 ```
 

fiddler_langgraph-1.0.0/fiddler_langgraph/VERSION

@@ -0,0 +1 @@
+1.0.0

{fiddler_langgraph-0.1.0rc1 → fiddler_langgraph-1.0.0}/fiddler_langgraph/core/attributes.py

@@ -3,8 +3,6 @@
 import contextvars
 from typing import Any
 
-from pydantic import ConfigDict, validate_call
-
 # Key used for storing Fiddler-specific attributes in metadata dictionary
 FIDDLER_METADATA_KEY = '_fiddler_attributes'
 
@@ -66,22 +64,3 @@ _CONVERSATION_ID: contextvars.ContextVar[str] = contextvars.ContextVar(
 _CUSTOM_ATTRIBUTES: contextvars.ContextVar[dict[str, Any]] = contextvars.ContextVar(
     '_CUSTOM_ATTRIBUTES'
 )
-
-
-@validate_call(config=ConfigDict(strict=True, arbitrary_types_allowed=True))
-def add_session_attributes(key: str, value: str) -> None:
-    """Adds Fiddler-specific attributes to a runnable's metadata.
-
-    This is used for various runnable types like Pregel nodes, LLM calls, tool
-    calls, and retriever calls.
-
-    Args:
-        key (str): The attribute key to add or update.
-        value (str): The attribute value to set.
-    """
-    try:
-        current_attributes = _CUSTOM_ATTRIBUTES.get().copy()
-    except LookupError:
-        current_attributes = {}
-    current_attributes[key] = value
-    _CUSTOM_ATTRIBUTES.set(current_attributes)

{fiddler_langgraph-0.1.0rc1 → fiddler_langgraph-1.0.0}/fiddler_langgraph/core/client.py

@@ -60,7 +60,7 @@ class FiddlerClient:
         self,
         api_key: str,
         application_id: str,
-        url: str = 'http://localhost:4318',
+        url: str,
         console_tracer: bool = False,
         span_limits: SpanLimits | None = _default_span_limits,
         sampler: sampling.Sampler | None = None,
@@ -76,41 +76,69 @@ class FiddlerClient:
         Args:
             api_key (str): The API key for authenticating with the Fiddler backend. **Required**.
             application_id (str): The unique identifier (UUID4) for the application. **Required**.
-            url (str): The base URL for the Fiddler backend. While it defaults to
-                `http://localhost:4318` for local development, this **must** be set to your
-                Fiddler instance URL for any other use.
+            url (str): The base URL for your Fiddler instance. This is specific to your
+                deployment, whether hosted, VPC-deployed, on-premise, or local development
+                (e.g., `https://your-instance.fiddler.ai`, `http://localhost:4318`). **Required**.
             console_tracer (bool): If True, traces will be printed to the console
                 instead of being sent to the Fiddler backend. Useful for debugging.
                 Defaults to `False`.
             span_limits (SpanLimits | None): Configuration for span limits, such as the
                 maximum number of attributes or events. Defaults to a restrictive
-                set of internal limits.
+                set of internal limits (32 events/links/attributes, 2048 char limit).
             sampler (sampling.Sampler | None): The sampler for deciding which spans to record.
-                Defaults to `None`, which uses the parent-based OpenTelemetry sampler.
+                Defaults to `None`, which uses the parent-based always-on OpenTelemetry sampler
+                (100% sampling).
             compression (Compression): The compression for exporting traces.
-                Can be `Compression.Gzip` or `Compression.NoCompression`.
-                Defaults to `Compression.Gzip`.
+                Can be `Compression.Gzip`, `Compression.Deflate`, or `Compression.NoCompression`.
+                Defaults to `Compression.Gzip` (recommended for production).
             jsonl_capture_enabled (bool): Whether to enable JSONL capture of trace data.
                 When enabled, all span data will be captured and saved to a JSONL file
-                in OpenTelemetry format for analysis. Defaults to `False`.
+                in OpenTelemetry format for offline analysis. Defaults to `False`.
             jsonl_file_path (str): Path to the JSONL file where trace data will be saved.
                 Only used when `jsonl_capture_enabled` is `True`. Defaults to
                 "fiddler_trace_data.jsonl".
 
         Raises:
             ValueError: If `application_id` is not a valid UUID4 or if the
-                `url` is not a valid HTTPS URL.
+                `url` is not a valid HTTP/HTTPS URL.
 
         Examples:
-            >>> from opentelemetry.sdk.trace import SpanLimits
-            >>> from fiddler_langgraph import FiddlerClient
-            >>>
-            >>> client = FiddlerClient(
-            ...     api_key='YOUR_API_KEY',
-            ...     application_id='YOUR_APPLICATION_ID',
-            ...     url='https://your-fiddler-instance.fiddler.ai',
-            ...     span_limits=SpanLimits(max_span_attributes=64),
-            ... )
+            Basic connection to your Fiddler instance:
+
+            .. code-block:: python
+
+                client = FiddlerClient(
+                    api_key='YOUR_API_KEY',
+                    application_id='YOUR_APPLICATION_ID',
+                    url='https://your-instance.fiddler.ai',
+                )
+
+            High-volume applications with custom configuration:
+
+            .. code-block:: python
+
+                from opentelemetry.sdk.trace import SpanLimits, sampling
+                from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
+
+                client = FiddlerClient(
+                    api_key='YOUR_API_KEY',
+                    application_id='YOUR_APPLICATION_ID',
+                    url='https://your-instance.fiddler.ai',
+                    span_limits=SpanLimits(max_span_attributes=64),
+                    sampler=sampling.TraceIdRatioBased(0.1),  # Sample 10% of traces
+                    compression=Compression.Gzip,
+                )
+
+            Local development with console output:
+
+            .. code-block:: python
+
+                client = FiddlerClient(
+                    api_key='dev-key',
+                    application_id='00000000-0000-0000-0000-000000000000',
+                    url='http://localhost:4318',
+                    console_tracer=True,  # Print traces to console for debugging
+                )
         """
         # Validate application_id is a valid UUID4
 
@@ -216,9 +244,11 @@ class FiddlerClient:
             ValueError: If the tracer has already been initialized.
 
         Examples:
-            >>> from fiddler_langgraph import FiddlerClient
-            >>> client = FiddlerClient(api_key='...', application_id='...')
-            >>> client.update_resource({'service.version': '1.2.3'})
+            .. code-block:: python
+
+                from fiddler_langgraph import FiddlerClient
+                client = FiddlerClient(api_key='...', application_id='...', url='https://your-instance.fiddler.ai')
+                client.update_resource({'service.version': '1.2.3'})
         """
         if self._tracer is not None:
             raise ValueError('Cannot update resource after tracer is initialized')
@@ -305,11 +335,13 @@ class FiddlerClient:
             RuntimeError: If tracer initialization fails.
 
         Examples:
-            >>> from fiddler_langgraph import FiddlerClient
-            >>> client = FiddlerClient(api_key='...', application_id='...')
-            >>> tracer = client.get_tracer()
-            >>> with tracer.start_as_current_span('my-operation'):
-            ...     print('Doing some work...')
+            .. code-block:: python
+
+                from fiddler_langgraph import FiddlerClient
+                client = FiddlerClient(api_key='...', application_id='...', url='https://your-instance.fiddler.ai')
+                tracer = client.get_tracer()
+                with tracer.start_as_current_span('my-operation'):
+                    print('Doing some work...')
         """
         if self._tracer is None:
             self._initialize_tracer()

{fiddler_langgraph-0.1.0rc1 → fiddler_langgraph-1.0.0}/fiddler_langgraph/tracing/callback.py

@@ -208,7 +208,12 @@ class _CallbackHandler(BaseCallbackHandler):
         if metadata is not None:
             fiddler_attributes = metadata.get(FIDDLER_METADATA_KEY, {})
             for key, value in fiddler_attributes.items():
-                fdl_key = FIDDLER_USER_SPAN_ATTRIBUTE_TEMPLATE.format(key=key)
+                # FiddlerSpanAttributes keys should not be prefixed with fiddler.span.user.
+                fdl_key = (
+                    key
+                    if key in vars(FiddlerSpanAttributes).values()
+                    else FIDDLER_USER_SPAN_ATTRIBUTE_TEMPLATE.format(key=key)
+                )
                 span.set_attribute(fdl_key, value)
 
     def _update_root_span_agent_name(self, agent_name: str) -> None:
@@ -626,7 +631,6 @@ class _CallbackHandler(BaseCallbackHandler):
             system_message = [m for m in messages[0] if isinstance(m, SystemMessage)]
             user_message = [m for m in messages[0] if isinstance(m, HumanMessage)]
 
-        # breakpoint()
         if metadata is not None:
             _set_agent_name(child_span, metadata)