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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.