@fallom/trace 0.1.3 → 0.1.5

package/dist/index.d.mts

@@ -7,6 +7,7 @@
 interface SessionContext {
     configKey: string;
     sessionId: string;
+    customerId?: string;
 }
 /**
  * Initialize Fallom tracing. Auto-instruments all LLM calls.
@@ -32,7 +33,7 @@ interface SessionContext {
  * await agent.run(message); // Automatically traced
  * ```
  */
-declare function init$2(options?: {
+declare function init$3(options?: {
     apiKey?: string;
     baseUrl?: string;
     captureContent?: boolean;
@@ -42,34 +43,36 @@ declare function init$2(options?: {
  * Set the current session context.
  *
  * All subsequent LLM calls in this async context will be
- * automatically tagged with this configKey and sessionId.
+ * automatically tagged with this configKey, sessionId, and customerId.
  *
  * @param configKey - Your config name (e.g., "linkedin-agent")
  * @param sessionId - Your session/conversation ID
+ * @param customerId - Optional customer/user identifier for analytics
  *
  * @example
  * ```typescript
- * trace.setSession("linkedin-agent", sessionId);
- * await agent.run(message); // Automatically traced with session
+ * trace.setSession("linkedin-agent", sessionId, "user_123");
+ * await agent.run(message); // Automatically traced with session + customer
  * ```
  */
-declare function setSession(configKey: string, sessionId: string): void;
+declare function setSession(configKey: string, sessionId: string, customerId?: string): void;
 /**
  * Run a function with session context.
  * Use this to ensure session context propagates across async boundaries.
  *
  * @param configKey - Your config name
  * @param sessionId - Your session ID
+ * @param customerId - Optional customer/user identifier
  * @param fn - Function to run with session context
  *
  * @example
  * ```typescript
- * await trace.runWithSession("my-agent", sessionId, async () => {
+ * await trace.runWithSession("my-agent", sessionId, "user_123", async () => {
  *   await agent.run(message); // Has session context
  * });
  * ```
  */
-declare function runWithSession<T>(configKey: string, sessionId: string, fn: () => T): T;
+declare function runWithSession<T>(configKey: string, sessionId: string, customerIdOrFn: string | (() => T), fn?: () => T): T;
 /**
  * Get current session context, if any.
  */
@@ -191,7 +194,7 @@ 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$2 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_wrapAnthropic as wrapAnthropic, trace_wrapGoogleAI as wrapGoogleAI, trace_wrapOpenAI as wrapOpenAI };
 }
 
 /**
@@ -212,7 +215,7 @@ declare namespace trace {
  * This is optional - get() will auto-init if needed.
  * Non-blocking: starts background config fetch immediately.
  */
-declare function init$1(options?: {
+declare function init$2(options?: {
     apiKey?: string;
     baseUrl?: string;
 }): void;
@@ -236,19 +239,132 @@ declare function init$1(options?: {
  * @returns Model string (e.g., "claude-opus", "gpt-4o")
  * @throws Error if config not found AND no fallback provided
  */
-declare function get(configKey: string, sessionId: string, options?: {
+declare function get$1(configKey: string, sessionId: string, options?: {
     version?: number;
     fallback?: string;
     debug?: boolean;
 }): Promise<string>;
 
-declare const models_get: typeof get;
 declare namespace models {
-  export { models_get as get, init$1 as init };
+  export { get$1 as get, init$2 as init };
+}
+
+/**
+ * Fallom prompts module.
+ *
+ * Provides prompt management and A/B testing.
+ * Zero latency on get() - uses local cache + template interpolation.
+ *
+ * Design principles:
+ * - Never block user's app if Fallom is down
+ * - Very short timeouts (1-2 seconds max)
+ * - Always return usable prompt (or throw if not found)
+ * - Background sync keeps prompts fresh
+ * - Auto-tag next trace with prompt context
+ */
+interface PromptContext {
+    promptKey: string;
+    promptVersion: number;
+    abTestKey?: string;
+    variantIndex?: number;
+}
+/**
+ * Result from prompts.get() or prompts.getAB()
+ */
+interface PromptResult {
+    key: string;
+    version: number;
+    system: string;
+    user: string;
+    abTestKey?: string;
+    variantIndex?: number;
+}
+/**
+ * Initialize Fallom prompts.
+ * This is called automatically by fallom.init().
+ */
+declare function init$1(options?: {
+    apiKey?: string;
+    baseUrl?: string;
+}): void;
+/**
+ * Get and clear prompt context (one-shot).
+ */
+declare function getPromptContext(): PromptContext | null;
+/**
+ * Get a prompt (non-A/B).
+ *
+ * Zero latency - uses local cache + string interpolation.
+ * Also sets prompt context for next trace auto-tagging.
+ *
+ * @param promptKey - Your prompt key (e.g., "onboarding")
+ * @param options - Optional settings
+ * @param options.variables - Template variables (e.g., { userName: "John" })
+ * @param options.version - Pin to specific version. undefined = current
+ * @param options.debug - Enable debug logging
+ *
+ * @example
+ * ```typescript
+ * const prompt = await prompts.get("onboarding", {
+ *   variables: { userName: "John" }
+ * });
+ *
+ * // Use with OpenAI
+ * const response = await openai.chat.completions.create({
+ *   model,
+ *   messages: [
+ *     { role: "system", content: prompt.system },
+ *     { role: "user", content: prompt.user }
+ *   ]
+ * });
+ * ```
+ */
+declare function get(promptKey: string, options?: {
+    variables?: Record<string, unknown>;
+    version?: number;
+    debug?: boolean;
+}): Promise<PromptResult>;
+/**
+ * Get a prompt from an A/B test.
+ *
+ * Uses sessionId hash for deterministic, sticky assignment.
+ * Same session always gets same variant.
+ *
+ * Also sets prompt context for next trace auto-tagging.
+ *
+ * @param abTestKey - Your A/B test key (e.g., "onboarding-experiment")
+ * @param sessionId - Your session/conversation ID (for sticky assignment)
+ * @param options - Optional settings
+ * @param options.variables - Template variables
+ * @param options.debug - Enable debug logging
+ *
+ * @example
+ * ```typescript
+ * const prompt = await prompts.getAB("onboarding-test", sessionId, {
+ *   variables: { userName: "John" }
+ * });
+ * ```
+ */
+declare function getAB(abTestKey: string, sessionId: string, options?: {
+    variables?: Record<string, unknown>;
+    debug?: boolean;
+}): Promise<PromptResult>;
+/**
+ * Manually clear prompt context.
+ */
+declare function clearPromptContext(): void;
+
+type prompts_PromptResult = PromptResult;
+declare const prompts_clearPromptContext: typeof clearPromptContext;
+declare const prompts_get: typeof get;
+declare const prompts_getAB: typeof getAB;
+declare const prompts_getPromptContext: typeof getPromptContext;
+declare namespace prompts {
+  export { type prompts_PromptResult as PromptResult, prompts_clearPromptContext as clearPromptContext, prompts_get as get, prompts_getAB as getAB, prompts_getPromptContext as getPromptContext, init$1 as init };
 }
 
 /**
- * Combined initialization for both trace and models.
+ * Combined initialization for trace, models, and prompts.
  */
 interface InitOptions {
     apiKey?: string;
@@ -281,7 +397,7 @@ interface InitOptions {
 declare function init(options?: InitOptions): Promise<void>;
 
 /**
- * Fallom - Model A/B testing and tracing for LLM applications.
+ * Fallom - Model A/B testing, prompt management, and tracing for LLM applications.
  *
  * @example
  * ```typescript
@@ -298,10 +414,18 @@ declare function init(options?: InitOptions): Promise<void>;
  *   fallback: "gpt-4o-mini"
  * });
  *
+ * // Get managed prompts (with optional A/B testing)
+ * const prompt = await fallom.prompts.get("onboarding", {
+ *   variables: { userName: "John" }
+ * });
+ *
  * // Use with OpenAI
  * const response = await openai.chat.completions.create({
  *   model,
- *   messages: [...]
+ *   messages: [
+ *     { role: "system", content: prompt.system },
+ *     { role: "user", content: prompt.user }
+ *   ]
  * });
  *
  * // Record custom metrics
@@ -313,6 +437,7 @@ declare const _default: {
     init: typeof init;
     trace: typeof trace;
     models: typeof models;
+    prompts: typeof prompts;
 };
 
-export { type InitOptions, _default as default, init, models, trace };
+export { type InitOptions, type PromptResult, _default as default, init, models, prompts, trace };

package/dist/index.d.ts

@@ -7,6 +7,7 @@
 interface SessionContext {
     configKey: string;
     sessionId: string;
+    customerId?: string;
 }
 /**
  * Initialize Fallom tracing. Auto-instruments all LLM calls.
@@ -32,7 +33,7 @@ interface SessionContext {
  * await agent.run(message); // Automatically traced
  * ```
  */
-declare function init$2(options?: {
+declare function init$3(options?: {
     apiKey?: string;
     baseUrl?: string;
     captureContent?: boolean;
@@ -42,34 +43,36 @@ declare function init$2(options?: {
  * Set the current session context.
  *
  * All subsequent LLM calls in this async context will be
- * automatically tagged with this configKey and sessionId.
+ * automatically tagged with this configKey, sessionId, and customerId.
  *
  * @param configKey - Your config name (e.g., "linkedin-agent")
  * @param sessionId - Your session/conversation ID
+ * @param customerId - Optional customer/user identifier for analytics
  *
  * @example
  * ```typescript
- * trace.setSession("linkedin-agent", sessionId);
- * await agent.run(message); // Automatically traced with session
+ * trace.setSession("linkedin-agent", sessionId, "user_123");
+ * await agent.run(message); // Automatically traced with session + customer
  * ```
  */
-declare function setSession(configKey: string, sessionId: string): void;
+declare function setSession(configKey: string, sessionId: string, customerId?: string): void;
 /**
  * Run a function with session context.
  * Use this to ensure session context propagates across async boundaries.
  *
  * @param configKey - Your config name
  * @param sessionId - Your session ID
+ * @param customerId - Optional customer/user identifier
  * @param fn - Function to run with session context
  *
  * @example
  * ```typescript
- * await trace.runWithSession("my-agent", sessionId, async () => {
+ * await trace.runWithSession("my-agent", sessionId, "user_123", async () => {
  *   await agent.run(message); // Has session context
  * });
  * ```
  */
-declare function runWithSession<T>(configKey: string, sessionId: string, fn: () => T): T;
+declare function runWithSession<T>(configKey: string, sessionId: string, customerIdOrFn: string | (() => T), fn?: () => T): T;
 /**
  * Get current session context, if any.
  */
@@ -191,7 +194,7 @@ 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$2 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_wrapAnthropic as wrapAnthropic, trace_wrapGoogleAI as wrapGoogleAI, trace_wrapOpenAI as wrapOpenAI };
 }
 
 /**
@@ -212,7 +215,7 @@ declare namespace trace {
  * This is optional - get() will auto-init if needed.
  * Non-blocking: starts background config fetch immediately.
  */
-declare function init$1(options?: {
+declare function init$2(options?: {
     apiKey?: string;
     baseUrl?: string;
 }): void;
@@ -236,19 +239,132 @@ declare function init$1(options?: {
  * @returns Model string (e.g., "claude-opus", "gpt-4o")
  * @throws Error if config not found AND no fallback provided
  */
-declare function get(configKey: string, sessionId: string, options?: {
+declare function get$1(configKey: string, sessionId: string, options?: {
     version?: number;
     fallback?: string;
     debug?: boolean;
 }): Promise<string>;
 
-declare const models_get: typeof get;
 declare namespace models {
-  export { models_get as get, init$1 as init };
+  export { get$1 as get, init$2 as init };
+}
+
+/**
+ * Fallom prompts module.
+ *
+ * Provides prompt management and A/B testing.
+ * Zero latency on get() - uses local cache + template interpolation.
+ *
+ * Design principles:
+ * - Never block user's app if Fallom is down
+ * - Very short timeouts (1-2 seconds max)
+ * - Always return usable prompt (or throw if not found)
+ * - Background sync keeps prompts fresh
+ * - Auto-tag next trace with prompt context
+ */
+interface PromptContext {
+    promptKey: string;
+    promptVersion: number;
+    abTestKey?: string;
+    variantIndex?: number;
+}
+/**
+ * Result from prompts.get() or prompts.getAB()
+ */
+interface PromptResult {
+    key: string;
+    version: number;
+    system: string;
+    user: string;
+    abTestKey?: string;
+    variantIndex?: number;
+}
+/**
+ * Initialize Fallom prompts.
+ * This is called automatically by fallom.init().
+ */
+declare function init$1(options?: {
+    apiKey?: string;
+    baseUrl?: string;
+}): void;
+/**
+ * Get and clear prompt context (one-shot).
+ */
+declare function getPromptContext(): PromptContext | null;
+/**
+ * Get a prompt (non-A/B).
+ *
+ * Zero latency - uses local cache + string interpolation.
+ * Also sets prompt context for next trace auto-tagging.
+ *
+ * @param promptKey - Your prompt key (e.g., "onboarding")
+ * @param options - Optional settings
+ * @param options.variables - Template variables (e.g., { userName: "John" })
+ * @param options.version - Pin to specific version. undefined = current
+ * @param options.debug - Enable debug logging
+ *
+ * @example
+ * ```typescript
+ * const prompt = await prompts.get("onboarding", {
+ *   variables: { userName: "John" }
+ * });
+ *
+ * // Use with OpenAI
+ * const response = await openai.chat.completions.create({
+ *   model,
+ *   messages: [
+ *     { role: "system", content: prompt.system },
+ *     { role: "user", content: prompt.user }
+ *   ]
+ * });
+ * ```
+ */
+declare function get(promptKey: string, options?: {
+    variables?: Record<string, unknown>;
+    version?: number;
+    debug?: boolean;
+}): Promise<PromptResult>;
+/**
+ * Get a prompt from an A/B test.
+ *
+ * Uses sessionId hash for deterministic, sticky assignment.
+ * Same session always gets same variant.
+ *
+ * Also sets prompt context for next trace auto-tagging.
+ *
+ * @param abTestKey - Your A/B test key (e.g., "onboarding-experiment")
+ * @param sessionId - Your session/conversation ID (for sticky assignment)
+ * @param options - Optional settings
+ * @param options.variables - Template variables
+ * @param options.debug - Enable debug logging
+ *
+ * @example
+ * ```typescript
+ * const prompt = await prompts.getAB("onboarding-test", sessionId, {
+ *   variables: { userName: "John" }
+ * });
+ * ```
+ */
+declare function getAB(abTestKey: string, sessionId: string, options?: {
+    variables?: Record<string, unknown>;
+    debug?: boolean;
+}): Promise<PromptResult>;
+/**
+ * Manually clear prompt context.
+ */
+declare function clearPromptContext(): void;
+
+type prompts_PromptResult = PromptResult;
+declare const prompts_clearPromptContext: typeof clearPromptContext;
+declare const prompts_get: typeof get;
+declare const prompts_getAB: typeof getAB;
+declare const prompts_getPromptContext: typeof getPromptContext;
+declare namespace prompts {
+  export { type prompts_PromptResult as PromptResult, prompts_clearPromptContext as clearPromptContext, prompts_get as get, prompts_getAB as getAB, prompts_getPromptContext as getPromptContext, init$1 as init };
 }
 
 /**
- * Combined initialization for both trace and models.
+ * Combined initialization for trace, models, and prompts.
  */
 interface InitOptions {
     apiKey?: string;
@@ -281,7 +397,7 @@ interface InitOptions {
 declare function init(options?: InitOptions): Promise<void>;
 
 /**
- * Fallom - Model A/B testing and tracing for LLM applications.
+ * Fallom - Model A/B testing, prompt management, and tracing for LLM applications.
  *
  * @example
  * ```typescript
@@ -298,10 +414,18 @@ declare function init(options?: InitOptions): Promise<void>;
  *   fallback: "gpt-4o-mini"
  * });
  *
+ * // Get managed prompts (with optional A/B testing)
+ * const prompt = await fallom.prompts.get("onboarding", {
+ *   variables: { userName: "John" }
+ * });
+ *
  * // Use with OpenAI
  * const response = await openai.chat.completions.create({
  *   model,
- *   messages: [...]
+ *   messages: [
+ *     { role: "system", content: prompt.system },
+ *     { role: "user", content: prompt.user }
+ *   ]
  * });
  *
  * // Record custom metrics
@@ -313,6 +437,7 @@ declare const _default: {
     init: typeof init;
     trace: typeof trace;
     models: typeof models;
+    prompts: typeof prompts;
 };
 
-export { type InitOptions, _default as default, init, models, trace };
+export { type InitOptions, type PromptResult, _default as default, init, models, prompts, trace };