@revenium/openai 1.0.11 → 1.0.12

package/examples/openai-function-calling.ts

@@ -0,0 +1,259 @@
+/**
+ * OpenAI Function Calling Example
+ *
+ * Demonstrates how Revenium middleware seamlessly tracks function/tool calling usage
+ * with OpenAI chat completions. Shows automatic tracking of:
+ * - Function definitions and calls
+ * - Token usage including function call overhead
+ * - Multi-turn conversations with function execution
+ * - Cost calculation for function calling features
+ *
+ * All metadata fields are optional and work seamlessly with function calling!
+ *
+ * For complete metadata field reference, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ *
+ * OpenAI Function Calling Reference:
+ * https://platform.openai.com/docs/guides/function-calling
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// Simulated weather API function
+function getCurrentWeather(location: string, unit: 'celsius' | 'fahrenheit' = 'celsius'): string {
+  // Simulate weather data
+  const temperature = unit === 'celsius' ? 22 : 72;
+  const conditions = 'sunny';
+
+  return JSON.stringify({
+    location,
+    temperature,
+    unit,
+    conditions,
+    forecast: 'Clear skies throughout the day',
+  });
+}
+
+async function openAIFunctionCallingExample() {
+  console.log('🔧 OpenAI Function Calling 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());
+
+  // Define function schema for OpenAI
+  const tools: OpenAI.Chat.Completions.ChatCompletionTool[] = [
+    {
+      type: 'function',
+      function: {
+        name: 'get_current_weather',
+        description: 'Get the current weather in a given location',
+        parameters: {
+          type: 'object',
+          properties: {
+            location: {
+              type: 'string',
+              description: 'The city and state, e.g. San Francisco, CA',
+            },
+            unit: {
+              type: 'string',
+              enum: ['celsius', 'fahrenheit'],
+              description: 'The temperature unit to use',
+            },
+          },
+          required: ['location'],
+        },
+      },
+    },
+  ];
+
+  // Example 1: Function calling without metadata (automatic tracking)
+  console.log('📍 Example 1: Basic function calling (automatic tracking)\n');
+
+  const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+    {
+      role: 'user',
+      content: "What's the weather like in San Francisco?",
+    },
+  ];
+
+  // First call - AI decides to use the function
+  const firstResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: messages,
+    tools: tools,
+    tool_choice: 'auto',
+    // No usageMetadata - still automatically tracked!
+  });
+
+  console.log('AI Response (First call):');
+  console.log('Usage:', firstResponse.usage);
+
+  const firstMessage = firstResponse.choices[0]?.message;
+  console.log('Finish reason:', firstResponse.choices[0]?.finish_reason);
+
+  // Check if AI wants to call a function
+  if (firstMessage?.tool_calls) {
+    console.log('\n🔧 AI decided to call function:', firstMessage.tool_calls[0]?.function.name);
+    console.log('Function arguments:', firstMessage.tool_calls[0]?.function.arguments);
+
+    // Execute the function
+    const functionCall = firstMessage.tool_calls[0];
+    const functionArgs = JSON.parse(functionCall?.function.arguments || '{}');
+    const functionResponse = getCurrentWeather(
+      functionArgs.location,
+      functionArgs.unit
+    );
+
+    console.log('Function result:', functionResponse);
+
+    // Add function call and result to conversation
+    messages.push(firstMessage);
+    messages.push({
+      role: 'tool',
+      tool_call_id: functionCall.id,
+      content: functionResponse,
+    });
+
+    // Second call - AI uses function result to answer
+    const secondResponse = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: messages,
+      tools: tools,
+      // No usageMetadata - still automatically tracked!
+    });
+
+    console.log('\n💬 AI Final Response:');
+    console.log('Content:', secondResponse.choices[0]?.message?.content);
+    console.log('Usage:', secondResponse.usage);
+    console.log('✅ Function calling automatically tracked without metadata\n');
+  }
+
+  // Example 2: Function calling with rich metadata
+  console.log('📊 Example 2: Function calling with comprehensive metadata\n');
+
+  const metadataMessages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+    {
+      role: 'user',
+      content: "I'm planning a trip. What's the weather in Boston and should I bring a jacket?",
+    },
+  ];
+
+  // First call with metadata
+  const metadataFirstResponse = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: metadataMessages,
+    tools: tools,
+    tool_choice: 'auto',
+
+    // ✨ All metadata fields are optional - perfect for tracking AI agents!
+    usageMetadata: {
+      subscriber: {
+        id: 'travel-user-456',
+        email: 'traveler@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'travel-key-789',
+        },
+      },
+      organizationId: 'travel-agency-corp',
+      productId: 'ai-travel-assistant',
+      subscriptionId: 'sub-pro-travel-123',
+      taskType: 'function-calling-weather',
+      traceId: `func-call-${Date.now()}`,
+      agent: 'weather-assistant-node',
+      responseQualityScore: 0.95,
+    },
+  });
+
+  console.log('AI Response with Metadata (First call):');
+  console.log('Usage:', metadataFirstResponse.usage);
+
+  const metadataFirstMessage = metadataFirstResponse.choices[0]?.message;
+  console.log('Finish reason:', metadataFirstResponse.choices[0]?.finish_reason);
+
+  // Process function calls if any
+  if (metadataFirstMessage?.tool_calls) {
+    console.log('\n🔧 Function calls requested:', metadataFirstMessage.tool_calls.length);
+
+    // Execute each function call
+    for (const toolCall of metadataFirstMessage.tool_calls) {
+      console.log('  - Function:', toolCall.function.name);
+      console.log('    Arguments:', toolCall.function.arguments);
+
+      const functionArgs = JSON.parse(toolCall.function.arguments);
+      const functionResponse = getCurrentWeather(
+        functionArgs.location,
+        functionArgs.unit
+      );
+
+      console.log('    Result:', functionResponse);
+
+      // Add function result to conversation
+      metadataMessages.push(metadataFirstMessage);
+      metadataMessages.push({
+        role: 'tool',
+        tool_call_id: toolCall.id,
+        content: functionResponse,
+      });
+    }
+
+    // Second call with metadata - AI generates final response
+    const metadataSecondResponse = await openai.chat.completions.create({
+      model: 'gpt-4o',
+      messages: metadataMessages,
+      tools: tools,
+
+      // ✨ Same metadata carried through the conversation
+      usageMetadata: {
+        subscriber: {
+          id: 'travel-user-456',
+          email: 'traveler@company.com',
+          credential: {
+            name: 'api-key',
+            value: 'travel-key-789',
+          },
+        },
+        organizationId: 'travel-agency-corp',
+        productId: 'ai-travel-assistant',
+        subscriptionId: 'sub-pro-travel-123',
+        taskType: 'function-calling-weather',
+        traceId: `func-call-${Date.now()}`,
+        agent: 'weather-assistant-node',
+        responseQualityScore: 0.98,
+      },
+    });
+
+    console.log('\n💬 AI Final Response with Metadata:');
+    console.log('Content:', metadataSecondResponse.choices[0]?.message?.content);
+    console.log('Usage:', metadataSecondResponse.usage);
+    console.log('✅ Function calling tracked with rich metadata for AI agent analytics\n');
+  }
+
+  // Summary
+  console.log('📈 Function Calling Summary:');
+  console.log('✅ Function definitions work seamlessly with middleware');
+  console.log('✅ Token usage tracked including function call overhead');
+  console.log('✅ Multi-turn conversations fully supported');
+  console.log('✅ All metadata fields optional and work perfectly');
+  console.log('✅ Cost calculation includes function calling tokens');
+  console.log('✅ No type casting required - native TypeScript support');
+  console.log('✅ Perfect for tracking AI agents and tool usage\n');
+
+  console.log('💡 Use Cases:');
+  console.log('   - AI agents with tool access');
+  console.log('   - Customer support bots with API integrations');
+  console.log('   - Data analysis assistants with function execution');
+  console.log('   - Multi-step workflows with external tools');
+}
+
+// Run the example
+openAIFunctionCallingExample().catch(console.error);

package/examples/openai-responses-basic.ts

@@ -5,7 +5,16 @@
  * The Responses API is a new stateful API that brings together capabilities from chat completions
  * and assistants API in one unified experience.
  *
- * Reference: https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/responses
+ * 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';
@@ -71,19 +80,29 @@ async function main() {
         ],
         max_output_tokens: 150,
         usageMetadata: {
+          // User identification
           subscriber: {
             id: 'user-123',
             email: 'user@example.com',
             credential: {
-              name: 'api-key',
-              value: 'sk-...',
+              name: 'api-key-prod',
+              value: 'key-efg-123',
             },
           },
+
+          // Organization & billing
           organizationId: 'org-456',
+          subscriptionId: 'plan-responses-2024',
+
+          // Product & task tracking
           productId: 'quantum-explainer',
           taskType: 'educational-content',
-          traceId: 'trace-789',
           agent: 'quantum-tutor',
+
+          // Session tracking
+          traceId: 'trace-789',
+
+          // Quality metrics
           responseQualityScore: 0.95,
         },
       } as ResponsesCreateParams);
@@ -146,19 +165,29 @@ async function main() {
         max_output_tokens: 200,
         instructions: 'You are a helpful AI assistant specializing in API documentation.',
         usageMetadata: {
+          // User identification
           subscriber: {
             id: 'enterprise-user-456',
             email: 'enterprise@company.com',
             credential: {
-              name: 'enterprise-key',
-              value: 'sk-enterprise-...',
+              name: 'api-key-prod',
+              value: 'key-hij-456',
             },
           },
+
+          // Organization & billing
           organizationId: 'enterprise-org-789',
+          subscriptionId: 'plan-enterprise-docs-2024',
+
+          // Product & task tracking
           productId: 'api-documentation-assistant',
           taskType: 'technical-documentation',
-          traceId: 'enterprise-trace-012',
           agent: 'documentation-expert',
+
+          // Session tracking
+          traceId: 'enterprise-trace-012',
+
+          // Quality metrics
           responseQualityScore: 0.98,
         },
       } as ResponsesCreateParams);

package/examples/openai-responses-streaming.ts

@@ -5,7 +5,16 @@
  * using the Revenium middleware. The Responses API supports streaming for real-time
  * response generation.
  *
- * Reference: https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/responses
+ * 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';
@@ -75,19 +84,29 @@ async function main() {
         stream: true,
         max_output_tokens: 200,
         usageMetadata: {
+          // User identification
           subscriber: {
             id: 'streaming-user-123',
             email: 'streaming@example.com',
             credential: {
-              name: 'streaming-key',
-              value: 'sk-streaming-...',
+              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',
-          traceId: 'stream-trace-789',
           agent: 'ml-tutor-stream',
+
+          // Session tracking
+          traceId: 'stream-trace-789',
+
+          // Quality metrics
           responseQualityScore: 0.92,
         },
       } as ResponsesCreateParams);
@@ -163,19 +182,29 @@ async function main() {
         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: 'enterprise-streaming-key',
-              value: 'sk-enterprise-streaming-...',
+              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',
-          traceId: 'advanced-stream-trace-345',
           agent: 'streaming-expert',
+
+          // Session tracking
+          traceId: 'advanced-stream-trace-345',
+
+          // Quality metrics
           responseQualityScore: 0.97,
         },
       } as ResponsesCreateParams);

package/examples/openai-streaming.ts

@@ -1,8 +1,17 @@
 /**
- *  OpenAI Streaming Example
+ * 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';
@@ -52,30 +61,32 @@ async function openaiStreamingExample() {
     messages: [{ role: 'user', content: 'Write a haiku about middleware' }],
     stream: true,
 
-    //  All metadata fields are optional - add what you need for analytics!
-    // Note: Nested subscriber structure matches Python middleware implementation
+    // Optional metadata for advanced reporting, lineage tracking, and cost allocation
     usageMetadata: {
-      // User tracking (optional) - nested subscriber object
+      // User identification
       subscriber: {
         id: 'streaming-user-456',
         email: 'poet@company.com',
         credential: {
-          name: 'stream-key',
-          value: 'stream456',
+          name: 'api-key-prod',
+          value: 'key-ghi-789',
         },
       },
 
-      // Business context (optional)
+      // Organization & billing
       organizationId: 'creative-company',
-      productId: 'ai-poet',
+      subscriptionId: 'plan-creative-2024',
 
-      // Task classification (optional)
+      // Product & task tracking
+      productId: 'ai-poet',
       taskType: 'creative-writing',
-      traceId: `stream-${Date.now()}`,
+      agent: 'openai-streaming-chat-node',
 
-      // Custom fields (optional)
-      agent: 'openai-streaming-chat-metadata-node',
-      responseQualityScore: 0.9,
+      // Session tracking
+      traceId: 'stream-' + Date.now(),
+
+      // Quality metrics
+      responseQualityScore: 0.92,
     },
   });