@fallom/trace 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Fallom tracing module.
+ *
+ * Auto-instruments all LLM calls via OTEL and groups them by session.
+ * Also supports custom spans for business metrics.
+ */
+interface SessionContext {
+    configKey: string;
+    sessionId: string;
+}
+/**
+ * Initialize Fallom tracing. Auto-instruments all LLM calls.
+ *
+ * @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 env var, or https://spans.fallom.com
+ * @param options.captureContent - Whether to capture prompt/completion content in traces.
+ *                                 Set to false for privacy/compliance. Defaults to true.
+ *                                 Also respects FALLOM_CAPTURE_CONTENT env var ("true"/"false").
+ *
+ * @example
+ * ```typescript
+ * import fallom from 'fallom';
+ *
+ * // Normal usage (captures everything)
+ * fallom.trace.init();
+ *
+ * // Privacy mode (no prompts/completions stored)
+ * fallom.trace.init({ captureContent: false });
+ *
+ * fallom.trace.setSession("my-agent", sessionId);
+ * await agent.run(message); // Automatically traced
+ * ```
+ */
+declare function init$2(options?: {
+    apiKey?: string;
+    baseUrl?: string;
+    captureContent?: boolean;
+}): void;
+/**
+ * Set the current session context.
+ *
+ * All subsequent LLM calls in this async context will be
+ * automatically tagged with this configKey and sessionId.
+ *
+ * @param configKey - Your config name (e.g., "linkedin-agent")
+ * @param sessionId - Your session/conversation ID
+ *
+ * @example
+ * ```typescript
+ * trace.setSession("linkedin-agent", sessionId);
+ * await agent.run(message); // Automatically traced with session
+ * ```
+ */
+declare function setSession(configKey: string, sessionId: 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 fn - Function to run with session context
+ *
+ * @example
+ * ```typescript
+ * await trace.runWithSession("my-agent", sessionId, async () => {
+ *   await agent.run(message); // Has session context
+ * });
+ * ```
+ */
+declare function runWithSession<T>(configKey: string, sessionId: string, fn: () => T): T;
+/**
+ * Get current session context, if any.
+ */
+declare function getSession(): SessionContext | undefined;
+/**
+ * Clear session context.
+ */
+declare function clearSession(): void;
+/**
+ * Record custom business metrics. Latest value per field wins.
+ *
+ * Use this for metrics that OTEL can't capture automatically:
+ * - Outlier scores
+ * - Engagement metrics
+ * - Conversion rates
+ * - Any business-specific outcome
+ *
+ * @param data - Dict of metrics to record
+ * @param options - Optional session identifiers
+ * @param options.configKey - Config name (optional if setSession was called)
+ * @param options.sessionId - Session ID (optional if setSession was called)
+ *
+ * @example
+ * ```typescript
+ * // If session context is set:
+ * trace.span({ outlier_score: 0.8, engagement: 42 });
+ *
+ * // Or explicitly:
+ * trace.span(
+ *   { outlier_score: 0.8 },
+ *   { configKey: "linkedin-agent", sessionId: "user123-convo456" }
+ * );
+ * ```
+ */
+declare function span(data: Record<string, unknown>, options?: {
+    configKey?: string;
+    sessionId?: string;
+}): void;
+/**
+ * Shutdown the tracing SDK gracefully.
+ */
+declare function shutdown(): Promise<void>;
+
+declare const trace_clearSession: typeof clearSession;
+declare const trace_getSession: typeof getSession;
+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 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 };
+}
+
+/**
+ * Fallom models module.
+ *
+ * Provides model A/B testing with versioned configs.
+ * Zero latency on get() - uses local hash + cached config.
+ *
+ * Design principles:
+ * - Never block user's app if Fallom is down
+ * - Very short timeouts (1-2 seconds max)
+ * - Always return a usable model (fallback if needed)
+ * - Background sync keeps configs fresh
+ */
+/**
+ * Initialize Fallom models.
+ *
+ * This is optional - get() will auto-init if needed.
+ * Non-blocking: starts background config fetch immediately.
+ */
+declare function init$1(options?: {
+    apiKey?: string;
+    baseUrl?: string;
+}): void;
+/**
+ * Get model assignment for a session.
+ *
+ * This is zero latency - uses local hash computation + cached config.
+ * No network call on the hot path.
+ *
+ * Same session_id always returns same model (sticky assignment).
+ *
+ * Also automatically sets trace context, so all subsequent LLM calls
+ * are tagged with this session.
+ *
+ * @param configKey - Your config name (e.g., "linkedin-agent")
+ * @param sessionId - Your session/conversation ID (must be consistent)
+ * @param options - Optional settings
+ * @param options.version - Pin to specific version (1, 2, etc). undefined = latest
+ * @param options.fallback - Model to return if config not found or Fallom is down
+ * @param options.debug - Enable debug logging
+ * @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?: {
+    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 };
+}
+
+/**
+ * Combined initialization for both trace and models.
+ */
+interface InitOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    captureContent?: boolean;
+}
+/**
+ * Initialize both trace and models 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.captureContent - Whether to capture prompt/completion content (default: true)
+ *
+ * @example
+ * ```typescript
+ * import fallom from 'fallom';
+ *
+ * // Basic initialization
+ * fallom.init({ apiKey: "your-api-key" });
+ *
+ * // Local development
+ * fallom.init({ baseUrl: "http://localhost:8001" });
+ *
+ * // Privacy mode
+ * fallom.init({ captureContent: false });
+ * ```
+ */
+declare function init(options?: InitOptions): void;
+
+/**
+ * Fallom - Model A/B testing and tracing for LLM applications.
+ *
+ * @example
+ * ```typescript
+ * import fallom from 'fallom';
+ *
+ * // Initialize (call this early, before LLM imports if possible)
+ * fallom.init({ apiKey: "your-api-key" });
+ *
+ * // Set session context for tracing
+ * fallom.trace.setSession("my-agent", sessionId);
+ *
+ * // Get A/B tested model
+ * const model = await fallom.models.get("my-config", sessionId, {
+ *   fallback: "gpt-4o-mini"
+ * });
+ *
+ * // Use with OpenAI
+ * const response = await openai.chat.completions.create({
+ *   model,
+ *   messages: [...]
+ * });
+ *
+ * // Record custom metrics
+ * fallom.trace.span({ user_satisfaction: 5 });
+ * ```
+ */
+
+declare const _default: {
+    init: typeof init;
+    trace: typeof trace;
+    models: typeof models;
+};
+
+export { type InitOptions, _default as default, init, models, trace };