Metadata-Version: 2.4
Name: observra
Version: 1.0.2
Summary: Framework-agnostic agent behavior analytics — CIM-based telemetry for AI agents
Author: Open Agent AI Security Contributors
Author-email: Exabeam <developer@exabeam.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/open-agent-ai-security/observra
Project-URL: Repository, https://github.com/open-agent-ai-security/observra
Project-URL: Issues, https://github.com/open-agent-ai-security/observra/issues
Keywords: agent,telemetry,observability,llm,ai,cim
Classifier: Development Status :: 5 - Production/Stable
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
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: python-ulid>=2.0.0
Provides-Extra: adk
Requires-Dist: google-adk>=1.0.0; extra == "adk"
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.1.37; extra == "claude"
Requires-Dist: tiktoken>=0.7.0; extra == "claude"
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.9.0; extra == "openai-agents"
Provides-Extra: langchain
Requires-Dist: langchain-core>=1.0.0; extra == "langchain"
Requires-Dist: langgraph>=0.2.0; extra == "langchain"
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai<2.0.0; extra == "pydantic-ai"
Requires-Dist: opentelemetry-sdk>=1.0.0; extra == "pydantic-ai"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.0.0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.0.0; extra == "otel"
Provides-Extra: exabeam
Requires-Dist: requests>=2.32.0; extra == "exabeam"
Provides-Extra: safe-regex
Requires-Dist: google-re2>=1.1; extra == "safe-regex"
Provides-Extra: encryption
Requires-Dist: cryptography>=41.0; extra == "encryption"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Requires-Dist: hypothesis>=6.0; extra == "test"
Requires-Dist: pytest-benchmark>=5.1; extra == "test"
Provides-Extra: all
Requires-Dist: observra[adk,claude,encryption,exabeam,langchain,openai-agents,otel,pydantic-ai,safe-regex]; extra == "all"
Dynamic: license-file

<!--
  Copyright 2026 Exabeam, Inc.
  SPDX-License-Identifier: Apache-2.0
-->
<p align="center">
  <img src="assets/hero.png" alt="observra — framework-agnostic agent behavior analytics" width="840">
</p>

# observra
**Framework-agnostic agent behavior analytics.**

[![License: Apache-2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE.md)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

Capture every meaningful agent action (token usage, tool calls, cost, errors) with structured context based on the Common Information Model (CIM).

Zero custom instrumentation per-agent. Answer "what happened, how much did it cost, and was it normal?" for any agent on any framework.

## Install

```bash
pip install observra
```

With framework extras:

```bash
pip install observra[adk]           # Google ADK
pip install observra[claude]        # Claude Agent SDK
pip install observra[openai-agents] # OpenAI Agents SDK
pip install observra[langchain]     # LangChain / LangGraph
pip install observra[pydantic-ai]   # Pydantic AI
```

With backend extras:

```bash
pip install observra[otel]          # OTel span + log export
```

Install everything:

```bash
pip install observra[all]
```

## Quick Start

```python
import observra
from observra import log

observra.initialize(backend="jsonl", path="telemetry.jsonl")
log.session_start(agent_name="my-agent")
log.model_response("gpt-4o", input_tokens=500, output_tokens=200)
log.session_end(agent_name="my-agent")
```

Sample output (one line per event in `telemetry.jsonl`):

```json
{"ts": "2025-01-15T10:23:45Z", "event_type": "model_response", "framework": "generic", "data": {"model": "gpt-4o", "in": 500, "out": 200, "cost_usd": 0.0035}}
```

## Supported Frameworks

| Framework | Install | Status | Captured Events |
|-----------|---------|--------|-----------------|
| [Google ADK](docs/getting-started/adk.md) | `[adk]` | Stable | LLM calls, tool calls, delegation depth, cost |
| [Claude SDK](docs/getting-started/claude.md) | `[claude]` | Stable | Tool calls, model responses, session cost |
| [OpenAI Agents SDK](docs/getting-started/openai.md) | `[openai-agents]` | Stable | Spans, tool calls, agent handoffs, cost |
| LangChain / LangGraph | `[langchain]` | Stable | Chain runs, tool calls, LLM calls, cost |
| Pydantic AI | `[pydantic-ai]` | Stable | Agent runs, tool calls, model calls |

## Backends

| Backend | Install | Description |
|---------|---------|-------------|
| JSONL | _(included)_ | Local JSON Lines file (default) |
| Webhook | _(included)_ | Generic HTTP webhook POST delivery |
| Multi | _(included)_ | Fan-out to multiple backends simultaneously |
| OTel Spans | `[otel]` | Export events as OTel spans via OTLP HTTP |
| OTel Logs | `[otel]` | Export events as OTel log records via OTLP HTTP |

### OTel Export (Dynatrace, Grafana, etc.)

```python
from observra.backends.otel import OTelExportBackend
from observra.backends.otel_log import OTelLogBackend
from observra.backends.multi import MultiBackend

# Spans only
span_backend = OTelExportBackend(
    endpoint="https://your-collector/v1/traces",
    headers={"Authorization": "Api-Token ..."},
    service_name="my-agent-svc",
)

# Logs only
log_backend = OTelLogBackend(
    endpoint="https://your-collector/v1/logs",
    headers={"Authorization": "Api-Token ..."},
    service_name="my-agent-svc",
)

# Both spans and logs
backend = MultiBackend([span_backend, log_backend])
```

## Key Features

- **Cost tracking** — per-session cost with model-specific pricing catalog and threshold alerts
- **PII redaction** — automatic secret/PII masking with configurable patterns
- **Non-blocking** — drop-oldest queue guarantees zero latency impact on the host agent
- **CIM-normalized** — structured events compatible with SIEM/analytics pipelines
- **Safe regex** — ReDoS-proof pattern matching via RE2 (optional: `[safe-regex]`)
- **Encryption at rest** — AES field-level encryption for sensitive telemetry (optional: `[encryption]`)
- **Prompt injection detection** — built-in heuristics for injection attempt classification
- **Observability** — `get_metrics()` / `get_stats()` for pipeline health introspection
- **Deduplication** — automatic event dedup across backends
- **Session context** — trace/span/session ID propagation with scoped contexts

## All Extras

| Extra | Dependencies |
|-------|-------------|
| `[adk]` | `google-adk>=1.0.0` |
| `[claude]` | `claude-agent-sdk>=0.1.37`, `tiktoken>=0.7.0` |
| `[openai-agents]` | `openai-agents>=0.9.0` |
| `[langchain]` | `langchain-core>=1.0.0`, `langgraph>=0.2.0` |
| `[pydantic-ai]` | `pydantic-ai<2.0.0`, `opentelemetry-sdk>=1.0.0` |
| `[otel]` | `opentelemetry-sdk>=1.0.0`, `opentelemetry-exporter-otlp-proto-http>=1.0.0` |
| `[exabeam]` | `requests>=2.32.0` |
| `[safe-regex]` | `google-re2>=1.1` |
| `[encryption]` | `cryptography>=41.0` |
| `[all]` | All of the above |

## Documentation

- [Getting Started](docs/getting-started/) — per-framework setup guides
- [API Reference](docs/api/) — public callables, config options, event examples
- [Event Schema](docs/event-schema.md) — CIM event contract
- [Architecture](docs/architecture.md) — system design overview
- [Compatibility](docs/COMPATIBILITY.md) — supported versions

## Project sponsor

observra is sponsored by [Exabeam](https://www.exabeam.com/). Exabeam contributed the initial code and continues to provide ongoing support and contributions to the project as part of its commitment to security in an increasingly agentic world.

## License

Apache 2.0 — see [LICENSE](LICENSE.md)
