Metadata-Version: 2.4
Name: fiddler-strands
Version: 0.3.0
Summary: Fiddler SDK for Strands Agent instrumentation with OpenTelemetry
Project-URL: Homepage, https://github.com/fiddler-labs/fiddler-strands-sdk
Project-URL: Repository, https://github.com/fiddler-labs/fiddler-strands-sdk
Project-URL: Documentation, https://docs.fiddler.ai/strands-sdk
Project-URL: Issues, https://github.com/fiddler-labs/fiddler-strands-sdk/issues
Author-email: Fiddler AI <support@fiddler.ai>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
Requires-Dist: opentelemetry-instrumentation>=0.41b0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: strands-agents>=1.10.0
Provides-Extra: dev
Requires-Dist: bandit>=1.8.5; extra == 'dev'
Requires-Dist: black>=25.1.0; extra == 'dev'
Requires-Dist: flake8>=7.2.0; extra == 'dev'
Requires-Dist: ipython>=8.12.3; extra == 'dev'
Requires-Dist: isort>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.16.1; extra == 'dev'
Requires-Dist: nox>=2025.5.1; extra == 'dev'
Requires-Dist: pre-commit>=4.2.0; extra == 'dev'
Requires-Dist: pylint>=3.3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
Requires-Dist: pytest>=8.3.5; extra == 'dev'
Requires-Dist: ruff>=0.13.3; extra == 'dev'
Requires-Dist: strands-agents[openai]==1.12.0; extra == 'dev'
Requires-Dist: tomli==2.2.1; extra == 'dev'
Provides-Extra: examples
Requires-Dist: openai>=1.0.0; extra == 'examples'
Requires-Dist: python-dotenv>=1.0.0; extra == 'examples'
Requires-Dist: strands-agents-tools>=0.2.0; extra == 'examples'
Description-Content-Type: text/markdown

# Fiddler Strands SDK

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

OpenTelemetry instrumentation SDK for [Strands AI](https://strands.ai) agents, providing automatic observability and monitoring capabilities through Fiddler's platform.

## Features

- 🎯 **Automatic Instrumentation**: Zero-code instrumentation of Strands agents using OpenTelemetry
- 🔍 **Built-in Observability**: Automatic logging hooks for agent interactions
- 📊 **Fiddler Integration**: Custom span processors for enhanced trace analysis
- 🛠️ **Extensible**: Easy to add custom hooks and processors
- 🚀 **Production Ready**: Built on OpenTelemetry standards

## Installation

### Using uv (Recommended)

```bash
# Install the SDK
uv add fiddler-strands
```

### Using pip

```bash
pip install fiddler-strands
```

## Quick Start

### Prerequisites

Before using the SDK, ensure you have:
- **Fiddler platform access** with API credentials
- **OpenAI API key** (if using OpenAI models)
- Configure environment variables:
  - `FIDDLER_ENDPOINT`: Your Fiddler platform URL
  - `FIDDLER_TOKEN`: Your Fiddler API token
  - `FIDDLER_APPLICATION_UUID`: Your application UUID from Fiddler

See the [full documentation](https://docs.fiddler.ai/api/fiddler-strands-sdk/strands) for detailed configuration steps.

### Basic Usage

```python
import os
from strands import Agent
from strands.models.openai import OpenAIModel
from strands.telemetry import StrandsTelemetry
from fiddler_strandsagents import StrandsAgentInstrumentor

strands_telemetry = StrandsTelemetry()
strands_telemetry.setup_otlp_exporter()
strands_telemetry.setup_console_exporter()
# Enable automatic instrumentation
StrandsAgentInstrumentor(strands_telemetry).instrument()

# Create your agent as usual - LoggingHook will be automatically injected
model = OpenAIModel(api_key=os.getenv("OPENAI_API_KEY"))
agent = Agent(model=model, system_prompt="You are a helpful assistant")

# Use your agent - all interactions will be automatically instrumented
response = agent("Hello, how are you?")
```

**Note:** The OTLP exporter requires Fiddler credentials to be configured as environment variables.

## API Reference

### StrandsAgentInstrumentor

The main instrumentor class for automatic agent instrumentation.

```python
from fiddler_strandsagents import StrandsAgentInstrumentor

instrumentor = StrandsAgentInstrumentor()

# Enable instrumentation
instrumentor.instrument()

# Check if instrumentation is active
is_active = instrumentor.is_instrumented_by_opentelemetry

# Disable instrumentation
instrumentor.uninstrument()
```

### Helper Functions

The SDK provides helper functions to add custom metadata to your telemetry spans:

#### `set_conversation_id(agent, conversation_id)`

Set a unique conversation ID for tracking related interactions:

```python
from fiddler_strandsagents import set_conversation_id

set_conversation_id(agent, 'session_1234567890')
```

#### `set_session_attributes(agent, **kwargs)`

Add custom session-level attributes to track business context:

```python
from fiddler_strandsagents import set_session_attributes

set_session_attributes(agent,
    role='customer_support',
    cost_center='travel_desk',
    region='us-west'
)
```

#### `set_span_attributes(obj, **kwargs)`

Add custom attributes to specific components (agents, models, or tools):

```python
from fiddler_strandsagents import set_span_attributes

# Add attributes to a model
set_span_attributes(model, model_id='gpt-4o-mini', temperature=0.7)

# Add attributes to a tool
set_span_attributes(tool, department='search', version='2.0')
```

#### `set_llm_context(model, context)`

Set additional context for LLM interactions:

```python
from fiddler_strandsagents import set_llm_context

set_llm_context(model, 'Available options: Option A, Option B, Option C...')
```

#### Getter Functions

Retrieve previously set metadata:

```python
from fiddler_strandsagents import (
    get_conversation_id,
    get_session_attributes,
    get_span_attributes
)

conversation_id = get_conversation_id(agent)
attributes = get_session_attributes(agent)
span_attrs = get_span_attributes(model)
```

## License

This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details.

## Support

- 📧 Email: support@fiddler.ai
- 📖 Documentation: https://docs.fiddler.ai/api/fiddler-strands-sdk/strands
- 🐛 Issues: https://github.com/fiddler-labs/fiddler-strands-sdk/issues

## Examples and Development

For example scripts and development information, please visit the [GitHub repository](https://github.com/fiddler-labs/fiddler-strands-sdk).
