Guide

Using the Kalmia SDK

Instrument your Python or TypeScript agent directly with the Kalmia SDK for zero-dependency tracing.

Overview

The Kalmia SDK wraps your LLM client (OpenAI or Anthropic) to automatically capture every API call as a trace span. Use traced() to group multiple calls into a single trace representing an agent run.

Installation

pip install kalmia-sdk

Initialize and wrap

Call init_logger to configure your Kalmia endpoint, then wrap your LLM client. Every subsequent API call is automatically captured.

from kalmia_sdk import init_logger, wrap_anthropic
import anthropic, os

init_logger(
    project_name="my-agent",
    base_url="https://your-kalmia.app",
    api_key=os.environ["KALMIA_API_KEY"],  # required (v0.2+)
)
client = wrap_anthropic(anthropic.Anthropic())

# This call is now automatically traced
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

Grouping calls with traced()

Without traced(), each LLM call creates its own standalone trace. Use traced() to group multiple calls, tool executions, and the full conversation into a single trace.

from kalmia_sdk import traced

@traced(name="my-agent-run")
def run(prompt):
    # All LLM calls within this function
    # are grouped into one trace
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.content[0].text

Tool spans

Wrap tool executions with traced() using span_type="tool" to capture them as tool spans.

with traced(name="get_weather", span_type="tool") as span:
    result = get_weather(city="Tokyo")
    span.log(input={"city": "Tokyo"}, output=result)

How it works under the hood

The SDK uses contextvars (Python) or AsyncLocalStorage (TypeScript) to automatically propagate span context. When you call an LLM inside a traced() block, the SDK attaches the span to the current trace without any manual passing.

When the trace completes, the SDK flushes the span tree to your Kalmia instance via an authenticated HTTP POST carrying your workspace API key. Delivery failures (network errors or non-2xx responses) are surfaced as warnings with the status or exception — never silently dropped — and never raise into your agent. The SDK has zero external dependencies.

Security & data handling

Captured traces include system prompts, full message history, and tool inputs/results, which may contain PII or credentials. Sanitize secrets in tool results before shipping — Kalmia v1 stores trace data encrypted at rest with bounded retention but does not redact payloads for you.

Root-cause analysis sends trace data to Anthropic (an external provider) via the Kalmia server. Under a DPA, treat this as data leaving your boundary. Self-hosting the judge is a future option.

To revoke a key, mark it revoked directly in the database (there is no revoke endpoint in v1):

update public.api_keys set revoked_at = now() where id = '<key id>';

API reference