Python SDK

The developer-facing primitives of chp-core — the host, the @capability decorator, the evidence store, adapters, serving, and the core types.

The chp-core Python package is the reference implementation. This page covers the primitives you use directly. The authoritative source is the package itself (pip show chp-core); signatures here track chp-core and may trail a release.

pip install chp-core

LocalCapabilityHost

The host registers capabilities, admits invocations, and writes evidence.

from chp_core import LocalCapabilityHost, capability

host = LocalCapabilityHost("my-host")

Method	Purpose
`register(fn)`	Register a `@capability`-decorated function (or an object exposing them).
`invoke(capability_id, payload, correlation_id=None, ...)`	Invoke a capability; returns an invocation result and emits evidence.
`replay(correlation_id)`	Return the ordered evidence events for a correlation id.
`discover(...)`	List the capabilities the host exposes.
`descriptor()`	The `HostDescriptor` (identity, capabilities, evidence store metadata).
`query_evidence(...)`	Query evidence by capability, outcome, time, etc.
`evidence_count(correlation_id)`	Count evidence events for a correlation id.
`grant_approval(...)` / `deny_approval(...)`	Record a human/organizational approval decision.

result = host.invoke(
    "payments.transfer",
    {"amount": 100.0, "to": "acct_456"},
    correlation_id="session-abc",
)
events = host.replay("session-abc")
# -> execution_started, execution_completed

@capability

Turn any function into a governed capability with a stable identity.

@capability(
    id="payments.transfer",
    version="1.0.0",
    description="Transfer funds.",
    # input_schema=... optional JSON Schema
)
def transfer(ctx, amount: float, to: str):
    execute_transfer(amount, to)
    return {"status": "ok", "amount": amount}

host.register(transfer)

The ctx is a CapabilityExecutionContext — it carries correlation_id, subject, and emit(...) for domain evidence events.

SQLiteEvidenceStore

Durable, append-only, SHA256 hash-chained evidence.

from chp_core import LocalCapabilityHost, SQLiteEvidenceStore

store = SQLiteEvidenceStore(".chp/evidence.sqlite")
host = LocalCapabilityHost("my-host", store=store)

Method	Purpose
`append(event)`	Append an evidence (or conversation) event.
`by_correlation(correlation_id)`	All events for a correlation id, in order.
`verify_chain(correlation_id)`	Verify SHA256 chain integrity (tamper detection).
`count_by_correlation(correlation_id)`	Count events for a correlation id.

Adapters

Adapters package external systems as CHP capabilities and are auto-discovered through the chp.adapters entry point.

from chp_core import auto_register_adapters, register_adapter

# Discover and register every installed adapter package
auto_register_adapters(host)

# Or register one explicitly
from chp_adapter_github import GitHubAdapter
register_adapter(host, GitHubAdapter())

Serving over HTTP

from chp_core import serve_http, RemoteCapabilityHost

serve_http(host, port=8803)                     # serve a host
remote = RemoteCapabilityHost("http://host:8803")  # call it from elsewhere

Agent sessions

Record an agent's work — LLM calls, tool calls — as first-class evidence.

from chp_core import AgentSession, wrap_tool_call

Persistence helper

Wire several SQLite-backed capabilities (state machine, event bus, retrieval, graph, incident) in one call.

from chp_core import setup_sqlite_capabilities

managers = setup_sqlite_capabilities(host, base_dir=".chp")

Core types

Type	What it is
`CapabilityDescriptor`	A capability's declared identity, version, modes, policy, evidence behavior.
`InvocationEnvelope`	The object that crosses the boundary: capability id, mode, correlation, subject, payload.
`ExecutionEvidence`	A structured evidence event (started / completed / failed / denied / skipped).
`ReplayQuery` / `ReplayResult`	Query and result for replay by correlation id.

See the spec and schema reference for the normative definitions, and the CLI reference for the chp command surface.

On this page