@fallom/trace 0.1.1 → 0.1.4

package/dist/index.d.mts

@@ -32,11 +32,12 @@ interface SessionContext {
  * await agent.run(message); // Automatically traced
  * ```
  */
-declare function init$2(options?: {
+declare function init$3(options?: {
     apiKey?: string;
     baseUrl?: string;
     captureContent?: boolean;
-}): void;
+    debug?: boolean;
+}): Promise<void>;
 /**
  * Set the current session context.
  *
@@ -111,6 +112,74 @@ declare function span(data: Record<string, unknown>, options?: {
  * Shutdown the tracing SDK gracefully.
  */
 declare function shutdown(): Promise<void>;
+/**
+ * Wrap an OpenAI client to automatically trace all chat completions.
+ * Works with OpenAI, OpenRouter, Azure OpenAI, LiteLLM, and any OpenAI-compatible API.
+ *
+ * @param client - The OpenAI client instance
+ * @returns The same client with tracing enabled
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from "openai";
+ * import { trace } from "@fallom/trace";
+ *
+ * const openai = trace.wrapOpenAI(new OpenAI());
+ *
+ * trace.setSession("my-config", sessionId);
+ * const response = await openai.chat.completions.create({...}); // Automatically traced!
+ * ```
+ */
+declare function wrapOpenAI<T extends {
+    chat: {
+        completions: {
+            create: (...args: any[]) => Promise<any>;
+        };
+    };
+}>(client: T): T;
+/**
+ * Wrap an Anthropic client to automatically trace all message creations.
+ *
+ * @param client - The Anthropic client instance
+ * @returns The same client with tracing enabled
+ *
+ * @example
+ * ```typescript
+ * import Anthropic from "@anthropic-ai/sdk";
+ * import { trace } from "@fallom/trace";
+ *
+ * const anthropic = trace.wrapAnthropic(new Anthropic());
+ *
+ * trace.setSession("my-config", sessionId);
+ * const response = await anthropic.messages.create({...}); // Automatically traced!
+ * ```
+ */
+declare function wrapAnthropic<T extends {
+    messages: {
+        create: (...args: any[]) => Promise<any>;
+    };
+}>(client: T): T;
+/**
+ * Wrap a Google Generative AI client to automatically trace all content generations.
+ *
+ * @param client - The GoogleGenerativeAI client instance
+ * @returns The same client with tracing enabled
+ *
+ * @example
+ * ```typescript
+ * import { GoogleGenerativeAI } from "@google/generative-ai";
+ * import { trace } from "@fallom/trace";
+ *
+ * const genAI = new GoogleGenerativeAI(apiKey);
+ * const model = trace.wrapGoogleAI(genAI.getGenerativeModel({ model: "gemini-pro" }));
+ *
+ * trace.setSession("my-config", sessionId);
+ * const response = await model.generateContent("Hello!"); // Automatically traced!
+ * ```
+ */
+declare function wrapGoogleAI<T extends {
+    generateContent: (...args: any[]) => Promise<any>;
+}>(model: T): T;
 
 declare const trace_clearSession: typeof clearSession;
 declare const trace_getSession: typeof getSession;
@@ -118,8 +187,11 @@ 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_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 };
+  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 };
 }
 
 /**
@@ -140,7 +212,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;
@@ -164,24 +236,138 @@ 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;
     baseUrl?: string;
     captureContent?: boolean;
+    debug?: boolean;
 }
 /**
  * Initialize both trace and models at once.
@@ -205,10 +391,10 @@ interface InitOptions {
  * fallom.init({ captureContent: false });
  * ```
  */
-declare function init(options?: InitOptions): void;
+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
@@ -225,10 +411,18 @@ declare function init(options?: InitOptions): 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
@@ -240,6 +434,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

@@ -32,11 +32,12 @@ interface SessionContext {
  * await agent.run(message); // Automatically traced
  * ```
  */
-declare function init$2(options?: {
+declare function init$3(options?: {
     apiKey?: string;
     baseUrl?: string;
     captureContent?: boolean;
-}): void;
+    debug?: boolean;
+}): Promise<void>;
 /**
  * Set the current session context.
  *
@@ -111,6 +112,74 @@ declare function span(data: Record<string, unknown>, options?: {
  * Shutdown the tracing SDK gracefully.
  */
 declare function shutdown(): Promise<void>;
+/**
+ * Wrap an OpenAI client to automatically trace all chat completions.
+ * Works with OpenAI, OpenRouter, Azure OpenAI, LiteLLM, and any OpenAI-compatible API.
+ *
+ * @param client - The OpenAI client instance
+ * @returns The same client with tracing enabled
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from "openai";
+ * import { trace } from "@fallom/trace";
+ *
+ * const openai = trace.wrapOpenAI(new OpenAI());
+ *
+ * trace.setSession("my-config", sessionId);
+ * const response = await openai.chat.completions.create({...}); // Automatically traced!
+ * ```
+ */
+declare function wrapOpenAI<T extends {
+    chat: {
+        completions: {
+            create: (...args: any[]) => Promise<any>;
+        };
+    };
+}>(client: T): T;
+/**
+ * Wrap an Anthropic client to automatically trace all message creations.
+ *
+ * @param client - The Anthropic client instance
+ * @returns The same client with tracing enabled
+ *
+ * @example
+ * ```typescript
+ * import Anthropic from "@anthropic-ai/sdk";
+ * import { trace } from "@fallom/trace";
+ *
+ * const anthropic = trace.wrapAnthropic(new Anthropic());
+ *
+ * trace.setSession("my-config", sessionId);
+ * const response = await anthropic.messages.create({...}); // Automatically traced!
+ * ```
+ */
+declare function wrapAnthropic<T extends {
+    messages: {
+        create: (...args: any[]) => Promise<any>;
+    };
+}>(client: T): T;
+/**
+ * Wrap a Google Generative AI client to automatically trace all content generations.
+ *
+ * @param client - The GoogleGenerativeAI client instance
+ * @returns The same client with tracing enabled
+ *
+ * @example
+ * ```typescript
+ * import { GoogleGenerativeAI } from "@google/generative-ai";
+ * import { trace } from "@fallom/trace";
+ *
+ * const genAI = new GoogleGenerativeAI(apiKey);
+ * const model = trace.wrapGoogleAI(genAI.getGenerativeModel({ model: "gemini-pro" }));
+ *
+ * trace.setSession("my-config", sessionId);
+ * const response = await model.generateContent("Hello!"); // Automatically traced!
+ * ```
+ */
+declare function wrapGoogleAI<T extends {
+    generateContent: (...args: any[]) => Promise<any>;
+}>(model: T): T;
 
 declare const trace_clearSession: typeof clearSession;
 declare const trace_getSession: typeof getSession;
@@ -118,8 +187,11 @@ 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_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 };
+  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 };
 }
 
 /**
@@ -140,7 +212,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;
@@ -164,24 +236,138 @@ 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;
     baseUrl?: string;
     captureContent?: boolean;
+    debug?: boolean;
 }
 /**
  * Initialize both trace and models at once.
@@ -205,10 +391,10 @@ interface InitOptions {
  * fallom.init({ captureContent: false });
  * ```
  */
-declare function init(options?: InitOptions): void;
+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
@@ -225,10 +411,18 @@ declare function init(options?: InitOptions): 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
@@ -240,6 +434,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 };