@getfoil/foil-js 0.4.0

package/README.md

@@ -0,0 +1,1029 @@
+# Foil JavaScript SDK
+
+JavaScript/Node.js SDK for monitoring and logging AI agent invocations with Foil. Features distributed tracing, semantic search, custom evaluations, multimodal content support (images, documents), signals/feedback, and framework integrations.
+
+## Installation
+
+```bash
+npm install @foil/foil-js
+```
+
+## Quick Start
+
+```javascript
+const { createFoilTracer, SpanKind, content, ContentBlock, MediaCategory } = require('@foil/foil-js');
+
+// Create a tracer for your agent
+const tracer = createFoilTracer({
+  apiKey: 'your-api-key',
+  agentName: 'my-agent',
+  baseUrl: 'https://api.foil.dev/api', // or your self-hosted URL
+});
+
+// Trace an agent execution
+const result = await tracer.trace(async (ctx) => {
+  // Create an LLM span
+  const llmSpan = await ctx.startSpan(SpanKind.LLM, 'gpt-4', {
+    input: 'What is the weather like?',
+  });
+
+  // ... call your LLM ...
+
+  await llmSpan.end({
+    output: 'The weather is sunny today!',
+    tokens: { prompt: 10, completion: 8, total: 18 },
+  });
+
+  return 'Agent completed';
+}, {
+  name: 'weather-query',
+  input: 'User asked about weather',
+});
+```
+
+## Table of Contents
+
+- [Distributed Tracing](#distributed-tracing)
+- [Semantic Search](#semantic-search)
+- [Custom Evaluations](#custom-evaluations)
+- [Multimodal Content](#multimodal-content)
+- [Signals & Feedback](#signals--feedback)
+- [Framework Integrations](#framework-integrations)
+- [OpenTelemetry Integration](#opentelemetry-integration)
+- [Experiments (A/B Testing)](#experiments-ab-testing)
+- [Low-Level API](#low-level-api)
+- [Debug Mode](#debug-mode)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+
+## Distributed Tracing
+
+### Basic Tracing
+
+The tracer captures the full lifecycle of your AI agent: prompts → LLM calls → tool executions → responses.
+
+```javascript
+const tracer = createFoilTracer({
+  apiKey: 'your-api-key',
+  agentName: 'customer-support-agent',
+});
+
+await tracer.trace(async (ctx) => {
+  // LLM span for the main model call
+  const llm = await ctx.startSpan(SpanKind.LLM, 'gpt-4-turbo', {
+    input: messages,
+  });
+
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4-turbo',
+    messages,
+  });
+
+  await llm.end({
+    output: response.choices[0].message.content,
+    tokens: {
+      prompt: response.usage.prompt_tokens,
+      completion: response.usage.completion_tokens,
+      total: response.usage.total_tokens,
+    },
+  });
+
+  return response.choices[0].message.content;
+}, {
+  name: 'support-query',
+  input: userMessage,
+  sessionId: conversationId, // Group traces by conversation
+});
+```
+
+### Span Kinds
+
+```javascript
+const { SpanKind } = require('@foil/foil-js');
+
+SpanKind.AGENT      // Root agent span (automatic for trace())
+SpanKind.LLM        // Language model calls
+SpanKind.TOOL       // Tool/function executions
+SpanKind.CHAIN      // Chain of operations
+SpanKind.RETRIEVER  // RAG retrieval operations
+SpanKind.EMBEDDING  // Embedding model calls
+SpanKind.CUSTOM     // Custom operation types
+```
+
+### Nested Spans
+
+Spans automatically nest based on the call stack:
+
+```javascript
+await tracer.trace(async (ctx) => {
+  // LLM decides to use a tool
+  const llmSpan = await ctx.startSpan(SpanKind.LLM, 'gpt-4', {
+    input: 'Find customer order #12345',
+  });
+
+  // Tool execution (automatically becomes child of LLM span)
+  const result = await ctx.tool('lookup_order', async () => {
+    return await database.findOrder('12345');
+  }, {
+    input: { orderId: '12345' },
+  });
+
+  await llmSpan.end({
+    output: `Order found: ${JSON.stringify(result)}`,
+  });
+}, { name: 'order-lookup' });
+```
+
+### Convenience Methods
+
+```javascript
+// Wrap tool execution
+await ctx.tool('search_database', async () => {
+  return await db.search(query);
+}, { input: { query } });
+
+// Wrap retriever operation
+await ctx.retriever('vector_store', async () => {
+  return await vectorStore.similaritySearch(query, 5);
+}, { input: query });
+
+// Wrap embedding operation
+await ctx.embedding('text-embedding-3-small', async () => {
+  return await openai.embeddings.create({ input: text, model: 'text-embedding-3-small' });
+}, { input: text });
+```
+
+## Semantic Search
+
+Search through your traces using natural language queries. Foil automatically embeds your trace content and enables AI-powered semantic search.
+
+### Basic Search
+
+```javascript
+const Foil = require('@foil/foil-js');
+
+const foil = new Foil({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.foil.dev/api',
+});
+
+// Search for conversations about a topic
+const results = await foil.semanticSearch('conversations about refund requests');
+
+console.log(`Found ${results.results.length} matching traces`);
+results.results.forEach((result) => {
+  console.log(`Trace: ${result.traceId}, Similarity: ${(result.similarity * 100).toFixed(1)}%`);
+});
+```
+
+### Search with Filters
+
+```javascript
+const results = await foil.semanticSearch('user asking about pricing', {
+  agentId: 'customer-support-agent',  // Filter by specific agent
+  agentName: 'support-bot',           // Or filter by agent name
+  from: '2024-01-01',                 // Start date (ISO format)
+  to: '2024-12-31',                   // End date (ISO format)
+  limit: 10,                          // Max results (default: 20)
+  offset: 0,                          // Pagination offset
+  threshold: 0.4,                     // Min similarity score 0-1 (default: 0.3)
+});
+```
+
+### Find Similar Traces
+
+Find traces that are semantically similar to a specific trace:
+
+```javascript
+// Find traces similar to a known trace
+const similar = await foil.findSimilarTraces('trace-abc-123', {
+  limit: 5,
+  threshold: 0.4,
+});
+
+console.log(`Found ${similar.results.length} similar traces`);
+similar.results.forEach((result) => {
+  console.log(`${result.traceId}: ${(result.similarity * 100).toFixed(1)}% similar`);
+});
+```
+
+### Check Semantic Search Status
+
+```javascript
+// Get overall embedding status
+const status = await foil.getSemanticSearchStatus();
+console.log(`Embedded: ${status.embeddedSpans} / ${status.totalSpans} spans`);
+console.log(`Coverage: ${status.coveragePercent}%`);
+console.log(`Ready: ${status.ready}`);
+
+// Get status for specific agent
+const agentStatus = await foil.getSemanticSearchStatus('my-agent-id');
+```
+
+## Custom Evaluations
+
+Define custom evaluation criteria to analyze your agent's responses. Evaluations run automatically on new traces and can be boolean, score-based, or categorical.
+
+### Get Evaluation Templates
+
+```javascript
+// List available pre-built evaluation templates
+const templates = await foil.getEvaluationTemplates();
+
+templates.templates.forEach((t) => {
+  console.log(`${t.name}: ${t.description}`);
+});
+```
+
+### Create a Boolean Evaluation
+
+```javascript
+const evaluation = await foil.createEvaluation('agent-123', {
+  name: 'professional_tone',
+  description: 'Checks if the response maintains a professional tone',
+  prompt: `Evaluate the assistant's response for professional tone.
+
+Consider:
+- Is the language respectful and courteous?
+- Does it avoid slang or casual expressions?
+- Is it helpful without being condescending?
+
+Return true if professional, false otherwise.`,
+  evaluationType: 'boolean',
+  enabled: true,
+});
+
+console.log('Created evaluation:', evaluation.evaluation.name);
+```
+
+### Create a Score Evaluation (1-10)
+
+```javascript
+const evaluation = await foil.createEvaluation('agent-123', {
+  name: 'helpfulness_score',
+  description: 'Rates response helpfulness on a scale of 1-10',
+  prompt: `Rate the helpfulness of the response on a scale of 1-10.
+
+Scoring:
+- 1-3: Unhelpful
+- 4-5: Somewhat helpful
+- 6-7: Helpful
+- 8-9: Very helpful
+- 10: Exceptional
+
+Return a single number from 1 to 10.`,
+  evaluationType: 'score',
+  scoreMin: 1,
+  scoreMax: 10,
+  enabled: true,
+});
+```
+
+### Create a Category Evaluation
+
+```javascript
+const evaluation = await foil.createEvaluation('agent-123', {
+  name: 'response_intent',
+  description: 'Categorizes the type of response',
+  prompt: `Classify the response into one category:
+
+- informational: Provides facts or explanations
+- action: Guides through a process
+- clarification: Asks for more information
+- escalation: Suggests human assistance
+- closure: Wraps up the conversation
+
+Return only the category name.`,
+  evaluationType: 'category',
+  categories: ['informational', 'action', 'clarification', 'escalation', 'closure'],
+  enabled: true,
+});
+```
+
+### Test an Evaluation
+
+Validate your evaluation prompt before enabling:
+
+```javascript
+const result = await foil.testEvaluation('agent-123', evaluationId, {
+  input: 'How do I reset my password?',
+  output: 'I\'d be happy to help! Go to Settings > Security > Reset Password.',
+});
+
+console.log('Result:', result.result);       // true/false, score, or category
+console.log('Reasoning:', result.reasoning); // Explanation
+```
+
+### Add Few-Shot Examples
+
+Improve evaluation accuracy with examples:
+
+```javascript
+// Add a positive example
+await foil.addEvaluationExample('agent-123', evaluationId, {
+  input: 'Why is my order late?',
+  output: 'I apologize for the delay. Let me check the status for you.',
+  expectedResult: true,
+  reasoning: 'Professional and helpful response',
+});
+
+// Add a negative example
+await foil.addEvaluationExample('agent-123', evaluationId, {
+  input: 'Why is my order late?',
+  output: 'idk check tracking yourself',
+  expectedResult: false,
+  reasoning: 'Casual and unhelpful',
+});
+```
+
+### Manage Evaluations
+
+```javascript
+// List all evaluations for an agent
+const evaluations = await foil.getAgentEvaluations('agent-123');
+
+// Get specific evaluation details
+const evaluation = await foil.getEvaluation('agent-123', evaluationId);
+
+// Update an evaluation
+await foil.updateEvaluation('agent-123', evaluationId, {
+  description: 'Updated description',
+  enabled: false,  // Disable temporarily
+});
+
+// Get evaluation analytics
+const analytics = await foil.getEvaluationAnalytics('agent-123', evaluationId);
+console.log('Total evaluations:', analytics.totalEvaluations);
+console.log('Distribution:', analytics.distribution);
+
+// Clone a template
+const cloned = await foil.cloneEvaluationTemplate('agent-123', templateId);
+
+// Delete an evaluation
+await foil.deleteEvaluation('agent-123', evaluationId);
+```
+
+## Multimodal Content
+
+Foil supports multimodal input/output including images, documents, and other media types.
+
+### Media Categories
+
+```javascript
+const { MediaCategory } = require('@foil/foil-js');
+
+MediaCategory.IMAGE       // Images (png, jpg, gif, webp, etc.)
+MediaCategory.DOCUMENT    // Documents (pdf, doc, docx, etc.)
+MediaCategory.SPREADSHEET // Spreadsheets (xlsx, csv, etc.)
+MediaCategory.CODE        // Code files
+MediaCategory.AUDIO       // Audio files
+MediaCategory.VIDEO       // Video files
+MediaCategory.ARCHIVE     // Archives (zip, tar, etc.)
+MediaCategory.NOTEBOOK    // Jupyter notebooks
+MediaCategory.OTHER       // Other file types
+```
+
+### Uploading Media
+
+```javascript
+const Foil = require('@foil/foil-js');
+
+const foil = new Foil({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.foil.dev/api',
+});
+
+// Upload from file path
+const result = await foil.uploadMedia('/path/to/image.png');
+console.log(result.mediaId);   // 'media_abc123'
+console.log(result.category);  // 'image'
+console.log(result.filename);  // 'image.png'
+console.log(result.mimeType);  // 'image/png'
+
+// Upload from Buffer
+const buffer = await fs.promises.readFile('/path/to/document.pdf');
+const result = await foil.uploadMedia(buffer, {
+  filename: 'document.pdf',
+  mimeType: 'application/pdf',
+});
+
+// Upload with trace/span association
+const result = await foil.uploadMedia('/path/to/image.png', {
+  traceId: 'trace_123',
+  spanId: 'span_456',
+  direction: 'input', // or 'output'
+});
+```
+
+### Content Blocks
+
+Use content blocks to create multimodal input/output:
+
+```javascript
+const { content, ContentBlock, MediaCategory } = require('@foil/foil-js');
+
+// Create multimodal content array
+const multimodalInput = content(
+  'Please analyze this image:',
+  ContentBlock.media(uploadResult.mediaId, {
+    category: MediaCategory.IMAGE,
+    filename: 'photo.jpg',
+    mimeType: 'image/jpeg',
+  }),
+  'Focus on the composition and colors.'
+);
+
+// Use in a span
+const span = await ctx.startSpan(SpanKind.LLM, 'gpt-4-vision-preview', {
+  input: multimodalInput,
+});
+```
+
+### Image Analysis Example
+
+```javascript
+const Foil = require('@foil/foil-js');
+const { createFoilTracer, SpanKind, content, ContentBlock, MediaCategory } = require('@foil/foil-js');
+
+const foil = new Foil({ apiKey: API_KEY, baseUrl: BASE_URL });
+const tracer = createFoilTracer({ apiKey: API_KEY, agentName: 'vision-agent', baseUrl: BASE_URL });
+
+// Upload the image
+const uploadResult = await foil.uploadMedia('/path/to/image.jpg');
+
+// Create a trace with multimodal content
+await tracer.trace(async (ctx) => {
+  const span = await ctx.startSpan(SpanKind.LLM, 'gpt-4-vision-preview', {
+    input: content(
+      'What objects do you see in this image?',
+      ContentBlock.media(uploadResult.mediaId, {
+        category: MediaCategory.IMAGE,
+        filename: uploadResult.filename,
+        mimeType: uploadResult.mimeType,
+      })
+    ),
+  });
+
+  // Call vision model...
+  const response = await callVisionModel(uploadResult.mediaId);
+
+  await span.end({
+    output: response.description,
+    tokens: { prompt: 1200, completion: 150, total: 1350 },
+  });
+
+  return response;
+}, {
+  name: 'image-analysis',
+  input: content(
+    'User uploaded an image for analysis',
+    ContentBlock.media(uploadResult.mediaId, {
+      category: MediaCategory.IMAGE,
+      filename: uploadResult.filename,
+    })
+  ),
+});
+```
+
+### Media Retrieval
+
+```javascript
+// Get media information
+const mediaInfo = await foil.getMedia(mediaId);
+
+// Get presigned URL for download
+const urlInfo = await foil.getMediaUrl(mediaId, 'original');
+console.log(urlInfo.url); // Presigned S3 URL
+
+// Get extracted content URL (for documents)
+const extractedUrl = await foil.getMediaUrl(mediaId, 'extracted');
+
+// Batch get multiple media
+const batchInfo = await foil.batchMediaInfo([mediaId1, mediaId2, mediaId3]);
+```
+
+## Signals & Feedback
+
+Record user feedback and custom signals for your traces:
+
+```javascript
+await tracer.trace(async (ctx) => {
+  // ... agent logic ...
+
+  // Record user feedback (thumbs up/down)
+  await ctx.recordFeedback(true); // thumbs up
+
+  // Record a rating
+  await ctx.recordRating(5); // 5-star rating
+
+  // Record custom signal
+  await ctx.recordSignal('response_quality', 0.95, {
+    signalType: 'quality',
+    source: 'llm', // or 'user', 'system'
+    metadata: { evaluator: 'gpt-4' },
+  });
+
+  return result;
+}, { name: 'support-query' });
+```
+
+### Direct Signal Recording
+
+```javascript
+const foil = new Foil({ apiKey: API_KEY });
+
+// Record a signal for a specific trace
+await foil.recordSignal({
+  traceId: 'trace_123',
+  signalName: 'user_satisfaction',
+  value: 4,
+  signalType: 'feedback',
+  source: 'user',
+});
+
+// Batch record signals
+await foil.recordSignalBatch([
+  { traceId: 'trace_123', signalName: 'thumbs', value: true, source: 'user' },
+  { traceId: 'trace_123', signalName: 'rating', value: 5, source: 'user' },
+]);
+
+// Get signals for a trace
+const signals = await foil.getTraceSignals('trace_123');
+```
+
+## Framework Integrations
+
+### OpenAI Integration
+
+Automatic tracing for OpenAI calls:
+
+```javascript
+const OpenAI = require('openai');
+const { createFoilTracer } = require('@foil/foil-js');
+
+const tracer = createFoilTracer({ apiKey: API_KEY, agentName: 'my-agent' });
+
+await tracer.trace(async (ctx) => {
+  const openai = new OpenAI();
+
+  // Wrap OpenAI client for automatic tracing
+  tracer.wrapOpenAI(openai, { context: ctx });
+
+  // All calls are now automatically traced
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Hello!' }],
+  });
+
+  return response.choices[0].message.content;
+}, { name: 'chat' });
+```
+
+### LangChain Integration
+
+```javascript
+const { createFoilTracer, createLangChainCallback } = require('@foil/foil-js');
+
+const tracer = createFoilTracer({ apiKey: API_KEY, agentName: 'langchain-agent' });
+const callbacks = [createLangChainCallback(tracer)];
+
+// Use with LangChain
+const chain = new LLMChain({ llm, prompt });
+const result = await chain.call({ input: 'Hello' }, { callbacks });
+```
+
+### Vercel AI SDK Integration
+
+```javascript
+const { createFoilTracer, createVercelAICallbacks } = require('@foil/foil-js');
+
+const tracer = createFoilTracer({ apiKey: API_KEY, agentName: 'vercel-agent' });
+const callbacks = createVercelAICallbacks(tracer);
+
+// Use with Vercel AI SDK
+const result = await streamText({
+  model: openai('gpt-4'),
+  messages,
+  ...callbacks,
+});
+```
+
+## OpenTelemetry Integration
+
+Foil supports OpenTelemetry (OTEL) for automatic instrumentation of LLM calls. This enables zero-code tracing when combined with instrumentations like [OpenLLMetry](https://github.com/traceloop/openllmetry-js).
+
+### Quick Setup with Foil.init()
+
+The easiest way to set up OpenTelemetry with Foil:
+
+```javascript
+const { Foil } = require('@foil/foil-js/otel');
+
+// Initialize Foil with OpenTelemetry
+Foil.init({
+  apiKey: process.env.FOIL_API_KEY,
+  agentName: 'my-ai-agent', // Optional, groups traces under this agent in Foil
+});
+
+// Now all OpenTelemetry traces will be exported to Foil
+// Add instrumentations like OpenLLMetry for automatic LLM tracing
+```
+
+### Using with OpenLLMetry
+
+[OpenLLMetry](https://github.com/traceloop/openllmetry-js) provides automatic instrumentation for popular LLM libraries:
+
+```bash
+npm install @traceloop/node-server-sdk @foil/foil-js @opentelemetry/sdk-trace-node
+```
+
+```javascript
+const { Foil } = require('@foil/foil-js/otel');
+const Traceloop = require('@traceloop/node-server-sdk');
+
+// Initialize Foil first
+const { provider } = Foil.init({
+  apiKey: process.env.FOIL_API_KEY,
+  agentName: 'my-openai-agent',
+});
+
+// Initialize OpenLLMetry with the Foil provider
+Traceloop.initialize({
+  disableBatch: true, // Send traces immediately
+  tracerProvider: provider,
+});
+
+// Now OpenAI, Anthropic, LangChain, etc. calls are automatically traced
+const OpenAI = require('openai');
+const openai = new OpenAI();
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+// ↑ This call is automatically traced to Foil!
+```
+
+### Manual Setup with FoilSpanProcessor
+
+For more control over the OpenTelemetry configuration:
+
+```javascript
+const { FoilSpanProcessor } = require('@foil/foil-js/otel');
+const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+const { Resource } = require('@opentelemetry/resources');
+
+// Create a custom provider
+const provider = new NodeTracerProvider({
+  resource: new Resource({
+    'service.name': 'my-custom-agent',
+    'deployment.environment': 'production',
+  }),
+});
+
+// Add the Foil processor
+provider.addSpanProcessor(new FoilSpanProcessor({
+  apiKey: process.env.FOIL_API_KEY,
+  maxBatchSize: 100,        // Max spans per batch (default: 100)
+  scheduledDelayMs: 5000,   // Batch export interval (default: 5000ms)
+  exportTimeoutMs: 30000,   // Request timeout (default: 30000ms)
+  debug: true,              // Enable debug logging
+}));
+
+// Register globally
+provider.register();
+```
+
+### Configuration Options
+
+#### Foil.init() Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | string | Yes | Your Foil API key |
+| `agentName` | string | No | Agent name for grouping traces in Foil |
+| `endpoint` | string | No | Custom OTLP endpoint URL |
+| `debug` | boolean | No | Enable debug logging |
+
+#### FoilSpanProcessor Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | string | Yes | Your Foil API key |
+| `endpoint` | string | No | Custom OTLP endpoint (default: `https://api.foil.dev/api/otlp/v1/traces`) |
+| `maxBatchSize` | number | No | Maximum spans per batch (default: 100) |
+| `scheduledDelayMs` | number | No | Batch export interval in ms (default: 5000) |
+| `exportTimeoutMs` | number | No | Export request timeout in ms (default: 30000) |
+| `debug` | boolean | No | Enable debug logging |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FOIL_API_KEY` | Foil API key (alternative to passing in options) |
+| `FOIL_OTLP_ENDPOINT` | Custom OTLP endpoint URL |
+| `FOIL_DEBUG` | Set to `'true'` to enable debug logging |
+| `OTEL_SERVICE_NAME` | Default service name for traces |
+
+### Supported Instrumentations
+
+When using OpenLLMetry or similar, the following are automatically instrumented:
+
+- **OpenAI** - Chat completions, embeddings, assistants
+- **Anthropic** - Claude messages
+- **Azure OpenAI** - All Azure OpenAI endpoints
+- **Cohere** - Chat, generate, embed
+- **Google Generative AI** - Gemini models
+- **Bedrock** - AWS Bedrock runtime
+- **LangChain** - Chains, agents, retrievers
+- **LlamaIndex** - Queries, retrievers
+
+### Shutdown and Cleanup
+
+Always shut down gracefully to flush pending spans:
+
+```javascript
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await Foil.shutdown();
+  process.exit(0);
+});
+
+// Or flush manually
+await Foil.flush();
+```
+
+### Combining with Manual Tracing
+
+You can use OpenTelemetry auto-instrumentation alongside manual Foil tracing:
+
+```javascript
+const { Foil } = require('@foil/foil-js/otel');
+const { createFoilTracer, SpanKind } = require('@foil/foil-js');
+
+// Set up OTEL for auto-instrumentation
+Foil.init({ apiKey: API_KEY });
+
+// Create a manual tracer for custom spans
+const tracer = createFoilTracer({
+  apiKey: API_KEY,
+  agentName: 'hybrid-agent',
+});
+
+await tracer.trace(async (ctx) => {
+  // Manual custom span
+  const span = await ctx.startSpan(SpanKind.CUSTOM, 'process-result', {
+    input: { action: 'validate' },
+  });
+
+  // Auto-instrumented OpenAI call (via OpenLLMetry)
+  const openai = new OpenAI();
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Hello!' }],
+  });
+
+  await span.end({ output: { validated: true } });
+
+  return response;
+}, { name: 'hybrid-trace' });
+```
+
+## Experiments (A/B Testing)
+
+Get variant assignments for experiments:
+
+```javascript
+const foil = new Foil({ apiKey: API_KEY });
+
+// Get assigned variant for a user
+const assignment = await foil.getExperimentVariant('experiment_123', userId);
+
+if (assignment.inExperiment) {
+  console.log(assignment.variantName);  // 'control' or 'treatment'
+  console.log(assignment.config);       // { model: 'gpt-4', temperature: 0.7 }
+}
+```
+
+## Low-Level API
+
+For more control, use the Foil client directly:
+
+```javascript
+const Foil = require('@foil/foil-js');
+
+const foil = new Foil({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.foil.dev/api',
+});
+
+// Manual span management
+const traceId = foil.createTraceId();
+const spanId = foil.createSpanId();
+
+await foil.startSpan({
+  spanId,
+  traceId,
+  name: 'gpt-4',
+  agentName: 'my-agent',
+  spanKind: 'llm',
+  input: messages,
+});
+
+// ... do work ...
+
+await foil.endSpan({
+  spanId,
+  traceId,
+  agentName: 'my-agent',
+  output: response,
+  tokens: { prompt: 100, completion: 50, total: 150 },
+});
+
+// Get trace data
+const trace = await foil.getTrace(traceId);
+
+// List traces
+const traces = await foil.listTraces({
+  agentName: 'my-agent',
+  limit: 10,
+  from: '2024-01-01T00:00:00Z',
+});
+```
+
+## Debug Mode
+
+Enable debug logging to see trace activity:
+
+```javascript
+// Via environment variable
+process.env.FOIL_DEBUG = 'true';
+
+// Or via tracer options
+const tracer = createFoilTracer({
+  apiKey: API_KEY,
+  agentName: 'my-agent',
+  debug: true,
+});
+```
+
+Output:
+```
+[Foil] ━━━ TRACE START: weather-query ━━━ {"traceId":"abc12345"}
+[Foil]   ▶ START [llm] gpt-4 {"spanId":"def67890"}
+[Foil]   ■ END [llm] gpt-4 {"spanId":"def67890","duration":"1234ms","tokens":18}
+[Foil] ━━━ TRACE END: weather-query ━━━ {"traceId":"abc12345","duration":"1250ms"}
+```
+
+## API Reference
+
+### Tracer Methods
+
+#### `createFoilTracer(options)`
+
+Create a tracer instance.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | string | Yes | Your Foil API key |
+| `agentName` | string | Yes | Unique name for your agent |
+| `baseUrl` | string | No | API base URL (default: api.getfoil.ai) |
+| `debug` | boolean | No | Enable debug logging |
+
+#### `tracer.trace(fn, options)`
+
+Execute a function within a traced context.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | string | Name for the root span |
+| `traceId` | string | Custom trace ID (auto-generated if not provided) |
+| `sessionId` | string | Session ID for conversation tracking |
+| `input` | any | Input to record (supports multimodal content) |
+| `properties` | object | Custom properties |
+
+#### `ctx.startSpan(spanKind, name, attributes)`
+
+Start a new span within a trace context.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `input` | any | Input to the operation (supports multimodal) |
+| `properties` | object | Custom properties |
+| `parentSpanId` | string | Explicit parent span ID |
+
+#### `span.end(result)`
+
+End a span with results.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `output` | any | Output from the operation |
+| `tokens` | object | Token usage `{ prompt, completion, total }` |
+| `error` | object | Error info `{ type, message }` |
+| `ttft` | number | Time to first token (ms) |
+
+### Foil Client Methods
+
+#### Semantic Search
+
+| Method | Description |
+|--------|-------------|
+| `semanticSearch(query, options)` | Search spans using natural language |
+| `findSimilarTraces(traceId, options)` | Find traces similar to a given trace |
+| `getSemanticSearchStatus(agentId?)` | Get embedding statistics |
+
+#### Custom Evaluations
+
+| Method | Description |
+|--------|-------------|
+| `getEvaluationTemplates()` | List available evaluation templates |
+| `getAgentEvaluations(agentId)` | List evaluations for an agent |
+| `getEvaluation(agentId, evaluationId)` | Get evaluation details |
+| `createEvaluation(agentId, data)` | Create a custom evaluation |
+| `updateEvaluation(agentId, evaluationId, data)` | Update an evaluation |
+| `deleteEvaluation(agentId, evaluationId)` | Delete an evaluation |
+| `testEvaluation(agentId, evaluationId, data)` | Test with sample data |
+| `cloneEvaluationTemplate(agentId, templateId)` | Clone a template |
+| `addEvaluationExample(agentId, evaluationId, data)` | Add few-shot example |
+| `removeEvaluationExample(agentId, evaluationId, exampleId)` | Remove example |
+| `getEvaluationAnalytics(agentId, evaluationId)` | Get evaluation metrics |
+
+#### Media
+
+| Method | Description |
+|--------|-------------|
+| `uploadMedia(file, options)` | Upload media for multimodal content |
+| `getMedia(mediaId, options)` | Get media information |
+| `getMediaUrl(mediaId, content)` | Get presigned download URL |
+| `batchMediaInfo(mediaIds)` | Get info for multiple media |
+
+#### Signals
+
+| Method | Description |
+|--------|-------------|
+| `recordSignal(data)` | Record a signal |
+| `recordSignalBatch(signals)` | Record multiple signals |
+| `getTraceSignals(traceId)` | Get signals for a trace |
+
+#### Traces
+
+| Method | Description |
+|--------|-------------|
+| `startSpan(data)` | Start a span |
+| `endSpan(data)` | End a span |
+| `getTrace(traceId)` | Get trace with all spans |
+| `listTraces(options)` | List traces with filters |
+
+#### Experiments
+
+| Method | Description |
+|--------|-------------|
+| `getExperimentVariant(experimentId, identifier)` | Get variant assignment |
+
+### Content Helpers
+
+#### `content(...parts)` / `ContentBlock`
+
+Create multimodal content arrays.
+
+```javascript
+// Using content() helper
+const input = content(
+  'Analyze this:',
+  ContentBlock.media(mediaId, { category: MediaCategory.IMAGE }),
+  'What do you see?'
+);
+
+// Manual content block creation
+const blocks = [
+  ContentBlock.text('Hello'),
+  ContentBlock.media(mediaId, { category: MediaCategory.IMAGE, filename: 'photo.jpg' }),
+];
+```
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `tracer-test.js` - Basic tracing setup
+- `openai-agent-test.js` - OpenAI integration
+- `multimodal-test.js` - Multimodal content handling
+- `semantic-search-example.js` - Semantic search usage
+- `custom-evaluations-example.js` - Custom evaluations
+- `otel-integration-example.js` - OpenTelemetry integration with multiple approaches
+
+Run examples:
+
+```bash
+npm run example:tracer
+npm run example:openai
+npm run example:multimodal
+npm run example:semantic-search
+npm run example:evaluations
+npm run example:otel
+```
+
+## License
+
+MIT