fiddler-otel 0.1.1__tar.gz

fiddler_otel-0.1.1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: fiddler-otel
+Version: 0.1.1
+Summary: Core OpenTelemetry instrumentation library for Fiddler GenAI observability
+Author-email: Fiddler AI <support@fiddler.ai>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://fiddler.ai
+Project-URL: Documentation, https://docs.fiddler.ai
+Project-URL: Repository, https://github.com/fiddler-labs/fiddler-sdk
+Project-URL: Issues, https://github.com/fiddler-labs/fiddler-sdk/issues
+Keywords: fiddler,ai,genai,llm,monitoring,observability,instrumentation,opentelemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Software Development :: Quality Assurance
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Requires-Dist: pydantic>=2.0
+
+# fiddler-otel
+
+Core OpenTelemetry instrumentation library for **Fiddler GenAI observability**. This is the foundation package used by all Fiddler framework integrations (`fiddler-langgraph`, `fiddler-langchain`).
+
+## Installation
+
+```bash
+pip install fiddler-otel
+```
+
+## Quick Start
+
+### Using the `@trace` decorator
+
+The simplest way to instrument any Python function — synchronous or async:
+
+```python
+from fiddler_otel import FiddlerClient, trace
+
+client = FiddlerClient(
+    api_key="YOUR_API_KEY",
+    application_id="YOUR_APPLICATION_ID",
+    url="https://your-instance.fiddler.ai",
+)
+
+@trace(span_type="generation", name="my_llm_call")
+def call_llm(prompt: str) -> str:
+    # your LLM call here
+    return response
+
+@trace(span_type="chain")
+async def run_pipeline(user_input: str) -> str:
+    result = call_llm(user_input)
+    return result
+```
+
+### Using span wrappers manually
+
+For fine-grained control over span attributes:
+
+```python
+from fiddler_otel import FiddlerClient, FiddlerGeneration, FiddlerChain, FiddlerTool
+
+client = FiddlerClient(
+    api_key="YOUR_API_KEY",
+    application_id="YOUR_APPLICATION_ID",
+    url="https://your-instance.fiddler.ai",
+)
+
+with client.start_span("my_agent", span_type="chain") as chain_span:
+    gen = FiddlerGeneration(client.start_span("llm_call"))
+    with gen as span:
+        span.set_input("What is the capital of France?")
+        response = call_llm("What is the capital of France?")
+        span.set_output(response)
+        span.set_usage(input_tokens=10, output_tokens=5, total_tokens=15)
+```
+
+### Multi-turn Conversations
+
+Link multiple agent invocations into a single conversation:
+
+```python
+from fiddler_otel import set_conversation_id
+import uuid
+
+set_conversation_id(str(uuid.uuid4()))
+
+# All spans created after this call carry the same conversation_id
+result = my_agent(user_message)
+```
+
+### Local JSONL Capture
+
+Capture all spans to a local file for debugging without sending to Fiddler:
+
+```python
+client = FiddlerClient(
+    api_key="...",
+    application_id="...",
+    url="...",
+    jsonl_capture_enabled=True,
+    jsonl_file_path="trace_data.jsonl",
+)
+```
+
+Or via environment variables:
+
+```bash
+FIDDLER_JSONL_ENABLED=true \
+FIDDLER_JSONL_FILE=trace_data.jsonl \
+python my_agent.py
+```
+
+### Console Tracing (Development)
+
+Print all spans to stdout during development:
+
+```python
+client = FiddlerClient(
+    api_key="...",
+    application_id="...",
+    url="...",
+    console_tracer=True,
+)
+```
+
+## Public API
+
+| Symbol | Description |
+|---|---|
+| `FiddlerClient` | Main client — configures the tracer and exports spans to Fiddler |
+| `FiddlerSpan` | Base span wrapper with `set_input`, `set_output`, `set_attribute` |
+| `FiddlerGeneration` | LLM span wrapper — adds `set_usage`, `set_messages`, `set_context` |
+| `FiddlerChain` | Chain/pipeline span wrapper |
+| `FiddlerTool` | Tool call span wrapper |
+| `trace` | Decorator for automatic span creation around any function |
+| `get_current_span` | Get the active Fiddler span inside a traced function |
+| `set_conversation_id` | Link multiple invocations into one conversation |
+| `get_client` | Return the global singleton `FiddlerClient` |
+
+## Context Isolation
+
+`fiddler-otel` uses its own **isolated OpenTelemetry context** that does not interfere with any existing global tracer in your application. If you already use OpenTelemetry for infrastructure tracing, Fiddler spans will not appear in your infrastructure traces and vice versa.
+
+## Framework Integrations
+
+| Package | Framework | Install |
+|---|---|---|
+| `fiddler-langgraph` | LangGraph + LangChain v0.x | `pip install fiddler-langgraph` |
+| `fiddler-langchain` | LangChain V1 (`create_agent`) | `pip install fiddler-langchain` |
+
+Both integration packages depend on `fiddler-otel` and re-export its core symbols, so you typically only need to install the integration package for your framework.
+
+## Requirements
+
+- Python 3.10+
+- `opentelemetry-api >= 1.27.0`
+- `opentelemetry-sdk >= 1.27.0`
+- `opentelemetry-exporter-otlp-proto-http >= 1.27.0`
+- `pydantic >= 2.0`

fiddler_otel-0.1.1/README.md

@@ -0,0 +1,141 @@
+# fiddler-otel
+
+Core OpenTelemetry instrumentation library for **Fiddler GenAI observability**. This is the foundation package used by all Fiddler framework integrations (`fiddler-langgraph`, `fiddler-langchain`).
+
+## Installation
+
+```bash
+pip install fiddler-otel
+```
+
+## Quick Start
+
+### Using the `@trace` decorator
+
+The simplest way to instrument any Python function — synchronous or async:
+
+```python
+from fiddler_otel import FiddlerClient, trace
+
+client = FiddlerClient(
+    api_key="YOUR_API_KEY",
+    application_id="YOUR_APPLICATION_ID",
+    url="https://your-instance.fiddler.ai",
+)
+
+@trace(span_type="generation", name="my_llm_call")
+def call_llm(prompt: str) -> str:
+    # your LLM call here
+    return response
+
+@trace(span_type="chain")
+async def run_pipeline(user_input: str) -> str:
+    result = call_llm(user_input)
+    return result
+```
+
+### Using span wrappers manually
+
+For fine-grained control over span attributes:
+
+```python
+from fiddler_otel import FiddlerClient, FiddlerGeneration, FiddlerChain, FiddlerTool
+
+client = FiddlerClient(
+    api_key="YOUR_API_KEY",
+    application_id="YOUR_APPLICATION_ID",
+    url="https://your-instance.fiddler.ai",
+)
+
+with client.start_span("my_agent", span_type="chain") as chain_span:
+    gen = FiddlerGeneration(client.start_span("llm_call"))
+    with gen as span:
+        span.set_input("What is the capital of France?")
+        response = call_llm("What is the capital of France?")
+        span.set_output(response)
+        span.set_usage(input_tokens=10, output_tokens=5, total_tokens=15)
+```
+
+### Multi-turn Conversations
+
+Link multiple agent invocations into a single conversation:
+
+```python
+from fiddler_otel import set_conversation_id
+import uuid
+
+set_conversation_id(str(uuid.uuid4()))
+
+# All spans created after this call carry the same conversation_id
+result = my_agent(user_message)
+```
+
+### Local JSONL Capture
+
+Capture all spans to a local file for debugging without sending to Fiddler:
+
+```python
+client = FiddlerClient(
+    api_key="...",
+    application_id="...",
+    url="...",
+    jsonl_capture_enabled=True,
+    jsonl_file_path="trace_data.jsonl",
+)
+```
+
+Or via environment variables:
+
+```bash
+FIDDLER_JSONL_ENABLED=true \
+FIDDLER_JSONL_FILE=trace_data.jsonl \
+python my_agent.py
+```
+
+### Console Tracing (Development)
+
+Print all spans to stdout during development:
+
+```python
+client = FiddlerClient(
+    api_key="...",
+    application_id="...",
+    url="...",
+    console_tracer=True,
+)
+```
+
+## Public API
+
+| Symbol | Description |
+|---|---|
+| `FiddlerClient` | Main client — configures the tracer and exports spans to Fiddler |
+| `FiddlerSpan` | Base span wrapper with `set_input`, `set_output`, `set_attribute` |
+| `FiddlerGeneration` | LLM span wrapper — adds `set_usage`, `set_messages`, `set_context` |
+| `FiddlerChain` | Chain/pipeline span wrapper |
+| `FiddlerTool` | Tool call span wrapper |
+| `trace` | Decorator for automatic span creation around any function |
+| `get_current_span` | Get the active Fiddler span inside a traced function |
+| `set_conversation_id` | Link multiple invocations into one conversation |
+| `get_client` | Return the global singleton `FiddlerClient` |
+
+## Context Isolation
+
+`fiddler-otel` uses its own **isolated OpenTelemetry context** that does not interfere with any existing global tracer in your application. If you already use OpenTelemetry for infrastructure tracing, Fiddler spans will not appear in your infrastructure traces and vice versa.
+
+## Framework Integrations
+
+| Package | Framework | Install |
+|---|---|---|
+| `fiddler-langgraph` | LangGraph + LangChain v0.x | `pip install fiddler-langgraph` |
+| `fiddler-langchain` | LangChain V1 (`create_agent`) | `pip install fiddler-langchain` |
+
+Both integration packages depend on `fiddler-otel` and re-export its core symbols, so you typically only need to install the integration package for your framework.
+
+## Requirements
+
+- Python 3.10+
+- `opentelemetry-api >= 1.27.0`
+- `opentelemetry-sdk >= 1.27.0`
+- `opentelemetry-exporter-otlp-proto-http >= 1.27.0`
+- `pydantic >= 2.0`

fiddler_otel-0.1.1/VERSION

@@ -0,0 +1 @@
+0.1.1

fiddler_otel-0.1.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0,<82.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fiddler-otel"
+dynamic = ["version"]
+authors = [
+    {name = "Fiddler AI", email = "support@fiddler.ai"},
+]
+description = "Core OpenTelemetry instrumentation library for Fiddler GenAI observability"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Topic :: Software Development :: Quality Assurance",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+keywords = ["fiddler", "ai", "genai", "llm", "monitoring", "observability", "instrumentation", "opentelemetry"]
+dependencies = [
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://fiddler.ai"
+Documentation = "https://docs.fiddler.ai"
+Repository = "https://github.com/fiddler-labs/fiddler-sdk"
+Issues = "https://github.com/fiddler-labs/fiddler-sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {file = ["VERSION"]}
+
+[tool.setuptools.package-data]
+fiddler_otel = ["VERSION"]

fiddler_otel-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fiddler_otel-0.1.1/src/fiddler_otel/__init__.py

@@ -0,0 +1,26 @@
+"""Fiddler OTel - core OpenTelemetry instrumentation for GenAI applications."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from fiddler_otel.attributes import set_conversation_id
+from fiddler_otel.client import FiddlerClient, get_client
+from fiddler_otel.decorators import get_current_span, trace
+from fiddler_otel.span_wrapper import FiddlerChain, FiddlerGeneration, FiddlerSpan, FiddlerTool
+
+try:
+    __version__ = version('fiddler-otel')
+except PackageNotFoundError:
+    __version__ = 'unknown'
+
+__all__ = [
+    'FiddlerChain',
+    'FiddlerClient',
+    'FiddlerGeneration',
+    'FiddlerSpan',
+    'FiddlerTool',
+    '__version__',
+    'get_client',
+    'get_current_span',
+    'set_conversation_id',
+    'trace',
+]

fiddler_otel-0.1.1/src/fiddler_otel/attributes.py

@@ -0,0 +1,97 @@
+"""OpenTelemetry span attributes for Fiddler instrumentation."""
+
+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'
+
+# Template strings for OpenTelemetry attribute key formatting
+FIDDLER_USER_SPAN_ATTRIBUTE_TEMPLATE = 'fiddler.span.user.{key}'
+FIDDLER_USER_SESSION_ATTRIBUTE_TEMPLATE = 'fiddler.session.user.{key}'
+
+
+class FiddlerSpanAttributes:  # pylint: disable=too-few-public-methods
+    """Constants for Fiddler OpenTelemetry span attributes."""
+
+    # common attributes
+    AGENT_NAME = 'gen_ai.agent.name'
+    AGENT_ID = 'gen_ai.agent.id'
+    CONVERSATION_ID = 'gen_ai.conversation.id'
+    TYPE = 'fiddler.span.type'
+    SERVICE_VERSION = 'service.version'
+
+    # LLM attributes
+    LLM_INPUT_SYSTEM = 'gen_ai.llm.input.system'
+    LLM_INPUT_USER = 'gen_ai.llm.input.user'
+    LLM_OUTPUT = 'gen_ai.llm.output'
+    LLM_CONTEXT = 'gen_ai.llm.context'
+
+    # Model attributes - following OpenTelemetry semantic conventions
+    LLM_REQUEST_MODEL = 'gen_ai.request.model'
+    LLM_SYSTEM = 'gen_ai.system'
+
+    # Token usage attributes
+    LLM_TOKEN_COUNT_INPUT = 'gen_ai.usage.input_tokens'
+    LLM_TOKEN_COUNT_OUTPUT = 'gen_ai.usage.output_tokens'
+    LLM_TOKEN_COUNT_TOTAL = 'gen_ai.usage.total_tokens'
+    GEN_AI_INPUT_MESSAGES = 'gen_ai.input.messages'
+    GEN_AI_OUTPUT_MESSAGES = 'gen_ai.output.messages'
+
+    # tool attributes
+    TOOL_INPUT = 'gen_ai.tool.input'
+    TOOL_OUTPUT = 'gen_ai.tool.output'
+    TOOL_NAME = 'gen_ai.tool.name'
+    TOOL_DEFINITIONS = 'gen_ai.tool.definitions'
+
+
+class FiddlerResourceAttributes:
+    """Constants for Fiddler OpenTelemetry resource attributes."""
+
+    APPLICATION_ID = 'application.id'
+
+
+class SpanType:
+    """Constants for Fiddler OpenTelemetry span types."""
+
+    AGENT = 'agent'
+    CHAIN = 'chain'
+    TOOL = 'tool'
+    LLM = 'llm'
+    OTHER = 'other'
+
+
+# context variable for conversation ID - used to store the conversation ID for the current
+# thread/async coroutine. Note that contextvars are shallow copied; dictionaries/lists are not
+# copied deeply and are shared between threads/coroutines.
+_CONVERSATION_ID: contextvars.ContextVar[str] = contextvars.ContextVar(
+    '_CONVERSATION_ID', default=''
+)
+_CUSTOM_ATTRIBUTES: contextvars.ContextVar[dict[str, Any] | None] = contextvars.ContextVar(
+    '_CUSTOM_ATTRIBUTES', default=None
+)
+
+
+@validate_call(config=ConfigDict(strict=True))
+def set_conversation_id(conversation_id: str) -> None:
+    """Set the conversation ID for the current execution context.
+
+    The conversation ID is propagated to all spans created in the current
+    thread or async coroutine, allowing the Fiddler dashboard to filter and
+    display the full ordered sequence of operations for a single conversation.
+
+    This value persists until it is called again with a new ID.
+
+    :param conversation_id: Unique identifier for the conversation session.
+
+    Example::
+
+        from fiddler_otel import set_conversation_id
+        import uuid
+
+        set_conversation_id(str(uuid.uuid4()))
+        agent.invoke({"messages": [{"role": "user", "content": "Hello"}]})
+    """
+    _CONVERSATION_ID.set(conversation_id)