npm package: @mode-7/tracelm
Description: TypeScript SDK for TraceLM - LLM observability and logging
Author: Mode 7
Latest version: 0.1.0

# @mode-7/tracelm

TypeScript SDK for [TraceLM](https://tracelm.com) - LLM observability and logging.

## Installation

```bash
npm install @mode-7/tracelm
```

## Quick Start

```ts
import { TraceLM } from "@mode-7/tracelm";

const tracelm = new TraceLM({
  apiKey: process.env.TRACELM_API_KEY!,
  applicationId: process.env.TRACELM_APP_ID!,
});

// Simple logging
await tracelm.info("User signed up");
await tracelm.error("Something went wrong");

// LLM observability
await tracelm.agent("Chat completion", {
  model: "gpt-4",
  provider: "openai",
  messages: [
    { role: "user", content: "Hello" },
    { role: "assistant", content: "Hi!" },
  ],
});
```

## Features

- **Simple logging** - `debug`, `info`, `warn`, `error`, `fatal` methods
- **LLM observability** - Track model usage, tokens, costs, and conversations
- **Automatic enrichment** - Token estimation, cost calculation, span extraction
- **Context helpers** - `withUser`, `withTrace`, `withSession`, `withMetadata`
- **Batching** - Optional event batching for high-volume applications
- **TypeScript** - Fully typed with inline documentation

## Configuration

```ts
const tracelm = new TraceLM({
  // Required
  apiKey: "your-api-key",
  applicationId: "your-app-id",

  // Optional
  baseUrl: "https://api.tracelm.com", // Custom API URL
  environment: "production", // Environment name
  timeout: 10000, // Request timeout (ms)
  throwOnError: false, // Throw on API errors
  batching: false, // Enable event batching
  batchInterval: 1000, // Batch flush interval (ms)
  batchSize: 100, // Max batch size
});
```

## Logging Methods

### Simple Logs

```ts
await tracelm.debug("Detailed debug info");
await tracelm.info("User action completed");
await tracelm.warn("Rate limit approaching");
await tracelm.error("Operation failed");
await tracelm.fatal("Critical system failure");
```

### With Options

```ts
await tracelm.info("User signed up", {
  user: { id: "user_123", email: "user@example.com" },
  metadata: { plan: "pro" },
  trace_id: "signup-flow-abc",
});
```

### Error Logging

```ts
try {
  await riskyOperation();
} catch (err) {
  await tracelm.error(err); // Accepts Error objects
}
```

## LLM Events

### Basic Usage

```ts
await tracelm.agent("Chat completion", {
  model: "gpt-4",
  provider: "openai",
  messages: [
    { role: "system", content: "You are helpful." },
    { role: "user", content: "Hello" },
    { role: "assistant", content: "Hi there!" },
  ],
});
```

### With Full Metrics

```ts
const startTime = Date.now();
const response = await openai.chat.completions.create({...});

await tracelm.agent("Chat completion", {
  model: response.model,
  provider: "openai",
  input_tokens: response.usage?.prompt_tokens,
  output_tokens: response.usage?.completion_tokens,
  latency_ms: Date.now() - startTime,
  messages: messages,
  output: response.choices[0].message.content,
});
```

### Tool Calls (Spans Auto-Extracted)

```ts
await tracelm.agent("Tool-assisted response", {
  model: "gpt-4",
  provider: "openai",
  messages: [
    { role: "user", content: "What's the weather in London?" },
    {
      role: "assistant",
      content: null,
      tool_calls: [
        {
          id: "call_1",
          type: "function",
          function: { name: "get_weather", arguments: '{"city":"London"}' },
        },
      ],
    },
    { role: "tool", content: '{"temp":18}', tool_call_id: "call_1" },
    { role: "assistant", content: "It's 18°C in London." },
  ],
});
```

## Context Helpers

Chain context methods to attach default values to all events:

```ts
const logger = tracelm
  .withUser({ id: "user_123" })
  .withTrace("request-abc")
  .withSession("session-xyz")
  .withMetadata({ version: "1.2.3" });

// All events include the attached context
await logger.info("User action");
await logger.agent("LLM call", { model: "gpt-4", provider: "openai" });
```

## Batching

For high-volume applications, enable batching to reduce API calls:

```ts
const tracelm = new TraceLM({
  apiKey: "...",
  applicationId: "...",
  batching: true,
  batchSize: 50,
  batchInterval: 2000,
});

// Events are batched automatically
tracelm.info("Event 1");
tracelm.info("Event 2");

// Flush before shutdown
await tracelm.flush();
```

## TypeScript Types

All types are exported for use in your application:

```ts
import type {
  TraceLMEvent,
  TraceLMLLM,
  LLMMessage,
  TraceLMUser,
  LogLevel,
} from "@tracelm/sdk";
```

## Automatic Backend Computation

TraceLM automatically computes these fields server-side if not provided:

- **Token counts** - Estimated via tiktoken from messages/output
- **Cost** - Calculated from provider pricing tables
- **Previews** - Extracted from message content
- **Spans** - Auto-extracted from messages with tool calls
- **Security scans** - PII detection, injection detection
- **Bot detection** - From request context

This means you can send minimal payloads and let TraceLM handle the rest:

```ts
// Minimal - TraceLM computes tokens, cost, previews
await tracelm.agent("Chat", {
  model: "gpt-4",
  provider: "openai",
  messages: [...],
});

// Full - Use your own values
await tracelm.agent("Chat", {
  model: "gpt-4",
  provider: "openai",
  input_tokens: 150,
  output_tokens: 89,
  cost: 0.0045,
  latency_ms: 1200,
  messages: [...],
});
```

## License

MIT