# TrackingKoala LLM Setup Guide

This file describes the recommended setup instructions for LLM agents.

## Canonical page
- https://trackingkoala.com/docs/llm-setup

## Scenario selection
- Use OpenAI template when you have model + token counts and want TrackingKoala to compute cost automatically.
- Use custom events when your system already computes cost/charge or uses custom pricing logic.

## Scenario A: OpenAI template
- Endpoint: POST https://api.trackingkoala.com/v1/templates/execute
- SDK method: koala.rateTemplate(...)
- Required payload fields:
  - templateId = "openai"
  - mode = "preview" | "track"
  - inputs.model
  - inputs.input_tokens
  - inputs.output_tokens
- Optional payload fields:
  - inputs.cached_input_tokens
  - event.{provider,action,environment,userId,traces,tags,metadata}

### Example (SDK)
```ts
import { TrackingKoala } from "@trackingkoala/sdk";

const koala = new TrackingKoala(process.env.KOALA_API_KEY!);

await koala.rateTemplate({
  templateId: "openai",
  mode: "track",
  inputs: {
    model: "gpt-5.1",
    input_tokens: 1200,
    cached_input_tokens: 300,
    output_tokens: 450
  },
  event: {
    source: "template",
    provider: "openai",
    action: "chat.completions",
    environment: "production",
    userId: "usr_8f9c"
  }
});
```

## Scenario B: Custom events
- Endpoint: POST https://api.trackingkoala.com/v1/events/track
- SDK method: koala.track(...)
- Required payload fields:
  - cost (> 0)
- Common optional fields:
  - charge, currency, environment, source, provider, action, userId, traces, tags, metadata

### Example (SDK)
```ts
import { TrackingKoala } from "@trackingkoala/sdk";

const koala = new TrackingKoala(process.env.KOALA_API_KEY!);

await koala.track({
  cost: 142,
  charge: 249,
  currency: "USD",
  environment: "production",
  source: "api",
  provider: "anthropic",
  action: "messages.create",
  userId: "usr_8f9c",
  tags: ["premium", "chat"],
  traces: ["trace_2039"],
  metadata: {
    model: "claude-sonnet-4",
    inputTokens: 1380,
    outputTokens: 420,
    latencyMs: 684
  }
});
```