@fallom/trace 0.1.6 → 0.1.10

package/README.md

@@ -226,7 +226,9 @@ trace.span({
 
 ```bash
 FALLOM_API_KEY=your-api-key
-FALLOM_BASE_URL=https://spans.fallom.com
+FALLOM_TRACES_URL=https://traces.fallom.com
+FALLOM_CONFIGS_URL=https://configs.fallom.com
+FALLOM_PROMPTS_URL=https://prompts.fallom.com
 FALLOM_CAPTURE_CONTENT=true  # set to "false" for privacy mode
 ```
 

package/dist/chunk-6MSTRIK4.mjs

@@ -0,0 +1,255 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/prompts.ts
+var prompts_exports = {};
+__export(prompts_exports, {
+  clearPromptContext: () => clearPromptContext,
+  get: () => get,
+  getAB: () => getAB,
+  getPromptContext: () => getPromptContext,
+  init: () => init
+});
+import { createHash } from "crypto";
+var apiKey = null;
+var baseUrl = "https://prompts.fallom.com";
+var initialized = false;
+var syncInterval = null;
+var debugMode = false;
+var promptCache = /* @__PURE__ */ new Map();
+var promptABCache = /* @__PURE__ */ new Map();
+var promptContext = null;
+var SYNC_TIMEOUT = 2e3;
+function log(msg) {
+  if (debugMode) {
+    console.log(`[Fallom Prompts] ${msg}`);
+  }
+}
+function init(options = {}) {
+  apiKey = options.apiKey || process.env.FALLOM_API_KEY || null;
+  baseUrl = options.baseUrl || process.env.FALLOM_PROMPTS_URL || process.env.FALLOM_BASE_URL || "https://prompts.fallom.com";
+  initialized = true;
+  if (!apiKey) {
+    return;
+  }
+  fetchAll().catch(() => {
+  });
+  if (!syncInterval) {
+    syncInterval = setInterval(() => {
+      fetchAll().catch(() => {
+      });
+    }, 3e4);
+    syncInterval.unref();
+  }
+}
+function ensureInit() {
+  if (!initialized) {
+    try {
+      init();
+    } catch {
+    }
+  }
+}
+async function fetchAll() {
+  await Promise.all([fetchPrompts(), fetchPromptABTests()]);
+}
+async function fetchPrompts(timeout = SYNC_TIMEOUT) {
+  if (!apiKey) return;
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const resp = await fetch(`${baseUrl}/prompts`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (resp.ok) {
+      const data = await resp.json();
+      for (const p of data.prompts || []) {
+        if (!promptCache.has(p.key)) {
+          promptCache.set(p.key, { versions: /* @__PURE__ */ new Map(), current: null });
+        }
+        const cached = promptCache.get(p.key);
+        cached.versions.set(p.version, {
+          systemPrompt: p.system_prompt,
+          userTemplate: p.user_template
+        });
+        cached.current = p.version;
+      }
+    }
+  } catch {
+  }
+}
+async function fetchPromptABTests(timeout = SYNC_TIMEOUT) {
+  if (!apiKey) return;
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const resp = await fetch(`${baseUrl}/prompt-ab-tests`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (resp.ok) {
+      const data = await resp.json();
+      for (const t of data.prompt_ab_tests || []) {
+        if (!promptABCache.has(t.key)) {
+          promptABCache.set(t.key, { versions: /* @__PURE__ */ new Map(), current: null });
+        }
+        const cached = promptABCache.get(t.key);
+        cached.versions.set(t.version, { variants: t.variants });
+        cached.current = t.version;
+      }
+    }
+  } catch {
+  }
+}
+function replaceVariables(template, variables) {
+  if (!variables) return template;
+  return template.replace(/\{\{(\s*\w+\s*)\}\}/g, (match, varName) => {
+    const key = varName.trim();
+    return key in variables ? String(variables[key]) : match;
+  });
+}
+function setPromptContext(ctx) {
+  promptContext = ctx;
+}
+function getPromptContext() {
+  const ctx = promptContext;
+  promptContext = null;
+  return ctx;
+}
+async function get(promptKey, options = {}) {
+  const { variables, version, debug = false } = options;
+  debugMode = debug;
+  ensureInit();
+  log(`get() called: promptKey=${promptKey}`);
+  let promptData = promptCache.get(promptKey);
+  if (!promptData) {
+    log("Not in cache, fetching...");
+    await fetchPrompts(SYNC_TIMEOUT);
+    promptData = promptCache.get(promptKey);
+  }
+  if (!promptData) {
+    throw new Error(
+      `Prompt '${promptKey}' not found. Check that it exists in your Fallom dashboard.`
+    );
+  }
+  const targetVersion = version ?? promptData.current;
+  const content = promptData.versions.get(targetVersion);
+  if (!content) {
+    throw new Error(
+      `Prompt '${promptKey}' version ${targetVersion} not found.`
+    );
+  }
+  const system = replaceVariables(content.systemPrompt, variables);
+  const user = replaceVariables(content.userTemplate, variables);
+  setPromptContext({
+    promptKey,
+    promptVersion: targetVersion
+  });
+  log(`\u2705 Got prompt: ${promptKey} v${targetVersion}`);
+  return {
+    key: promptKey,
+    version: targetVersion,
+    system,
+    user
+  };
+}
+async function getAB(abTestKey, sessionId, options = {}) {
+  const { variables, debug = false } = options;
+  debugMode = debug;
+  ensureInit();
+  log(`getAB() called: abTestKey=${abTestKey}, sessionId=${sessionId}`);
+  let abData = promptABCache.get(abTestKey);
+  if (!abData) {
+    log("Not in cache, fetching...");
+    await fetchPromptABTests(SYNC_TIMEOUT);
+    abData = promptABCache.get(abTestKey);
+  }
+  if (!abData) {
+    throw new Error(
+      `Prompt A/B test '${abTestKey}' not found. Check that it exists in your Fallom dashboard.`
+    );
+  }
+  const currentVersion = abData.current;
+  const versionData = abData.versions.get(currentVersion);
+  if (!versionData) {
+    throw new Error(`Prompt A/B test '${abTestKey}' has no current version.`);
+  }
+  const { variants } = versionData;
+  log(`A/B test '${abTestKey}' has ${variants?.length ?? 0} variants`);
+  log(`Version data: ${JSON.stringify(versionData, null, 2)}`);
+  if (!variants || variants.length === 0) {
+    throw new Error(
+      `Prompt A/B test '${abTestKey}' has no variants configured.`
+    );
+  }
+  const hashBytes = createHash("md5").update(sessionId).digest();
+  const hashVal = hashBytes.readUInt32BE(0) % 1e6;
+  let cumulative = 0;
+  let selectedVariant = variants[variants.length - 1];
+  let selectedIndex = variants.length - 1;
+  for (let i = 0; i < variants.length; i++) {
+    cumulative += variants[i].weight * 1e4;
+    if (hashVal < cumulative) {
+      selectedVariant = variants[i];
+      selectedIndex = i;
+      break;
+    }
+  }
+  const promptKey = selectedVariant.prompt_key;
+  const promptVersion = selectedVariant.prompt_version;
+  let promptData = promptCache.get(promptKey);
+  if (!promptData) {
+    await fetchPrompts(SYNC_TIMEOUT);
+    promptData = promptCache.get(promptKey);
+  }
+  if (!promptData) {
+    throw new Error(
+      `Prompt '${promptKey}' (from A/B test '${abTestKey}') not found.`
+    );
+  }
+  const targetVersion = promptVersion ?? promptData.current;
+  const content = promptData.versions.get(targetVersion);
+  if (!content) {
+    throw new Error(
+      `Prompt '${promptKey}' version ${targetVersion} not found.`
+    );
+  }
+  const system = replaceVariables(content.systemPrompt, variables);
+  const user = replaceVariables(content.userTemplate, variables);
+  setPromptContext({
+    promptKey,
+    promptVersion: targetVersion,
+    abTestKey,
+    variantIndex: selectedIndex
+  });
+  log(
+    `\u2705 Got prompt from A/B: ${promptKey} v${targetVersion} (variant ${selectedIndex})`
+  );
+  return {
+    key: promptKey,
+    version: targetVersion,
+    system,
+    user,
+    abTestKey,
+    variantIndex: selectedIndex
+  };
+}
+function clearPromptContext() {
+  promptContext = null;
+}
+
+export {
+  __export,
+  init,
+  getPromptContext,
+  get,
+  getAB,
+  clearPromptContext,
+  prompts_exports
+};

package/dist/chunk-H2EACSBT.mjs

@@ -0,0 +1,255 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/prompts.ts
+var prompts_exports = {};
+__export(prompts_exports, {
+  clearPromptContext: () => clearPromptContext,
+  get: () => get,
+  getAB: () => getAB,
+  getPromptContext: () => getPromptContext,
+  init: () => init
+});
+import { createHash } from "crypto";
+var apiKey = null;
+var baseUrl = "https://prompts.fallom.com";
+var initialized = false;
+var syncInterval = null;
+var debugMode = false;
+var promptCache = /* @__PURE__ */ new Map();
+var promptABCache = /* @__PURE__ */ new Map();
+var promptContext = null;
+var SYNC_TIMEOUT = 2e3;
+function log(msg) {
+  if (debugMode) {
+    console.log(`[Fallom Prompts] ${msg}`);
+  }
+}
+function init(options = {}) {
+  apiKey = options.apiKey || process.env.FALLOM_API_KEY || null;
+  baseUrl = options.baseUrl || process.env.FALLOM_PROMPTS_URL || process.env.FALLOM_BASE_URL || "https://prompts.fallom.com";
+  initialized = true;
+  if (!apiKey) {
+    return;
+  }
+  fetchAll().catch(() => {
+  });
+  if (!syncInterval) {
+    syncInterval = setInterval(() => {
+      fetchAll().catch(() => {
+      });
+    }, 3e4);
+    syncInterval.unref();
+  }
+}
+function ensureInit() {
+  if (!initialized) {
+    try {
+      init();
+    } catch {
+    }
+  }
+}
+async function fetchAll() {
+  await Promise.all([fetchPrompts(), fetchPromptABTests()]);
+}
+async function fetchPrompts(timeout = SYNC_TIMEOUT) {
+  if (!apiKey) return;
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const resp = await fetch(`${baseUrl}/prompts`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (resp.ok) {
+      const data = await resp.json();
+      for (const p of data.prompts || []) {
+        if (!promptCache.has(p.key)) {
+          promptCache.set(p.key, { versions: /* @__PURE__ */ new Map(), current: null });
+        }
+        const cached = promptCache.get(p.key);
+        cached.versions.set(p.version, {
+          systemPrompt: p.system_prompt,
+          userTemplate: p.user_template
+        });
+        cached.current = p.version;
+      }
+    }
+  } catch {
+  }
+}
+async function fetchPromptABTests(timeout = SYNC_TIMEOUT) {
+  if (!apiKey) return;
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const resp = await fetch(`${baseUrl}/prompt-ab-tests`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (resp.ok) {
+      const data = await resp.json();
+      for (const t of data.prompt_ab_tests || []) {
+        if (!promptABCache.has(t.key)) {
+          promptABCache.set(t.key, { versions: /* @__PURE__ */ new Map(), current: null });
+        }
+        const cached = promptABCache.get(t.key);
+        cached.versions.set(t.version, { variants: t.variants });
+        cached.current = t.version;
+      }
+    }
+  } catch {
+  }
+}
+function replaceVariables(template, variables) {
+  if (!variables) return template;
+  return template.replace(/\{\{(\s*\w+\s*)\}\}/g, (match, varName) => {
+    const key = varName.trim();
+    return key in variables ? String(variables[key]) : match;
+  });
+}
+function setPromptContext(ctx) {
+  promptContext = ctx;
+}
+function getPromptContext() {
+  const ctx = promptContext;
+  promptContext = null;
+  return ctx;
+}
+async function get(promptKey, options = {}) {
+  const { variables, version, debug = false } = options;
+  debugMode = debug;
+  ensureInit();
+  log(`get() called: promptKey=${promptKey}`);
+  let promptData = promptCache.get(promptKey);
+  if (!promptData) {
+    log("Not in cache, fetching...");
+    await fetchPrompts(SYNC_TIMEOUT);
+    promptData = promptCache.get(promptKey);
+  }
+  if (!promptData) {
+    throw new Error(
+      `Prompt '${promptKey}' not found. Check that it exists in your Fallom dashboard.`
+    );
+  }
+  const targetVersion = version ?? promptData.current;
+  const content = promptData.versions.get(targetVersion);
+  if (!content) {
+    throw new Error(
+      `Prompt '${promptKey}' version ${targetVersion} not found.`
+    );
+  }
+  const system = replaceVariables(content.systemPrompt, variables);
+  const user = replaceVariables(content.userTemplate, variables);
+  setPromptContext({
+    promptKey,
+    promptVersion: targetVersion
+  });
+  log(`\u2705 Got prompt: ${promptKey} v${targetVersion}`);
+  return {
+    key: promptKey,
+    version: targetVersion,
+    system,
+    user
+  };
+}
+async function getAB(abTestKey, sessionId, options = {}) {
+  const { variables, debug = false } = options;
+  debugMode = debug;
+  ensureInit();
+  log(`getAB() called: abTestKey=${abTestKey}, sessionId=${sessionId}`);
+  let abData = promptABCache.get(abTestKey);
+  if (!abData) {
+    log("Not in cache, fetching...");
+    await fetchPromptABTests(SYNC_TIMEOUT);
+    abData = promptABCache.get(abTestKey);
+  }
+  if (!abData) {
+    throw new Error(
+      `Prompt A/B test '${abTestKey}' not found. Check that it exists in your Fallom dashboard.`
+    );
+  }
+  const currentVersion = abData.current;
+  const versionData = abData.versions.get(currentVersion);
+  if (!versionData) {
+    throw new Error(`Prompt A/B test '${abTestKey}' has no current version.`);
+  }
+  const { variants } = versionData;
+  log(`A/B test '${abTestKey}' has ${variants?.length ?? 0} variants`);
+  log(`Version data:`, JSON.stringify(versionData, null, 2));
+  if (!variants || variants.length === 0) {
+    throw new Error(
+      `Prompt A/B test '${abTestKey}' has no variants configured.`
+    );
+  }
+  const hashBytes = createHash("md5").update(sessionId).digest();
+  const hashVal = hashBytes.readUInt32BE(0) % 1e6;
+  let cumulative = 0;
+  let selectedVariant = variants[variants.length - 1];
+  let selectedIndex = variants.length - 1;
+  for (let i = 0; i < variants.length; i++) {
+    cumulative += variants[i].weight * 1e4;
+    if (hashVal < cumulative) {
+      selectedVariant = variants[i];
+      selectedIndex = i;
+      break;
+    }
+  }
+  const promptKey = selectedVariant.prompt_key;
+  const promptVersion = selectedVariant.prompt_version;
+  let promptData = promptCache.get(promptKey);
+  if (!promptData) {
+    await fetchPrompts(SYNC_TIMEOUT);
+    promptData = promptCache.get(promptKey);
+  }
+  if (!promptData) {
+    throw new Error(
+      `Prompt '${promptKey}' (from A/B test '${abTestKey}') not found.`
+    );
+  }
+  const targetVersion = promptVersion ?? promptData.current;
+  const content = promptData.versions.get(targetVersion);
+  if (!content) {
+    throw new Error(
+      `Prompt '${promptKey}' version ${targetVersion} not found.`
+    );
+  }
+  const system = replaceVariables(content.systemPrompt, variables);
+  const user = replaceVariables(content.userTemplate, variables);
+  setPromptContext({
+    promptKey,
+    promptVersion: targetVersion,
+    abTestKey,
+    variantIndex: selectedIndex
+  });
+  log(
+    `\u2705 Got prompt from A/B: ${promptKey} v${targetVersion} (variant ${selectedIndex})`
+  );
+  return {
+    key: promptKey,
+    version: targetVersion,
+    system,
+    user,
+    abTestKey,
+    variantIndex: selectedIndex
+  };
+}
+function clearPromptContext() {
+  promptContext = null;
+}
+
+export {
+  __export,
+  init,
+  getPromptContext,
+  get,
+  getAB,
+  clearPromptContext,
+  prompts_exports
+};

package/dist/index.d.mts

@@ -183,6 +183,45 @@ declare function wrapAnthropic<T extends {
 declare function wrapGoogleAI<T extends {
     generateContent: (...args: any[]) => Promise<any>;
 }>(model: T): T;
+/**
+ * Wrap the Vercel AI SDK to automatically trace all LLM calls.
+ * Works with generateText, streamText, generateObject, streamObject.
+ *
+ * @param ai - The ai module (import * as ai from "ai")
+ * @returns Object with wrapped generateText, streamText, generateObject, streamObject
+ *
+ * @example
+ * ```typescript
+ * import * as ai from "ai";
+ * import { createOpenAI } from "@ai-sdk/openai";
+ * import { trace } from "@fallom/trace";
+ *
+ * await trace.init({ apiKey: process.env.FALLOM_API_KEY });
+ * const { generateText, streamText } = trace.wrapAISDK(ai);
+ *
+ * const openrouter = createOpenAI({
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ *   baseURL: "https://openrouter.ai/api/v1",
+ * });
+ *
+ * trace.setSession("my-config", sessionId);
+ * const { text } = await generateText({
+ *   model: openrouter("openai/gpt-4o-mini"),
+ *   prompt: "Hello!",
+ * }); // Automatically traced!
+ * ```
+ */
+declare function wrapAISDK<T extends {
+    generateText: (...args: any[]) => Promise<any>;
+    streamText: (...args: any[]) => any;
+    generateObject?: (...args: any[]) => Promise<any>;
+    streamObject?: (...args: any[]) => any;
+}>(ai: T): {
+    generateText: T["generateText"];
+    streamText: T["streamText"];
+    generateObject: T["generateObject"];
+    streamObject: T["streamObject"];
+};
 
 declare const trace_clearSession: typeof clearSession;
 declare const trace_getSession: typeof getSession;
@@ -190,11 +229,12 @@ declare const trace_runWithSession: typeof runWithSession;
 declare const trace_setSession: typeof setSession;
 declare const trace_shutdown: typeof shutdown;
 declare const trace_span: typeof span;
+declare const trace_wrapAISDK: typeof wrapAISDK;
 declare const trace_wrapAnthropic: typeof wrapAnthropic;
 declare const trace_wrapGoogleAI: typeof wrapGoogleAI;
 declare const trace_wrapOpenAI: typeof wrapOpenAI;
 declare namespace trace {
-  export { trace_clearSession as clearSession, trace_getSession as getSession, init$3 as init, trace_runWithSession as runWithSession, trace_setSession as setSession, trace_shutdown as shutdown, trace_span as span, trace_wrapAnthropic as wrapAnthropic, trace_wrapGoogleAI as wrapGoogleAI, trace_wrapOpenAI as wrapOpenAI };
+  export { trace_clearSession as clearSession, trace_getSession as getSession, init$3 as init, trace_runWithSession as runWithSession, trace_setSession as setSession, trace_shutdown as shutdown, trace_span as span, trace_wrapAISDK as wrapAISDK, trace_wrapAnthropic as wrapAnthropic, trace_wrapGoogleAI as wrapGoogleAI, trace_wrapOpenAI as wrapOpenAI };
 }
 
 /**
@@ -368,16 +408,20 @@ declare namespace prompts {
  */
 interface InitOptions {
     apiKey?: string;
-    baseUrl?: string;
+    tracesUrl?: string;
+    configsUrl?: string;
+    promptsUrl?: string;
     captureContent?: boolean;
     debug?: boolean;
 }
 /**
- * Initialize both trace and models at once.
+ * Initialize trace, models, and prompts at once.
  *
  * @param options - Configuration options
  * @param options.apiKey - Your Fallom API key. Defaults to FALLOM_API_KEY env var.
- * @param options.baseUrl - API base URL. Defaults to FALLOM_BASE_URL or https://spans.fallom.com
+ * @param options.tracesUrl - Traces API URL. Defaults to FALLOM_TRACES_URL or https://traces.fallom.com
+ * @param options.configsUrl - Configs API URL. Defaults to FALLOM_CONFIGS_URL or https://configs.fallom.com
+ * @param options.promptsUrl - Prompts API URL. Defaults to FALLOM_PROMPTS_URL or https://prompts.fallom.com
  * @param options.captureContent - Whether to capture prompt/completion content (default: true)
  *
  * @example
@@ -388,7 +432,11 @@ interface InitOptions {
  * fallom.init({ apiKey: "your-api-key" });
  *
  * // Local development
- * fallom.init({ baseUrl: "http://localhost:8001" });
+ * fallom.init({
+ *   tracesUrl: "http://localhost:3002",
+ *   configsUrl: "http://localhost:3003",
+ *   promptsUrl: "http://localhost:3004"
+ * });
  *
  * // Privacy mode
  * fallom.init({ captureContent: false });