> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracelm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> TraceLM TypeScript SDK: tracing, task lifecycle, reliability detection, and conversation context

Official TypeScript SDK for reliability-first observability in production agents.

## Install

```bash theme={null}
npm install tracelm
```

## Quick Start

```typescript theme={null}
import { TraceLM } from 'tracelm';

const tracelm = new TraceLM({
  apiKey: 'lt_your_tracelm_key',
  openaiApiKey: 'sk-your-openai-key',
});

const response = await tracelm.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello' }],
});
```

## Providers

`TraceLM` supports `provider: 'openai' | 'anthropic' | 'google'` with provider routing through `/v1/chat/completions`.

You can also use:

* `AnthropicTraceLM`
* `GeminiTraceLM`

## Task Grouping + Detection

```typescript theme={null}
const task = tracelm.startTask({ name: 'booking_flow', userId: 'user_123' });

try {
  await tracelm.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Book a flight' }],
  });

  const result = await task.complete();
  console.log(result?.loops.detected);
  console.log(result?.failures.explicit);
  console.log(result?.context.total);
  console.log(result?.toolFailureCount);
  console.log(result?.contextFailureCount);
} finally {
  tracelm.endTask();
}
```

## Manual Detection (No Completion)

```typescript theme={null}
const detection = await task.detect();
console.log(detection.loops.patterns);
console.log(detection.failures.semantic);
console.log(detection.context.lostContext);
```

## Conversation Tracking

```typescript theme={null}
const conversation = tracelm.startConversation({ userId: 'user_123', sessionId: 'sess_1' });

const turn = conversation.startTask({ name: 'turn_1' });
await tracelm.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hi' }],
});
await turn.complete();
tracelm.endTask();
tracelm.endConversation();
```

## Query APIs

```typescript theme={null}
const tasks = await tracelm.listTasks({ hasIssues: true });
const task = await tracelm.getTask('task-uuid');
const conversations = await tracelm.listConversations({ userId: 'user_123' });
const contextFailures = await tracelm.getConversationContextFailures('conv-uuid');
```

Use these queries to move from single requests to execution-level diagnosis.

## Environment Variables

```bash theme={null}
TRACELM_API_KEY=lt_...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
TRACELM_BASE_URL=https://api.tracelm.ai
```

## Notes

* `task.complete()` returns `null` if the backend task record does not exist yet.
* Use `task.complete({ runDetection: false })` for completion without detection.
* Detection results are cached in task metadata under `detection_results`.