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
- 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.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| akhu_observer-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for akhu_observer-1.0.2-py3-none-any.whl |
Release files / akhu_observer-1.0.2-py3-none-any.whl
| Download URL | akhu_observer-1.0.2-py3-none-any.whl |
|---|---|
| Size | 35.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3d93836444e05afef56f1bbeabfd52ee79251ccd44025c74805dbb4bfa0b585d
|
|
BLAKE2b-256 checksum How to use checksums |
27b3e78f3d9dc0b1fb401dfbd3f7806f94a43cb43bede6ad533984061f49c353
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for akhu-observer 1.0.2
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.