lightrace-js

Lightweight LLM tracing SDK for TypeScript/JavaScript with remote tool invocation.

Install

yarn add lightrace

Quick Start

import { Lightrace, trace } from "lightrace";

const lt = new Lightrace({
  publicKey: "pk-lt-demo",
  secretKey: "sk-lt-demo",
  host: "http://localhost:3002",
});

// Root trace
const runAgent = trace("run-agent", async (query: string) => {
  const results = await search(query);
  return results;
});

// Span
const search = trace("search", { type: "span" }, async (query: string) => {
  return ["result1", "result2"];
});

// Generation (LLM call)
const generate = trace(
  "generate",
  { type: "generation", model: "gpt-4o" },
  async (prompt: string) => {
    return "LLM response";
  },
);

// Tool — remotely invocable from the Lightrace UI
const weatherLookup = trace("weather", { type: "tool" }, async (input: { city: string }) => {
  return { temp: 72, unit: "F" };
});

// Tool — traced but NOT remotely invocable
const readFile = trace("read-file", { type: "tool", invoke: false }, async (path: string) => {
  return "file contents";
});

await runAgent("hello");
lt.flush();
await lt.shutdown();

trace() API

// Root trace (no options)
trace(name, fn);

// With options
trace(name, options, fn);

Options

| Option | Type | Default | Description | | ------------- | --------- | ----------- | -------------------------------------------------------- | | type | string | undefined | "span", "generation", "tool", "chain", "event" | | invoke | boolean | true | For type: "tool": register for remote invocation | | model | string | undefined | For type: "generation": LLM model name | | inputSchema | ZodType | undefined | Optional Zod schema for tool input | | metadata | Record | undefined | Static metadata attached to every call |

Compatibility

Lightrace server also accepts traces from Langfuse Python/JS SDKs.

Development

yarn install
yarn test
yarn typecheck
yarn lint
yarn format

License

MIT