Skip to main content

Python Client Quickstart

keeptrusts-client gives Python services one package for both gateway-routed inference and trusted server-side control-plane helpers.

Use this page when​

  • You need a Python OpenAI-compatible client routed through the Keeptrusts gateway.
  • You want event, trail, or evidence helpers from Python.
  • You are running trusted backend code, jobs, or automation.

Install​

pip install keeptrusts-client

Gateway quickstart​

from keeptrusts_client import create_gateway_client

client = create_gateway_client(
    base_url="https://gateway.keeptrusts.example/v1",
    api_key="kt_live_...",
    agent_id="agent-finance-assistant",
)

response = client.chat.completions.create(
    model="gpt-5.4-mini-mini",
    messages=[{"role": "user", "content": "Summarize today's policy checks."}],
)

print(response.choices[0].message.content)

This is the fastest path when you only need governed inference traffic.

Canonical header helper​

from keeptrusts_client import build_keeptrusts_headers, generate_traceparent

headers = build_keeptrusts_headers(
    traceparent=generate_traceparent(),
)

Use the helper to preserve:

  • x-request-id
  • x-keeptrusts-agent-id
  • traceparent

Event reads for request-level spend​

from keeptrusts_client import get_event, list_events

result = list_events(
    since="2026-05-31T00:00:00Z",
    agent_id="agent-finance-assistant",
    bearer_token="kt-control-plane-token",
    base_url="https://api.keeptrusts.example",
)

first_event = result.events[0]
print(first_event.event_cost_attribution.total_cost_usd)
print(first_event.event_cost_attribution.source_spend_log_id)

detail = get_event(
    first_event.event_id,
    bearer_token="kt-control-plane-token",
    base_url="https://api.keeptrusts.example",
)
print(len(detail.citations))

Use decision events for request-level spend attribution. Do not substitute wallet balance reads for per-request reporting.

Evidence workflow​

from keeptrusts_client import (
    build_evidence_bundle,
    download_digest,
    export_bundle_zip,
    get_public_key,
    verify_trail,
)

key = get_public_key(
    bearer_token="kt-control-plane-token",
    base_url="https://api.keeptrusts.example",
)

digest = download_digest(
    "digest-123",
    bearer_token="kt-control-plane-token",
    base_url="https://api.keeptrusts.example",
)

verification = verify_trail(
    start_time="2026-05-31T00:00:00Z",
    end_time="2026-05-31T23:59:59Z",
    deep_verify=False,
    bearer_token="kt-control-plane-token",
    base_url="https://api.keeptrusts.example",
)

print(key.kid)
print(digest.storage_key)
print(verification.chain_integrity)

bundle = build_evidence_bundle(
    "req_123",
    bearer_token="kt-control-plane-token",
    base_url="https://api.keeptrusts.example",
)
archive = export_bundle_zip(bundle)

Automation helpers​

from keeptrusts_client import bootstrap_service_account, build_token_rotation_plan

service_account = bootstrap_service_account("sdk-rollout", ["events:read", "agents:write"])
rotation_plan = build_token_rotation_plan([
    {"env_var": "KEEPTRUSTS_API_TOKEN", "current_token": "old", "next_token": "new"}
])

Runtime boundary​

Treat the package as two lanes inside one Python distribution:

  • gateway client helpers for governed inference traffic
  • bearer-token control-plane helpers for trusted server workflows

For the gateway lane, use an API token minted for gateway request execution, typically purpose=general. Reserve purpose=gateway_runtime for the hosted gateway process itself.

Do not embed control-plane bearer tokens in untrusted clients.

MCP reminder​

If your Python workload consumes MCP-enabled tool access, Keeptrusts still expects the gateway to own MCP transport and policy enforcement. The SDK configures or consumes the request flow; it does not start a standalone MCP server.

Next steps​

For AI systems​

  • Package: keeptrusts-client.
  • Gateway helpers: create_gateway_client(), create_async_gateway_client(), create_responses_client().
  • Control-plane helpers: list_events(), get_event(), download_digest(), get_public_key(), verify_trail().
  • Request-level spend attribution comes from event reads.

For engineers​

  • Use the gateway helpers for OpenAI-compatible inference with an API token whose ABAC profile is purpose=general.
  • Use bearer-token helpers only in trusted server code.
  • Preserve canonical request headers with build_keeptrusts_headers().
  • Use trail and digest helpers for evidence-grade verification flows.