Metadata-Version: 2.4
Name: kestrel-feature-observability
Version: 0.11.0
Summary: Observability feature for Kestrel Sovereign — a per-agent emitter that POSTs hook-driven lifecycle events to the fleet observability store, with a shared Prometheus registry
Project-URL: Homepage, https://kestrelsovereign.com
Project-URL: Source, https://github.com/KestrelSovereignAI/kestrel-feature-observability
Project-URL: Issues, https://github.com/KestrelSovereignAI/kestrel-feature-observability/issues
Author: UncleSaurus
Maintainer: UncleSaurus
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,kestrel,metrics,observability,prometheus
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Requires-Python: <3.15,>=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: kestrel-sovereign-sdk<1,>=0.14.1
Requires-Dist: openinference-semantic-conventions>=0.1.9
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.20
Requires-Dist: opentelemetry-sdk<2,>=1.20
Provides-Extra: fleet
Requires-Dist: kestrel-feature-entities<1,>=0.1; extra == 'fleet'
Requires-Dist: kestrel-sovereign-sdk<0.31,>=0.30.0; extra == 'fleet'
Provides-Extra: metrics
Requires-Dist: kestrel-sovereign-sdk[metrics]<1,>=0.14.1; extra == 'metrics'
Provides-Extra: test
Requires-Dist: fastapi>=0.110.0; extra == 'test'
Requires-Dist: httpx>=0.27.0; extra == 'test'
Requires-Dist: kestrel-feature-entities<1,>=0.1; extra == 'test'
Requires-Dist: kestrel-sovereign-sdk[metrics]<0.31,>=0.30.0; extra == 'test'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# kestrel-feature-observability

The **single** observability package for Kestrel Sovereign — one repo, one
version, one source of truth for the whole observability domain — with two roles
selected by the two entry-point groups (package boundaries need not match
process boundaries):

- **Base install** (`pip install kestrel-feature-observability`) — the
  lightweight per-agent **emitter** `Feature` (the `kestrel_sovereign.features`
  entry point). It attaches an `ObservabilityHook` to the agent's hook system;
  every lifecycle event is POSTed to the fleet host's observability store
  (`POST {KESTREL_OBSERVABILITY_URL}/api/host/observability/events`). No
  `entities`, no DB — this is what every agent gets. Prometheus metrics emit
  through the SDK's shared registry, so a single `/metrics` scrape stays
  coherent across the framework + every feature package.
- **Host extra** (`kestrel-feature-observability[fleet]`) — pulls
  `kestrel-feature-entities` and enables the **`FleetObservabilityHostFeature`**
  (tenant-scoped event store + query routes + orchestrator swimlane; the
  `kestrel_sovereign.host_features` entry point). The HostFeature lives in the
  `kestrel_feature_observability.fleet` subpackage and its import/entry point is
  **guarded** — on a base install (extra absent) it resolves to `None` and the
  host skips it, so the emitter path never imports `entities`.

> This package supersedes the separate `kestrel-feature-observability-fleet`
> package, which is deprecated: its HostFeature, store, and swimlane now live
> here behind the `[fleet]` extra.

## Installation

```bash
uv pip install kestrel-feature-observability
```

For real Prometheus output:

```bash
uv pip install 'kestrel-feature-observability[metrics]'
```

For the fleet host role (event store + swimlane):

```bash
uv pip install 'kestrel-feature-observability[fleet]'
```

Both features are auto-discovered by Kestrel Sovereign via their entry-point
groups — install the base package alongside `kestrel-sovereign` and
`ObservabilityFeature` registers itself into every agent; install with `[fleet]`
on the host and `FleetObservabilityHostFeature` registers at host scope.

## Emitter transport

The hook reads two **frozen** env vars (the same keys talon's emitter uses):

- `KESTREL_OBSERVABILITY_URL` — the fleet host root. The hook POSTs to this URL
  plus the path `/api/host/observability/events`. When unset, the emit path is a
  **no-op** (the agent still runs; Prometheus counters still fire).
- `KESTREL_OBSERVABILITY_KEY` — sent as the `X-API-Key` request header when set.

Delivery is lightweight and best-effort: an `httpx.AsyncClient` POST,
fire-and-forget with a short (~2s) timeout, **all failures swallowed, no
buffering, no retry, no `entities` dependency**. Each event payload carries
`orchestrator`/`session_id`/`tool_name`/lineage and friends; `orchestrator` is
the agent itself when self-driven, else `null` (rendered "Direct" by the fleet
store).

## Privacy

The hook is observational — it never blocks, denies, or modifies. User-message content is **not** sent (only length); tool errors are truncated to 200 chars; exceptions in the hook are swallowed so they cannot affect agent operation.

## Dependencies

- `kestrel-sovereign-sdk>=0.14.1,<1` — base `Feature`, `Hook`, and shared `metrics` module
- `httpx>=0.27.0` — lightweight HTTP client for the emitter POST
- Optional `[metrics]` extra → `kestrel-sovereign-sdk[metrics]` → `prometheus-client`
- Optional `[fleet]` extra → `kestrel-sovereign-sdk>=0.29.2,<0.30` (the HostFeature
  contract) + `kestrel-feature-entities` (the tenant-scoped event store, pulling
  SQLAlchemy 2.0 async + Alembic). Only this extra pulls `entities`.

The base emitter has **no** runtime dependency on `kestrel-sovereign` (or any
`entities`/fleet package); the hook talks to the fleet host purely over HTTP.
The store's heavy dependencies live entirely behind the `[fleet]` extra, so
agents stay lightweight.

## Development

```bash
uv pip install -e '.[test]'
uv run pytest
```

## License

Apache-2.0
