Metadata-Version: 2.1
Name: interactiveai
Version: 1.0.3
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 Interactive

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

# 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/integrations/native/interactiveai-sdk)
- [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.

