Metadata-Version: 2.1
Name: interactiveai
Version: 1.0.0
Summary: A client library for accessing InteractiveAI
License: MIT
Author: InteractiveAI
Author-email: developers@interactive.ai
Requires-Python: >=3.10,<4.0
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
Provides-Extra: openai
Requires-Dist: backoff (>=1.10.0)
Requires-Dist: httpx (>=0.15.4,<1.0)
Requires-Dist: openai (>=0.27.8) ; extra == "openai"
Requires-Dist: opentelemetry-api (>=1.33.1,<2.0.0)
Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.33.1,<2.0.0)
Requires-Dist: opentelemetry-sdk (>=1.33.1,<2.0.0)
Requires-Dist: packaging (>=23.2,<26.0)
Requires-Dist: pydantic (>=1.10.7,<3.0)
Requires-Dist: requests (>=2,<3)
Requires-Dist: wrapt (>=1.14,<2.0)
Description-Content-Type: text/markdown

# InteractiveAI Python SDK

[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![PyPI Version](https://img.shields.io/pypi/v/interactiveai.svg?style=flat-square&label=pypi+interactiveai)](https://pypi.python.org/pypi/interactiveai)

The official Python SDK for [InteractiveAI](https://interactive.ai) - an observability platform for LLM applications. This SDK provides tracing, automatic instrumentation for popular LLM frameworks, and direct API access to InteractiveAI's features.

## Installation

### From PyPI (Production)

Install the latest stable release:

```bash
pip install interactiveai
```

With optional integrations:

```bash
# With OpenAI instrumentation
pip install "interactiveai[openai]"
```

**In requirements.txt:**

```txt
interactiveai>=4.0.0
# or with extras
interactiveai[openai]>=4.0.0
```

**In pyproject.toml (Poetry):**

```toml
[tool.poetry.dependencies]
interactiveai = "^4.0.0"
# or with extras
interactiveai = { version = "^4.0.0", extras = ["openai"] }
```

**In pyproject.toml (pip/uv):**

```toml
[project]
dependencies = [
    "interactiveai>=4.0.0",
]

# or with extras
[project.optional-dependencies]
llm = ["interactiveai[openai]>=4.0.0"]
```

### From GitHub (Internal Development)

Install a specific tagged version:

```bash
pip install git+https://github.com/InteractiveAI/interactiveai-python-sdk.git@v4.1.0.dev1
```

Install from the main branch:

```bash
pip install git+https://github.com/InteractiveAI/interactiveai-python-sdk.git@main
```

**In requirements.txt:**

```txt
# Specific tag
interactiveai @ git+https://github.com/InteractiveAI/interactiveai-python-sdk.git@v4.1.0.dev1

# Main branch (latest)
interactiveai @ git+https://github.com/InteractiveAI/interactiveai-python-sdk.git@main
```

**In pyproject.toml (Poetry):**

```toml
[tool.poetry.dependencies]
# Specific tag
interactiveai = { git = "https://github.com/InteractiveAI/interactiveai-python-sdk.git", tag = "v4.1.0.dev1" }

# Main branch
interactiveai = { git = "https://github.com/InteractiveAI/interactiveai-python-sdk.git", branch = "main" }
```

## Quick Start

### Basic Usage

```python
from interactiveai import InteractiveAI

# Initialize the client (uses environment variables by default)
client = InteractiveAI()

# Create a trace
trace = client.trace(name="my-llm-app")

# Create a span within the trace
span = trace.span(name="llm-call")

# ... your LLM operations ...

# End the span with output
span.end(output={"response": "Hello, world!"})

# Flush to ensure all data is sent
client.flush()
```

### Using the @observe Decorator

```python
from interactiveai import observe

@observe()
def my_llm_function(prompt: str) -> str:
    # Your LLM logic here
    response = call_llm(prompt)
    return response

# The function is automatically traced
result = my_llm_function("Hello!")
```

### OpenAI Integration

```python
from interactiveai.openai import openai

# Use openai as normal - all calls are automatically traced
response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

## Configuration

The SDK is configured via environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `INTERACTIVEAI_PUBLIC_KEY` | Your InteractiveAI public API key | Required |
| `INTERACTIVEAI_SECRET_KEY` | Your InteractiveAI secret API key | Required |
| `INTERACTIVEAI_HOST` | API endpoint URL | `https://cloud.interactive.ai` |
| `INTERACTIVEAI_DEBUG` | Enable debug logging | `false` |
| `INTERACTIVEAI_TRACING_ENABLED` | Enable/disable tracing | `true` |
| `INTERACTIVEAI_SAMPLE_RATE` | Sampling rate for traces (0.0-1.0) | `1.0` |

## Documentation

For detailed documentation, guides, and API reference, visit:

- [SDK Documentation](https://docs.interactive.ai/sdk/python)
- [API Reference](https://docs.interactive.ai/api)
- [Migration Guide](./MIGRATION.md) - For users migrating from other observability SDKs

## License

MIT License - see [LICENSE](./LICENSE) for details.

