Metadata-Version: 2.4
Name: abi-observability
Version: 0.1.3
Summary: Event/span pipeline with offline exporters for the ABI ecosystem
Project-URL: Homepage, https://github.com/AbilityBI/abi-observability
Project-URL: Repository, https://github.com/AbilityBI/abi-observability
Project-URL: Documentation, https://abilitybi.github.io/abi-infra/
Project-URL: Changelog, https://github.com/AbilityBI/abi-observability/blob/main/CHANGELOG.md
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# abi-observability

OTLP-compliant event and span pipeline with multi-backend export and built-in PII redaction. Plugs into any OpenTelemetry pipeline. Aligned with the [OTel GenAI SIG](https://github.com/open-telemetry/community/blob/main/projects/gen-ai.md) semantic conventions.

Zero production dependencies. Standalone.

## Install (after PyPI publication)

```bash
pip install abi-observability
```

> **Status**: Not yet published to PyPI. Install from source: `pip install -e .` from the repo root.

## Quick start

```python
from abi_observability import Event, Span, Collector, CollectorConfig

# Set up a collector with buffering and file-based export
config = CollectorConfig(
    buffer_size=100,
    flush_interval=60.0,
    enabled_exporters=["file"],
    auto_flush=True,
)
collector = Collector(config)

# Collect an event
event = Event(
    event_id="evt-001",
    event_type="MODEL_CALL",
    timestamp="2026-03-13T10:00:00Z",
    run_id="run-42",
    payload={"model": "claude-sonnet-4-20250514", "tokens": 512},
)
collector.collect_event(event)

# Collect a span
span = Span(
    span_id="span-001",
    trace_id="trace-001",
    name="llm.generate",
    start_time="2026-03-13T10:00:00Z",
    end_time="2026-03-13T10:00:01Z",
    attributes={"model": "claude-sonnet-4-20250514"},
)
collector.collect_span(span)

# Flush buffered data to exporters
collector.flush()
```

### OTel GenAI semantic conventions

```python
from abi_observability import GenAIAttributes, to_genai_attributes

# Build OTel GenAI-compliant attributes for a span
attrs = to_genai_attributes(
    system="anthropic",
    model="claude-sonnet-4-20250514",
    input_tokens=1500,
    output_tokens=300,
)
# attrs = {"gen_ai.system": "anthropic", "gen_ai.request.model": "claude-sonnet-4-20250514", ...}
```

## What's included

- **Event and span models** -- structured `Event` and `Span` types with NDJSON serialization
- **Collector** -- in-process event collector with buffering and multi-exporter support
- **OTLP exporter** -- sends spans in OTLP-compatible JSON (file or HTTP)
- **Langfuse exporter** -- optional LLM observability backend
- **PII redaction** -- environment variable and path scrubbing before export
- **OTel GenAI SIG alignment** -- `GenAIAttributes` constants and `to_genai_attributes()` helper for interoperable telemetry
- **Status dashboard** -- `python -m abi_observability.dashboard` for pipeline visualization

## Use it standalone

`abi-observability` works with any OpenTelemetry pipeline. Configure an exporter, point it at your collector, and start recording. No ABI ecosystem integration required.

Within the ABI ecosystem, it integrates with the orchestrator for end-to-end trace propagation across agent workflows.

## ABI ecosystem

Related packages:

- [abi-control-core](https://github.com/AbilityBI/abi-core) -- contracts and audit trail SDK
- [abi-evals](https://github.com/AbilityBI/abi-evals) -- eval runner and golden management
- [abi-runtime](https://github.com/AbilityBI/abi-runtime) -- sandboxed tool runtime

## Versioning

Follows Semantic Versioning. Current version: `0.1.3`. See CHANGELOG.md for release notes.

## License

MIT License (see LICENSE file).
