Metadata-Version: 2.4
Name: aip-otel-exporter
Version: 0.5.0
Summary: OpenTelemetry exporter for AIP integrity checkpoints and AAP verification results
Project-URL: Homepage, https://github.com/mnemom/aip-otel-exporter
Project-URL: Documentation, https://github.com/mnemom/aip-otel-exporter#readme
Project-URL: Repository, https://github.com/mnemom/aip-otel-exporter
Project-URL: Issues, https://github.com/mnemom/aip-otel-exporter/issues
Project-URL: Changelog, https://github.com/mnemom/aip-otel-exporter/blob/main/CHANGELOG.md
Author-email: "Mnemom.ai" <dev@mnemom.ai>
License-Expression: Apache-2.0
Keywords: aap,agent,ai,aip,alignment,integrity,observability,opentelemetry,otel,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: aap
Requires-Dist: agent-alignment-protocol>=0.1.8; extra == 'aap'
Provides-Extra: aip
Requires-Dist: agent-integrity-protocol>=0.1.5; extra == 'aip'
Provides-Extra: all
Requires-Dist: agent-alignment-protocol>=0.1.8; extra == 'all'
Requires-Dist: agent-integrity-protocol>=0.1.5; extra == 'all'
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'all'
Requires-Dist: opentelemetry-instrumentation>=0.40b0; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'all'
Provides-Extra: auto
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'auto'
Requires-Dist: opentelemetry-instrumentation>=0.40b0; extra == 'auto'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'auto'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'dev'
Requires-Dist: opentelemetry-instrumentation>=0.40b0; extra == 'dev'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'
Description-Content-Type: text/markdown

# aip-otel-exporter

[![PyPI](https://img.shields.io/pypi/v/aip-otel-exporter)](https://pypi.org/project/aip-otel-exporter/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)

OpenTelemetry exporter for [AIP](https://github.com/mnemom/aip) integrity checkpoints and
[AAP](https://github.com/mnemom/aap) verification results.

Python companion to [`@mnemom/aip-otel-exporter`](../typescript/README.md).

## Installation

```bash
pip install aip-otel-exporter[otel]    # with OpenTelemetry SDK
pip install aip-otel-exporter[auto]    # with auto-instrumentation support
pip install aip-otel-exporter[all]     # all optional dependencies
```

## Quick Start

### Manual API

```python
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

from aip_otel_exporter import AIPOTelRecorder

# Set up OTel
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

# Create recorder
recorder = AIPOTelRecorder(tracer_provider=provider)

# After an AIP integrity check:
recorder.record_integrity_check(signal)

# After an AAP verification:
recorder.record_verification(result)

# After an AAP coherence check:
recorder.record_coherence(result)

# After AAP drift detection:
recorder.record_drift(alerts, traces_analyzed=50)
```

### Auto-instrumentation

```python
from aip_otel_exporter import AIPInstrumentor

# Automatically wraps AIP/AAP functions to record spans
AIPInstrumentor().instrument()

# Now AIP/AAP calls are automatically traced:
# from aip import AIPClient
# signal = client.check(thinking_block, card)
# ^^^ span is recorded automatically
```

### Direct Functions

For fine-grained control, use the recording functions directly:

```python
from opentelemetry import trace
from aip_otel_exporter.manual import (
    record_integrity_check,
    record_verification,
    record_coherence,
    record_drift,
)

tracer = trace.get_tracer("my-app")
record_integrity_check(tracer, signal)
record_verification(tracer, result)
```

## Span Hierarchy

Spans are created as children of the current active span:

```
your_application_span
  ├── aip.integrity_check
  │    ├── event: aip.concern (one per concern)
  │    └── event: aip.drift_alert (when drift active)
  ├── aap.verify_trace
  │    └── event: aap.violation (one per violation)
  ├── aap.check_coherence
  └── aap.detect_drift
       └── event: aap.drift_alert (one per alert)
```

## Attributes

### `aip.integrity_check` span — 22 attributes + 2 GenAI SIG aliases

| Attribute | Type | Description |
|---|---|---|
| `aip.integrity.checkpoint_id` | string | Checkpoint ID |
| `aip.integrity.verdict` | string | clear / review_needed / boundary_violation |
| `aip.integrity.proceed` | boolean | Whether to proceed |
| `aip.integrity.recommended_action` | string | Recommended action |
| `aip.integrity.concerns_count` | int | Number of concerns |
| `aip.integrity.agent_id` | string | Agent ID |
| `aip.integrity.card_id` | string | Alignment Card ID |
| `aip.integrity.session_id` | string | Session ID |
| `aip.integrity.thinking_hash` | string | SHA-256 of thinking block |
| `aip.integrity.analysis_model` | string | Analysis LLM model |
| `aip.integrity.analysis_duration_ms` | float | Analysis duration |
| `aip.integrity.thinking_tokens` | int | Original thinking tokens |
| `aip.integrity.truncated` | boolean | Whether thinking was truncated |
| `aip.integrity.extraction_confidence` | float | Extraction confidence |
| `aip.conscience.consultation_depth` | string | surface / standard / deep |
| `aip.conscience.values_checked_count` | int | Values checked count |
| `aip.conscience.conflicts_count` | int | Conflicts count |
| `aip.window.size` | int | Window size |
| `aip.window.integrity_ratio` | float | Integrity ratio (0.0–1.0) |
| `aip.window.drift_alert_active` | boolean | Drift alert active |
| `gen_ai.evaluation.verdict` | string | GenAI SIG forward-compat alias |
| `gen_ai.evaluation.score` | float | GenAI SIG forward-compat alias |

### `aap.verify_trace` span — 8 attributes

| Attribute | Type |
|---|---|
| `aap.verification.result` | boolean |
| `aap.verification.similarity_score` | float |
| `aap.verification.violations_count` | int |
| `aap.verification.warnings_count` | int |
| `aap.verification.trace_id` | string |
| `aap.verification.card_id` | string |
| `aap.verification.duration_ms` | float |
| `aap.verification.checks_performed` | string (comma-separated) |

### `aap.check_coherence` span — 5 attributes

| Attribute | Type |
|---|---|
| `aap.coherence.compatible` | boolean |
| `aap.coherence.score` | float |
| `aap.coherence.proceed` | boolean |
| `aap.coherence.matched_count` | int |
| `aap.coherence.conflict_count` | int |

### `aap.detect_drift` span — 2 attributes

| Attribute | Type |
|---|---|
| `aap.drift.alerts_count` | int |
| `aap.drift.traces_analyzed` | int |

## Metrics

```python
from aip_otel_exporter.metrics import (
    create_aip_metrics,
    record_integrity_metrics,
    record_verification_metrics,
    record_coherence_metrics,
    record_drift_metrics,
)

metrics = create_aip_metrics(meter_provider)
record_integrity_metrics(metrics, signal)
```

| Metric | Type | Labels |
|---|---|---|
| `aip.integrity_checks.total` | Counter | verdict, agent_id |
| `aip.concerns.total` | Counter | category, severity |
| `aip.analysis.duration_ms` | Histogram | verdict |
| `aip.window.integrity_ratio` | Histogram | — |
| `aip.drift_alerts.total` | Counter | — |
| `aap.verifications.total` | Counter | verified |
| `aap.violations.total` | Counter | type, severity |
| `aap.verification.duration_ms` | Histogram | — |
| `aap.coherence.score` | Histogram | compatible |

## Performance

TypeScript benchmarks (Python exhibits comparable characteristics — duck-typed dict input, single span creation):

| Operation | Mean | p99 | Ops/sec |
|---|---|---|---|
| `record_integrity_check()` | 0.007 ms | 0.023 ms | 142,540 |
| `record_verification()` | 0.003 ms | 0.004 ms | 310,510 |
| `record_coherence()` | 0.003 ms | 0.003 ms | 321,385 |
| `record_drift()` | 0.003 ms | 0.007 ms | 295,807 |

All operations are sub-0.01ms mean. Zero measurable overhead on hot paths.

## Requirements

- Python >= 3.9
- OpenTelemetry SDK >= 1.20.0 (for `[otel]` extra)

## License

[Apache 2.0](../../LICENSE)
