# Using the Kalmia SDK

Instrument a Python or TypeScript agent with the Kalmia SDK.
Wrap your model client and every call is captured; use `traced()` to group a whole run into one trace.

## Install

pip:

```bash
pip install kalmia
```

npm:

```bash
npm install kalmia-sdk
```

- **Python**: Zero external dependencies
- **TypeScript**: Automatic context propagation (AsyncLocalStorage)

## Initialize & wrap

Call the initializer with your workspace API key (from **Settings → API Keys**, or the `KALMIA_API_KEY` env var), then wrap your OpenAI or Anthropic client.
Every call is now traced.

```python
from kalmia import init_logger, wrap_anthropic
import anthropic

init_logger(project_name="my-agent", api_key="kal_live_your_api_key", base_url="https://www.kalmia.dev")
client = wrap_anthropic(anthropic.Anthropic())
```

```typescript
import Anthropic from "@anthropic-ai/sdk";
import { initLogger, wrapAnthropic } from "kalmia-sdk";

initLogger({ projectName: "my-agent", apiKey: "kal_live_your_api_key", baseUrl: "https://www.kalmia.dev" });
const client = wrapAnthropic(new Anthropic());
```

## Group a run

Use `traced()` to capture a whole agent run — multiple calls, tools, and the full conversation — as one trace.
Without it, each call is its own standalone trace.

```python
@traced(name="my-agent-run")
def run(prompt):
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.content[0].text
```

```typescript
await traced(async () => {
  const response = await client.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    messages: [{ role: "user", content: prompt }],
  });
  return response.content[0].text;
}, { name: "my-agent-run" });
```

## Tool spans

Wrap tool executions with `span_type="tool"` so they appear alongside the model calls in the trace.

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

```typescript
await span.traced("get_weather", async (toolSpan) => {
  const result = await fetchWeather(city);
  toolSpan.log({ input: { city }, output: result });
}, { type: "tool" });
```

## Tag variants

Pass `variant` in the run metadata to compare versions of your agent in [Metrics](https://www.kalmia.dev/docs/analytics.md#metrics) and [Trends](https://www.kalmia.dev/docs/analytics.md#trends).
Any label works.

```python
with traced(name="my-agent-run", metadata={"variant": "rag"}) as span:
    # ... run this variant ...
    span.log(output=result)
```

```typescript
await traced(async (span) => {
  // ... run this variant ...
  span.log({ output: result });
}, { name: "my-agent-run", metadata: { variant: "rag" } });
```

See [Capturing traces](https://www.kalmia.dev/docs/capture.md) for OpenTelemetry and direct ingestion, and [Concepts](https://www.kalmia.dev/docs/concepts.md#traces) for the trace data model.
