@revenium/openai 1.0.10 → 1.0.12

package/examples/README.md

@@ -0,0 +1,357 @@
+# Revenium OpenAI Middleware - Examples
+
+**TypeScript-first** examples demonstrating automatic Revenium usage tracking with the OpenAI SDK.
+
+## Getting Started - Step by Step
+
+### 1. Create Your Project
+
+```bash
+# Create project directory
+mkdir my-openai-project
+cd my-openai-project
+
+# Initialize Node.js project
+npm init -y
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install @revenium/openai openai dotenv
+npm install -D typescript tsx @types/node  # For TypeScript
+```
+
+### 3. Environment Setup
+
+Create a `.env` file in your project root:
+
+```bash
+# Required
+REVENIUM_METERING_API_KEY=hak_your_revenium_api_key
+OPENAI_API_KEY=sk_your_openai_api_key
+
+# Optional
+REVENIUM_METERING_BASE_URL=https://api.revenium.io
+REVENIUM_DEBUG=false
+
+# Optional - For Azure OpenAI examples
+AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
+AZURE_OPENAI_API_KEY=your-azure-api-key
+AZURE_OPENAI_DEPLOYMENT=your-deployment-name
+AZURE_OPENAI_API_VERSION=2024-12-01-preview
+```
+
+### 4. Run Examples
+
+**If you cloned from GitHub:**
+
+```bash
+# Run examples directly
+npx tsx examples/getting_started.ts
+npx tsx examples/openai-basic.ts
+npx tsx examples/openai-streaming.ts
+```
+
+**If you installed via npm:**
+
+Examples are included in your `node_modules/@revenium/openai/examples/` directory:
+
+```bash
+npx tsx node_modules/@revenium/openai/examples/getting_started.ts
+npx tsx node_modules/@revenium/openai/examples/openai-basic.ts
+npx tsx node_modules/@revenium/openai/examples/openai-streaming.ts
+```
+
+## Available Examples
+
+### `getting_started.ts` - Simple Entry Point
+
+The simplest example to get you started with Revenium tracking:
+
+- **Minimal setup** - Just import, configure, and start tracking
+- **Complete metadata example** - Shows all 11 optional metadata fields in comments
+- **Ready to customize** - Uncomment the metadata section to add tracking context
+
+**Key Features:**
+
+- Auto-initialization from environment variables
+- Native `usageMetadata` support via module augmentation
+- All metadata fields documented with examples
+- Single API call demonstration
+
+**Perfect for:** First-time users, quick validation, understanding metadata structure
+
+**See the file for complete code examples.**
+
+### `openai-basic.ts` - Chat Completions and Embeddings
+
+Demonstrates standard OpenAI API usage with automatic tracking:
+
+- **Chat completions** - Basic chat API with metadata tracking
+- **Embeddings** - Text embedding generation with usage tracking
+- **Multiple API calls** - Batch operations with consistent metadata
+
+**Key Features:**
+
+- TypeScript module augmentation for native `usageMetadata` support
+- Full type safety with IntelliSense
+- Comprehensive metadata examples
+- Error handling patterns
+
+**Perfect for:** Understanding basic OpenAI API patterns with tracking
+
+**See the file for complete code examples.**
+
+### `openai-streaming.ts` - Real-time Streaming
+
+Demonstrates streaming responses with automatic token tracking:
+
+- **Streaming chat completions** - Real-time token streaming with metadata
+- **Batch embeddings** - Multiple embedding requests efficiently
+- **Stream processing** - Type-safe event handling
+
+**Key Features:**
+
+- Automatic tracking when stream completes
+- Real-time token counting
+- Time-to-first-token metrics
+- Stream error handling
+
+**Perfect for:** Real-time applications, chatbots, interactive AI assistants
+
+**See the file for complete code examples.**
+
+### `openai-function-calling.ts` - Function Calling with Tools
+
+Demonstrates OpenAI function calling (tools) with tracking:
+
+- **Tool definitions** - Define functions for the AI to call
+- **Function execution** - Handle tool calls and return results
+- **Multi-turn conversations** - Manage conversation flow with function results
+
+**Key Features:**
+
+- Complete function calling workflow
+- Type-safe tool definitions
+- Automatic tracking of tool usage
+- Multi-turn conversation handling
+
+**Perfect for:** AI agents, function-calling applications, structured outputs
+
+**See the file for complete code examples.**
+
+### `openai-vision.ts` - Vision API with Images
+
+Demonstrates OpenAI Vision API with image analysis:
+
+- **Image URL analysis** - Analyze images from URLs
+- **Base64 images** - Process local images as base64
+- **Multi-image analysis** - Compare multiple images in one request
+
+**Key Features:**
+
+- Image analysis with GPT-4 Vision
+- Multiple image input methods
+- Detailed image descriptions
+- Usage tracking for vision API calls
+
+**Perfect for:** Image analysis applications, visual search, accessibility tools
+
+**See the file for complete code examples.**
+
+### `openai-responses-basic.ts` - New Responses API
+
+Demonstrates OpenAI's new Responses API (SDK 5.8+):
+
+- **Simplified interface** - Uses `input` instead of `messages` parameter
+- **Stateful API** - Enhanced capabilities for agent-like applications
+- **Unified experience** - Combines chat completions and assistants features
+
+**Key Features:**
+
+- New Responses API patterns
+- Automatic tracking with new API
+- Metadata support
+- Backward compatibility notes
+
+**Perfect for:** Applications using OpenAI's latest API features
+
+**See the file for complete code examples.**
+
+### `openai-responses-streaming.ts` - Responses API Streaming
+
+Demonstrates streaming with the new Responses API:
+
+- **Streaming responses** - Real-time responses with new API
+- **Event handling** - Process response events as they arrive
+- **Usage tracking** - Automatic tracking for streaming responses
+
+**Key Features:**
+
+- Responses API streaming patterns
+- Type-safe event processing
+- Automatic usage metrics
+- Stream completion tracking
+
+**Perfect for:** Real-time applications using the new Responses API
+
+**See the file for complete code examples.**
+
+### Azure OpenAI Examples
+
+#### `azure-basic.ts` - Azure Chat Completions
+
+Demonstrates Azure OpenAI integration with automatic detection:
+
+- **Azure configuration** - Environment-based Azure setup
+- **Chat completions** - Azure-hosted models with tracking
+- **Automatic detection** - Middleware detects Azure vs OpenAI automatically
+
+**Key Features:**
+
+- Azure OpenAI deployment configuration
+- Model name resolution for Azure
+- Accurate Azure pricing
+- Metadata tracking with Azure
+
+**Perfect for:** Enterprise applications using Azure OpenAI
+
+**See the file for complete code examples.**
+
+#### `azure-streaming.ts` - Azure Streaming
+
+Demonstrates streaming with Azure OpenAI:
+
+- **Azure streaming** - Real-time responses from Azure-hosted models
+- **Deployment resolution** - Automatic Azure deployment name handling
+- **Usage tracking** - Azure-specific metrics and pricing
+
+**Perfect for:** Real-time Azure OpenAI applications
+
+**See the file for complete code examples.**
+
+#### `azure-responses-basic.ts` - Azure Responses API
+
+Demonstrates new Responses API with Azure OpenAI:
+
+- **Azure + Responses API** - Combine Azure hosting with new API
+- **Unified interface** - Same Responses API patterns on Azure
+- **Automatic tracking** - Azure-aware usage tracking
+
+**Perfect for:** Azure applications using latest OpenAI features
+
+**See the file for complete code examples.**
+
+#### `azure-responses-streaming.ts` - Azure Responses Streaming
+
+Demonstrates Responses API streaming with Azure OpenAI:
+
+- **Azure streaming** - Real-time Responses API on Azure
+- **Event handling** - Process Azure response events
+- **Complete tracking** - Azure metrics with new API
+
+**Perfect for:** Real-time Azure applications with Responses API
+
+**See the file for complete code examples.**
+
+## TypeScript Configuration
+
+Ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## Requirements
+
+- **Node.js 16+** with TypeScript support
+- **TypeScript 4.5+** for module augmentation features
+- **Valid Revenium API key** (starts with `hak_`)
+- **Valid OpenAI API key** (starts with `sk-`) or Azure OpenAI credentials
+- **OpenAI SDK 5.0+** (5.8+ for Responses API)
+
+## Troubleshooting
+
+### Module Augmentation Not Working
+
+**Problem:** TypeScript doesn't recognize `usageMetadata` in OpenAI SDK calls
+
+**Solution:**
+
+```typescript
+// ❌ Wrong - missing module augmentation import
+import { initializeReveniumFromEnv } from "@revenium/openai";
+
+// ✅ Correct - import for module augmentation
+import { initializeReveniumFromEnv, patchOpenAIInstance } from "@revenium/openai";
+import OpenAI from "openai";
+```
+
+### Environment Variables Not Loading
+
+**Problem:** `REVENIUM_METERING_API_KEY` or `OPENAI_API_KEY` not found
+
+**Solutions:**
+
+- Ensure `.env` file is in project root
+- Check variable names match exactly
+- Verify you're importing `dotenv/config` before the middleware
+- Check API keys have correct prefixes (`hak_` for Revenium, `sk-` for OpenAI)
+
+### TypeScript Compilation Errors
+
+**Problem:** Module resolution or import errors
+
+**Solution:** Verify your `tsconfig.json` settings:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  }
+}
+```
+
+### Azure Configuration Issues
+
+**Problem:** Azure OpenAI not working or incorrect pricing
+
+**Solutions:**
+
+- Verify all Azure environment variables are set (`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_DEPLOYMENT`)
+- Check deployment name matches your Azure resource
+- Ensure API version is compatible (`2024-12-01-preview` or later recommended)
+- Verify endpoint URL format: `https://your-resource-name.openai.azure.com/`
+
+### Debug Mode
+
+Enable detailed logging to troubleshoot issues:
+
+```bash
+# In .env file
+REVENIUM_DEBUG=true
+
+# Then run examples
+npx tsx examples/getting_started.ts
+```
+
+## Additional Resources
+
+- **Main Documentation**: See root [README.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/README.md)
+- **API Reference**: [Revenium Metadata Fields](https://revenium.readme.io/reference/meter_ai_completion)
+- **OpenAI Documentation**: [OpenAI API Reference](https://platform.openai.com/docs)
+- **Issues**: [Report bugs](https://github.com/revenium/revenium-middleware-openai-node/issues)

package/examples/azure-basic.ts

@@ -0,0 +1,206 @@
+/**
+ * Azure OpenAI Basic Example
+ *
+ * Shows how to use Revenium middleware with Azure OpenAI chat completions and embeddings.
+ * Demonstrates seamless metadata integration with Azure - 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 { AzureOpenAI } from 'openai';
+
+async function azureBasicExample() {
+  console.log('️ Azure OpenAI Basic Usage 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 Azure OpenAI instance and patch it
+  const azure = patchOpenAIInstance(
+    new AzureOpenAI({
+      endpoint: process.env.AZURE_OPENAI_ENDPOINT,
+      apiKey: process.env.AZURE_OPENAI_API_KEY,
+      apiVersion: process.env.AZURE_OPENAI_API_VERSION || '2024-12-01-preview',
+    })
+  );
+
+  console.log(' Azure OpenAI client configured and patched');
+  console.log(' Endpoint:', process.env.AZURE_OPENAI_ENDPOINT);
+  console.log(' API Version:', process.env.AZURE_OPENAI_API_VERSION || '2024-12-01-preview');
+  console.log();
+
+  // Check if we have a chat model configured
+  const deployment = process.env.AZURE_OPENAI_DEPLOYMENT;
+  const isChatModel = deployment && !deployment.includes('embedding');
+
+  if (!isChatModel) {
+    console.log('️  Note: Current Azure deployment appears to be for embeddings.');
+    console.log('   To test chat completions, update .env to use a chat model:');
+    console.log('   - Comment out the embeddings section');
+    console.log('   - Uncomment the chat testing section');
+    console.log('   - Set AZURE_OPENAI_DEPLOYMENT=gpt-4o');
+    console.log('\n   Skipping chat examples and testing embeddings instead...\n');
+  } else {
+    // Example 1: Basic Azure chat completion (no metadata)
+    console.log(' Example 1: Basic Azure chat completion (automatic tracking)');
+
+    const basicResponse = await azure.chat.completions.create({
+      model: deployment,
+      messages: [{ role: 'user', content: 'What are the benefits of using Azure OpenAI?' }],
+      // No usageMetadata - still automatically tracked with Azure provider info!
+      // No max_tokens - let response complete naturally
+    });
+
+    console.log(' Response:', basicResponse.choices[0]?.message?.content);
+    console.log(' Usage:', basicResponse.usage);
+    console.log(' Automatically tracked to Revenium with Azure provider metadata\n');
+  }
+
+  if (isChatModel) {
+    // Example 2: Azure chat completion with rich metadata (all optional!)
+    console.log(' Example 2: Azure chat completion with rich metadata');
+
+    const metadataResponse = await azure.chat.completions.create({
+      model: deployment,
+      messages: [
+        {
+          role: 'user',
+          content: 'Explain how Azure OpenAI differs from standard OpenAI in 3 points.',
+        },
+      ],
+
+      // Optional metadata for advanced reporting, lineage tracking, and cost allocation
+      usageMetadata: {
+        // User identification
+        subscriber: {
+          id: 'azure-user-789',
+          email: 'azure-dev@company.com',
+          credential: {
+            name: 'api-key-prod',
+            value: 'key-jkl-012',
+          },
+        },
+
+        // Organization & billing
+        organizationId: 'enterprise-corp',
+        subscriptionId: 'plan-azure-enterprise-2024',
+
+        // Product & task tracking
+        productId: 'azure-ai-platform',
+        taskType: 'azure-comparison',
+        agent: 'azure-basic-chat-node',
+
+        // Session tracking
+        traceId: 'azure-' + Date.now(),
+
+        // Quality metrics
+        responseQualityScore: 0.92,
+      },
+    });
+
+    console.log(' Response:', metadataResponse.choices[0]?.message?.content);
+    console.log(' Usage:', metadataResponse.usage);
+    console.log(' Tracked with Azure provider + rich metadata for enterprise analytics\n');
+  }
+
+  // Example 3: Azure embeddings (requires embeddings model)
+  console.log(' Example 3: Azure embeddings');
+
+  if (isChatModel) {
+    console.log('️  Note: Current deployment is a chat model (gpt-4o).');
+    console.log('   Embeddings require an embedding model like text-embedding-3-large.');
+    console.log('   To test embeddings, switch .env to embeddings configuration.');
+    console.log('   Skipping embeddings examples.\n');
+  } else {
+    console.log(' Example 3a: Basic Azure embeddings (automatic tracking)');
+
+    const basicEmbedding = await azure.embeddings.create({
+      model: deployment || 'text-embedding-3-large',
+      input:
+        'Azure OpenAI provides enterprise-grade AI capabilities with enhanced security and compliance',
+      // No usageMetadata - still automatically tracked with Azure provider info!
+    });
+
+    console.log(' Model:', basicEmbedding.model);
+    console.log(' Usage:', basicEmbedding.usage);
+    console.log(' Embedding dimensions:', basicEmbedding.data[0]?.embedding.length);
+    console.log(' Azure embeddings automatically tracked without metadata\n');
+
+    // Example 4: Azure embeddings with metadata (all optional!)
+    console.log(' Example 3b: Azure embeddings with rich metadata');
+
+    const metadataEmbedding = await azure.embeddings.create({
+      model: deployment || 'text-embedding-3-large',
+      input:
+        'Enterprise document processing with Azure OpenAI embeddings and comprehensive tracking',
+
+      //  All metadata fields are optional - perfect for Azure enterprise use cases!
+      // Note: Nested subscriber structure matches Python middleware for consistency
+      usageMetadata: {
+        subscriber: {
+          id: 'azure-embed-user-456',
+          email: 'embeddings@enterprise-corp.com',
+          credential: {
+            name: 'azure-embed-key',
+            value: 'embed456',
+          },
+        },
+        organizationId: 'enterprise-corp',
+        productId: 'azure-search-platform',
+        subscriptionId: 'sub-azure-premium-999',
+        taskType: 'enterprise-document-embedding',
+        traceId: `azure-embed-${Date.now()}`,
+        agent: 'azure-basic-embeddings-node',
+      },
+    });
+
+    console.log(' Model:', metadataEmbedding.model);
+    console.log(' Usage:', metadataEmbedding.usage);
+    console.log(' Embedding dimensions:', metadataEmbedding.data[0]?.embedding.length);
+    console.log(' Azure embeddings tracked with metadata for enterprise analytics\n');
+  }
+
+  // Summary
+  console.log(' Azure OpenAI Summary:');
+  console.log(' Azure OpenAI automatically detected and tracked');
+  console.log(' Model name resolution for accurate pricing');
+  console.log(' Provider metadata includes "Azure" for analytics');
+  if (isChatModel) {
+    console.log(' Chat completions work with or without metadata');
+  } else {
+    console.log(' Embeddings work with or without metadata');
+  }
+  console.log(' All metadata fields are optional');
+  console.log(' No type casting required - native TypeScript support');
+  console.log(' Enterprise-grade tracking with Azure compliance');
+
+  if (!isChatModel) {
+    console.log('\n To test Azure chat completions:');
+    console.log('   1. Edit .env file');
+    console.log('   2. Comment out embeddings section');
+    console.log('   3. Uncomment chat section');
+    console.log('   4. Run this example again');
+  } else {
+    console.log('\n To test Azure embeddings:');
+    console.log('   1. Edit .env file');
+    console.log('   2. Comment out chat section');
+    console.log('   3. Uncomment embeddings section');
+    console.log('   4. Run this example again');
+  }
+}
+
+// Run the example
+azureBasicExample().catch(console.error);