moda-ai 0.1.5 → 0.1.8

package/README.md

@@ -100,9 +100,9 @@ await withContext('conv_123', 'user_456', async () => {
 });
 ```
 
-## Automatic Fallback
+## Automatic Fallback (Simple Chatbots Only)
 
-If you don't set a conversation ID, the SDK automatically computes one from the first user message and system prompt. This works well for simple use cases but explicit IDs are recommended for production:
+If you don't set a conversation ID, the SDK automatically computes one by hashing the first user message and system prompt. **This only works for simple chatbots where you pass the full message history with each API call:**
 
 ```typescript
 // Turn 1
@@ -114,7 +114,44 @@ messages.push({ role: 'assistant', content: r1.choices[0].message.content });
 messages.push({ role: 'user', content: 'How do I read a file?' });
 const r2 = await openai.chat.completions.create({ model: 'gpt-4', messages });
 
-// Both turns have the SAME conversation_id in your Moda dashboard
+// Both turns have the SAME conversation_id because "Hi, help with TypeScript"
+// is still the first user message in both calls
+```
+
+### Why This Works
+
+LLM APIs are stateless. Each API call must include the full conversation history. The SDK extracts the first user message from the `messages` array and hashes it to create a stable conversation ID across turns.
+
+### When Automatic Detection Does NOT Work
+
+**Agent frameworks (LangChain, Claude Agent SDK, CrewAI, AutoGPT, etc.) do NOT pass full message history.** Each agent iteration typically passes only:
+- System prompt (with context baked in)
+- Tool results from the previous step
+- A continuation prompt
+
+This means each iteration has a **different** first user message, resulting in **different** conversation IDs:
+
+```typescript
+// Agent iteration 1
+messages = [{ role: 'user', content: 'What are my top clusters?' }]  // conv_abc123
+
+// Agent iteration 2 (tool result)
+messages = [{ role: 'user', content: 'Tool returned: ...' }]  // conv_xyz789 - DIFFERENT!
+
+// Agent iteration 3
+messages = [{ role: 'user', content: 'Based on the data...' }]  // conv_def456 - DIFFERENT!
+```
+
+**For agent-based applications, you MUST use explicit conversation IDs:**
+
+```typescript
+// Wrap your entire agent execution
+Moda.conversationId = 'agent_session_' + sessionId;
+
+const agent = new LangChainAgent();
+await agent.run('What are my top clusters?');  // All internal LLM calls share same ID
+
+Moda.conversationId = null;
 ```
 
 ## Anthropic Support
@@ -153,6 +190,71 @@ for await (const chunk of stream) {
 // Streaming responses are automatically tracked
 ```
 
+## Using with Sentry (or other OpenTelemetry SDKs)
+
+The Moda SDK automatically detects and coexists with other OpenTelemetry-based SDKs like Sentry. When an existing TracerProvider is detected, Moda adds its SpanProcessor to the existing provider instead of creating a new one.
+
+### Sentry v8+ Integration
+
+Sentry v8+ uses OpenTelemetry internally for tracing. Initialize Sentry first, then Moda:
+
+```typescript
+import * as Sentry from '@sentry/node';
+import { Moda } from 'moda-ai';
+import OpenAI from 'openai';
+
+// 1. Initialize Sentry FIRST (sets up OpenTelemetry TracerProvider)
+Sentry.init({
+  dsn: 'https://xxx@xxx.ingest.sentry.io/xxx',
+  tracesSampleRate: 1.0,
+});
+
+// 2. Initialize Moda SECOND (detects Sentry's provider automatically)
+await Moda.init('moda_your_api_key', {
+  debug: true, // Shows: "[Moda] Detected existing TracerProvider, adding Moda SpanProcessor to it"
+});
+
+// 3. Use OpenAI normally - spans go to BOTH Sentry and Moda
+const openai = new OpenAI();
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+// 4. Cleanup - Moda shutdown preserves Sentry
+await Moda.flush();
+await Moda.shutdown(); // Only shuts down Moda's processor, Sentry continues working
+```
+
+### How It Works
+
+When Moda detects an existing TracerProvider (e.g., from Sentry):
+- Moda adds its SpanProcessor to the existing provider
+- Both SDKs receive the same spans with identical trace IDs
+- `Moda.shutdown()` only removes Moda's processor, preserving the other SDK
+- You can re-initialize Moda after shutdown
+
+### Expected Behavior
+
+With `debug: true`, you should see:
+```
+[Moda] Detected existing TracerProvider, adding Moda SpanProcessor to it
+```
+
+You should NOT see:
+```
+Error: Attempted duplicate registration of tracer provider
+```
+
+### Supported SDKs
+
+This coexistence works with any SDK that uses OpenTelemetry's TracerProvider:
+- Sentry v8+
+- Datadog APM
+- New Relic
+- Honeycomb
+- Custom OpenTelemetry setups
+
 ## Configuration Options
 
 ```typescript

package/dist/index.cjs

@@ -1040,6 +1040,9 @@ async function registerInstrumentations() {
 
 let provider = null;
 let exporter = null;
+let modaProcessor = null;
+// Track if we're using an external provider (e.g., Sentry)
+let usingExternalProvider = false;
 /**
  * Check if the SDK is initialized
  */
@@ -1093,12 +1096,6 @@ async function init(apiKey, options = {}) {
     if (mergedOptions.debug) {
         api.diag.setLogger(new api.DiagConsoleLogger(), api.DiagLogLevel.DEBUG);
     }
-    // Create resource with service info
-    const resource = new resources.Resource({
-        [semconv__namespace.ATTR_SERVICE_NAME]: 'moda-sdk',
-        [semconv__namespace.ATTR_SERVICE_VERSION]: '0.1.0',
-        'moda.environment': mergedOptions.environment,
-    });
     // Create OTLP exporter with Moda API key in headers
     exporter = new exporterTraceOtlpProto.OTLPTraceExporter({
         url: mergedOptions.baseUrl,
@@ -1107,20 +1104,54 @@ async function init(apiKey, options = {}) {
             'Content-Type': 'application/x-protobuf',
         },
     });
-    // Create tracer provider
-    provider = new sdkTraceNode.NodeTracerProvider({
-        resource,
-    });
-    // Use BatchSpanProcessor for production, SimpleSpanProcessor for debug
-    const processor = mergedOptions.debug
+    // Create Moda's span processor
+    modaProcessor = mergedOptions.debug
         ? new sdkTraceBase.SimpleSpanProcessor(exporter)
         : new sdkTraceBase.BatchSpanProcessor(exporter, {
             maxQueueSize: mergedOptions.batchSize * 2,
             maxExportBatchSize: mergedOptions.batchSize,
             scheduledDelayMillis: mergedOptions.flushInterval,
         });
-    provider.addSpanProcessor(processor);
-    provider.register();
+    // Check if there's already a registered TracerProvider (e.g., from Sentry)
+    // Sentry (and other SDKs) may wrap their provider in a ProxyTracerProvider,
+    // so we need to check both the proxy and its delegate
+    const existingProvider = api.trace.getTracerProvider();
+    const isProxyProvider = existingProvider?.constructor?.name === 'ProxyTracerProvider';
+    // Try to get the underlying provider if it's a proxy
+    let targetProvider = existingProvider;
+    if (isProxyProvider) {
+        // ProxyTracerProvider wraps the real provider - get the delegate
+        const delegate = existingProvider.getDelegate?.() || existingProvider._delegate;
+        if (delegate && delegate.constructor?.name !== 'ProxyTracerProvider') {
+            targetProvider = delegate;
+        }
+    }
+    // Check if the target provider has addSpanProcessor (indicates a real SDK-managed provider)
+    const hasAddSpanProcessor = targetProvider &&
+        typeof targetProvider.addSpanProcessor === 'function';
+    // Detect if this is a real external provider (not just the default noop proxy)
+    const isExternalProvider = hasAddSpanProcessor &&
+        targetProvider?.constructor?.name !== 'ProxyTracerProvider';
+    if (isExternalProvider && targetProvider) {
+        // Another SDK (like Sentry) already set up OTEL - add our processor to their provider
+        targetProvider.addSpanProcessor(modaProcessor);
+        usingExternalProvider = true;
+        if (mergedOptions.debug) {
+            console.log('[Moda] Detected existing TracerProvider, adding Moda SpanProcessor to it');
+        }
+    }
+    else {
+        // No existing provider - create and register our own
+        const resource = new resources.Resource({
+            [semconv__namespace.ATTR_SERVICE_NAME]: 'moda-sdk',
+            [semconv__namespace.ATTR_SERVICE_VERSION]: '0.1.0',
+            'moda.environment': mergedOptions.environment,
+        });
+        provider = new sdkTraceNode.NodeTracerProvider({ resource });
+        provider.addSpanProcessor(modaProcessor);
+        provider.register();
+        usingExternalProvider = false;
+    }
     // Register LLM instrumentations (async - uses dynamic imports for ESM compatibility)
     await registerInstrumentations();
     state.initialized = true;
@@ -1142,11 +1173,20 @@ async function init(apiKey, options = {}) {
  * ```
  */
 async function flush() {
-    if (!state.initialized || !provider) {
+    if (!state.initialized) {
         return;
     }
     try {
-        await provider.forceFlush();
+        if (usingExternalProvider) {
+            // External provider: flush our processor directly
+            if (modaProcessor) {
+                await modaProcessor.forceFlush();
+            }
+        }
+        else if (provider) {
+            // Our own provider: flush the whole provider
+            await provider.forceFlush();
+        }
         if (state.options.debug) {
             console.log('[Moda] Flushed all pending spans');
         }
@@ -1175,11 +1215,21 @@ async function shutdown() {
         return;
     }
     try {
-        if (provider) {
-            await provider.shutdown();
+        if (usingExternalProvider) {
+            // External provider: shutdown our processor only, preserve their provider
+            if (modaProcessor) {
+                await modaProcessor.shutdown();
+            }
+            if (state.options.debug) {
+                console.log('[Moda] Moda processor shutdown complete (external provider preserved)');
+            }
         }
-        if (state.options.debug) {
-            console.log('[Moda] SDK shutdown complete');
+        else if (provider) {
+            // Our own provider: shutdown everything
+            await provider.shutdown();
+            if (state.options.debug) {
+                console.log('[Moda] SDK shutdown complete');
+            }
         }
     }
     catch (error) {
@@ -1192,6 +1242,8 @@ async function shutdown() {
         resetState();
         provider = null;
         exporter = null;
+        modaProcessor = null;
+        usingExternalProvider = false;
     }
 }
 /**
@@ -1201,6 +1253,289 @@ async function shutdown() {
 function getTracer() {
     return api.trace.getTracer('moda-sdk', '0.1.0');
 }
+/**
+ * Create a standalone Moda SpanProcessor for advanced OTEL setups.
+ * Use when you need full control over your OpenTelemetry configuration.
+ *
+ * @example
+ * ```typescript
+ * import { createModaSpanProcessor } from 'moda-ai';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * const processor = createModaSpanProcessor({ apiKey: 'moda_xxx' });
+ * (trace.getTracerProvider() as any).addSpanProcessor(processor);
+ * ```
+ */
+function createModaSpanProcessor(options) {
+    const { apiKey, baseUrl = DEFAULT_OPTIONS.baseUrl, debug = false, batchSize = DEFAULT_OPTIONS.batchSize, flushInterval = DEFAULT_OPTIONS.flushInterval, } = options;
+    if (!apiKey || typeof apiKey !== 'string') {
+        throw new Error('[Moda] API key is required');
+    }
+    const processorExporter = new exporterTraceOtlpProto.OTLPTraceExporter({
+        url: baseUrl,
+        headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'Content-Type': 'application/x-protobuf',
+        },
+    });
+    return debug
+        ? new sdkTraceBase.SimpleSpanProcessor(processorExporter)
+        : new sdkTraceBase.BatchSpanProcessor(processorExporter, {
+            maxQueueSize: batchSize * 2,
+            maxExportBatchSize: batchSize,
+            scheduledDelayMillis: flushInterval,
+        });
+}
+
+/**
+ * Manual LLM tracing API for instrumenting arbitrary LLM calls.
+ * Use this when you can't use auto-instrumented SDKs (OpenAI/Anthropic).
+ *
+ * @example
+ * ```typescript
+ * const result = await withLLMCall(
+ *   { vendor: 'openrouter', type: 'chat' },
+ *   async ({ span }) => {
+ *     span.reportRequest({ model: 'gpt-4', messages });
+ *     const response = await fetch('https://api.example.com/chat', {...});
+ *     const data = await response.json();
+ *     span.reportResponse({ model: data.model, usage: data.usage, completions: data.choices });
+ *     return data;
+ *   }
+ * );
+ * ```
+ */
+/**
+ * Create an LLMSpanHelper that wraps an OpenTelemetry span
+ */
+function createSpanHelper(span) {
+    return {
+        reportRequest(options) {
+            const { model, messages, conversationId, userId } = options;
+            // Set model
+            span.setAttribute('llm.request.model', model);
+            // Get effective context (global + local overrides)
+            const globalContext = getEffectiveContext();
+            // Determine conversation ID: local override > global > computed
+            let effectiveConversationId = conversationId;
+            if (!effectiveConversationId && globalContext.conversationId) {
+                effectiveConversationId = globalContext.conversationId;
+            }
+            if (!effectiveConversationId) {
+                effectiveConversationId = computeConversationId(messages);
+            }
+            span.setAttribute('moda.conversation_id', effectiveConversationId);
+            // Set user ID if provided or from global context
+            const effectiveUserId = userId ?? globalContext.userId;
+            if (effectiveUserId) {
+                span.setAttribute('moda.user_id', effectiveUserId);
+            }
+            // Format and set message attributes
+            const messageAttrs = formatMessagesForSpan(messages);
+            for (const [key, value] of Object.entries(messageAttrs)) {
+                span.setAttribute(key, value);
+            }
+        },
+        reportResponse(options) {
+            const { model, usage, completions } = options;
+            // Set response model if provided
+            if (model) {
+                span.setAttribute('llm.response.model', model);
+            }
+            // Set usage metrics
+            if (usage) {
+                const promptTokens = usage.prompt_tokens ?? usage.input_tokens;
+                const completionTokens = usage.completion_tokens ?? usage.output_tokens;
+                const totalTokens = usage.total_tokens ??
+                    (promptTokens !== undefined && completionTokens !== undefined
+                        ? promptTokens + completionTokens
+                        : undefined);
+                if (promptTokens !== undefined) {
+                    span.setAttribute('llm.usage.prompt_tokens', promptTokens);
+                }
+                if (completionTokens !== undefined) {
+                    span.setAttribute('llm.usage.completion_tokens', completionTokens);
+                }
+                if (totalTokens !== undefined) {
+                    span.setAttribute('llm.usage.total_tokens', totalTokens);
+                }
+            }
+            // Set completion attributes
+            if (completions && completions.length > 0) {
+                completions.forEach((completion, index) => {
+                    // Handle OpenAI-style nested message or direct properties
+                    const role = completion.role ?? completion.message?.role ?? 'assistant';
+                    const content = completion.content ?? completion.message?.content ?? '';
+                    const attrs = formatCompletionForSpan(role, content, index);
+                    for (const [key, value] of Object.entries(attrs)) {
+                        span.setAttribute(key, value);
+                    }
+                    // Set finish reason from first completion
+                    if (index === 0 && completion.finish_reason) {
+                        span.setAttribute('llm.response.finish_reason', completion.finish_reason);
+                    }
+                });
+            }
+        },
+        get rawSpan() {
+            return span;
+        },
+    };
+}
+/**
+ * Wrap an arbitrary LLM call with OpenTelemetry tracing.
+ *
+ * Use this when you can't use auto-instrumented SDKs (OpenAI/Anthropic)
+ * and need to manually instrument LLM calls (e.g., direct fetch to OpenRouter,
+ * custom LLM providers, proxied requests).
+ *
+ * @param options - Vendor and request type configuration
+ * @param callback - Async function that makes the LLM call
+ * @returns The return value of the callback
+ *
+ * @example
+ * ```typescript
+ * const result = await withLLMCall(
+ *   { vendor: 'openrouter', type: 'chat' },
+ *   async ({ span }) => {
+ *     span.reportRequest({ model: 'anthropic/claude-3-sonnet', messages });
+ *
+ *     const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+ *       method: 'POST',
+ *       headers: { Authorization: `Bearer ${apiKey}` },
+ *       body: JSON.stringify({ model, messages }),
+ *     });
+ *     const data = await response.json();
+ *
+ *     span.reportResponse({
+ *       model: data.model,
+ *       usage: data.usage,
+ *       completions: data.choices,
+ *     });
+ *
+ *     return data;
+ *   }
+ * );
+ * ```
+ */
+async function withLLMCall(options, callback) {
+    const { vendor, type } = options;
+    const tracer = api.trace.getTracer('moda-sdk', '0.1.0');
+    const span = tracer.startSpan(`${vendor}.${type}`, {
+        attributes: {
+            'llm.vendor': vendor,
+            'llm.request.type': type,
+        },
+    });
+    const spanHelper = createSpanHelper(span);
+    try {
+        const result = await callback({ span: spanHelper });
+        span.setStatus({ code: api.SpanStatusCode.OK });
+        return result;
+    }
+    catch (error) {
+        span.setStatus({
+            code: api.SpanStatusCode.ERROR,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        if (error instanceof Error) {
+            span.recordException(error);
+        }
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+
+/**
+ * Vercel AI SDK integration for Moda observability.
+ *
+ * The Vercel AI SDK has built-in OpenTelemetry support via `experimental_telemetry`.
+ * This module provides helper functions to integrate Moda with the AI SDK.
+ *
+ * @example
+ * ```typescript
+ * import { Moda } from 'moda-ai';
+ * import { generateText } from 'ai';
+ *
+ * Moda.init('your-api-key');
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Hello',
+ *   experimental_telemetry: Moda.getVercelAITelemetry(),
+ * });
+ * ```
+ */
+/**
+ * Get a telemetry configuration object for the Vercel AI SDK.
+ *
+ * This returns a configuration that can be passed directly to the
+ * `experimental_telemetry` option of AI SDK functions like `generateText`,
+ * `streamText`, `generateObject`, etc.
+ *
+ * The configuration includes:
+ * - Moda's OpenTelemetry tracer for span collection
+ * - Automatic inclusion of conversation_id and user_id in metadata
+ * - Configurable input/output recording for privacy control
+ *
+ * @param options - Optional configuration overrides
+ * @returns Telemetry configuration for Vercel AI SDK
+ *
+ * @example
+ * ```typescript
+ * import { Moda } from 'moda-ai';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * Moda.init('your-api-key');
+ * Moda.conversationId = 'conv_123';
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Write a haiku about coding',
+ *   experimental_telemetry: Moda.getVercelAITelemetry(),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Process this sensitive data',
+ *   experimental_telemetry: Moda.getVercelAITelemetry({
+ *     recordInputs: false,  // Don't record sensitive prompts
+ *     recordOutputs: false, // Don't record sensitive outputs
+ *     functionId: 'sensitive-processor',
+ *     metadata: { operation: 'pii-processing' },
+ *   }),
+ * });
+ * ```
+ */
+function getVercelAITelemetry(options = {}) {
+    const context = getEffectiveContext();
+    // Build metadata with Moda context
+    const metadata = {
+        ...options.metadata,
+    };
+    // Add Moda context to metadata
+    if (context.conversationId) {
+        metadata['moda.conversation_id'] = context.conversationId;
+    }
+    if (context.userId) {
+        metadata['moda.user_id'] = context.userId;
+    }
+    return {
+        isEnabled: true,
+        recordInputs: options.recordInputs,
+        recordOutputs: options.recordOutputs,
+        functionId: options.functionId,
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+        tracer: getTracer(),
+    };
+}
 
 /**
  * @moda/sdk - Official TypeScript/Node.js SDK for Moda LLM observability
@@ -1270,6 +1605,43 @@ const Moda = {
      * @see {@link getTracer}
      */
     getTracer,
+    /**
+     * Manually trace an LLM call when using non-instrumented providers
+     * @see {@link withLLMCall}
+     */
+    withLLMCall,
+    /**
+     * Get telemetry configuration for Vercel AI SDK integration.
+     * Returns a config object for the `experimental_telemetry` option.
+     * @see {@link getVercelAITelemetry}
+     *
+     * @example
+     * ```typescript
+     * import { generateText } from 'ai';
+     *
+     * const result = await generateText({
+     *   model: openai('gpt-4o'),
+     *   prompt: 'Hello',
+     *   experimental_telemetry: Moda.getVercelAITelemetry(),
+     * });
+     * ```
+     */
+    getVercelAITelemetry,
+    /**
+     * Create a standalone Moda SpanProcessor for advanced OTEL setups.
+     * Use when you need full control over your OpenTelemetry configuration.
+     * @see {@link createModaSpanProcessor}
+     *
+     * @example
+     * ```typescript
+     * import { Moda } from 'moda-ai';
+     * import { trace } from '@opentelemetry/api';
+     *
+     * const processor = Moda.createModaSpanProcessor({ apiKey: 'moda_xxx' });
+     * (trace.getTracerProvider() as any).addSpanProcessor(processor);
+     * ```
+     */
+    createModaSpanProcessor,
     /**
      * Get or set the global conversation ID.
      * Setting to null clears the conversation ID.
@@ -1321,6 +1693,7 @@ exports.Moda = Moda;
 exports.clearConversationId = clearConversationId;
 exports.clearUserId = clearUserId;
 exports.computeConversationId = computeConversationId;
+exports.createModaSpanProcessor = createModaSpanProcessor;
 exports.default = Moda;
 exports.flush = flush;
 exports.generateRandomConversationId = generateRandomConversationId;
@@ -1328,6 +1701,7 @@ exports.getContext = getContext;
 exports.getEffectiveContext = getEffectiveContext;
 exports.getGlobalContext = getGlobalContext;
 exports.getTracer = getTracer;
+exports.getVercelAITelemetry = getVercelAITelemetry;
 exports.init = init;
 exports.isInitialized = isInitialized;
 exports.isValidConversationId = isValidConversationId;
@@ -1336,5 +1710,6 @@ exports.setUserId = setUserId;
 exports.shutdown = shutdown;
 exports.withContext = withContext;
 exports.withConversationId = withConversationId;
+exports.withLLMCall = withLLMCall;
 exports.withUserId = withUserId;
 //# sourceMappingURL=index.cjs.map