Skip to main content
Official TypeScript SDK for reliability-first observability in production agents.

​
Install

npm install tracelm

​
Quick Start

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

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)

const detection = await task.detect();
console.log(detection.loops.patterns);
console.log(detection.failures.semantic);
console.log(detection.context.lostContext);

​
Conversation Tracking

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

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

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.