Metadata-Version: 2.4
Name: nthlayer-override-adapter
Version: 0.1.0
Summary: NthLayer override-event sidecar — HTTP → gen_ai.override OTel span bridge
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: nthlayer-common<2.0.0,>=1.5.0
Requires-Dist: starlette>=0.40
Requires-Dist: uvicorn>=0.30
Requires-Dist: opentelemetry-api>=1.28
Requires-Dist: opentelemetry-sdk>=1.28
Requires-Dist: opentelemetry-exporter-otlp>=1.28
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: prometheus-client>=0.21
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"

# nthlayer-override-adapter

Standalone HTTP sidecar that accepts human-override events and emits them as `gen_ai.override` OTel spans. Part of the [NthLayer](https://github.com/rsionnach/nthlayer) ecosystem; implements [`opensrm-jmy.7`](https://github.com/rsionnach/opensrm) — § 4 of `NTHLAYER_MISSING_CAPABILITIES_SPEC.md`.

## Why

`nthlayer-measure` computes judgment SLOs from override metrics consumed via OTel. Operators reviewing AI decisions live in heterogeneous tools (Slack, Jira, internal review UIs, email). The override-adapter is the translation layer: HTTP in, canonical OTel `gen_ai.override` events out.

## Endpoints

- `POST /api/v1/overrides` — canonical OverrideEvent JSON in.
- `POST /api/v1/overrides/batch` — `{overrides: [...]}` with last-in-array-wins on duplicate `decision_id`.
- `POST /webhook/{source}` — one route per configured adapter; runs a YAML-declared field mapping on the inbound webhook payload.
- `GET /healthz` — liveness probe.
- `GET /metrics` — Prometheus self-observability.

## Run locally

```bash
uv sync --extra dev
uv run nthlayer-override-adapter serve --config override-adapter-config.yaml
```

See `override-adapter-config.yaml.example` for a Jira-shaped adapter declaration.

## Tests

```bash
uv run pytest -q
uv run ruff check src/ tests/
```

## License

Apache 2.0.
