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

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 that identifier so an ambiguous network outcome cannot create a second fact. on_flush runs only after AKHU confirms a durable receipt; callback failures never trigger redelivery. on_error and on_flush are isolated from the observed application.

Architecture

Operational outcomes and framing

Batches are framed by observation count and exact encoded body bytes. Local ceilings are 5,000 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. Older or unavailable introspection retains local ceilings; the HTTP outcome and confirmed durable receipt remain authoritative.

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.

Privacy preprocessing has separate local bounds: 10,000 Unicode characters per string, 1,000 items per collection and bounded nesting. Truncation markers describe omitted material. These transformations do not increase runtime admission capacity. See the runtime contract for scopes and persistence.

  • 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 — forbidden credential values are replaced 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

Metadata

Release files for akhu-observer 1.2.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 1.2.0
File Size Uploaded Provenance Actions
akhu_observer-1.2.0.tar.gz 52.5 kB Without provenance Details for akhu_observer-1.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 91.4 kB

Release files / akhu_observer-1.2.0.tar.gz

Download URL akhu_observer-1.2.0.tar.gz
Size 52.5 kB
Tags Source
SHA-256 checksum
How to use checksums
367dd4a1669cb13cf130091a6ee13828d2e3c65581fe8d3a2161359b4e9b9ac6
BLAKE2b-256 checksum
How to use checksums
3b8b758acc9ea9f1245153c886fa28c2285fc82e47fce59391151b49a09110cc
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-1.2.0-py3-none-any.whl

Download URL akhu_observer-1.2.0-py3-none-any.whl
Size 38.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb5f88acd5fc5db960b5c935bb6a70d50a65e6ca23687309e6119100d3be7f2f
BLAKE2b-256 checksum
How to use checksums
a06e80a5939c0ac56cc8a6b64f75dab92d5938d83aae8883b24a3beb2dded446
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 1.2.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