Python SDK

The Python SDK (kaplaix) provides a client for instrumenting Python-based AI agents.

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)

The context manager calls session.end() automatically.

Client options

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

Creating sessions


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

Use as a context manager or manage the lifecycle explicitly:


# Context manager (recommended)
with client.session(agent_id="my-agent") as session:
    session.log_tool_call("tool", "hash")
 
# Explicit lifecycle
session = client.session(agent_id="my-agent")
session.log_tool_call("tool", "hash")
session.end()

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__}")