kaplaix 0.1.0

Python SDK for Kaplaix AI agent governance platform

kaplaix — Python SDK

Python SDK for instrumenting AI agents with Kaplaix.

Requirements

• Python >= 3.10
• httpx (installed automatically)

Installation

pip install kaplaix

Quick start

from kaplaix import KaplaixClient

client = KaplaixClient(api_key="al_live_...")

with client.session(agent_id="my-agent") as session:
    session.log_tool_call("web_search", "sha256-of-args", response_status=200)

Client options

Parameter	Type	Default	Description
api_key	str	required	Tenant API key (al_live_...)
base_url	str	https://api.kaplaix.io	API base URL
timeout_ms	float	10000	Request timeout in milliseconds
retries	int	3	Retry attempts on transient errors (429, 502, 503, 504)
metadata	SdkMetadata	—	Optional environment metadata

Session

session = client.session(
    agent_id="my-agent",
    session_id="optional-custom-id",  # any non-empty string; UUID generated if absent
)

Use as a context manager (calls end() automatically) or manage lifecycle explicitly.

Event helpers

Tool call

session.log_tool_call(
    tool_name="database_query",
    arguments_hash="sha256-hex",   # hash of args — never log raw args
    response_status=200,           # optional HTTP status
    endpoint="/api/query",         # optional
)

Data movement

session.log_data_movement(
    operation="export",            # "read" | "write" | "delete" | "export"
    object_ids=["record-001"],
    diff_summary="Exported 1 record",  # optional
)

Approval

session.log_approval(
    approver_id="user-42",
    scope="delete:crm:customers:bulk",
    decision="rejected",           # "approved" | "rejected"
)

Environment

session.log_environment(
    is_sandbox=False,
    network_segment="prod-vpc",
    workspace="production-cluster",
)

Raw event

session.log_event(
    category="reasoning",
    payload={"summary": "Decided to proceed with deletion"},
)

Retry behavior

The SDK retries on HTTP 429, 502, 503, and 504 using exponential backoff with full jitter. Non-retryable errors (4xx) are raised immediately.

Error handling

from kaplaix import KaplaixError, KaplaixNetworkError, KaplaixTimeoutError

try:
    session.log_tool_call("tool", "hash")
except KaplaixError as e:
    print(f"API error {e.status_code}: {e.body}")
except KaplaixTimeoutError:
    print("Request timed out")
except KaplaixNetworkError as e:
    print(f"Network error: {e.__cause__}")