Helio Python SDK

Thin Python client for the Helio MCP governance proxy. Communicates with the proxy's sideband HTTP API to report evidence and context. The SDK never makes governance decisions — that is always the proxy's job.

Install

pip install helio-client

helio-client is only the PyPI distribution name — the string you pip install. This package is the Helio Python SDK; the distribution name differs solely because the bare helio name on PyPI is held by an unrelated abandoned project. It changes nothing about how you use the SDK — the import path stays helio (from helio import HelioContext), and these docs refer to it as the Helio Python SDK throughout.

Quick Start

When the proxy runs with sdk.enabled: true (off by default), it prints a per-boot SDK token to stderr on startup (SDK token (generated per-boot HELIO_SDK_TOKEN; pass as HELIO_SDK_TOKEN env var to your SDK clients): ...); if the proxy's environment already has HELIO_SDK_TOKEN set, that value is reused instead and not echoed. Export the same token in the environment where your SDK client runs — the client reads HELIO_SDK_TOKEN automatically and attaches it as Authorization: Bearer <token> on every sideband call. Without it, requests to the proxy sideband are rejected with 401.

export HELIO_SDK_TOKEN=<token-from-proxy-startup-logs>

from helio import HelioContext

with HelioContext(proxy_url="http://127.0.0.1:3200") as ctx:
    # Declare what evidence this session needs
    ctx.require_evidence("orders.lookup")

    # Mark tool output as evidence under the required key
    ctx.mark_evidence("get_order", "orders.lookup", {"orderId": 42})

    # Set arbitrary session context
    ctx.set("agent_id", "support-bot")

    # Check what evidence the proxy has
    report = ctx.get_evidence_state()
    print(report.satisfied)  # ['orders.lookup']
    print(report.missing)    # []

API

HelioContext

High-level wrapper with local requirement tracking.

HelioClient

Low-level HTTP client mapping to the sideband API.

HelioError

All SDK methods raise HelioError on failure instead of raw HTTP exceptions. The error includes an actionable message and an optional status_code attribute.

from helio import HelioContext, HelioError

try:
    with HelioContext() as ctx:
        ctx.mark_evidence("tool", "key", "data")
except HelioError as e:
    print(e)              # "POST /evidence failed: HTTP 400"
    print(e.status_code)  # 400

Caught error types:

• Connection errors — proxy unreachable ("Cannot connect to proxy at ...")
• Timeout errors — proxy did not respond in time ("Proxy request timed out: ...")
• HTTP errors — proxy returned 4xx/5xx ("POST /evidence failed: HTTP 400")
• Serialization errors — request payload is not JSON-serializable for POST calls (for example, {"v": object()}), normalized to HelioError with endpoint context ("Failed to serialize POST /evidence payload as JSON: ...").
• Evidence allowlist errors — POST /evidence may return code=evidence_key_not_in_policy_allowlist when evidence_key does not match any policy evidence.requires key. The SDK includes the rejected key and configured-key preview in HelioError for quick diagnosis.
• Malformed sideband responses — invalid JSON or missing fields from GET /session/:session_id/state are normalized to HelioError ("... returned malformed response payload").

Configuration

Correlating with MCP traffic: session_id is the canonical correlation key between the SDK and the proxy's MCP door. Give the SDK an explicit session_id and send the same value as the x-helio-session-id header on every MCP request — the default session identity chain resolves it with zero proxy configuration. The auto-generated UUID default cannot satisfy evidence or dependency gates on its own: the proxy never sees it on the MCP side, so gated calls fail closed until both sides share one id.

Constraints

• Under 500 lines — governance logic belongs in the proxy, not the SDK
• Thin client only — no caching, no policy evaluation, no decision-making
• Python 3.10+ required

License

Apache 2.0