Metadata-Version: 2.4
Name: volra-observe
Version: 0.1.0
Summary: Framework-agnostic LLM observability for Volra agents
Project-URL: Homepage, https://github.com/antonioromero/volra
Project-URL: Documentation, https://github.com/antonioromero/volra/tree/main/volra-observe
Author: Antonio Romero
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: prometheus-client>=0.20.0
Provides-Extra: all
Requires-Dist: anthropic>=0.20.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: anthropic>=0.20.0; extra == 'dev'
Requires-Dist: openai>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# volra-observe

Framework-agnostic LLM observability for [Volra](https://github.com/antonioromero/volra) agents.

## Install

```bash
pip install volra-observe
```

## Quick Start

```python
import volra_observe

# Auto-patches OpenAI and Anthropic SDKs, starts Prometheus server on :9101
volra_observe.init(port=9101)
```

## Metrics Exposed

| Metric | Type | Labels |
|--------|------|--------|
| `volra_llm_tokens_total` | Counter | model, type (input/output) |
| `volra_llm_cost_dollars_total` | Counter | model |
| `volra_llm_request_duration_seconds` | Histogram | model, status |
| `volra_llm_errors_total` | Counter | model, error_type |
| `volra_tool_calls_total` | Counter | tool_name |

## Manual Instrumentation

```python
from volra_observe import track_llm, llm_context

# Decorator
@track_llm(model="gpt-4o")
def call_llm(prompt):
    return client.chat.completions.create(model="gpt-4o", messages=[...])

# Context manager
with llm_context(model="claude-sonnet-4-20250514") as ctx:
    response = anthropic.messages.create(...)
    ctx["response"] = response
```
