TypeScript SDK

npm install @seer/sdk

# With OpenTelemetry support (optional)
npm install @seer/sdk @opentelemetry/api

import { SeerClient } from '@seer/sdk';

const client = new SeerClient();  // reads SEER_API_KEY from env

// No await needed! Fire-and-forget by default
client.log({
  task: "How do I reset my password?",
  context: [
    { text: "To reset your password, go to Settings...", score: 0.89 }
  ],
});

// Events auto-flush on process exit

const client = new SeerClient({
  apiKey: "seer_live_...",           // or from SEER_API_KEY env
  fireAndForget: true,               // async (default) or sync
  maxQueueSize: 10_000,              // max events before dropping
  flushInterval: 500,                // worker flush interval (ms)
  timeout: 5000,                     // HTTP timeout (ms)
});

await client.log({
  // Required
  task: string,                              // The user query
  context: Array<string | Passage>,          // Retrieved passages

  // Metadata
  metadata?: Record<string, unknown>,        // Free-form metadata

  // OpenTelemetry (auto-detected by default)
  trace_id?: string,                         // OTEL trace ID (32 hex)
  span_id?: string,                          // OTEL span ID (16 hex)
  parent_span_id?: string,                   // OTEL parent span ID
  span_name?: string,                        // Operation type
  useOtelTrace?: boolean,                    // Auto-detect OTEL context (default: true)

  // Multi-hop / Agentic
  is_final_context?: boolean,                // Mark as final evidence
  subquery?: string,                         // Decomposed sub-question

  // Accuracy testing
  ground_truth?: GroundTruth,                // For comparing against expected

  // Other options
  created_at?: string,                       // ISO8601 timestamp override
  sample_rate?: number,                      // 0.0-1.0 sampling rate
});

await client.flush(timeout?: number);

const stats = client.stats();
console.log(`Sent: ${stats.eventsSent}, Failed: ${stats.eventsFailed}`);

interface ClientStats {
  eventsEnqueued: number;
  eventsSent: number;
  eventsDropped: number;
  eventsFailed: number;
  bytesSent: number;
  lastError?: string;
}

await client.close();

// Simple strings
const context = ["Passage one...", "Passage two..."];

// Passage objects (recommended)
const context = [
  {
    text: "The main content...",      // Required
    score: 0.95,                       // Optional: retrieval score
    id: "doc-123",                     // Optional: document ID
    source: "wiki",                    // Optional: source name
    metadata: { author: "..." },       // Optional: custom metadata
  }
];

import { wrapWithSeerTrace, SeerClient } from '@seer/sdk';

const client = new SeerClient();

const tracedRetrieve = wrapWithSeerTrace(
  async (query: string) => {
    // Your retrieval logic
    return [{ text: "Result...", score: 0.9 }];
  },
  {
    taskArgIndex: 0,           // Index of the query argument
    contextFromReturn: true,   // Return value is the context
    metadata: { service: "help-bot" },
    sampleRate: 0.10,
    client,
  }
);

// Automatically logged when called
const results = await tracedRetrieve("How do I reset my password?");

const client = new SeerClient();  // fireAndForget: true (default)

// Just call and continue - no await!
client.log({ task: "...", context: [...] });

// Events are batched and sent automatically
// Auto-flushes on process exit

const client = new SeerClient({ fireAndForget: false });

// Await to get the record_id
const recordId = await client.log({ task: "...", context: [...] });
console.log(`Created: ${recordId}`);

import { trace } from '@opentelemetry/api';
import { SeerClient } from '@seer/sdk';

const tracer = trace.getTracer('my-app');
const client = new SeerClient();

await tracer.startActiveSpan('retrieval', async (span) => {
  // trace_id, span_id, span_name are captured automatically
  // No await needed in fire-and-forget mode
  client.log({ task: "...", context: [...] });
  span.end();
});

// No await needed in fire-and-forget mode
client.log({
  task: "...",
  context: [...],
  trace_id: "0af7651916cd43dd8448eb211c80319c",
  span_id: "b7ad6b7169203331",
  span_name: "retrieval",
  useOtelTrace: false,  // disable auto-detection
});

// No await needed in fire-and-forget mode
client.log({
  task: "What is machine learning?",
  context: [
    { text: "ML is a subset of AI...", id: "doc-ml-intro" },
    { text: "Neural networks learn from data...", id: "doc-nn-basics" },
  ],
  ground_truth: {
    // Document IDs that are relevant (matched against passage.id)
    gold_doc_ids: ["doc-ml-intro", "doc-nn-basics"],
    answer: "ML is a type of AI that learns from data",  // optional
  },
});

import { seerLog } from '@seer/sdk';

// No await needed - fire-and-forget by default
seerLog({
  task: "Quick question",
  context: [{ text: "Answer..." }],
});

import type {
  Passage,
  GroundTruth,
  LogEvent,
  LogOptions,
  ClientStats,
  SeerClientOptions,
} from '@seer/sdk';