keyhole-sdk 0.4.0

Official public Python SDK for interacting with Keyhole governance runtimes

keyhole-sdk

Python SDK for interacting with Keyhole-compatible runtimes.

Install

pip install keyhole-sdk

Quickstart

from keyhole_sdk import KeyholeClient

client = KeyholeClient(base_url="http://localhost:8080")

# Health check
print(client.health())

# Runtime identity and capabilities
identity = client.identity()
print(identity)

# Current runtime state
print(client.state())

# Submit a realization request
receipt = client.realize(
    candidate_digest="sha256:abc123",
    payload={},
)
print(receipt)

# Replay the same digest safely
replay = client.realize(
    candidate_digest="sha256:abc123",
    payload={},
)
print(replay)

client.close()

Note: By default the test runtime runs in local-only mode — realization is not gated through MCP governance. Set KEYHOLE_MCP_URL and KEYHOLE_MCP_TOKEN on the runtime to enable governed mode.

API

Method	Description
health()	GET /healthz — runtime liveness
identity()	GET /identity — runtime identity and capabilities
state()	GET /state — current runtime-local state
realize(candidate_digest, payload)	POST /realize — bounded realization request
close()	Close the underlying HTTP session

Models

Pydantic models are available in keyhole_sdk.models:

• RuntimeIdentity
• RuntimeState
• RealizationRequest
• RealizationReceipt

Configuration

client = KeyholeClient(
    base_url="http://localhost:8080",
    timeout=10.0,  # default
)

You can also pass a custom requests.Session for advanced use cases.

Compatibility

RuntimeBridgeClient is available as a backward-compatible alias for KeyholeClient.

License

Apache 2.0 — see LICENSE.