# Fiddler LangGraph SDK

[![PyPI](https://img.shields.io/pypi/v/fiddler-langgraph)](https://pypi.org/project/fiddler-langgraph/)

## Deprecation notices

### Re-exported `fiddler-otel` symbols

Importing core `fiddler-otel` symbols directly from `fiddler_langgraph` is deprecated and will be removed in a future major release. This affects the following imports:

```python
# Deprecated — will be removed in a future release
from fiddler_langgraph import FiddlerClient
from fiddler_langgraph import FiddlerSpan, FiddlerGeneration, FiddlerChain, FiddlerTool
from fiddler_langgraph import trace, get_current_span, get_client, set_conversation_id
```

**Recommended migration:** Import these symbols from `fiddler_otel` directly:

```python
# Correct — import from fiddler_otel
from fiddler_otel import FiddlerClient
from fiddler_otel import FiddlerSpan, FiddlerGeneration, FiddlerChain, FiddlerTool
from fiddler_otel import trace, get_current_span, get_client, set_conversation_id
```

`LangGraphInstrumentor`, `add_session_attributes`, `add_span_attributes`, and `set_llm_context` remain in `fiddler_langgraph` and are not affected.

***

## 1.4

### **1.4.1**

*March 20, 2026*

* **Bug Fixes**
  * **Fixed `set_conversation_id()` ignored after first LangGraph invocation**: When using `LangGraphInstrumentor`, calling `set_conversation_id()` between agent invocations had no effect — every span after the first run carried the conversation ID from the initial call. The root cause was a `@cached_property` on the internal `_CallbackHandler` that read the conversation ID contextvar once on first access and froze that value for the lifetime of the `_CallbackHandler` instance. The cached property has been replaced with a direct contextvar read on every span, matching the behaviour of `FiddlerSpanProcessor`. `set_conversation_id()` now takes effect immediately for all subsequent invocations.

### **1.4.0**

*February 18, 2026*

* **Added**
  * **Decorator-based instrumentation**: New `@trace()` decorator for automatic function instrumentation.
    * `@trace()` decorator for instrumenting any Python function with minimal boilerplate.
    * `get_current_span()` to access the current span inside decorated functions.
    * Support for span types: `span`, `generation`, `chain`, `tool`, with type-specific wrappers and helpers (e.g. `set_user_prompt()`, `set_tool_input()`).
    * Automatic parent-child relationship from call stack.
    * Decorator arguments for metadata: `model`, `system`, `user_id`, `version`.
    * `capture_input` and `capture_output` arguments for controlling automatic argument/return value capture.
    * Automatic async function detection — `@trace()` works with both sync and async functions.
  * **Manual instrumentation**: Context managers and explicit control.
    * `client.start_as_current_span(name, as_type=...)` for context-manager usage with automatic lifecycle and exception recording.
    * `client.start_span(name, as_type=...)` for explicit control; caller must call `span.end()`.
    * Support for all span types with both patterns.
  * **Span wrapper classes**: Typed wrappers with semantic convention helpers.
    * `FiddlerSpan` (base), `FiddlerGeneration`, `FiddlerChain`, `FiddlerTool` — returned by `start_as_current_span()`, `start_span()`, and `get_current_span()`.
    * `FiddlerGeneration` helpers: `set_model()`, `set_system()`, `set_user_prompt()`, `set_completion()`, `set_usage()`, `set_messages()`, `set_output_messages()`, `set_tool_definitions()`.
    * `FiddlerTool` helpers: `set_tool_name()`, `set_tool_input()`, `set_tool_output()`.
    * Common helpers on all wrappers: `set_input()`, `set_output()`, `set_attribute()`, `set_agent_name()`, `set_conversation_id()`.
  * **Global client accessor**: `get_client()` retrieves the active `FiddlerClient` singleton for use in decorators and utility functions.
  * **Context isolation**: Isolation from other OpenTelemetry tracers.
    * Each `FiddlerClient` uses its own isolated `Context`.
    * `is_fiddler_span()` utility to verify span ownership.

## 1.3

### **1.3.1**

*February 5, 2026*

* **Enhancements**
  * **Automatic Span Flush on Exit**: `FiddlerClient` now registers an `atexit` handler to automatically flush and shut down the tracer provider when the process exits, reducing span loss from in-memory buffering.
  * **Explicit Flush and Shutdown Methods**: New `force_flush(timeout_millis)` and `shutdown()` methods on `FiddlerClient` for explicit control over span export. `shutdown()` is idempotent and safe to call multiple times.
  * **Asyncio Support**: New `aflush()` and `ashutdown()` async methods run flush and shutdown in a thread pool, avoiding event loop blocking in asyncio applications.
  * **Context Manager Support**: `FiddlerClient` can now be used as a context manager (`with FiddlerClient(...) as client:`) to ensure automatic shutdown on exit.
* **Bug Fixes**
  * **Fixed Pydantic Double-Encoding**: Corrected JSON serialization of Pydantic models to use `model_dump()` instead of `model_dump_json()`, preventing double-encoded JSON strings in span attributes.
  * **Deduplicated Retriever Span Attributes**: Removed duplicate `TYPE` and `TOOL_NAME` attribute assignments in the `on_retriever_start` callback.
  * **Replaced `print()` with `logging`**: All `print()` calls in `jsonl_capture.py` now use the standard `logging` module for proper log management.

### **1.3.0**

*January 21, 2026*

* **Enhancements**
  * **OpenTelemetry Version Upgrade**: Updated OpenTelemetry dependencies to version 1.39.1/0.60b1 for improved performance and compatibility:
    * `opentelemetry-api`: now supports up to 1.39.1
    * `opentelemetry-sdk`: now supports up to 1.39.1
    * `opentelemetry-instrumentation`: now supports up to 0.60b1
    * `opentelemetry-exporter-otlp-proto-http`: now supports up to 1.39.1

## 1.2

### **1.2.0**

*January 14, 2026*

* **Enhancements**
  * **Removed Hardcoded OpenTelemetry Limits**: Removed hardcoded default values for span limits and batch span processor configuration. The SDK now relies on OpenTelemetry SDK's built-in defaults, simplifying configuration and ensuring consistency with standard OpenTelemetry defaults.
  * **Enhanced LangGraph Tracing with Full Message History**: Introduced comprehensive message lifecycle tracking with two new span attributes:
    * `gen_ai.input.messages`: Captures the complete message history provided as input to the LLM, including system, user, assistant, and tool messages
    * `gen_ai.output.messages`: Captures the output messages generated by the LLM, including tool calls and finish\_reason when available
    * Both attributes are aligned with GenAI semantic conventions for standardized observability
  * **Extracted Message History from Strands Span Events**: Added support for extracting `gen_ai.input.messages` and `gen_ai.output.messages` from Strands span events (emitted as events rather than attributes) and storing them as span-level attributes in ClickHouse for unified querying and analysis.

## 1.0

### **1.0.0**

*December 6, 2025*

* **Breaking Changes**
  * **Moved `add_session_attributes` to Tracing Module**: The `add_session_attributes()` method has been relocated from the Core module to the Tracing module to co-locate session management functions with related tracing utilities.
    * **Old import**: `from fiddler_langgraph.core.attributes import add_session_attributes`
    * **New import**: `from fiddler_langgraph.tracing.instrumentation import add_session_attributes`
    * **Migration**: Update import statements in your code. No functional changes—all behavior remains identical.
    * **Impact**: Existing code using the old import path will fail with ImportError

## 0.1

### **0.1.1**

*Previous Release*

Initial release of Fiddler LangGraph SDK.