Metadata-Version: 2.4
Name: aviaraeye
Version: 0.2.0
Summary: Ergonomic LLM observability wrapper around Langfuse
Project-URL: Homepage, https://github.com/aviaralabs/aviaraeye
Project-URL: Documentation, https://aviaraeye.aviaralabs.com/docs
Author-email: Aviara Labs <dev@aviaralabs.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: langfuse>=3.13.0
Provides-Extra: all
Requires-Dist: google-genai>=1.0.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: openinference-instrumentation-google-genai>=0.1.0; extra == 'all'
Provides-Extra: azure
Requires-Dist: openai>=1.0.0; extra == 'azure'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
Requires-Dist: openinference-instrumentation-google-genai>=0.1.0; extra == 'gemini'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# AviаraEye

Ergonomic LLM observability wrapper around [Langfuse](https://langfuse.com). Provides tracing, prompt management, scoring, and auto-instrumentation for OpenAI, Azure OpenAI, and Google Gemini.

## Installation

```bash
pip install aviaraeye[all]

# Or with uv
uv pip install aviaraeye[all]

# Individual providers
pip install aviaraeye[openai]   # OpenAI
pip install aviaraeye[azure]    # Azure OpenAI
pip install aviaraeye[gemini]   # Google Gemini
```

## Configuration

Set environment variables:

```bash
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_HOST="https://aviaraeye.aviaralabs.com"
```

## Quick Start

```python
from aviaraeye import AviaraEye, traced, observe, get_prompt
from aviaraeye.providers.openai import OpenAI

# Initialize
eye = AviaraEye()

# Auto-traced OpenAI calls
client = OpenAI()

with traced("my-pipeline", user_id="user-1", tags=["demo"]) as t:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    t.set_output(response.choices[0].message.content)
    t.score("quality", 1.0)

# Decorator-based tracing
@observe
def process_document(doc: bytes) -> dict:
    return extract(doc)

# Prompt management
prompt = get_prompt("extraction-v2", label="production")
compiled = prompt.compile(schema=my_schema)

# Flush before shutdown
eye.flush()
```

## Features

| Feature | Description |
|---------|-------------|
| **Tracing** | `traced()`, `span()`, `event()` context managers |
| **Decorators** | `@observe`, `@generation` for auto-tracing functions |
| **Providers** | Drop-in OpenAI, Azure OpenAI, Gemini auto-instrumentation |
| **Prompts** | Versioned prompt fetch, compile, and link to traces |
| **Scoring** | Numeric, boolean, categorical, and text scores |
| **Sessions** | `session_context()` for user/session propagation |
| **Metadata** | `Metadata`, `Tags` builders for standardised annotation |

## Provider Usage

### OpenAI / Azure OpenAI

```python
from aviaraeye.providers.openai import OpenAI
from aviaraeye.providers.azure_openai import AzureOpenAI

# Drop-in — all calls auto-traced
client = OpenAI()
response = client.chat.completions.create(model="gpt-4", messages=[...])
```

### Google Gemini

```python
from aviaraeye.providers.gemini import instrument_gemini
from google import genai

instrument_gemini()  # One-time setup (auto-called by AviaraEye())

client = genai.Client(api_key="...")
response = client.models.generate_content(model="gemini-2.5-flash", contents="...")
```

## Documentation

- [Getting Started](docs/getting-started.md)
- [Tracing Guide](docs/tracing.md)
- [Provider Integration](docs/providers.md)
- [Prompt Management](docs/prompts.md)
- [Scoring & Evaluation](docs/scoring.md)
- [User & Session Tracking](docs/sessions.md)

## Development

```bash
# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

# Type check
mypy src/
```

## License

MIT - Aviara Labs
