Skip to main content

akhu-observer (Python)

AKHU Observer SDK — evidence instrumentation for AI systems.

Zero-runtime-dependency Python SDK for connecting applications to the AKHU evidence ledger.

Install

Observer 2.0.0 requires an AKHU API that supports the current delivery receipts and the akhu.security-strip 2.0 capture policy. The API exposes the ingestion contract at GET /api/v1/ingest/contract.

pip install akhu-observer

With provider support:

pip install "akhu-observer[openai]"      # OpenAI wrapper
pip install "akhu-observer[anthropic]"   # Anthropic wrapper

Quick Start

Direct Client

from akhu_observer import AkhuClient

client = AkhuClient(
    url="http://akhu-api:3000",
    channel_id="commissioned-system-slot",
)
client.observe("DOCUMENT_PROCESSED", {"doc_id": "abc-123", "pages": 12})

OpenAI Wrapper

from openai import OpenAI
from akhu_observer import observe_openai

client = observe_openai(
    OpenAI(),
    akhu_url="http://akhu-api:3000",
    channel_id="commissioned-openai-slot",
)
response = client.chat.completions.create(model="gpt-4o", messages=[...])
# Observation sent automatically — response unmodified

Anthropic Wrapper

from anthropic import Anthropic
from akhu_observer import observe_anthropic

client = observe_anthropic(
    Anthropic(),
    akhu_url="http://akhu-api:3000",
    channel_id="commissioned-anthropic-slot",
)
response = client.messages.create(model="claude-sonnet-4-20250514", max_tokens=1024, messages=[...])

Sync and async provider clients are supported. OpenAI instrumentation covers Chat Completions and Responses. Streams remain caller-driven and are not pre-consumed.

Provider wrappers record MODEL_TOOL_REQUEST_OBSERVED when a model requests a tool. That is not proof of execution. Instrument the actual boundary when execution matters:

from akhu_observer import observe_executor, observe_mcp_client, observe_mcp_handler

observed_handler = observe_executor(handler, akhu=client, handler_name="review_case")
session = observe_mcp_client(session, akhu=client)
server_handler = observe_mcp_handler(server_handler, akhu=client, tool_name="review_case")

MCP support is structural and does not add an MCP SDK dependency. It observes only calls made through the configured client or handler.

Provider and MCP wrappers are delegating views over the original objects; they do not patch the supplied client. Sync and async return behavior, context-manager use and caller-driven stream consumption remain under application control.

Provider wrappers own an internal delivery client. Call close_provider_observer(client) during application shutdown to drain it without closing the provider client.

Environment Variables

export AKHU_URL="http://akhu-api:3000"
export AKHU_CHANNEL_ID="my-channel"
# No config needed — reads from environment
client = AkhuClient()

Commissioning contract

channel_id is not a free-form registration request. It must identify a channel slot in the signed Evidence Scope installed on the target AKHU instance. The SDK never creates, deletes, or changes channels. The API rejects observations whose slot, transport, or event type is outside that scope.

Each observation receives a stable delivery identifier before its first send. Retries reuse it under the API's established deduplication authority. on_flush reports confirmed durable receipts, including an established prefix of a partial result. Consumer callbacks cannot trigger redelivery. A capture-only receipt has its declared local scope; it does not certify continuity with unavailable history.

Architecture

Operational outcomes and framing

Batches are framed by observation count and exact encoded body bytes. Local ceilings are 100 observations and 1,048,576 bytes, reduced by smaller effective installation declarations read from /api/v1/system/operational-envelope. That best-effort read is cached for 60 seconds. Unavailable introspection retains bounded local defaults; the HTTP outcome and confirmed durable receipt remain authoritative.

Delivery custody

The client owns at most 1,000 observations and 8,388,608 encoded observation bytes by default. maximum_buffered_events and maximum_buffered_bytes govern queued, preparing and in-flight work together; buffer_size is only a flush trigger. Admission reserves one preparation slot before copying. Private wire bytes are prepared once. Capture has a bounded local CPU cost on the caller's thread.

delivery_timeout_s defaults to 20 seconds across capture, queue residence, lock wait, HTTP and retry. timeout_s bounds each absolute HTTP attempt; incoming bytes cannot renew it. A receiver's longer Retry-After is preserved rather than shortened. shutdown_timeout_s defaults to five seconds. request_close() bars new work; wait_closed() establishes actual transport retirement. Native DNS/I/O that cannot be interrupted keeps its one slot and bounded material until it returns. It cannot send a late POST after cancellation. A failed close preserves the resource and the client remains CLOSING.

on_delivery receives the original index and deliveryId with CONFIRMED, REJECTED, UNKNOWN or NOT_ATTEMPTED and any validated receipt. A later rejection does not resolve an earlier lost response. Keep original source material and its identity outside this best-effort client when recovery across processes is required.

Retries reuse the same serialized material and stable delivery identifiers. A known refusal before admission can reduce framing and resend only the refused portion. Previously confirmed chunks are not resent. A non-retryable evaluation deferral is not retried merely because its HTTP status is 503.

AkhuProtocolError exposes status_code, code, validated operational facts, request_id, retry_after_s and retryable; arbitrary response fields are discarded. AkhuClientBoundaryError exposes observed_bytes and max_request_bytes for local framing refusal without an invented HTTP response or L0 receipt. Both inherit ValueError. Asynchronous delivery reports failures through on_error; the explicit blocking observe_sync operation can raise. on_flush concerns only confirmed durable receipts. Earlier chunks may be confirmed before a later failure.

The shared akhu.security-strip 2.0 policy takes an owned, bounded JSON snapshot. Known sensitive fields are omitted, with exact RFC 6901 paths and policy/version in context.capture.redactions. Accepted values are not truncated or replaced by a common string. Resource or representation failures refuse the whole observation locally through on_error / observe_sync(); no receipt is invented. The institution's capture policy is retained separately, and FULL cannot survive an actual omission. The runtime enforces its declared admission, scope and persistence boundaries.

  • Zero required runtime dependencies — core delivery uses only Python stdlib (http.client, threading, json)
  • Fail-open — observation failures never affect the observed system
  • Privacy by default — content redacted unless explicitly opted in
  • Credential redaction — known credential fields are omitted and declared even with capture_content=True
  • Thread-safe — one background worker drains observations without creating a thread per event

The exported client surface is defined in src/akhu_observer/client.py; provider wrappers are isolated under src/akhu_observer/wrappers.

Development

cd packages/observer-python
pip install -e ".[dev]"
pytest
pytest tests/invariants/       # Property-based tests
pytest tests/adversarial/      # Injection/attack resistance

Capture scope and compatibility

This field-name policy is not a general personal-data classifier: text and embedded JSON strings are not searched for secrets. Choose unmasked, qualified correlation identifiers and perform any necessary institutional minimization before capture, with declared provenance. Cryptographic preservation concerns the representation actually received, not an omitted original. The evaluator excludes redacted values and reported omitted paths from comparisons and correlations. The new SDK metadata requires the matching updated API; provenance is never silently removed to accommodate an older runtime.

Source bounds: 60 levels, 65,536 nodes, 16,384 members per collection, 262,144 UTF-16 units per string, 512 KB of encoded payload; 256 omissions per report, 512 UTF-16 units per path, eight reports. Lower server framing limits still apply. Payloads are JSON scalars, dictionaries with string keys, lists and tuples; unknown objects are not reflected, and binary or non-finite values are not converted into invented facts.

The API uses ECMAScript/binary64 numeric semantics. Use strings for exact identifiers and precision-sensitive decimals; the SDK does not certify arbitrary-precision arithmetic.

Metadata

Release files for akhu-observer 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for akhu-observer 2.0.0
File Size Uploaded Provenance Actions
akhu_observer-2.0.0.tar.gz 42.3 kB Without provenance Details for akhu_observer-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for akhu-observer 2.0.0
File Interpreter ABI Platform Actions
akhu_observer-2.0.0-py3-none-any.whl Python 3 none any Details for akhu_observer-2.0.0-py3-none-any.whl

Total release size: 98.9 kB

Release files / akhu_observer-2.0.0.tar.gz

Download URL akhu_observer-2.0.0.tar.gz
Size 42.3 kB
Tags Source
SHA-256 checksum
How to use checksums
da72652c33c07fbc07a9c7c0c27e7f88432c0a0fee62bcc0ae264277fc6b57e4
BLAKE2b-256 checksum
How to use checksums
7b77996b1177b14c12125fb5ed9e134771af70f589e6a2e8a01c8f983123906a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.8

Release files / akhu_observer-2.0.0-py3-none-any.whl

Download URL akhu_observer-2.0.0-py3-none-any.whl
Size 56.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dfea989ce7d97fb5adbdbbd83bb474838b018d58db7a2a238d91b0196a969dee
BLAKE2b-256 checksum
How to use checksums
f663f132e224e044722fd1b2ecd3a8c044170c6433853d7e23ecb4ad2b105fa8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.8

Security for akhu-observer 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page