@fallom/trace 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # @fallom/trace
 
-Model A/B testing and tracing for LLM applications. Zero latency, production-ready.
+Model A/B testing, prompt management, and tracing for LLM applications. Zero latency, production-ready.
 
 ## Installation
 
@@ -52,6 +52,82 @@ const model = await models.get("my-config", sessionId, {
 });
 ```
 
+## Prompt Management
+
+Manage prompts centrally and A/B test them with zero latency.
+
+### Basic Prompt Retrieval
+
+```typescript
+import { prompts } from "@fallom/trace";
+
+// Get a managed prompt (with template variables)
+const prompt = await prompts.get("onboarding", {
+  variables: { userName: "John", company: "Acme" },
+});
+
+// Use the prompt with any LLM
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [
+    { role: "system", content: prompt.system },
+    { role: "user", content: prompt.user },
+  ],
+});
+```
+
+The `prompt` object contains:
+- `key`: The prompt key
+- `version`: The prompt version
+- `system`: The system prompt (with variables replaced)
+- `user`: The user template (with variables replaced)
+
+### Prompt A/B Testing
+
+Run experiments on different prompt versions:
+
+```typescript
+import { prompts } from "@fallom/trace";
+
+// Get prompt from A/B test (sticky assignment based on sessionId)
+const prompt = await prompts.getAB("onboarding-test", sessionId, {
+  variables: { userName: "John" },
+});
+
+// prompt.abTestKey and prompt.variantIndex are set
+// for analytics in your dashboard
+```
+
+### Version Pinning
+
+```typescript
+// Use latest version (default)
+const prompt = await prompts.get("my-prompt");
+
+// Pin to specific version
+const prompt = await prompts.get("my-prompt", { version: 2 });
+```
+
+### Automatic Trace Tagging
+
+When you call `prompts.get()` or `prompts.getAB()`, the next LLM call is automatically tagged with the prompt information. This allows you to see which prompts are used in your traces without any extra code.
+
+```typescript
+// Get prompt - sets up auto-tagging for next LLM call
+const prompt = await prompts.get("onboarding", {
+  variables: { userName: "John" },
+});
+
+// This call is automatically tagged with promptKey, promptVersion, etc.
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [
+    { role: "system", content: prompt.system },
+    { role: "user", content: prompt.user },
+  ],
+});
+```
+
 ## Tracing
 
 Wrap your LLM client once, all calls are automatically traced.
@@ -128,6 +204,7 @@ For each LLM call, Fallom automatically captures:
 - ✅ Input/output content (can be disabled)
 - ✅ Errors
 - ✅ Config key + session ID (for A/B analysis)
+- ✅ Prompt key + version (when using prompt management)
 
 ## Custom Metrics
 
@@ -187,10 +264,52 @@ Set session context for tracing.
 
 Get model assignment for A/B testing. Returns `Promise<string>`.
 
+### `fallom.prompts.get(promptKey, options?)`
+
+Get a managed prompt. Returns `Promise<PromptResult>`.
+- `promptKey`: Your prompt key from the dashboard
+- `options.variables`: Template variables (e.g., `{ userName: "John" }`)
+- `options.version`: Pin to specific version (default: latest)
+
+### `fallom.prompts.getAB(abTestKey, sessionId, options?)`
+
+Get a prompt from an A/B test. Returns `Promise<PromptResult>`.
+- `abTestKey`: Your A/B test key from the dashboard
+- `sessionId`: Session ID for sticky assignment
+- `options.variables`: Template variables
+
 ### `fallom.trace.span(data)`
 
 Record custom business metrics.
 
+## Testing
+
+Run the test suite:
+
+```bash
+cd sdk/typescript-sdk
+npm install
+npm test
+```
+
+## Deploying
+
+To publish a new version to npm:
+
+```bash
+cd sdk/typescript-sdk
+
+# Update version in package.json
+# Then:
+npm run build
+npm publish --access public
+
+# Or use convenience scripts:
+npm run publish:patch  # 0.1.0 -> 0.1.1
+npm run publish:minor  # 0.1.0 -> 0.2.0
+npm run publish:major  # 0.1.0 -> 1.0.0
+```
+
 ## Requirements
 
 - Node.js >= 18.0.0

package/dist/chunk-IGJD7GBO.mjs

@@ -0,0 +1,248 @@
+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://spans.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_BASE_URL || "https://spans.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;
+  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-VNUUS74T.mjs

@@ -0,0 +1,242 @@
+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://spans.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_BASE_URL || "https://spans.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;
+  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
+};