Metadata-Version: 2.4
Name: fiddler-strands
Version: 0.1.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: mypy>=1.18.2
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: ruff>=0.13.3
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: python-dotenv>=1.0.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: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

# For development
uv add fiddler-strands[dev]

# For running examples
uv add fiddler-strands[examples]
```

### Using pip

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

## Quick Start

### 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?")
```

## Examples

The `examples/` directory contains complete working examples:

- **`travel_agent.py`**: Complete travel booking agent with tools
- **`async_travel_agent.py`**: Async version of the travel booking agent

### Running Examples

```bash
# Clone the repository
git clone https://github.com/fiddler-labs/fiddler-strands-sdk
cd fiddler-strands-sdk

# Set up environment
export OPENAI_API_KEY="your-api-key-here"

# Install dependencies
uv sync --extra examples

# Run an example
uv run python examples/travel_agent.py
```

## 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()
```

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/fiddler-labs/fiddler-strands-sdk
cd fiddler-strands-sdk

# Install with development dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run linting
uv run black fiddler_strandsagents/ examples/
uv run isort fiddler_strandsagents/ examples/
uv run flake8 fiddler_strandsagents/ examples/
```

### Project Structure

```
fiddler-strands-sdk/
├── fiddler_strandsagents/    # Main SDK package
│   ├── __init__.py             # Public API exports
│   ├── instrumentation.py      # OpenTelemetry instrumentor
│   ├── hooks.py                # Hook providers
│   └── span_processor.py       # Custom span processors
├── examples/                   # Usage examples
├── tests/                      # Test suite
├── pyproject.toml             # Project configuration
└── README.md                  # This file
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting (`uv run pytest && uv run black fiddler_strandsagents/`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

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