@revenium/openai 1.0.10 → 1.0.12

package/examples/openai-responses-streaming.ts

@@ -0,0 +1,232 @@
+/**
+ * OpenAI Responses API Streaming Examples
+ *
+ * This file demonstrates how to use the new OpenAI Responses API with streaming enabled
+ * using the Revenium middleware. The Responses API supports streaming for real-time
+ * response generation.
+ *
+ * Metadata Options:
+ * - Start with basic usage (no metadata) - tracking works automatically
+ * - Add subscriber info for user tracking
+ * - Include organization/product IDs for business analytics
+ * - Use task type and trace ID for detailed analysis
+ *
+ * For complete metadata field reference, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ *
+ * Responses API Reference: https://platform.openai.com/docs/api-reference/responses
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// Import types for the new Responses API
+import type { ResponsesCreateParams } from '../src/types/responses-api.js';
+
+async function main() {
+  // Initialize Revenium middleware
+  await initializeReveniumFromEnv();
+
+  // Create OpenAI client
+  const openai = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  // Patch the OpenAI instance to add Revenium tracking
+  patchOpenAIInstance(openai);
+
+  console.log(' OpenAI Responses API Streaming Examples\n');
+
+  // Example 1: Basic Responses API streaming (no metadata)
+  console.log(' Example 1: Basic Responses API streaming (no metadata)');
+  try {
+    const responsesAPI = openai as any; // Type assertion for new API
+
+    if (responsesAPI.responses?.create) {
+      const stream = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: 'Tell me a short story about a robot learning to paint.',
+        stream: true,
+      } as ResponsesCreateParams);
+
+      console.log('Streaming response:');
+      for await (const event of stream) {
+        if (event.type === 'response.output_text.delta') {
+          process.stdout.write(event.delta);
+        }
+      }
+      console.log('\n Stream completed');
+    } else {
+      throw new Error('Responses API not available');
+    }
+  } catch (error) {
+    console.log('️ Responses API not yet available in this OpenAI SDK version');
+    console.log('   Error:', (error as Error).message);
+  }
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 2: Responses API streaming with rich metadata
+  console.log(' Example 2: Responses API streaming with rich metadata');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const stream = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: [
+          {
+            role: 'user',
+            content: 'Explain the concept of machine learning in a conversational way.',
+          },
+        ],
+        stream: true,
+        max_output_tokens: 200,
+        usageMetadata: {
+          // User identification
+          subscriber: {
+            id: 'streaming-user-123',
+            email: 'streaming@example.com',
+            credential: {
+              name: 'api-key-prod',
+              value: 'key-klm-789',
+            },
+          },
+
+          // Organization & billing
+          organizationId: 'streaming-org-456',
+          subscriptionId: 'plan-streaming-edu-2024',
+
+          // Product & task tracking
+          productId: 'ml-educator',
+          taskType: 'educational-streaming',
+          agent: 'ml-tutor-stream',
+
+          // Session tracking
+          traceId: 'stream-trace-789',
+
+          // Quality metrics
+          responseQualityScore: 0.92,
+        },
+      } as ResponsesCreateParams);
+
+      console.log('Streaming response with metadata:');
+      for await (const event of stream) {
+        if (event.type === 'response.output_text.delta') {
+          process.stdout.write(event.delta);
+        }
+      }
+      console.log('\n Stream with metadata completed');
+    } else {
+      throw new Error('Responses API not available');
+    }
+  } catch (error) {
+    console.log('️ Responses API not yet available in this OpenAI SDK version');
+    console.log('   Error:', (error as Error).message);
+  }
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 3: Basic Responses API streaming with array input (no metadata)
+  console.log(' Example 3: Basic Responses API streaming with array input (no metadata)');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const stream = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: [
+          {
+            role: 'user',
+            content: 'Write a poem about the beauty of code.',
+          },
+        ],
+        stream: true,
+      } as ResponsesCreateParams);
+
+      console.log('Streaming poetry:');
+      for await (const event of stream) {
+        if (event.type === 'response.output_text.delta') {
+          process.stdout.write(event.delta);
+        }
+      }
+      console.log('\n Poetry stream completed');
+    } else {
+      throw new Error('Responses API not available');
+    }
+  } catch (error) {
+    console.log('️ Responses API not yet available in this OpenAI SDK version');
+    console.log('   Error:', (error as Error).message);
+  }
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 4: Advanced Responses API streaming with comprehensive metadata
+  console.log(' Example 4: Advanced Responses API streaming with comprehensive metadata');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const stream = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: [
+          {
+            role: 'user',
+            content:
+              'Provide a detailed explanation of how streaming APIs work in real-time applications.',
+          },
+        ],
+        stream: true,
+        max_output_tokens: 300,
+        instructions:
+          'You are a technical expert explaining streaming APIs with practical examples.',
+        usageMetadata: {
+          // User identification
+          subscriber: {
+            id: 'advanced-streaming-user-789',
+            email: 'advanced@enterprise.com',
+            credential: {
+              name: 'api-key-prod',
+              value: 'key-nop-012',
+            },
+          },
+
+          // Organization & billing
+          organizationId: 'enterprise-streaming-org-012',
+          subscriptionId: 'plan-enterprise-stream-2024',
+
+          // Product & task tracking
+          productId: 'streaming-api-educator',
+          taskType: 'advanced-technical-streaming',
+          agent: 'streaming-expert',
+
+          // Session tracking
+          traceId: 'advanced-stream-trace-345',
+
+          // Quality metrics
+          responseQualityScore: 0.97,
+        },
+      } as ResponsesCreateParams);
+
+      console.log('Advanced streaming response:');
+      let deltaCount = 0;
+      for await (const event of stream) {
+        if (event.type === 'response.output_text.delta') {
+          process.stdout.write(event.delta);
+          deltaCount++;
+        }
+      }
+      console.log(`\n Advanced stream completed (${deltaCount} delta events)`);
+    } else {
+      throw new Error('Responses API not available');
+    }
+  } catch (error) {
+    console.log('️ Responses API not yet available in this OpenAI SDK version');
+    console.log('   Error:', (error as Error).message);
+  }
+
+  console.log('\n All Responses API streaming examples completed!');
+}
+
+main().catch(console.error);

package/examples/openai-streaming.ts

@@ -0,0 +1,172 @@
+/**
+ * OpenAI Streaming Example
+ *
+ * Shows how to use Revenium middleware with streaming OpenAI responses and batch embeddings.
+ * Demonstrates seamless metadata integration with streaming - all metadata fields are optional!
+ *
+ * Metadata Options:
+ * - Start with basic usage (no metadata) - tracking works automatically
+ * - Add subscriber info for user tracking
+ * - Include organization/product IDs for business analytics
+ * - Use task type and trace ID for detailed analysis
+ *
+ * For complete metadata field reference, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+async function openaiStreamingExample() {
+  console.log(' OpenAI Streaming with Seamless Metadata Integration\n');
+
+  // Initialize Revenium middleware
+  const initResult = initializeReveniumFromEnv();
+  if (!initResult.success) {
+    console.error(' Failed to initialize Revenium:', initResult.message);
+    process.exit(1);
+  }
+
+  // Create and patch OpenAI instance
+  const openai = patchOpenAIInstance(new OpenAI());
+
+  // Example 1: Basic streaming (no metadata)
+  console.log(' Example 1: Basic streaming chat (automatic tracking)');
+  console.log(' Assistant: ');
+
+  const basicStream = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: 'Count from 1 to 5 slowly' }],
+    stream: true,
+    // No usageMetadata - still automatically tracked when stream completes!
+    // No max_tokens - let response complete naturally
+  });
+
+  for await (const chunk of basicStream) {
+    const content = chunk.choices[0]?.delta?.content || '';
+    if (content) {
+      process.stdout.write(content);
+    }
+  }
+
+  console.log('\n Streaming automatically tracked to Revenium without metadata\n');
+
+  // Example 2: Streaming with rich metadata (all optional!)
+  console.log(' Example 2: Streaming chat with rich metadata');
+  console.log(' Assistant: ');
+
+  const metadataStream = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: 'Write a haiku about middleware' }],
+    stream: true,
+
+    // Optional metadata for advanced reporting, lineage tracking, and cost allocation
+    usageMetadata: {
+      // User identification
+      subscriber: {
+        id: 'streaming-user-456',
+        email: 'poet@company.com',
+        credential: {
+          name: 'api-key-prod',
+          value: 'key-ghi-789',
+        },
+      },
+
+      // Organization & billing
+      organizationId: 'creative-company',
+      subscriptionId: 'plan-creative-2024',
+
+      // Product & task tracking
+      productId: 'ai-poet',
+      taskType: 'creative-writing',
+      agent: 'openai-streaming-chat-node',
+
+      // Session tracking
+      traceId: 'stream-' + Date.now(),
+
+      // Quality metrics
+      responseQualityScore: 0.92,
+    },
+  });
+
+  for await (const chunk of metadataStream) {
+    const content = chunk.choices[0]?.delta?.content || '';
+    if (content) {
+      process.stdout.write(content);
+    }
+  }
+
+  console.log('\n Streaming tracked with rich metadata for analytics\n');
+
+  // Example 3: Batch embeddings (no metadata)
+  console.log(' Example 3: Batch embeddings (automatic tracking)');
+
+  const batchEmbeddings = await openai.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: [
+      'First document for batch processing',
+      'Second document for batch processing',
+      'Third document for batch processing',
+    ],
+    // No usageMetadata - still automatically tracked!
+  });
+
+  console.log(' Model:', batchEmbeddings.model);
+  console.log(' Usage:', batchEmbeddings.usage);
+  console.log(' Embeddings count:', batchEmbeddings.data.length);
+  console.log(' Batch embeddings automatically tracked without metadata\n');
+
+  // Example 4: Embeddings with metadata for batch processing
+  console.log(' Example 4: Batch embeddings with metadata');
+
+  const metadataBatchEmbeddings = await openai.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: [
+      'Document 1: Streaming responses provide real-time feedback',
+      'Document 2: Metadata enables rich business analytics',
+      'Document 3: Batch processing improves efficiency',
+    ],
+
+    //  All metadata fields are optional - perfect for batch operations!
+    usageMetadata: {
+      // User tracking (optional) - nested subscriber object
+      subscriber: {
+        id: 'batch-processor-123',
+        email: 'batch@data-company.com',
+        credential: {
+          name: 'batch-key',
+          value: 'batch-value-456',
+        },
+      },
+
+      // Business context (optional)
+      organizationId: 'data-company',
+      productId: 'document-search',
+
+      // Task classification (optional)
+      taskType: 'batch-document-embedding',
+      traceId: `batch-${Date.now()}`,
+
+      // Custom fields (optional)
+      agent: 'openai-batch-embeddings-metadata-node',
+    },
+  });
+
+  console.log(' Model:', metadataBatchEmbeddings.model);
+  console.log(' Usage:', metadataBatchEmbeddings.usage);
+  console.log(' Embeddings count:', metadataBatchEmbeddings.data.length);
+  console.log(' Batch embeddings tracked with metadata for business insights\n');
+
+  // Summary
+  console.log(' Summary:');
+  console.log(' Streaming responses work seamlessly with metadata');
+  console.log(' Usage tracked automatically when streams complete');
+  console.log(' Batch embeddings supported with optional metadata');
+  console.log(' All metadata fields are optional');
+  console.log(' No type casting required - native TypeScript support');
+  console.log(' Real-time streaming + comprehensive analytics');
+}
+
+// Run the example
+openaiStreamingExample().catch(console.error);

package/examples/openai-vision.ts

@@ -0,0 +1,289 @@
+/**
+ * OpenAI Vision Example
+ *
+ * Demonstrates how Revenium middleware seamlessly tracks GPT-4o vision API usage
+ * with multimodal inputs (text + images). Shows automatic tracking of:
+ * - Vision API calls with image URLs
+ * - Token usage including image processing tokens
+ * - Cost calculation for vision features
+ * - Different image detail levels (low, high, auto)
+ *
+ * All metadata fields are optional and work seamlessly with vision API!
+ *
+ * For complete metadata field reference, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ *
+ * OpenAI Vision API Reference:
+ * https://platform.openai.com/docs/guides/vision
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+async function openAIVisionExample() {
+  console.log('🖼️  OpenAI Vision API with Revenium Tracking\n');
+
+  // Initialize Revenium middleware
+  const initResult = initializeReveniumFromEnv();
+  if (!initResult.success) {
+    console.error('❌ Failed to initialize Revenium:', initResult.message);
+    process.exit(1);
+  }
+
+  // Create and patch OpenAI instance
+  const openai = patchOpenAIInstance(new OpenAI());
+
+  // Sample image URLs for demonstration
+  const imageUrl = 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg';
+
+  // Example 1: Basic vision request without metadata (automatic tracking)
+  console.log('📸 Example 1: Basic vision analysis (automatic tracking)\n');
+
+  const basicVisionResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: 'What is in this image? Describe it in one sentence.',
+          },
+          {
+            type: 'image_url',
+            image_url: {
+              url: imageUrl,
+            },
+          },
+        ],
+      },
+    ],
+    max_tokens: 300,
+    // No usageMetadata - still automatically tracked!
+  });
+
+  console.log('AI Response:', basicVisionResponse.choices[0]?.message?.content);
+  console.log('Usage:', basicVisionResponse.usage);
+  console.log('✅ Vision API automatically tracked without metadata\n');
+
+  // Example 2: Vision with detailed image analysis and metadata
+  console.log('🔍 Example 2: High-detail vision analysis with comprehensive metadata\n');
+
+  const detailedVisionResponse = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: 'Please analyze this image in detail. Describe the scene, colors, composition, and any notable features.',
+          },
+          {
+            type: 'image_url',
+            image_url: {
+              url: imageUrl,
+              detail: 'high', // High detail for better analysis (costs more tokens)
+            },
+          },
+        ],
+      },
+    ],
+    max_tokens: 500,
+
+    // ✨ All metadata fields are optional - perfect for tracking vision AI!
+    usageMetadata: {
+      subscriber: {
+        id: 'vision-user-123',
+        email: 'vision@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'vision-key-456',
+        },
+      },
+      organizationId: 'image-analysis-corp',
+      productId: 'ai-vision-platform',
+      subscriptionId: 'sub-vision-pro-789',
+      taskType: 'image-analysis-detailed',
+      traceId: `vision-${Date.now()}`,
+      agent: 'vision-analyzer-node',
+      responseQualityScore: 0.96,
+    },
+  });
+
+  console.log('AI Detailed Analysis:', detailedVisionResponse.choices[0]?.message?.content);
+  console.log('Usage:', detailedVisionResponse.usage);
+  console.log('✅ Vision API tracked with rich metadata for image analytics\n');
+
+  // Example 3: Multiple images in one request
+  console.log('🖼️ 🖼️  Example 3: Multiple images with low-detail mode\n');
+
+  const multiImageResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: 'Compare these two images. What do they have in common?',
+          },
+          {
+            type: 'image_url',
+            image_url: {
+              url: imageUrl,
+              detail: 'low', // Low detail for cost-effective processing
+            },
+          },
+          {
+            type: 'image_url',
+            image_url: {
+              url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Placeholder_view_vector.svg/310px-Placeholder_view_vector.svg.png',
+              detail: 'low',
+            },
+          },
+        ],
+      },
+    ],
+    max_tokens: 300,
+
+    // ✨ Tracking multi-image requests
+    usageMetadata: {
+      subscriber: {
+        id: 'multi-vision-user-789',
+        email: 'multi@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'multi-key-999',
+        },
+      },
+      organizationId: 'comparison-ai-corp',
+      productId: 'image-comparison-tool',
+      subscriptionId: 'sub-comparison-basic-456',
+      taskType: 'multi-image-comparison',
+      traceId: `multi-vision-${Date.now()}`,
+      agent: 'comparison-analyzer-node',
+      responseQualityScore: 0.88,
+    },
+  });
+
+  console.log('AI Comparison:', multiImageResponse.choices[0]?.message?.content);
+  console.log('Usage:', multiImageResponse.usage);
+  console.log('✅ Multiple images tracked with metadata for comparison analytics\n');
+
+  // Example 4: Vision with conversation context
+  console.log('💬 Example 4: Vision with multi-turn conversation\n');
+
+  const conversationMessages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+    {
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'What colors are prominent in this image?',
+        },
+        {
+          type: 'image_url',
+          image_url: {
+            url: imageUrl,
+            detail: 'auto', // Auto detail - OpenAI decides optimal level
+          },
+        },
+      ],
+    },
+  ];
+
+  const firstTurnResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: conversationMessages,
+    max_tokens: 200,
+
+    usageMetadata: {
+      subscriber: {
+        id: 'conversation-user-456',
+        email: 'conversation@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'conv-key-123',
+        },
+      },
+      organizationId: 'chat-vision-corp',
+      productId: 'interactive-vision-assistant',
+      subscriptionId: 'sub-interactive-premium-321',
+      taskType: 'conversational-vision',
+      traceId: `conv-vision-${Date.now()}`,
+      agent: 'conversation-vision-node',
+    },
+  });
+
+  console.log('First Turn - AI:', firstTurnResponse.choices[0]?.message?.content);
+  console.log('Usage:', firstTurnResponse.usage);
+
+  // Add AI response to conversation
+  conversationMessages.push({
+    role: 'assistant',
+    content: firstTurnResponse.choices[0]?.message?.content || '',
+  });
+
+  // Follow-up question without image
+  conversationMessages.push({
+    role: 'user',
+    content: 'Based on those colors, what mood does the image convey?',
+  });
+
+  const secondTurnResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: conversationMessages,
+    max_tokens: 200,
+
+    usageMetadata: {
+      subscriber: {
+        id: 'conversation-user-456',
+        email: 'conversation@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'conv-key-123',
+        },
+      },
+      organizationId: 'chat-vision-corp',
+      productId: 'interactive-vision-assistant',
+      subscriptionId: 'sub-interactive-premium-321',
+      taskType: 'conversational-vision-followup',
+      traceId: `conv-vision-${Date.now()}`,
+      agent: 'conversation-vision-node',
+    },
+  });
+
+  console.log('Second Turn - AI:', secondTurnResponse.choices[0]?.message?.content);
+  console.log('Usage:', secondTurnResponse.usage);
+  console.log('✅ Multi-turn vision conversation fully tracked\n');
+
+  // Summary
+  console.log('📈 Vision API Summary:');
+  console.log('✅ Image analysis with URLs fully supported');
+  console.log('✅ Token usage tracked including image processing tokens');
+  console.log('✅ Multiple images in one request work seamlessly');
+  console.log('✅ Detail levels (low, high, auto) all supported');
+  console.log('✅ Multi-turn conversations with image context tracked');
+  console.log('✅ All metadata fields optional and work perfectly');
+  console.log('✅ Cost calculation includes vision-specific tokens');
+  console.log('✅ No type casting required - native TypeScript support\n');
+
+  console.log('💡 Use Cases:');
+  console.log('   - Image content moderation and analysis');
+  console.log('   - Product catalog image descriptions');
+  console.log('   - Document and diagram understanding');
+  console.log('   - Visual question answering systems');
+  console.log('   - Accessibility tools (image descriptions)');
+  console.log('   - Quality control and inspection automation\n');
+
+  console.log('💰 Cost Optimization Tips:');
+  console.log('   - Use "low" detail for simple images to save tokens');
+  console.log('   - Use "high" detail only when fine details matter');
+  console.log('   - Use "auto" to let OpenAI optimize automatically');
+  console.log('   - Revenium tracks all token usage for accurate cost analytics');
+}
+
+// Run the example
+openAIVisionExample().catch(console.error);