0xtrace 1.0.0 → 1.0.1

package/src/core/tracer.ts

@@ -0,0 +1,171 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/sdk/src/core/tracer.ts
+//
+// Responsibilities:
+//   1. Own one logical "session" (a single agent run).
+//   2. Maintain a monotonic step counter across all calls in that session.
+//   3. Enrich a RawCapturePayload into a full TracePayload (ids, cost, ts).
+//   4. Hand the enriched payload to the Dispatcher non-blocking.
+//   5. Expose a flush() for clean shutdown / test assertions.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { Dispatcher }                            from "./dispatcher";
+import { calcCostUsd }                           from "../utils/cost";
+import type {
+  RawCapturePayload,
+  TracePayload,
+  TracerOptions,
+  IDispatcher,
+}                                                from "./types";
+
+// ── SDK version (keep in sync with package.json) ─────────────────────────────
+const SDK_VERSION = "0.1.0";
+
+// ── UUID helper ──────────────────────────────────────────────────────────────
+// crypto.randomUUID() is available in Node ≥ 14.17, modern browsers, and
+// the Edge runtime. Provide a tiny fallback for exotic environments.
+function uuid(): string {
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    return crypto.randomUUID();
+  }
+  // Fallback: RFC-4122 v4 UUID
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+// ── Tracer ────────────────────────────────────────────────────────────────────
+
+export class Tracer {
+  /** Groups all LLM calls in this agent run. */
+  readonly sessionId: string;
+
+  /** Caller-supplied arbitrary metadata attached to every payload. */
+  private readonly metadata: Record<string, string>;
+
+  /** Whether telemetry is active (can be disabled via options). */
+  private readonly enabled: boolean;
+
+  /** Delivery engine — injectable for unit-testing. */
+  private readonly dispatcher: IDispatcher;
+
+  /**
+   * Monotonically increasing step counter.
+   * Step 1 → first call in the session (triggers full snapshot in the DB).
+   * Step N → subsequent calls (store diff only).
+   */
+  private stepCounter = 0;
+
+  constructor(opts: TracerOptions, dispatcher?: IDispatcher) {
+    this.sessionId  = opts.sessionId ?? uuid();
+    this.metadata   = opts.metadata  ?? {};
+    this.enabled    = opts.enabled   ?? true;
+
+    // Use an injected dispatcher (useful in tests) or create the real one.
+    this.dispatcher = dispatcher ?? new Dispatcher({
+      ingestUrl:       opts.ingestUrl,
+      apiKey:    opts.apiKey,
+      timeoutMs:       opts.timeoutMs,
+      onError:         opts.onError
+        ? (err, payloads) => payloads.forEach((p) => opts.onError!(err, p))
+        : undefined,
+    });
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────────
+
+  /**
+   * The method called by every SDK wrapper after intercepting an LLM call.
+   *
+   * Design contract:
+   *   - NEVER awaited by the wrapper; fire-and-forget on microtask queue.
+   *   - Returns void so the wrapper cannot accidentally `await` it.
+   *
+   * @example
+   * // Inside wrappers/openai.ts — after receiving the result:
+   * tracer.captureAsync({ prompt, response, model, tokensIn, tokensOut, latencyMs, isStream });
+   */
+  captureAsync(raw: RawCapturePayload): void {
+    if (!this.enabled) return;
+
+    // Schedule enrichment + dispatch asynchronously so it never adds
+    // synchronous latency to the intercepted call path.
+    Promise.resolve().then(() => {
+      try {
+        const payload = this._enrich(raw);
+        this.dispatcher.send(payload);
+      } catch (err) {
+        // Tracer must NEVER throw into user code.
+        console.warn("[PromptTracer] Failed to enrich payload:", err);
+      }
+    });
+  }
+
+  /**
+   * Returns the step index the *next* call will be assigned.
+   * Useful for callers who need to know if this is step 1 (full snapshot)
+   * vs. a later step (diff only) before making the LLM call.
+   */
+  get nextStepIndex(): number {
+    return this.stepCounter + 1;
+  }
+
+  /**
+   * Waits for all buffered and in-flight payloads to be delivered.
+   * Call before process exit or at the end of integration tests.
+   *
+   * @example
+   * afterAll(async () => { await tracer.flush(); });
+   */
+  async flush(): Promise<void> {
+    await this.dispatcher.flush();
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Takes a raw capture from the wrapper and enriches it with:
+   *   - a unique callId
+   *   - the session's sessionId
+   *   - a monotonic stepIndex
+   *   - ISO-8601 timestamp
+   *   - USD cost estimate
+   *   - SDK version string
+   *   - caller metadata
+   */
+  private _enrich(raw: RawCapturePayload): TracePayload {
+    this.stepCounter += 1;
+
+    const estimatedCostUsd = calcCostUsd({
+      model:     raw.model,
+      tokensIn:  raw.tokensIn  ?? 0,
+      tokensOut: raw.tokensOut ?? 0,
+    });
+
+    return {
+      // ── Core identity ───────────────────────────────────────────────────
+      callId:     uuid(),
+      sessionId:  this.sessionId,
+      stepIndex:  this.stepCounter,
+      timestamp:  new Date().toISOString(),
+
+      // ── Raw capture data (passed through unchanged) ──────────────────────
+      ...raw,
+
+      // ── Enrichment ───────────────────────────────────────────────────────
+      estimatedCostUsd,
+      sdkVersion: SDK_VERSION,
+
+      // Merge metadata into the payload so the ingest API can index on it.
+      // We spread it flat; the ingest schema should have a metadata JSONB col.
+      ...(Object.keys(this.metadata).length > 0
+        ? { metadata: this.metadata }
+        : {}),
+    } as TracePayload;
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,73 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/sdk/src/core/types.ts
+// Central type contracts for the entire SDK. No runtime code lives here.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A single message in an OpenAI-compatible chat conversation. */
+export interface ChatMessage {
+  role: "system" | "user" | "assistant" | "tool" | "function";
+  content: string | null;
+  name?: string;
+  tool_call_id?: string;
+}
+
+/** Raw data captured at the intercept point, before any enrichment. */
+export interface RawCapturePayload {
+  /** The messages array sent to the model. */
+  prompt: ChatMessage[] | readonly ChatMessage[];
+  /** The text content of the completion (reconstructed for streams). */
+  response: string;
+  /** Model string exactly as passed by the caller e.g. "gpt-4o". */
+  model: string;
+  /** Prompt tokens from usage object. Undefined for streams (not available). */
+  tokensIn: number | undefined;
+  /** Completion tokens. For streams this is an approximation (chunk count). */
+  tokensOut: number | undefined;
+  /** Wall-clock ms from request start to last byte received. */
+  latencyMs: number;
+  /** Whether the call used server-sent streaming. */
+  isStream: boolean;
+}
+
+/** The fully enriched payload that gets pushed to the ingest queue. */
+export interface TracePayload extends RawCapturePayload {
+  /** SDK-generated UUID for this individual LLM call. */
+  callId: string;
+  /** Session/trace ID grouping multiple calls in one agent run.
+   *  Set via TracerOptions.sessionId or auto-generated per Tracer instance. */
+  sessionId: string;
+  /** Step index within the session (1-based, incremented per capture). */
+  stepIndex: number;
+  /** ISO-8601 timestamp of the call start. */
+  timestamp: string;
+  /** Estimated USD cost for this call. */
+  estimatedCostUsd: number;
+  /** Version string of the SDK emitting this payload. */
+  sdkVersion: string;
+}
+
+/** Options passed when constructing a Tracer instance. */
+export interface TracerOptions {
+  /** Full URL of your Next.js ingest endpoint.
+   *  e.g. "https://your-app.vercel.app/api/ingest" */
+  ingestUrl: string;
+  apiKey?: string;
+  /** Optional session ID to group multiple calls into one trace. If omitted,
+  /** Groups multiple LLM calls into one logical agent run.
+   *  Auto-generated (UUID v4) if omitted. */
+  sessionId?: string;
+  /** Attach arbitrary key/value metadata to every payload (e.g. userId, env). */
+  metadata?: Record<string, string>;
+  /** Max ms to wait for the ingest POST before aborting. Default: 5000. */
+  timeoutMs?: number;
+  /** Called when the ingest POST fails. Defaults to console.warn. */
+  onError?: (error: Error, payload: TracePayload) => void;
+  /** Set false to completely disable telemetry (e.g. in unit tests). Default: true */
+  enabled?: boolean;
+}
+
+/** Minimal interface the Dispatcher must satisfy — useful for testing. */
+export interface IDispatcher {
+  send(payload: TracePayload): void; // non-blocking fire-and-forget
+  flush(): Promise<void>;            // drain all pending sends (use in tests / shutdown)
+}

package/src/diff.ts

@@ -0,0 +1,181 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/sdk/src/utils/diff.ts
+//
+// Computes a minimal, git-style diff between two chat message arrays.
+// The ingest API uses this to decide what to store:
+//   - Step 1  → store full snapshot (no previous to diff against)
+//   - Step 2+ → store only the diff; reconstruct full array on the frontend
+//
+// Design goals:
+//   1. Deterministic — same inputs always produce same diff.
+//   2. Reversible — applyDiff(prev, computeDiff(prev, curr)) === curr
+//   3. Zero dependencies on the openai SDK — works with plain objects.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { ChatMessage } from "./core/types";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** A single entry in the diff — describes ONE message's change. */
+export type DiffOperation =
+  | { op: "add";    index: number; message: ChatMessage }
+  | { op: "remove"; index: number }
+  | { op: "keep";   index: number };   // kept for position bookkeeping
+
+/** The payload stored in prompt_snapshots.diff_from_previous */
+export interface MessageDiff {
+  /** Only the add/remove operations (keeps are omitted to save bytes). */
+  operations: Array<
+    | { op: "add";    index: number; message: ChatMessage }
+    | { op: "remove"; index: number }
+  >;
+  /** Net token change: positive = context grew, negative = messages pruned. */
+  tokenDelta: number;
+  /** How many messages were added in this step. */
+  added: number;
+  /** How many messages were removed in this step. */
+  removed: number;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Stable string key for a message — used for identity comparison.
+ * We hash role + content so order changes are detected correctly.
+ */
+function messageKey(m: ChatMessage): string {
+  return `${m.role}::${m.content ?? ""}`;
+}
+
+/**
+ * Rough token estimator — 1 token ≈ 4 characters (GPT rule of thumb).
+ * The SDK does not run a full tokenizer to stay dependency-free.
+ * The backend can re-calculate with tiktoken if needed.
+ */
+export function estimateTokens(messages: readonly ChatMessage[]): number {
+  return messages.reduce((sum, m) => {
+    const chars = (m.content ?? "").length;
+    return sum + Math.ceil(chars / 4);
+  }, 0);
+}
+
+// ── Core diff algorithm ───────────────────────────────────────────────────────
+
+/**
+ * Computes the minimal diff between `prev` and `curr` message arrays.
+ *
+ * Algorithm: O(n) two-pointer walk.
+ *   1. Build a Set of keys in `prev` for O(1) lookup.
+ *   2. Walk `curr` — any message not in `prev` is an ADD.
+ *   3. Walk `prev` — any message not in `curr` is a REMOVE.
+ *
+ * This is sufficient for 99% of real agent patterns where the context
+ * array only ever has messages appended (never reordered mid-stream).
+ * For adversarial reordering, swap to Myers diff.
+ *
+ * @example
+ * const diff = computeMessageDiff(step1Messages, step2Messages);
+ * // { operations: [{ op: "add", index: 3, message: {...} }], tokenDelta: 42, added: 1, removed: 0 }
+ */
+export function computeMessageDiff(
+  prev: readonly ChatMessage[],
+  curr: readonly ChatMessage[]
+): MessageDiff {
+  const prevKeys = new Set(prev.map(messageKey));
+  const currKeys = new Set(curr.map(messageKey));
+
+  const operations: MessageDiff["operations"] = [];
+
+  // Detect additions — messages in curr that weren't in prev
+  curr.forEach((message, index) => {
+    if (!prevKeys.has(messageKey(message))) {
+      operations.push({ op: "add", index, message });
+    }
+  });
+
+  // Detect removals — messages in prev that aren't in curr
+  prev.forEach((message, index) => {
+    if (!currKeys.has(messageKey(message))) {
+      operations.push({ op: "remove", index });
+    }
+  });
+
+  const tokenDelta =
+    estimateTokens(curr) - estimateTokens(prev);
+
+  return {
+    operations,
+    tokenDelta,
+    added:   operations.filter((o) => o.op === "add").length,
+    removed: operations.filter((o) => o.op === "remove").length,
+  };
+}
+
+// ── Reconstruction (used by the frontend to replay diffs) ─────────────────────
+
+/**
+ * Applies a stored diff forward onto a base message array.
+ * The frontend calls this to reconstruct the full message array for step N:
+ *
+ *   const step1 = fullSnapshot;           // stored in DB for step 1
+ *   const step2 = applyDiff(step1, diff); // reconstructed from diff
+ *   const step3 = applyDiff(step2, diff); // and so on...
+ *
+ * @throws {Error} if the diff references an out-of-bounds index.
+ */
+export function applyDiff(
+  base: readonly ChatMessage[],
+  diff: MessageDiff
+): ChatMessage[] {
+  const result = [...base];
+
+  // Process removes first (high-index first to avoid index shifting)
+  const removes = diff.operations
+    .filter((o): o is { op: "remove"; index: number } => o.op === "remove")
+    .sort((a, b) => b.index - a.index);
+
+  for (const op of removes) {
+    if (op.index >= result.length) {
+      throw new Error(
+        `[PromptTracer] applyDiff: remove index ${op.index} out of bounds (len=${result.length})`
+      );
+    }
+    result.splice(op.index, 1);
+  }
+
+  // Process adds (low-index first to preserve insertion order)
+  const adds = diff.operations
+    .filter(
+      (o): o is { op: "add"; index: number; message: ChatMessage } =>
+        o.op === "add"
+    )
+    .sort((a, b) => a.index - b.index);
+
+  for (const op of adds) {
+    result.splice(op.index, 0, op.message);
+  }
+
+  return result;
+}
+
+/**
+ * Replays an ordered series of diffs from a base snapshot.
+ * Use this when you need to reconstruct every step in a session at once.
+ *
+ * @example
+ * const steps = replayDiffs(step1Snapshot, [diff2, diff3, diff4]);
+ * // steps[0] === step1, steps[1] === step2, steps[2] === step3, steps[3] === step4
+ */
+export function replayDiffs(
+  baseSnapshot: readonly ChatMessage[],
+  diffs: MessageDiff[]
+): ChatMessage[][] {
+  const results: ChatMessage[][] = [Array.from(baseSnapshot)];
+
+  for (const diff of diffs) {
+    const prev = results[results.length - 1];
+    results.push(applyDiff(prev, diff));
+  }
+
+  return results;
+}

package/src/index.ts

@@ -1,37 +1,24 @@
-export interface TracePayload {
-  sessionId: string;
-  stepIndex: number;
-  model: string;
-  messages: any[];
-  latencyMs: number;
-  tokensIn: number;
-  tokensOut: number;
-  estimatedCostUsd: number;
-  isStream?: boolean;
-}
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/sdk/src/index.ts
+// Public surface of the @prompt-tracer/sdk package.
+// ─────────────────────────────────────────────────────────────────────────────
 
+// Core
+export { Tracer }          from "./core/tracer";
+export { Dispatcher }      from "./core/dispatcher";
 
-// Import process for Node.js type support
+// Wrappers
+export { wrapOpenAI }      from "./wrappers/openai";
 
-export async function traceLlmCall(payload: TracePayload) {
-  const redisUrl = process.env.UPSTASH_REDIS_REST_URL;
-  const redisToken = process.env.UPSTASH_REDIS_REST_TOKEN;
+// Utilities
+export { calcCostUsd, formatCostUsd } from "./utils/cost";
 
-  if (!redisUrl || !redisToken) return;
-
-  try {
-    fetch(`${redisUrl}/lpush/0xtrace_queue`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${redisToken}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        ...payload,
-        timestamp: new Date().toISOString(),
-      }),
-    }).catch((e) => console.error(e));
-  } catch (error) {
-    console.error(error);
-  }
-}
+// Types — consumers can import these without `import type` gymnastics
+export type {
+  ChatMessage,
+  RawCapturePayload,
+  TracePayload,
+  TracerOptions,
+  IDispatcher,
+} from "./core/types";
+export type { DispatcherOptions } from "./core/dispatcher";

package/src/utils/cost.ts

@@ -0,0 +1,104 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/sdk/src/utils/cost.ts
+//
+// Calculates estimated USD cost for a single LLM call.
+// Prices are per 1 million tokens (as published by each provider).
+// Update MODEL_PRICES when providers change pricing.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface ModelPrice {
+  /** USD per 1M input tokens  */
+  inputPer1M:  number;
+  /** USD per 1M output tokens */
+  outputPer1M: number;
+}
+
+/**
+ * Pricing table keyed by model string.
+ * Keys are matched with startsWith() so "gpt-4o-mini-2024-07-18" resolves
+ * to the "gpt-4o-mini" entry automatically.
+ */
+const MODEL_PRICES: Record<string, ModelPrice> = {
+  // ── OpenAI ──────────────────────────────────────────────────────────────
+  "gpt-4o":                   { inputPer1M:  2.50, outputPer1M: 10.00 },
+  "gpt-4o-mini":              { inputPer1M:  0.15, outputPer1M:  0.60 },
+  "gpt-4-turbo":              { inputPer1M: 10.00, outputPer1M: 30.00 },
+  "gpt-4":                    { inputPer1M: 30.00, outputPer1M: 60.00 },
+  "gpt-3.5-turbo":            { inputPer1M:  0.50, outputPer1M:  1.50 },
+  "o1":                       { inputPer1M: 15.00, outputPer1M: 60.00 },
+  "o1-mini":                  { inputPer1M:  3.00, outputPer1M: 12.00 },
+  "o3-mini":                  { inputPer1M:  1.10, outputPer1M:  4.40 },
+
+  // ── Anthropic ───────────────────────────────────────────────────────────
+  "claude-opus-4":            { inputPer1M: 15.00, outputPer1M: 75.00 },
+  "claude-sonnet-4":          { inputPer1M:  3.00, outputPer1M: 15.00 },
+  "claude-haiku-4":           { inputPer1M:  0.80, outputPer1M:  4.00 },
+  "claude-3-5-sonnet":        { inputPer1M:  3.00, outputPer1M: 15.00 },
+  "claude-3-5-haiku":         { inputPer1M:  0.80, outputPer1M:  4.00 },
+  "claude-3-opus":            { inputPer1M: 15.00, outputPer1M: 75.00 },
+
+  // ── Google ──────────────────────────────────────────────────────────────
+  "gemini-1.5-pro":           { inputPer1M:  3.50, outputPer1M: 10.50 },
+  "gemini-1.5-flash":         { inputPer1M:  0.35, outputPer1M:  1.05 },
+  "gemini-2.0-flash":         { inputPer1M:  0.10, outputPer1M:  0.40 },
+};
+
+/** Fallback when the model string is unrecognised. */
+const UNKNOWN_PRICE: ModelPrice = { inputPer1M: 0, outputPer1M: 0 };
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Resolves a model string to its price entry.
+ * Tries exact match first, then prefix match (handles dated model variants).
+ */
+function resolvePrice(model: string): ModelPrice {
+  const normalised = model.toLowerCase().trim();
+
+  // 1. Exact match
+  if (normalised in MODEL_PRICES) return MODEL_PRICES[normalised];
+
+  // 2. Prefix match — e.g. "gpt-4o-2024-11-20" → "gpt-4o"
+  for (const key of Object.keys(MODEL_PRICES)) {
+    if (normalised.startsWith(key)) return MODEL_PRICES[key];
+  }
+
+  return UNKNOWN_PRICE;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+export interface CalcCostParams {
+  model:     string;
+  tokensIn:  number;
+  tokensOut: number;
+}
+
+/**
+ * Returns the estimated USD cost for a single LLM call.
+ * Returns 0 for unrecognised models rather than throwing, so the SDK
+ * never crashes user code due to a missing pricing entry.
+ *
+ * @example
+ * calcCostUsd({ model: "gpt-4o", tokensIn: 1000, tokensOut: 500 })
+ * // → 0.00750
+ */
+export function calcCostUsd({ model, tokensIn, tokensOut }: CalcCostParams): number {
+  const price = resolvePrice(model);
+  const inputCost  = (tokensIn  / 1_000_000) * price.inputPer1M;
+  const outputCost = (tokensOut / 1_000_000) * price.outputPer1M;
+  // Round to 8 decimal places to avoid floating-point noise in the DB.
+  return Math.round((inputCost + outputCost) * 1e8) / 1e8;
+}
+
+/**
+ * Formats a USD cost as a human-readable string.
+ * @example formatCost(0.0075) → "$0.0075"
+ * @example formatCost(0.00000120) → "$0.0000012"
+ */
+export function formatCostUsd(usd: number): string {
+  if (usd === 0) return "$0.00";
+  if (usd < 0.0001) return `$${usd.toFixed(8).replace(/0+$/, "")}`;
+  if (usd < 0.01)   return `$${usd.toFixed(6).replace(/0+$/, "")}`;
+  return `$${usd.toFixed(4)}`;
+}