Metadata-Version: 2.4
Name: sideseat
Version: 0.1.0
Summary: OpenTelemetry SDK for AI/LLM observability with SideSeat
Project-URL: Homepage, https://sideseat.ai
Project-URL: Documentation, https://docs.sideseat.ai
Project-URL: Repository, https://github.com/sideseat/sideseat-python
Author-email: SideSeat <support@sideseat.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,llm,observability,opentelemetry,telemetry,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# SideSeat Python SDK

OpenTelemetry SDK for AI/LLM observability with [SideSeat](https://sideseat.ai).

## Installation

```bash
pip install sideseat
```

## Quick Start

```python
from sideseat import SideSeatTelemetry

# Initialize telemetry
telemetry = SideSeatTelemetry()

# Configure exporters (chainable)
telemetry.setup_otlp_exporter(endpoint="http://localhost:5388/otel/default/v1/traces")
telemetry.setup_console_exporter()

# Your AI/LLM code here...

# Graceful shutdown (also registered with atexit for file exporters)
telemetry.shutdown()
```

## Features

- **Easy Setup**: One-liner OpenTelemetry configuration
- **Binary Encoding**: Automatic base64 encoding for images/audio
- **Multiple Exporters**: OTLP, Console, and JSONL file output
- **Framework Support**: Works with Strands, LangChain, CrewAI, AutoGen
- **Method Chaining**: Fluent API for configuration
- **Thread-Safe**: Safe for concurrent use

## Configuration

### Custom Service Name

```python
telemetry = SideSeatTelemetry(
    service_name="my-ai-app",
    service_version="1.0.0",
)
```

By default, the SDK auto-detects common AI frameworks (Strands, LangChain, CrewAI, AutoGen).

### Disable Binary Encoding

```python
telemetry = SideSeatTelemetry(encode_binary_as_base64=False)
```

## Exporters

### OTLP (recommended)

```python
telemetry.setup_otlp_exporter(
    endpoint="http://localhost:5388/otel/default/v1/traces"
)
```

### Console

```python
telemetry.setup_console_exporter()
```

### File (JSONL)

```python
# Append mode (default) - safe for multiple runs
telemetry.setup_file_exporter(path="traces.jsonl")

# Overwrite mode
telemetry.setup_file_exporter(path="traces.jsonl", mode="w")
```

### Metrics

```python
telemetry.setup_meter(
    enable_console_exporter=True,
    enable_otlp_exporter=True,
)
```

## Utilities

### encode_value

Encode Python values for JSON, with base64 encoding for binary data:

```python
from sideseat import encode_value

encode_value(b"binary")           # "YmluYXJ5" (base64)
encode_value({"key": b"value"})   # {"key": "dmFsdWU="}
encode_value({1, 2, 3})           # [1, 2, 3] (sorted list)
```

## License

MIT
