@getfoil/foil-js 0.4.0

package/src/foil.js

@@ -0,0 +1,2214 @@
+const axios = require('axios');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const FormData = require('form-data');
+
+/**
+ * Foil JavaScript SDK
+ *
+ * This SDK can be used alongside OpenTelemetry (OTEL) instrumentation like OpenLLMetry/Traceloop.
+ * Below is a reference of which fields are auto-captured by OTEL vs which require manual setting.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════════════════════
+ * ATTRIBUTE REFERENCE: OTEL Auto-Captured vs Custom (Manual)
+ * ═══════════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * LLM CONFIG (auto-captured by OpenLLMetry when passed to LLM call):
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * | Field            | OTEL Attribute                    | Auto-captured? | Notes                |
+ * |------------------|-----------------------------------|----------------|----------------------|
+ * | temperature      | gen_ai.request.temperature        | ✅ Yes         | Pass to LLM call     |
+ * | maxTokens        | gen_ai.request.max_tokens         | ✅ Yes         | Pass to LLM call     |
+ * | topP             | gen_ai.request.top_p              | ✅ Yes         | Pass to LLM call     |
+ * | frequencyPenalty | llm.frequency_penalty             | ✅ Yes         | Pass to LLM call     |
+ * | presencePenalty  | llm.presence_penalty              | ✅ Yes         | Pass to LLM call     |
+ * | stopSequences    | gen_ai.request.stop_sequences     | ❌ No          | Not captured         |
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ *
+ * SESSION & USER TRACKING (requires manual setting):
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * | Field              | OTEL Attribute              | Auto-captured? | How to set             |
+ * |--------------------|---------------------------- |----------------|------------------------|
+ * | sessionId          | gen_ai.conversation.id      | ❌ No          | span.setAttribute()    |
+ * |                    | session.id                  |                |                        |
+ * |                    | foil.session_id             |                |                        |
+ * | endUserId          | llm.user                    | ⚠️ Partial     | OpenAI 'user' param    |
+ * |                    | user.id                     |                | or span.setAttribute() |
+ * |                    | foil.end_user_id            |                |                        |
+ * | endUserProperties  | foil.end_user.*             | ❌ No          | span.setAttribute()    |
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ *
+ * DEVICE CONTEXT (requires manual setting - useful for client-side apps):
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * | Field        | OTEL Attribute          | Fallback OTEL Attr  | Auto-captured?            |
+ * |--------------|-------------------------|---------------------|---------------------------|
+ * | platform     | foil.device.platform    | -                   | ❌ No                     |
+ * | os           | foil.device.os          | os.type             | ⚠️ os.type may be set    |
+ * | browser      | foil.device.browser     | browser.name        | ⚠️ browser.name may be set|
+ * | deviceType   | foil.device.type        | -                   | ❌ No                     |
+ * | appVersion   | foil.device.app_version | service.version     | ⚠️ service.version set   |
+ * | locale       | foil.device.locale      | -                   | ❌ No                     |
+ * | timezone     | foil.device.timezone    | -                   | ❌ No                     |
+ * | userAgent    | foil.device.user_agent  | http.user_agent     | ⚠️ http.user_agent may be|
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ *
+ * EXAMPLE: Setting custom attributes with OpenLLMetry/Traceloop:
+ * ```javascript
+ * import { trace } from "@opentelemetry/api";
+ *
+ * const span = trace.getActiveSpan();
+ * span?.setAttribute("gen_ai.conversation.id", sessionId);  // Session tracking
+ * span?.setAttribute("llm.user", userId);                    // End user tracking
+ * span?.setAttribute("foil.end_user.plan", "premium");       // End user properties
+ * span?.setAttribute("foil.device.platform", "web");         // Device context
+ * ```
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════════════════════
+ */
+
+// Debug logging - enable with FOIL_DEBUG=true or pass debug: true to tracer
+const isDebugEnabled = () => process.env.FOIL_DEBUG === 'true';
+
+/**
+ * Span kinds supported by Foil tracing
+ */
+const SpanKind = {
+  AGENT: 'agent',
+  LLM: 'llm',
+  TOOL: 'tool',
+  CHAIN: 'chain',
+  RETRIEVER: 'retriever',
+  EMBEDDING: 'embedding',
+  CUSTOM: 'custom',
+};
+
+/**
+ * Media categories for multimodal content
+ */
+const MediaCategory = {
+  IMAGE: 'image',
+  DOCUMENT: 'document',
+  SPREADSHEET: 'spreadsheet',
+  CODE: 'code',
+  AUDIO: 'audio',
+  VIDEO: 'video',
+  ARCHIVE: 'archive',
+  NOTEBOOK: 'notebook',
+  OTHER: 'other',
+};
+
+/**
+ * Content block helpers for multimodal input/output
+ */
+const ContentBlock = {
+  /**
+   * Create a text content block
+   * @param {string} text - The text content
+   * @returns {Object} Text content block
+   */
+  text(text) {
+    return { type: 'text', text };
+  },
+
+  /**
+   * Create a media content block
+   * @param {string} mediaId - The media ID from uploadMedia
+   * @param {Object} [options] - Additional options
+   * @param {string} [options.category] - Media category
+   * @param {string} [options.mimeType] - MIME type
+   * @param {string} [options.filename] - Original filename
+   * @returns {Object} Media content block
+   */
+  media(mediaId, options = {}) {
+    return {
+      type: 'media',
+      mediaId,
+      category: options.category,
+      mimeType: options.mimeType,
+      filename: options.filename,
+    };
+  },
+};
+
+/**
+ * Helper function to create content blocks array from mixed inputs
+ * @param {...(string|Object)} parts - Text strings or content block objects
+ * @returns {Array} Array of content blocks
+ */
+function content(...parts) {
+  return parts.map((part) => {
+    if (typeof part === 'string') {
+      return ContentBlock.text(part);
+    }
+    return part;
+  });
+}
+
+// Default timeout for spans (5 minutes)
+const DEFAULT_SPAN_TIMEOUT_MS = 300000;
+
+/**
+ * TraceContext provides span management within a trace
+ * Passed to traced functions to allow creating child spans
+ */
+class TraceContext {
+  constructor(tracer, traceId, rootSpanId, agentName, depth = 0) {
+    this.tracer = tracer;
+    this.traceId = traceId;
+    this.rootSpanId = rootSpanId;
+    this.agentName = agentName;
+    this.depth = depth;
+    this.activeSpans = new Map();
+    this.debug = tracer.debug || isDebugEnabled();
+    // Stack to track current active span for proper parent-child relationships
+    this._spanStack = [rootSpanId];
+  }
+
+  /**
+   * Get the current parent span ID (the most recent active span)
+   */
+  get currentParentSpanId() {
+    return this._spanStack[this._spanStack.length - 1];
+  }
+
+  /**
+   * Log debug message with indentation based on depth
+   */
+  _log(message, data = {}) {
+    if (!this.debug) return;
+    const indent = '  '.repeat(this.depth);
+    const dataStr = Object.keys(data).length > 0 ? ` ${JSON.stringify(data)}` : '';
+    console.log(`[Foil] ${indent}${message}${dataStr}`);
+  }
+
+  /**
+   * Start a new child span
+   * @param {string} spanKind - Type of span (llm, tool, chain, etc.)
+   * @param {string} name - Name of the span (model name, tool name, etc.)
+   * @param {Object} [attributes] - Additional span attributes
+   * @param {string} [attributes.parentSpanId] - Explicit parent span ID (overrides automatic stack-based parent)
+   * @param {Array} [attributes.attachments] - Input attachments array
+   * @param {string} attributes.attachments[].type - Attachment type: 'image', 'code', 'text', 'iframe'
+   * @param {string} attributes.attachments[].value - URL for images, content for code/text
+   * @param {string} [attributes.attachments[].name] - Optional filename
+   * @param {string} [attributes.attachments[].language] - Optional language for code type
+   * @param {number} [attributes.timeout] - Timeout in ms (default: 5 minutes, 0 to disable)
+   * @returns {Object} Span object with spanId and methods to end the span
+   */
+  async startSpan(spanKind, name, attributes = {}) {
+    const spanId = crypto.randomUUID();
+    const startTime = Date.now();
+    // Use explicit parent if provided, otherwise use current parent from stack
+    const parentSpanId = attributes.parentSpanId || this.currentParentSpanId;
+
+    // Extract LLM config if provided
+    const llmConfig = attributes.llmConfig || {};
+
+    // Store all span data locally (no server call)
+    const localSpanData = {
+      spanId,
+      name,
+      agentName: this.agentName,
+      traceId: this.traceId,
+      parentSpanId,
+      spanKind,
+      model: spanKind === SpanKind.LLM ? name : attributes.model,
+      input: attributes.input,
+      properties: attributes.properties || {},
+      sessionId: attributes.sessionId,
+      experimentId: attributes.experimentId,
+      variantId: attributes.variantId,
+      endUserId: attributes.userId,
+      endUserProperties: attributes.userProperties,
+      device: attributes.device,
+      // Input attachments (images, code, text)
+      inputAttachments: attributes.attachments,
+      // LLM Configuration for replay/debugging
+      llmConfig: spanKind === SpanKind.LLM ? {
+        temperature: llmConfig.temperature,
+        maxTokens: llmConfig.maxTokens,
+        topP: llmConfig.topP,
+        frequencyPenalty: llmConfig.frequencyPenalty,
+        presencePenalty: llmConfig.presencePenalty,
+        systemPrompt: llmConfig.systemPrompt,
+        tools: llmConfig.tools,
+        responseFormat: llmConfig.responseFormat,
+        stopSequences: llmConfig.stopSequences,
+        seed: llmConfig.seed,
+      } : undefined,
+      startTime,
+    };
+
+    // Push this span onto the stack - it becomes the parent for subsequent spans
+    this._spanStack.push(spanId);
+
+    this._log(`▶ START [${spanKind}] ${name}`, { spanId: spanId.slice(0, 8), parentId: parentSpanId?.slice(0, 8) });
+
+    // Set up timeout for hung spans
+    const timeoutMs = attributes.timeout ?? DEFAULT_SPAN_TIMEOUT_MS;
+    let timeoutId = null;
+    let hasEnded = false;
+
+    const span = {
+      spanId,
+      spanKind,
+      name,
+      startTime,
+      depth: this.depth + 1,
+      attributes,
+      _localData: localSpanData,
+      _hasEnded: false,
+      /**
+       * Create a child context for this span
+       * @returns {TraceContext}
+       */
+      createChildContext: () => {
+        return new TraceContext(
+          this.tracer,
+          this.traceId,
+          spanId,
+          this.agentName,
+          this.depth + 1
+        );
+      },
+      /**
+       * End this span
+       * @param {Object} [result] - Span result
+       * @param {*} [result.output] - Output from the operation
+       * @param {Object} [result.tokens] - Token usage
+       * @param {Object} [result.error] - Error if operation failed
+       * @param {Array} [result.attachments] - Output attachments array
+       * @param {string} result.attachments[].type - Attachment type: 'image', 'code', 'text', 'iframe'
+       * @param {string} result.attachments[].value - URL for images, content for code/text
+       * @param {string} [result.attachments[].name] - Optional filename
+       * @param {string} [result.attachments[].language] - Optional language for code type
+       */
+      end: async (result = {}) => {
+        // Prevent double-ending
+        if (hasEnded) {
+          return { spanId, duration: 0 };
+        }
+        hasEnded = true;
+        span._hasEnded = true;
+
+        // Clear timeout
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+
+        const endTime = Date.now();
+        const duration = endTime - startTime;
+
+        // Build complete span data from local storage + end result
+        const completeSpanData = {
+          // All data from start (stored locally)
+          spanId: localSpanData.spanId,
+          traceId: localSpanData.traceId,
+          parentSpanId: localSpanData.parentSpanId,
+          name: localSpanData.name,
+          spanKind: localSpanData.spanKind,
+          agentName: localSpanData.agentName,
+          sessionId: localSpanData.sessionId,
+          model: localSpanData.model,
+          input: localSpanData.input,
+          properties: localSpanData.properties,
+          llmConfig: localSpanData.llmConfig,
+          device: localSpanData.device,
+          endUserId: localSpanData.endUserId,
+          endUserProperties: localSpanData.endUserProperties,
+          experimentId: localSpanData.experimentId,
+          variantId: localSpanData.variantId,
+          inputAttachments: localSpanData.inputAttachments,
+          // End data
+          output: result.output,
+          tokens: result.tokens,
+          timing: { totalDuration: duration, ttft: result.ttft },
+          error: result.error,
+          attachments: result.attachments,
+          // Timestamps
+          startTime: new Date(startTime).toISOString(),
+          endTime: new Date(endTime).toISOString(),
+        };
+
+        this.activeSpans.delete(spanId);
+
+        // Pop this span from the stack (restore parent as current)
+        const stackIdx = this._spanStack.indexOf(spanId);
+        if (stackIdx !== -1) {
+          this._spanStack.splice(stackIdx, 1);
+        }
+
+        const logData = { spanId: spanId.slice(0, 8), duration: `${duration}ms` };
+        if (result.tokens?.total) logData.tokens = result.tokens.total;
+        if (result.error) logData.error = result.error.message || result.error;
+        this._log(`■ END [${spanKind}] ${name}`, logData);
+
+        // Send complete span data to server (fire and forget)
+        this.tracer.foil.endSpan(completeSpanData).catch((err) => {
+          console.error('Foil span end failed:', err.message);
+        });
+
+        return { spanId, duration };
+      },
+    };
+
+    // Set up timeout if enabled
+    if (timeoutMs > 0) {
+      timeoutId = setTimeout(() => {
+        if (!hasEnded) {
+          this._log(`⚠ TIMEOUT [${spanKind}] ${name}`, { spanId: spanId.slice(0, 8), timeoutMs });
+          span.end({
+            error: { type: 'timeout', message: `Span timed out after ${timeoutMs}ms` },
+          });
+        }
+      }, timeoutMs);
+    }
+
+    this.activeSpans.set(spanId, span);
+    return span;
+  }
+
+  /**
+   * Wrap an async function in a span
+   * @param {string} spanKind - Type of span
+   * @param {string} name - Name of the span
+   * @param {Function} fn - Async function to execute
+   * @param {Object} [attributes] - Additional span attributes
+   * @returns {Promise<*>} Result of the function
+   */
+  async wrapInSpan(spanKind, name, fn, attributes = {}) {
+    const span = await this.startSpan(spanKind, name, attributes);
+
+    try {
+      // Pass the same context - span stack handles parent-child relationships
+      const result = await fn(this);
+      await span.end({ output: result });
+      return result;
+    } catch (error) {
+      await span.end({ error: { type: error.name, message: error.message } });
+      throw error;
+    }
+  }
+
+  /**
+   * Create an LLM span and return wrapper functions
+   * @param {string} model - Model name
+   * @param {Object} [attributes] - Additional attributes
+   * @returns {Promise<Object>} LLM span with helper methods
+   */
+  async llm(model, attributes = {}) {
+    return this.startSpan(SpanKind.LLM, model, attributes);
+  }
+
+  /**
+   * Wrap a tool execution
+   * @param {string} toolName - Name of the tool
+   * @param {Function} fn - Tool function to execute
+   * @param {Object} [attributes] - Additional attributes (arguments, etc.)
+   * @returns {Promise<*>} Result of the tool
+   */
+  async tool(toolName, fn, attributes = {}) {
+    return this.wrapInSpan(SpanKind.TOOL, toolName, fn, attributes);
+  }
+
+  /**
+   * Wrap a retriever operation
+   * @param {string} retrieverName - Name of the retriever
+   * @param {Function} fn - Retriever function to execute
+   * @param {Object} [attributes] - Additional attributes
+   * @returns {Promise<*>} Retriever results
+   */
+  async retriever(retrieverName, fn, attributes = {}) {
+    return this.wrapInSpan(SpanKind.RETRIEVER, retrieverName, fn, attributes);
+  }
+
+  /**
+   * Wrap an embedding operation
+   * @param {string} model - Embedding model name
+   * @param {Function} fn - Embedding function to execute
+   * @param {Object} [attributes] - Additional attributes
+   * @returns {Promise<*>} Embedding results
+   */
+  async embedding(model, fn, attributes = {}) {
+    return this.wrapInSpan(SpanKind.EMBEDDING, model, fn, attributes);
+  }
+
+  /**
+   * Record a signal for this trace
+   * @param {string} signalName - Name of the signal (e.g., 'user_thumbs', 'sentiment')
+   * @param {boolean|number|string} value - Signal value
+   * @param {Object} [options] - Additional options
+   * @param {string} [options.spanId] - Specific span ID to associate with
+   * @param {string} [options.signalType] - Type of signal (feedback, sentiment, quality, etc.)
+   * @param {string} [options.source] - Signal source (user, llm, system)
+   * @param {Object} [options.metadata] - Additional metadata
+   * @returns {Promise<Object>} Recorded signal
+   */
+  async recordSignal(signalName, value, options = {}) {
+    const signalData = {
+      traceId: this.traceId,
+      spanId: options.spanId || '',
+      agentName: this.agentName,
+      signalName,
+      value,
+      signalType: options.signalType || 'feedback',
+      source: options.source || 'user',
+      metadata: options.metadata,
+    };
+
+    this._log(`📊 SIGNAL: ${signalName}`, { value, traceId: this.traceId.slice(0, 8) });
+
+    return this.tracer.foil.recordSignal(signalData).catch((err) => {
+      console.error('Foil signal recording failed:', err.message);
+    });
+  }
+
+  /**
+   * Record user feedback (thumbs up/down)
+   * @param {boolean} positive - True for thumbs up, false for thumbs down
+   * @param {Object} [options] - Additional options
+   * @returns {Promise<Object>} Recorded signal
+   */
+  async recordFeedback(positive, options = {}) {
+    return this.recordSignal('user_thumbs', positive, {
+      signalType: 'feedback',
+      source: 'user',
+      ...options,
+    });
+  }
+
+  /**
+   * Record a user rating
+   * @param {number} rating - Rating value (e.g., 1-5)
+   * @param {Object} [options] - Additional options
+   * @returns {Promise<Object>} Recorded signal
+   */
+  async recordRating(rating, options = {}) {
+    return this.recordSignal('user_rating', rating, {
+      signalType: 'feedback',
+      source: 'user',
+      ...options,
+    });
+  }
+}
+
+/**
+ * FoilTracer provides comprehensive tracing for AI applications
+ * Captures the full lifecycle: prompt → LLM → tools → response
+ */
+class FoilTracer {
+  constructor(foil, options = {}) {
+    this.foil = foil;
+    this.agentName = options.agentName || 'default-agent';
+    this.defaultModel = options.defaultModel;
+    this.activeTraces = new Map();
+    this.debug = options.debug || isDebugEnabled();
+    this._cleanupRegistered = false;
+
+    // Register process cleanup handlers
+    this._registerCleanup();
+  }
+
+  /**
+   * Register process exit handlers to cleanup abandoned spans
+   * @private
+   */
+  _registerCleanup() {
+    if (this._cleanupRegistered) return;
+    this._cleanupRegistered = true;
+
+    const cleanup = () => {
+      if (this.activeTraces.size === 0) return;
+
+      this._log('Process exiting, cleaning up abandoned traces...');
+
+      for (const [traceId, traceInfo] of this.activeTraces) {
+        const { context, spanId, startTime } = traceInfo;
+        const duration = Date.now() - startTime;
+
+        // End the root span with abandoned error
+        const completeSpanData = {
+          spanId,
+          traceId,
+          agentName: this.agentName,
+          error: { type: 'abandoned', message: 'Process exited before span completed' },
+          timing: { totalDuration: duration },
+          startTime: new Date(startTime).toISOString(),
+          endTime: new Date().toISOString(),
+        };
+
+        // Synchronous - best effort cleanup
+        try {
+          this.foil.endSpan(completeSpanData).catch(() => {});
+        } catch {
+          // Ignore errors during cleanup
+        }
+      }
+      this.activeTraces.clear();
+    };
+
+    // Register for various exit signals
+    process.on('beforeExit', cleanup);
+    process.on('SIGINT', () => {
+      cleanup();
+      process.exit(130);
+    });
+    process.on('SIGTERM', () => {
+      cleanup();
+      process.exit(143);
+    });
+  }
+
+  /**
+   * Log debug message
+   */
+  _log(message, data = {}) {
+    if (!this.debug) return;
+    const dataStr = Object.keys(data).length > 0 ? ` ${JSON.stringify(data)}` : '';
+    console.log(`[Foil] ${message}${dataStr}`);
+  }
+
+  /**
+   * Execute a function within a traced context
+   * @param {Function} fn - Async function to execute, receives TraceContext
+   * @param {Object} [options] - Trace options
+   * @param {string} [options.name] - Name for the root span
+   * @param {string} [options.traceId] - Custom trace ID (auto-generated if not provided)
+   * @param {string} [options.sessionId] - Session ID for conversation tracking
+   * @param {*} [options.input] - Input to record
+   * @param {Object} [options.properties] - Custom properties
+   * @param {string} [options.userId] - User identifier for tracking which user triggered this trace
+   * @param {Object} [options.userProperties] - Additional user attributes (plan, company, role, etc.)
+   * @param {Object} [options.device] - Device/platform information
+   * @param {string} [options.device.platform] - Platform type: 'web', 'ios', 'android', 'desktop', 'api'
+   * @param {string} [options.device.os] - Operating system (e.g., 'iOS 17.0', 'macOS 14.0', 'Windows 11')
+   * @param {string} [options.device.browser] - Browser name and version (e.g., 'Chrome 120', 'Safari 17')
+   * @param {string} [options.device.deviceType] - Device type: 'phone', 'tablet', 'desktop'
+   * @param {string} [options.device.appVersion] - Application version
+   * @param {string} [options.device.locale] - User locale (e.g., 'en-US')
+   * @param {string} [options.device.timezone] - User timezone (e.g., 'America/Los_Angeles')
+   * @param {string} [options.device.screenResolution] - Screen resolution (e.g., '1920x1080')
+   * @param {string} [options.device.userAgent] - Full user agent string
+   * @param {string} [options.device.ip] - IP address (for geo-location)
+   * @param {number} [options.timeout] - Timeout in ms for root span (default: 5 minutes, 0 to disable)
+   * @returns {Promise<*>} Result of the function
+   */
+  async trace(fn, options = {}) {
+    const traceId = options.traceId || crypto.randomUUID();
+    const spanId = crypto.randomUUID();
+    const startTime = Date.now();
+    const traceName = options.name || 'trace';
+
+    this._log(`━━━ TRACE START: ${traceName} ━━━`, { traceId: traceId.slice(0, 8), spanId: spanId.slice(0, 8) });
+
+    // Store root span data locally (no server call on start)
+    const localRootSpanData = {
+      spanId,
+      name: traceName,
+      agentName: this.agentName,
+      traceId,
+      parentSpanId: null,
+      spanKind: SpanKind.AGENT,
+      input: options.input,
+      sessionId: options.sessionId,
+      properties: options.properties || {},
+      // User tracking
+      endUserId: options.userId,
+      endUserProperties: options.userProperties,
+      // Device/platform context
+      device: options.device,
+      startTime,
+    };
+
+    const context = new TraceContext(this, traceId, spanId, this.agentName, 0);
+
+    // Track active trace with local data
+    this.activeTraces.set(traceId, { spanId, startTime, context, localData: localRootSpanData });
+
+    // Set up timeout for root span
+    const timeoutMs = options.timeout ?? DEFAULT_SPAN_TIMEOUT_MS;
+    let timeoutId = null;
+    let hasEnded = false;
+
+    if (timeoutMs > 0) {
+      timeoutId = setTimeout(() => {
+        if (!hasEnded) {
+          this._log(`⚠ TRACE TIMEOUT: ${traceName}`, { traceId: traceId.slice(0, 8), timeoutMs });
+          // Force end the trace with timeout error
+          const endTime = Date.now();
+          const duration = endTime - startTime;
+          const completeSpanData = {
+            ...localRootSpanData,
+            error: { type: 'timeout', message: `Trace timed out after ${timeoutMs}ms` },
+            timing: { totalDuration: duration },
+            startTime: new Date(startTime).toISOString(),
+            endTime: new Date(endTime).toISOString(),
+          };
+          this.foil.endSpan(completeSpanData).catch(() => {});
+          this.activeTraces.delete(traceId);
+          hasEnded = true;
+        }
+      }, timeoutMs);
+    }
+
+    try {
+      const result = await fn(context);
+
+      if (hasEnded) return result; // Already timed out
+      hasEnded = true;
+      if (timeoutId) clearTimeout(timeoutId);
+
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+
+      this._log(`━━━ TRACE END: ${traceName} ━━━`, { traceId: traceId.slice(0, 8), duration: `${duration}ms` });
+
+      // Send complete span data to server
+      const completeSpanData = {
+        ...localRootSpanData,
+        output: result,
+        timing: { totalDuration: duration },
+        startTime: new Date(startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await this.foil.endSpan(completeSpanData).catch((err) => {
+        console.error('Foil trace end failed:', err.message);
+      });
+
+      this.activeTraces.delete(traceId);
+      return result;
+    } catch (error) {
+      if (hasEnded) throw error; // Already timed out
+      hasEnded = true;
+      if (timeoutId) clearTimeout(timeoutId);
+
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+
+      this._log(`━━━ TRACE ERROR: ${traceName} ━━━`, { traceId: traceId.slice(0, 8), duration: `${duration}ms`, error: error.message });
+
+      // Send complete span data to server with error
+      const completeSpanData = {
+        ...localRootSpanData,
+        error: { type: error.name, message: error.message },
+        timing: { totalDuration: duration },
+        startTime: new Date(startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await this.foil.endSpan(completeSpanData).catch((err) => {
+        console.error('Foil trace end (error) failed:', err.message);
+      });
+
+      this.activeTraces.delete(traceId);
+      throw error;
+    }
+  }
+
+  /**
+   * Get the trace data for a completed trace
+   * @param {string} traceId - The trace ID
+   * @returns {Promise<Object>} Trace data with all spans
+   */
+  async getTrace(traceId) {
+    return this.foil.getTrace(traceId);
+  }
+
+  /**
+   * Create an OpenAI client wrapper with automatic tracing
+   * @param {Object} openai - OpenAI client instance
+   * @param {Object} [options] - Wrapper options
+   * @returns {Object} Wrapped OpenAI client with tracing
+   */
+  wrapOpenAI(openai, options = {}) {
+    const tracer = this;
+    const originalCreate = openai.chat.completions.create.bind(openai.chat.completions);
+
+    openai.chat.completions.create = async function (params, reqOptions) {
+      // If we're in a trace context, create a child span
+      const context = options.context;
+      let span = null;
+
+      // Extract system prompt from messages
+      const systemMessage = params.messages?.find(m => m.role === 'system');
+      const systemPrompt = systemMessage?.content;
+
+      if (context) {
+        span = await context.startSpan(SpanKind.LLM, params.model || 'openai', {
+          input: params.messages,
+          properties: { tools: params.tools?.map((t) => t.function?.name) },
+          // LLM Configuration for replay/debugging
+          llmConfig: {
+            temperature: params.temperature,
+            maxTokens: params.max_tokens,
+            topP: params.top_p,
+            frequencyPenalty: params.frequency_penalty,
+            presencePenalty: params.presence_penalty,
+            systemPrompt,
+            tools: params.tools,
+            responseFormat: params.response_format,
+            stopSequences: params.stop,
+            seed: params.seed,
+          },
+        });
+      }
+
+      const startTime = Date.now();
+      let ttft = null;
+
+      try {
+        const response = await originalCreate(params, reqOptions);
+
+        // Handle streaming
+        if (params.stream) {
+          const originalIterator = response[Symbol.asyncIterator].bind(response);
+          let firstChunk = true;
+          let collectedContent = '';
+          let collectedToolCalls = [];
+          let usage = null;
+
+          const wrappedIterator = async function* () {
+            for await (const chunk of originalIterator()) {
+              if (firstChunk) {
+                ttft = Date.now() - startTime;
+                firstChunk = false;
+              }
+
+              const delta = chunk.choices?.[0]?.delta;
+              if (delta?.content) {
+                collectedContent += delta.content;
+              }
+
+              if (delta?.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                  if (!collectedToolCalls[tc.index]) {
+                    collectedToolCalls[tc.index] = {
+                      id: tc.id,
+                      type: tc.type,
+                      function: { name: '', arguments: '' },
+                    };
+                  }
+                  if (tc.id) collectedToolCalls[tc.index].id = tc.id;
+                  if (tc.function?.name) collectedToolCalls[tc.index].function.name += tc.function.name;
+                  if (tc.function?.arguments) collectedToolCalls[tc.index].function.arguments += tc.function.arguments;
+                }
+              }
+
+              if (chunk.usage) {
+                usage = chunk.usage;
+              }
+
+              yield chunk;
+            }
+
+            // After stream completes, end the span
+            if (span) {
+              await span.end({
+                output: collectedContent || collectedToolCalls,
+                ttft,
+                tokens: usage
+                  ? {
+                      prompt: usage.prompt_tokens,
+                      completion: usage.completion_tokens,
+                      total: usage.total_tokens,
+                    }
+                  : undefined,
+              });
+            }
+          };
+
+          response[Symbol.asyncIterator] = wrappedIterator;
+          return response;
+        }
+
+        // Non-streaming response
+        const endTime = Date.now();
+        const choice = response.choices?.[0];
+        const output = choice?.message?.content;
+        const toolCalls = choice?.message?.tool_calls;
+
+        if (span) {
+          await span.end({
+            output: output || toolCalls,
+            ttft: endTime - startTime,
+            tokens: response.usage
+              ? {
+                  prompt: response.usage.prompt_tokens,
+                  completion: response.usage.completion_tokens,
+                  total: response.usage.total_tokens,
+                }
+              : undefined,
+          });
+        }
+
+        return response;
+      } catch (error) {
+        if (span) {
+          await span.end({ error: { type: error.name, message: error.message } });
+        }
+        throw error;
+      }
+    };
+
+    return openai;
+  }
+
+  /**
+   * Create a tool executor that automatically traces tool calls
+   * @param {Object} tools - Map of tool name to function
+   * @param {TraceContext} context - Current trace context
+   * @returns {Function} Tool executor function
+   */
+  createToolExecutor(tools, context) {
+    return async (toolCall) => {
+      const toolName = toolCall.function?.name || toolCall.name;
+      const toolFn = tools[toolName];
+
+      if (!toolFn) {
+        throw new Error(`Tool not found: ${toolName}`);
+      }
+
+      let args = toolCall.function?.arguments || toolCall.arguments;
+      if (typeof args === 'string') {
+        try {
+          args = JSON.parse(args);
+        } catch {
+          // Keep as string if not valid JSON
+        }
+      }
+
+      return context.tool(toolName, async () => {
+        return toolFn(args);
+      }, { input: args });
+    };
+  }
+}
+
+/**
+ * Create LangChain callback handler for automatic tracing
+ * @param {FoilTracer} tracer - Foil tracer instance
+ * @param {Object} [options] - Callback options
+ * @returns {Object} LangChain callback handler
+ */
+function createLangChainCallback(tracer, options = {}) {
+  const traceId = options.traceId || crypto.randomUUID();
+  // Store complete span data locally, keyed by runId
+  const spanDataMap = new Map();
+
+  return {
+    name: 'FoilTracingCallback',
+
+    async handleLLMStart(llm, prompts, runId, parentRunId, extraParams) {
+      const spanId = crypto.randomUUID();
+      const startTime = Date.now();
+
+      // Find parent span from stack
+      let parentSpanId = null;
+      for (const [, data] of spanDataMap) {
+        if (data.runId === parentRunId) {
+          parentSpanId = data.spanId;
+          break;
+        }
+      }
+
+      // Extract LLM config from extraParams or llm object
+      const invocationParams = extraParams?.invocation_params || {};
+      const llmConfig = {
+        temperature: invocationParams.temperature ?? llm.temperature,
+        maxTokens: invocationParams.max_tokens ?? llm.maxTokens,
+        topP: invocationParams.top_p ?? llm.topP,
+        frequencyPenalty: invocationParams.frequency_penalty,
+        presencePenalty: invocationParams.presence_penalty,
+        tools: invocationParams.tools || invocationParams.functions,
+        responseFormat: invocationParams.response_format,
+        stopSequences: invocationParams.stop,
+        seed: invocationParams.seed,
+      };
+
+      // Store complete span data locally
+      spanDataMap.set(runId, {
+        spanId,
+        runId,
+        startTime,
+        name: llm.name || 'unknown',
+        agentName: tracer.agentName,
+        traceId,
+        parentSpanId,
+        spanKind: SpanKind.LLM,
+        model: llm.name,
+        input: prompts,
+        llmConfig,
+      });
+    },
+
+    async handleLLMEnd(output, runId) {
+      const spanData = spanDataMap.get(runId);
+      if (!spanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...spanData,
+        output: output.generations?.[0]?.[0]?.text,
+        timing: { totalDuration: endTime - spanData.startTime },
+        tokens: output.llmOutput?.tokenUsage,
+        startTime: new Date(spanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      spanDataMap.delete(runId);
+    },
+
+    async handleLLMError(err, runId) {
+      const spanData = spanDataMap.get(runId);
+      if (!spanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...spanData,
+        error: { type: err.name, message: err.message },
+        timing: { totalDuration: endTime - spanData.startTime },
+        startTime: new Date(spanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      spanDataMap.delete(runId);
+    },
+
+    async handleToolStart(tool, input, runId, parentRunId) {
+      const spanId = crypto.randomUUID();
+      const startTime = Date.now();
+
+      // Find parent span
+      let parentSpanId = null;
+      for (const [, data] of spanDataMap) {
+        if (data.runId === parentRunId) {
+          parentSpanId = data.spanId;
+          break;
+        }
+      }
+
+      spanDataMap.set(runId, {
+        spanId,
+        runId,
+        startTime,
+        name: tool.name || 'unknown',
+        agentName: tracer.agentName,
+        traceId,
+        parentSpanId,
+        spanKind: SpanKind.TOOL,
+        input,
+      });
+    },
+
+    async handleToolEnd(output, runId) {
+      const spanData = spanDataMap.get(runId);
+      if (!spanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...spanData,
+        output,
+        timing: { totalDuration: endTime - spanData.startTime },
+        startTime: new Date(spanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      spanDataMap.delete(runId);
+    },
+
+    async handleToolError(err, runId) {
+      const spanData = spanDataMap.get(runId);
+      if (!spanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...spanData,
+        error: { type: err.name, message: err.message },
+        timing: { totalDuration: endTime - spanData.startTime },
+        startTime: new Date(spanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      spanDataMap.delete(runId);
+    },
+
+    async handleChainStart(chain, inputs, runId, parentRunId) {
+      const spanId = crypto.randomUUID();
+      const startTime = Date.now();
+
+      // Find parent span
+      let parentSpanId = null;
+      for (const [, data] of spanDataMap) {
+        if (data.runId === parentRunId) {
+          parentSpanId = data.spanId;
+          break;
+        }
+      }
+
+      spanDataMap.set(runId, {
+        spanId,
+        runId,
+        startTime,
+        name: chain.name || 'unknown',
+        agentName: tracer.agentName,
+        traceId,
+        parentSpanId,
+        spanKind: SpanKind.CHAIN,
+        input: inputs,
+      });
+    },
+
+    async handleChainEnd(outputs, runId) {
+      const spanData = spanDataMap.get(runId);
+      if (!spanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...spanData,
+        output: outputs,
+        timing: { totalDuration: endTime - spanData.startTime },
+        startTime: new Date(spanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      spanDataMap.delete(runId);
+    },
+
+    async handleChainError(err, runId) {
+      const spanData = spanDataMap.get(runId);
+      if (!spanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...spanData,
+        error: { type: err.name, message: err.message },
+        timing: { totalDuration: endTime - spanData.startTime },
+        startTime: new Date(spanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      spanDataMap.delete(runId);
+    },
+
+    async handleRetrieverStart(retriever, query, runId, parentRunId) {
+      const spanId = crypto.randomUUID();
+      const startTime = Date.now();
+
+      // Find parent span
+      let parentSpanId = null;
+      for (const [, data] of spanDataMap) {
+        if (data.runId === parentRunId) {
+          parentSpanId = data.spanId;
+          break;
+        }
+      }
+
+      spanDataMap.set(runId, {
+        spanId,
+        runId,
+        startTime,
+        name: retriever.name || 'unknown',
+        agentName: tracer.agentName,
+        traceId,
+        parentSpanId,
+        spanKind: SpanKind.RETRIEVER,
+        input: query,
+      });
+    },
+
+    async handleRetrieverEnd(documents, runId) {
+      const spanData = spanDataMap.get(runId);
+      if (!spanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...spanData,
+        output: documents,
+        timing: { totalDuration: endTime - spanData.startTime },
+        startTime: new Date(spanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      spanDataMap.delete(runId);
+    },
+
+    async handleRetrieverError(err, runId) {
+      const spanData = spanDataMap.get(runId);
+      if (!spanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...spanData,
+        error: { type: err.name, message: err.message },
+        timing: { totalDuration: endTime - spanData.startTime },
+        startTime: new Date(spanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      spanDataMap.delete(runId);
+    },
+  };
+}
+
+/**
+ * Create Vercel AI SDK callbacks for automatic tracing
+ * @param {FoilTracer} tracer - Foil tracer instance
+ * @param {Object} [options] - Callback options
+ * @returns {Object} Vercel AI SDK callbacks
+ */
+function createVercelAICallbacks(tracer, options = {}) {
+  const traceId = options.traceId || crypto.randomUUID();
+  // Store complete span data locally
+  let currentSpanData = null;
+  let toolSpanDataMap = new Map();
+
+  return {
+    onStart: async ({ messages, model, ...params }) => {
+      const spanId = crypto.randomUUID();
+      const startTime = Date.now();
+
+      // Extract system prompt from messages
+      const systemMessage = messages?.find(m => m.role === 'system');
+      const systemPrompt = systemMessage?.content;
+
+      // Store complete span data locally (no server call)
+      currentSpanData = {
+        spanId,
+        startTime,
+        name: model || 'unknown',
+        agentName: tracer.agentName,
+        traceId,
+        parentSpanId: options.parentSpanId,
+        spanKind: SpanKind.LLM,
+        model,
+        input: messages,
+        // LLM Configuration for replay/debugging
+        llmConfig: {
+          temperature: params.temperature,
+          maxTokens: params.maxTokens || params.max_tokens,
+          topP: params.topP || params.top_p,
+          frequencyPenalty: params.frequencyPenalty || params.frequency_penalty,
+          presencePenalty: params.presencePenalty || params.presence_penalty,
+          systemPrompt,
+          tools: params.tools,
+          responseFormat: params.responseFormat || params.response_format,
+          stopSequences: params.stop || params.stopSequences,
+          seed: params.seed,
+        },
+      };
+    },
+
+    onToken: async (token) => {
+      // First token received - could track TTFT here
+    },
+
+    onToolCall: async ({ toolCall }) => {
+      const spanId = crypto.randomUUID();
+      const startTime = Date.now();
+
+      // Store complete tool span data locally
+      toolSpanDataMap.set(toolCall.toolCallId, {
+        spanId,
+        startTime,
+        name: toolCall.toolName,
+        agentName: tracer.agentName,
+        traceId,
+        parentSpanId: currentSpanData?.spanId,
+        spanKind: SpanKind.TOOL,
+        input: toolCall.args,
+      });
+    },
+
+    onToolResult: async ({ toolCallId, result }) => {
+      const toolSpanData = toolSpanDataMap.get(toolCallId);
+      if (!toolSpanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...toolSpanData,
+        output: result,
+        timing: { totalDuration: endTime - toolSpanData.startTime },
+        startTime: new Date(toolSpanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      toolSpanDataMap.delete(toolCallId);
+    },
+
+    onFinish: async ({ text, toolCalls, usage, finishReason }) => {
+      if (!currentSpanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...currentSpanData,
+        output: text || toolCalls,
+        timing: { totalDuration: endTime - currentSpanData.startTime },
+        tokens: usage
+          ? {
+              prompt: usage.promptTokens,
+              completion: usage.completionTokens,
+              total: usage.totalTokens,
+            }
+          : undefined,
+        startTime: new Date(currentSpanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      currentSpanData = null;
+    },
+
+    onError: async (error) => {
+      if (!currentSpanData) return;
+
+      const endTime = Date.now();
+      const completeSpanData = {
+        ...currentSpanData,
+        error: { type: error.name, message: error.message },
+        timing: { totalDuration: endTime - currentSpanData.startTime },
+        startTime: new Date(currentSpanData.startTime).toISOString(),
+        endTime: new Date(endTime).toISOString(),
+      };
+
+      await tracer.foil.endSpan(completeSpanData).catch(() => {});
+      currentSpanData = null;
+    },
+  };
+}
+
+/**
+ * Factory function to create a FoilTracer
+ * @param {Object} options - Tracer options
+ * @param {string} options.apiKey - Foil API key
+ * @param {string} options.agentName - Name of the agent
+ * @param {string} [options.baseUrl] - Foil API base URL
+ * @param {string} [options.defaultModel] - Default model name
+ * @param {boolean} [options.debug] - Enable debug logging (also enabled via FOIL_DEBUG=true env var)
+ * @returns {FoilTracer} Configured tracer instance
+ */
+function createFoilTracer(options = {}) {
+  if (!options.apiKey) {
+    throw new Error('apiKey is required');
+  }
+  if (!options.agentName) {
+    throw new Error('agentName is required');
+  }
+
+  const foil = new Foil({
+    apiKey: options.apiKey,
+    baseUrl: options.baseUrl,
+  });
+
+  return new FoilTracer(foil, {
+    agentName: options.agentName,
+    defaultModel: options.defaultModel,
+    debug: options.debug,
+  });
+}
+
+class Foil {
+  constructor(options = {}) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl || 'https://api.getfoil.ai/api';
+  }
+
+  /**
+   * Generate a unique trace ID
+   * @returns {string} A unique trace ID
+   */
+  createTraceId() {
+    return crypto.randomUUID();
+  }
+
+  /**
+   * Generate a unique span ID
+   * @returns {string} A unique span ID
+   */
+  createSpanId() {
+    return crypto.randomUUID();
+  }
+
+  /**
+   * Start a span (signals the beginning of an operation)
+   * @param {Object} data - Span data
+   * @param {string} data.spanId - Unique identifier for this span
+   * @param {string} data.name - Name of the span (model name, tool name, etc.)
+   * @param {string} data.agentName - Name of the agent (must be unique per user)
+   * @param {string} [data.input] - Input to the operation
+   * @param {string} [data.model] - Model name/identifier (for LLM spans)
+   * @param {string} [data.sessionId] - Session/conversation identifier
+   * @param {Object} [data.properties] - Additional custom properties
+   * @param {string} [data.traceId] - Trace ID for grouping related spans
+   * @param {string} [data.parentSpanId] - Parent span ID for nested spans
+   * @param {string} [data.spanKind] - Span kind ('agent', 'llm', 'tool', 'chain', 'retriever', 'embedding', 'custom')
+   * @returns {Promise<Object>} The created span object
+   */
+  async startSpan(data) {
+    if (!data.agentName) {
+      throw new Error('agentName is required');
+    }
+    try {
+      const response = await axios.post(`${this.baseUrl}/traces/spans/start`, data, {
+        headers: {
+          Authorization: this.apiKey,
+        },
+      });
+      return response.data;
+    } catch (error) {
+      const errDetails = error.response?.data || error.message;
+      console.error('Foil Start Span Failed:', JSON.stringify(errDetails));
+      throw error;
+    }
+  }
+
+  /**
+   * End a span (signals the completion of an operation)
+   * @param {Object} data - End span data
+   * @param {string} data.spanId - The spanId of the span to end
+   * @param {string} [data.agentName] - Agent name (fallback if start span not yet processed)
+   * @param {*} [data.output] - Output from the operation
+   * @param {Object} [data.tokens] - Token usage {prompt, completion, total}
+   * @param {Object} [data.timing] - Timing metrics {ttft, totalDuration}
+   * @param {Object} [data.error] - Error if operation failed {type, message}
+   * @returns {Promise<Object>} The updated span object
+   */
+  async endSpan(data) {
+    try {
+      const response = await axios.post(`${this.baseUrl}/traces/spans/end`, data, {
+        headers: {
+          Authorization: this.apiKey,
+        },
+      });
+      return response.data;
+    } catch (error) {
+      console.error('Foil End Span Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get a trace with all its spans
+   * @param {string} traceId - The trace ID
+   * @returns {Promise<Object>} The trace data with spans and tree structure
+   */
+  async getTrace(traceId) {
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/traces/${traceId}`,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Trace Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * List traces with optional filtering
+   * @param {Object} [options] - Query options
+   * @param {number} [options.page] - Page number
+   * @param {number} [options.limit] - Results per page
+   * @param {string} [options.agentName] - Filter by agent name
+   * @param {string} [options.status] - Filter by status
+   * @param {string} [options.from] - Start date (ISO string)
+   * @param {string} [options.to] - End date (ISO string)
+   * @returns {Promise<Object>} Paginated trace results
+   */
+  async listTraces(options = {}) {
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/traces`,
+        {
+          params: options,
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil List Traces Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Record a signal (user feedback, LLM analysis, etc.)
+   * @param {Object} data - Signal data
+   * @param {string} data.signalName - Name of the signal (e.g., 'user_thumbs', 'sentiment')
+   * @param {boolean|number|string} data.value - Signal value
+   * @param {string} [data.traceId] - Associated trace ID
+   * @param {string} [data.spanId] - Associated span ID
+   * @param {string} [data.sessionId] - Associated session ID
+   * @param {string} [data.agentId] - Agent ID
+   * @param {string} [data.agentName] - Agent name
+   * @param {string} [data.signalType] - Type (feedback, sentiment, quality, completion, safety, effort, engagement, custom)
+   * @param {string} [data.source] - Source (user, llm, system)
+   * @param {string} [data.valueType] - Explicit value type (boolean, number, category, text)
+   * @param {Object} [data.metadata] - Additional metadata
+   * @param {number} [data.confidence] - Confidence score 0-1 (for LLM signals)
+   * @param {string} [data.reasoning] - LLM reasoning (for LLM signals)
+   * @param {string} [data.modelUsed] - Model used (for LLM signals)
+   * @returns {Promise<Object>} The recorded signal
+   */
+  async recordSignal(data) {
+    try {
+      const response = await axios.post(
+        `${this.baseUrl}/signals`,
+        data,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Record Signal Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Record multiple signals in batch
+   * @param {Array<Object>} signals - Array of signal objects (same format as recordSignal)
+   * @returns {Promise<Object>} The recorded signals
+   */
+  async recordSignalBatch(signals) {
+    try {
+      const response = await axios.post(
+        `${this.baseUrl}/signals/batch`,
+        { signals },
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Record Signal Batch Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get signals for a trace
+   * @param {string} traceId - The trace ID
+   * @returns {Promise<Object>} Signals associated with the trace
+   */
+  async getTraceSignals(traceId) {
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/signals/trace/${traceId}`,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Trace Signals Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get variant assignment for an experiment
+   * Uses deterministic hashing so the same identifier always gets the same variant
+   * @param {string} experimentId - The experiment ID
+   * @param {string} identifier - Unique identifier (userId, sessionId, etc.) for consistent assignment
+   * @returns {Promise<Object>} Assignment result with variant details
+   * @returns {boolean} result.inExperiment - Whether the identifier is in the experiment
+   * @returns {string} [result.experimentId] - The experiment ID
+   * @returns {string} [result.experimentName] - The experiment name
+   * @returns {string} [result.variantId] - Assigned variant ID
+   * @returns {string} [result.variantName] - Assigned variant name
+   * @returns {Object} [result.config] - Variant configuration (model, systemPrompt, temperature, etc.)
+   * @returns {string} [result.message] - Message if excluded from experiment
+   */
+  async getExperimentVariant(experimentId, identifier) {
+    if (!experimentId) {
+      throw new Error('experimentId is required');
+    }
+    if (!identifier) {
+      throw new Error('identifier is required');
+    }
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/experiments/${experimentId}/assign`,
+        {
+          params: { identifier },
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Experiment Variant Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Upload a media file for multimodal spans
+   * @param {string|Buffer|ReadStream} file - File path, Buffer, or ReadStream
+   * @param {Object} [options] - Upload options
+   * @param {string} [options.filename] - Override filename (required for Buffer)
+   * @param {string} [options.mimeType] - Override MIME type
+   * @param {string} [options.spanId] - Associate with a span
+   * @param {string} [options.traceId] - Associate with a trace
+   * @param {string} [options.direction] - 'input' or 'output'
+   * @returns {Promise<Object>} Upload result with mediaId and category
+   */
+  async uploadMedia(file, options = {}) {
+    try {
+      const form = new FormData();
+
+      // Handle different input types
+      if (typeof file === 'string') {
+        // File path
+        const filename = options.filename || path.basename(file);
+        form.append('file', fs.createReadStream(file), {
+          filename,
+          contentType: options.mimeType,
+        });
+      } else if (Buffer.isBuffer(file)) {
+        // Buffer - filename is required
+        if (!options.filename) {
+          throw new Error('filename is required when uploading a Buffer');
+        }
+        form.append('file', file, {
+          filename: options.filename,
+          contentType: options.mimeType,
+        });
+      } else if (file && typeof file.pipe === 'function') {
+        // ReadStream
+        const filename = options.filename || (file.path ? path.basename(file.path) : 'upload');
+        form.append('file', file, {
+          filename,
+          contentType: options.mimeType,
+        });
+      } else {
+        throw new Error('file must be a path string, Buffer, or ReadStream');
+      }
+
+      // Add optional fields
+      if (options.spanId) form.append('spanId', options.spanId);
+      if (options.traceId) form.append('traceId', options.traceId);
+      if (options.direction) form.append('direction', options.direction);
+
+      const response = await axios.post(`${this.baseUrl}/media/upload`, form, {
+        headers: {
+          ...form.getHeaders(),
+          Authorization: this.apiKey,
+        },
+        maxContentLength: Infinity,
+        maxBodyLength: Infinity,
+      });
+
+      return response.data;
+    } catch (error) {
+      const errDetails = error.response?.data || error.message;
+      console.error('Foil Upload Media Failed:', JSON.stringify(errDetails));
+      throw error;
+    }
+  }
+
+  /**
+   * Get media information by ID
+   * @param {string} mediaId - The media ID
+   * @param {Object} [options] - Options
+   * @param {string} [options.content] - Content type to get URL for ('original', 'extracted', 'preview', 'structured')
+   * @returns {Promise<Object>} Media information
+   */
+  async getMedia(mediaId, options = {}) {
+    try {
+      const response = await axios.get(`${this.baseUrl}/media/${mediaId}`, {
+        params: { content: options.content },
+        headers: {
+          Authorization: this.apiKey,
+        },
+      });
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Media Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get presigned download URL for media content
+   * @param {string} mediaId - The media ID
+   * @param {string} [content='original'] - Content type ('original', 'extracted', 'preview', 'structured')
+   * @returns {Promise<Object>} Presigned URL info
+   */
+  async getMediaUrl(mediaId, content = 'original') {
+    try {
+      const response = await axios.get(`${this.baseUrl}/media/${mediaId}/url`, {
+        params: { content },
+        headers: {
+          Authorization: this.apiKey,
+        },
+      });
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Media URL Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get information for multiple media IDs
+   * @param {string[]} mediaIds - Array of media IDs
+   * @returns {Promise<Object>} Batch media info
+   */
+  async batchMediaInfo(mediaIds) {
+    try {
+      const response = await axios.post(
+        `${this.baseUrl}/media/batch`,
+        { mediaIds },
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Batch Media Info Failed:', error.message);
+      throw error;
+    }
+  }
+
+  // ============================================
+  // Semantic Search Methods
+  // ============================================
+
+  /**
+   * Search spans using natural language queries
+   * Uses AI embeddings to find semantically similar content
+   * @param {string} query - Natural language search query (e.g., "conversations about refunds")
+   * @param {Object} [options] - Search options
+   * @param {string} [options.agentId] - Filter by specific agent
+   * @param {string} [options.agentName] - Filter by agent name
+   * @param {string} [options.from] - Start date (ISO string)
+   * @param {string} [options.to] - End date (ISO string)
+   * @param {number} [options.limit=20] - Maximum results to return
+   * @param {number} [options.offset=0] - Offset for pagination
+   * @param {number} [options.threshold=0.3] - Minimum similarity threshold (0-1)
+   * @returns {Promise<Object>} Search results with similarity scores
+   * @returns {Array} result.results - Array of matching spans with similarity scores
+   * @returns {Object} result.pagination - Pagination info (total, limit, offset, hasMore)
+   * @returns {Object} result.query - Query info (text, threshold, embedding status)
+   * @example
+   * const results = await foil.semanticSearch('conversations about refunds', {
+   *   agentId: 'agent-123',
+   *   limit: 10,
+   *   threshold: 0.4
+   * });
+   */
+  async semanticSearch(query, options = {}) {
+    if (!query || typeof query !== 'string') {
+      throw new Error('query is required and must be a string');
+    }
+    try {
+      const response = await axios.post(
+        `${this.baseUrl}/semantic-search/query`,
+        {
+          query,
+          filters: {
+            agentId: options.agentId,
+            agentName: options.agentName,
+            from: options.from,
+            to: options.to,
+          },
+          limit: options.limit,
+          offset: options.offset,
+          threshold: options.threshold,
+        },
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Semantic Search Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Find traces similar to a given trace
+   * Uses the trace's content embeddings to find related conversations
+   * @param {string} traceId - The trace ID to find similar traces for
+   * @param {Object} [options] - Search options
+   * @param {number} [options.limit=10] - Maximum results to return
+   * @param {number} [options.threshold=0.3] - Minimum similarity threshold (0-1)
+   * @returns {Promise<Object>} Similar traces with similarity scores
+   * @returns {Array} result.results - Array of similar traces
+   * @returns {Object} result.sourceTrace - Info about the source trace
+   * @example
+   * const similar = await foil.findSimilarTraces('trace-abc-123', {
+   *   limit: 5,
+   *   threshold: 0.5
+   * });
+   */
+  async findSimilarTraces(traceId, options = {}) {
+    if (!traceId) {
+      throw new Error('traceId is required');
+    }
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/semantic-search/similar/${traceId}`,
+        {
+          params: {
+            limit: options.limit,
+            threshold: options.threshold,
+          },
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Find Similar Traces Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get semantic search status and embedding statistics
+   * Shows how many spans have been embedded and are searchable
+   * @param {string} [agentId] - Optional agent ID to get stats for specific agent
+   * @returns {Promise<Object>} Embedding status and statistics
+   * @returns {number} result.embeddedSpans - Number of spans with embeddings
+   * @returns {number} result.totalSpans - Total eligible spans
+   * @returns {number} result.coveragePercent - Percentage of spans embedded
+   * @returns {boolean} result.ready - Whether semantic search is ready
+   */
+  async getSemanticSearchStatus(agentId) {
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/semantic-search/status`,
+        {
+          params: agentId ? { agentId } : {},
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Semantic Search Status Failed:', error.message);
+      throw error;
+    }
+  }
+
+  // ============================================
+  // Custom Evaluation Methods
+  // ============================================
+
+  /**
+   * Get available evaluation templates
+   * Templates are pre-built evaluation criteria that can be cloned and customized
+   * @returns {Promise<Object>} List of available evaluation templates
+   * @returns {Array} result.templates - Array of template objects
+   * @returns {Array} result.builtin - Built-in evaluation types
+   */
+  async getEvaluationTemplates() {
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/evaluations/templates`,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Evaluation Templates Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get evaluations configured for an agent
+   * @param {string} agentId - The agent ID
+   * @returns {Promise<Object>} List of evaluations for the agent
+   * @returns {Array} result.evaluations - Array of evaluation configurations
+   */
+  async getAgentEvaluations(agentId) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/agents/${agentId}/evaluations`,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Agent Evaluations Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get a specific evaluation by ID
+   * @param {string} agentId - The agent ID
+   * @param {string} evaluationId - The evaluation ID
+   * @returns {Promise<Object>} Evaluation details
+   */
+  async getEvaluation(agentId, evaluationId) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!evaluationId) {
+      throw new Error('evaluationId is required');
+    }
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/agents/${agentId}/evaluations/${evaluationId}`,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Evaluation Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Create a custom evaluation for an agent
+   * Custom evaluations define criteria for analyzing agent responses
+   * @param {string} agentId - The agent ID to create evaluation for
+   * @param {Object} data - Evaluation configuration
+   * @param {string} data.name - Unique name for the evaluation
+   * @param {string} data.description - Description of what this evaluation checks
+   * @param {string} data.prompt - The evaluation prompt/criteria
+   * @param {string} [data.evaluationType='boolean'] - Result type: 'boolean', 'score', 'category'
+   * @param {Array} [data.categories] - Categories if evaluationType is 'category'
+   * @param {number} [data.scoreMin] - Minimum score if evaluationType is 'score'
+   * @param {number} [data.scoreMax] - Maximum score if evaluationType is 'score'
+   * @param {boolean} [data.enabled=true] - Whether evaluation is active
+   * @param {Array} [data.examples] - Example inputs/outputs for few-shot learning
+   * @returns {Promise<Object>} Created evaluation
+   * @example
+   * const evaluation = await foil.createEvaluation('agent-123', {
+   *   name: 'tone_check',
+   *   description: 'Checks if response maintains professional tone',
+   *   prompt: 'Evaluate if the assistant response maintains a professional and helpful tone. Return true if professional, false otherwise.',
+   *   evaluationType: 'boolean',
+   *   enabled: true
+   * });
+   */
+  async createEvaluation(agentId, data) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!data.name) {
+      throw new Error('evaluation name is required');
+    }
+    if (!data.prompt) {
+      throw new Error('evaluation prompt is required');
+    }
+    try {
+      const response = await axios.post(
+        `${this.baseUrl}/agents/${agentId}/evaluations`,
+        data,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      const errDetails = error.response?.data || error.message;
+      console.error('Foil Create Evaluation Failed:', JSON.stringify(errDetails));
+      throw error;
+    }
+  }
+
+  /**
+   * Update an existing evaluation
+   * @param {string} agentId - The agent ID
+   * @param {string} evaluationId - The evaluation ID to update
+   * @param {Object} data - Fields to update
+   * @param {string} [data.name] - New name
+   * @param {string} [data.description] - New description
+   * @param {string} [data.prompt] - New evaluation prompt
+   * @param {boolean} [data.enabled] - Enable/disable the evaluation
+   * @returns {Promise<Object>} Updated evaluation
+   */
+  async updateEvaluation(agentId, evaluationId, data) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!evaluationId) {
+      throw new Error('evaluationId is required');
+    }
+    try {
+      const response = await axios.put(
+        `${this.baseUrl}/agents/${agentId}/evaluations/${evaluationId}`,
+        data,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Update Evaluation Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Delete an evaluation
+   * @param {string} agentId - The agent ID
+   * @param {string} evaluationId - The evaluation ID to delete
+   * @returns {Promise<Object>} Deletion confirmation
+   */
+  async deleteEvaluation(agentId, evaluationId) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!evaluationId) {
+      throw new Error('evaluationId is required');
+    }
+    try {
+      const response = await axios.delete(
+        `${this.baseUrl}/agents/${agentId}/evaluations/${evaluationId}`,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Delete Evaluation Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Test an evaluation with sample input/output
+   * Useful for validating evaluation prompts before enabling
+   * @param {string} agentId - The agent ID
+   * @param {string} evaluationId - The evaluation ID to test
+   * @param {Object} data - Test data
+   * @param {string} data.input - Sample user input
+   * @param {string} data.output - Sample assistant output
+   * @returns {Promise<Object>} Test results with evaluation outcome
+   * @returns {boolean|number|string} result.result - Evaluation result
+   * @returns {string} result.reasoning - Explanation for the result
+   */
+  async testEvaluation(agentId, evaluationId, data) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!evaluationId) {
+      throw new Error('evaluationId is required');
+    }
+    try {
+      const response = await axios.post(
+        `${this.baseUrl}/agents/${agentId}/evaluations/${evaluationId}/test`,
+        data,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Test Evaluation Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Clone an evaluation template to an agent
+   * Creates a customizable copy of a pre-built evaluation template
+   * @param {string} agentId - The agent ID to clone the template to
+   * @param {string} templateId - The template ID to clone
+   * @returns {Promise<Object>} Cloned evaluation
+   */
+  async cloneEvaluationTemplate(agentId, templateId) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!templateId) {
+      throw new Error('templateId is required');
+    }
+    try {
+      const response = await axios.post(
+        `${this.baseUrl}/agents/${agentId}/evaluations/templates/${templateId}/clone`,
+        {},
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Clone Evaluation Template Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Add an example to an evaluation for few-shot learning
+   * Examples help improve evaluation accuracy
+   * @param {string} agentId - The agent ID
+   * @param {string} evaluationId - The evaluation ID
+   * @param {Object} data - Example data
+   * @param {string} data.input - Example user input
+   * @param {string} data.output - Example assistant output
+   * @param {boolean|number|string} data.expectedResult - Expected evaluation result
+   * @param {string} [data.reasoning] - Explanation for the expected result
+   * @returns {Promise<Object>} Updated evaluation with new example
+   */
+  async addEvaluationExample(agentId, evaluationId, data) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!evaluationId) {
+      throw new Error('evaluationId is required');
+    }
+    try {
+      const response = await axios.post(
+        `${this.baseUrl}/agents/${agentId}/evaluations/${evaluationId}/examples`,
+        data,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Add Evaluation Example Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Remove an example from an evaluation
+   * @param {string} agentId - The agent ID
+   * @param {string} evaluationId - The evaluation ID
+   * @param {string} exampleId - The example ID to remove
+   * @returns {Promise<Object>} Updated evaluation
+   */
+  async removeEvaluationExample(agentId, evaluationId, exampleId) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!evaluationId) {
+      throw new Error('evaluationId is required');
+    }
+    if (!exampleId) {
+      throw new Error('exampleId is required');
+    }
+    try {
+      const response = await axios.delete(
+        `${this.baseUrl}/agents/${agentId}/evaluations/${evaluationId}/examples/${exampleId}`,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Remove Evaluation Example Failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get analytics for an evaluation
+   * Shows how the evaluation has performed over time
+   * @param {string} agentId - The agent ID
+   * @param {string} evaluationId - The evaluation ID
+   * @returns {Promise<Object>} Evaluation analytics
+   * @returns {number} result.totalEvaluations - Total times evaluated
+   * @returns {Object} result.distribution - Result distribution
+   * @returns {Array} result.trend - Results over time
+   */
+  async getEvaluationAnalytics(agentId, evaluationId) {
+    if (!agentId) {
+      throw new Error('agentId is required');
+    }
+    if (!evaluationId) {
+      throw new Error('evaluationId is required');
+    }
+    try {
+      const response = await axios.get(
+        `${this.baseUrl}/agents/${agentId}/evaluations/${evaluationId}/analytics`,
+        {
+          headers: {
+            Authorization: this.apiKey,
+          },
+        }
+      );
+      return response.data;
+    } catch (error) {
+      console.error('Foil Get Evaluation Analytics Failed:', error.message);
+      throw error;
+    }
+  }
+}
+
+// Main export for backwards compatibility
+module.exports = Foil;
+
+// Named exports for modern usage
+module.exports.Foil = Foil;
+module.exports.FoilTracer = FoilTracer;
+module.exports.TraceContext = TraceContext;
+module.exports.SpanKind = SpanKind;
+module.exports.createFoilTracer = createFoilTracer;
+module.exports.createLangChainCallback = createLangChainCallback;
+module.exports.createVercelAICallbacks = createVercelAICallbacks;
+
+// Multimodal support exports
+module.exports.MediaCategory = MediaCategory;
+module.exports.ContentBlock = ContentBlock;
+module.exports.content = content;