@revenium/openai 1.0.10 → 1.0.12

package/src/types/responses-api.ts

@@ -0,0 +1,308 @@
+/**
+ * Types for OpenAI Responses API support
+ *
+ * This module defines types for the new OpenAI Responses API that replaces
+ * the traditional Chat Completions API. The Responses API provides a unified
+ * interface for building agent-like applications with built-in tools and capabilities.
+ *
+ * Reference: https://platform.openai.com/docs/guides/migrate-to-responses
+ */
+
+import { UsageMetadata } from './index.js';
+
+/**
+ * OpenAI Responses API request parameters
+ * Based on the official OpenAI Responses API documentation
+ * Reference: https://platform.openai.com/docs/guides/migrate-to-responses
+ */
+export interface OpenAIResponsesRequest {
+  /** The model to use for the response */
+  model: string;
+
+  /** Input for the response - can be string or message array */
+  input:
+    | string
+    | Array<{
+        role: 'user' | 'assistant' | 'system';
+        content: string;
+      }>;
+
+  /** Whether to stream the response */
+  stream?: boolean;
+
+  /** Maximum number of output tokens to generate */
+  max_output_tokens?: number;
+
+  /** Temperature for response generation (0.0 to 2.0) */
+  temperature?: number;
+
+  /** Top-p sampling parameter (0.0 to 1.0) */
+  top_p?: number;
+
+  /** Instructions for the model (replaces system messages) */
+  instructions?: string;
+
+  /** Tools available to the model */
+  tools?: Array<{
+    type: 'function' | 'web_search' | 'file_search' | 'code_interpreter' | 'image_generation';
+    // For function tools (internally tagged)
+    name?: string;
+    description?: string;
+    parameters?: {
+      type: 'object';
+      properties: Record<string, unknown>;
+      required?: string[];
+      additionalProperties?: boolean;
+    };
+    // For other tools
+    [key: string]: unknown;
+  }>;
+
+  /** Tool choice configuration */
+  tool_choice?: 'auto' | 'none' | { type: 'function'; name: string };
+
+  /** Structured output configuration */
+  text?: {
+    format?: {
+      type: 'json_schema';
+      name: string;
+      strict?: boolean;
+      schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+      };
+    };
+  };
+
+  /** Metadata for the request */
+  metadata?: Record<string, unknown>;
+
+  /** ID of previous response to continue from */
+  previous_response_id?: string;
+
+  /** Whether to run in background mode */
+  background?: boolean;
+
+  /** Whether to store the response (default: true) */
+  store?: boolean;
+
+  /** Parallel tool calls configuration */
+  parallel_tool_calls?: boolean;
+
+  /** Reasoning effort level */
+  reasoning_effort?: 'low' | 'medium' | 'high';
+
+  /** Include additional data in response */
+  include?: Array<'reasoning.encrypted_content'>;
+
+  /** Custom metadata field for Revenium tracking */
+  usageMetadata?: UsageMetadata;
+
+  /** Additional parameters */
+  [key: string]: unknown;
+}
+
+/**
+ * OpenAI Responses API response structure
+ * Based on the official Azure OpenAI Responses API documentation
+ */
+export interface OpenAIResponsesResponse {
+  /** Unique identifier for the response */
+  id: string;
+
+  /** Timestamp when the response was created */
+  created_at: number;
+
+  /** The model used for the response */
+  model: string;
+
+  /** Response object type */
+  object: 'response';
+
+  /** Response status */
+  status: 'queued' | 'in_progress' | 'completed' | 'incomplete' | 'cancelled' | 'failed';
+
+  /** Response output array */
+  output: Array<{
+    id: string;
+    type: 'message' | 'function_call' | 'function_call_output' | 'image_generation_call';
+    role?: 'assistant';
+    content?: Array<{
+      type: 'output_text' | 'text';
+      text?: string;
+      annotations?: Array<unknown>;
+    }>;
+    name?: string;
+    call_id?: string;
+    output?: string;
+    result?: string;
+    status?: string | null;
+  }>;
+
+  /** Simplified output text (convenience field) */
+  output_text?: string;
+
+  /** Usage statistics */
+  usage?: {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    output_tokens_details?: {
+      reasoning_tokens: number;
+    };
+  };
+
+  /** Response metadata */
+  metadata?: Record<string, unknown>;
+
+  /** Instructions used */
+  instructions?: string | null;
+
+  /** Tools configuration */
+  tools?: Array<unknown>;
+
+  /** Tool choice configuration */
+  tool_choice?: unknown;
+
+  /** Parallel tool calls setting */
+  parallel_tool_calls?: boolean | null;
+
+  /** Temperature used */
+  temperature?: number;
+
+  /** Top-p used */
+  top_p?: number;
+
+  /** Max output tokens */
+  max_output_tokens?: number | null;
+
+  /** Previous response ID */
+  previous_response_id?: string | null;
+
+  /** Error information */
+  error?: unknown | null;
+
+  /** Incomplete details */
+  incomplete_details?: unknown | null;
+
+  /** Reasoning information */
+  reasoning?: unknown | null;
+
+  /** Text field */
+  text?: unknown | null;
+
+  /** Truncation information */
+  truncation?: unknown | null;
+
+  /** User information */
+  user?: unknown | null;
+
+  /** Reasoning effort */
+  reasoning_effort?: unknown | null;
+}
+
+/**
+ * Streaming chunk for Responses API
+ */
+export interface OpenAIResponsesStreamChunk {
+  /** Unique identifier for the response */
+  id: string;
+
+  /** The model used */
+  model: string;
+
+  /** Delta content for this chunk */
+  delta?: {
+    content?: Array<{
+      type: 'text' | 'tool_use';
+      text?: string;
+      [key: string]: unknown;
+    }>;
+  };
+
+  /** Usage information (typically in final chunk) */
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    reasoning_tokens?: number;
+    cached_tokens?: number;
+  };
+
+  /** Finish reason (in final chunk) */
+  finish_reason?: string | null;
+
+  /** Additional chunk fields */
+  [key: string]: unknown;
+}
+
+/**
+ * Type guard to check if a request is for Responses API
+ */
+export function isResponsesRequest(params: unknown): params is OpenAIResponsesRequest {
+  return typeof params === 'object' && params !== null && 'input' in params && 'model' in params;
+}
+
+/**
+ * Type guard to check if a response is from Responses API
+ */
+export function isResponsesResponse(response: unknown): response is OpenAIResponsesResponse {
+  return (
+    typeof response === 'object' &&
+    response !== null &&
+    'id' in response &&
+    'model' in response &&
+    ('output' in response || 'usage' in response)
+  );
+}
+
+/**
+ * Simplified interface for Responses API create parameters (for examples)
+ */
+export interface ResponsesCreateParams {
+  model: string;
+  input: string | Array<{ role: 'user' | 'assistant' | 'system'; content: string }>;
+  stream?: boolean;
+  max_output_tokens?: number;
+  temperature?: number;
+  instructions?: string;
+  tools?: Array<{
+    type: 'function' | 'web_search' | 'file_search' | 'code_interpreter' | 'image_generation';
+    function?: {
+      name: string;
+      description?: string;
+      parameters?: Record<string, unknown>;
+    };
+  }>;
+  usageMetadata?: UsageMetadata;
+}
+
+/**
+ * Simplified interface for Responses API response (for examples)
+ */
+export interface ResponsesResponse {
+  id: string;
+  model: string;
+  object: 'response';
+  status: string;
+  output: Array<{
+    id: string;
+    type: string;
+    role?: string;
+    content?: Array<{
+      type: 'output_text' | 'text';
+      text?: string;
+    }>;
+  }>;
+  output_text?: string;
+  usage?: {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    output_tokens_details?: {
+      reasoning_tokens: number;
+    };
+  };
+}

package/src/utils/azure-model-resolver.ts

@@ -0,0 +1,220 @@
+import { getLogger } from '../core/config/index.js';
+import { knownModels } from './constants.js';
+
+/**
+ * Azure Model Name Resolution Module
+ *
+ * This module maps Azure deployment names to LiteLLM-compatible model names for accurate pricing.
+ * Based on learnings from the Python implementation, it uses heuristic pattern matching
+ * with fallback strategies to ensure reliable model name resolution.
+ *
+ * Key patterns observed in real Azure deployments:
+ * - "gpt-4o-2024-11-20" → "gpt-4o"
+ * - "text-embedding-3-large" → "text-embedding-3-large" (exact match)
+ * - "o4-mini" → "gpt-4o-mini"
+ * - "gpt4o-prod" → "gpt-4o"
+ * - "gpt-35-turbo-dev" → "gpt-3.5-turbo"
+ */
+
+/**
+ * In-memory cache for resolved model names
+ * Using Map for thread-safe operations in Node.js
+ */
+const modelNameCache = new Map<string, string>();
+
+/**
+ * Cache for failed resolution attempts to avoid repeated warnings
+ */
+const failedResolutionCache = new Set<string>();
+
+// Global logger
+const logger = getLogger();
+
+/**
+ * Resolve Azure deployment name to LiteLLM-compatible model name
+ *
+ * @param deploymentName - Azure deployment name
+ * @param useCache - Whether to use cached results (default: true)
+ * @returns LiteLLM-compatible model name
+ */
+export function resolveAzureModelName(deploymentName: string, useCache: boolean = true): string {
+  if (!deploymentName) {
+    logger.warn('Empty deployment name provided to model resolver');
+    return deploymentName;
+  }
+
+  // Check cache first
+  if (useCache && modelNameCache.has(deploymentName)) {
+    const cachedResult = modelNameCache.get(deploymentName)!;
+    logger.debug('Model name resolved from cache', {
+      deployment: deploymentName,
+      resolved: cachedResult,
+    });
+    return cachedResult;
+  }
+
+  try {
+    const resolved = resolveModelNameHeuristic(deploymentName);
+
+    // Cache the result
+    if (useCache) {
+      modelNameCache.set(deploymentName, resolved);
+    }
+
+    // Log successful resolution
+    if (resolved !== deploymentName) {
+      logger.debug('Model name resolved via heuristics', {
+        deployment: deploymentName,
+        resolved,
+      });
+    }
+
+    return resolved;
+  } catch (error) {
+    logger.error('Error during model name resolution', {
+      deployment: deploymentName,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    // Fallback to deployment name
+    return deploymentName;
+  }
+}
+
+/**
+ * Heuristic pattern matching for Azure deployment names
+ * Based on real-world patterns observed in the Python implementation
+ *
+ * @param deploymentName - Azure deployment name
+ * @returns LiteLLM-compatible model name
+ */
+function resolveModelNameHeuristic(deploymentName: string): string {
+  const nameLower = deploymentName.toLowerCase();
+
+  // GPT-4o family - handle both "gpt-4o" and "o4" patterns
+  if (/gpt-?4o/.test(nameLower) || /o4/.test(nameLower)) {
+    if (/mini/.test(nameLower)) return 'gpt-4o-mini';
+    return 'gpt-4o';
+  }
+
+  // GPT-4 family (non-omni)
+  if (/gpt-?4(?!o)/.test(nameLower)) {
+    if (/turbo/.test(nameLower)) return 'gpt-4-turbo';
+    if (/vision/.test(nameLower) || /v/.test(nameLower)) return 'gpt-4-vision-preview';
+    return 'gpt-4';
+  }
+
+  // GPT-3.5 family
+  if (/gpt-?3\.?5/.test(nameLower) || /35-turbo/.test(nameLower) || /gpt-35/.test(nameLower)) {
+    if (/instruct/.test(nameLower)) return 'gpt-3.5-turbo-instruct';
+    return 'gpt-3.5-turbo';
+  }
+
+  // Embedding models - exact matches work well
+  if (/embed/.test(nameLower)) {
+    if (/text-embedding-3-large/.test(nameLower)) return 'text-embedding-3-large';
+    if (/text-embedding-3-small/.test(nameLower)) return 'text-embedding-3-small';
+    if (/text-embedding-ada-002/.test(nameLower) || /ada-002/.test(nameLower))
+      return 'text-embedding-ada-002';
+    if (/3-large/.test(nameLower)) return 'text-embedding-3-large';
+    if (/3-small/.test(nameLower)) return 'text-embedding-3-small';
+  }
+
+  // Ada-002 pattern (can appear without "embed" in deployment name)
+  if (/ada-002/.test(nameLower)) return 'text-embedding-ada-002';
+
+  // DALL-E models
+  if (/dall-?e/.test(nameLower)) {
+    if (/3/.test(nameLower)) return 'dall-e-3';
+    if (/2/.test(nameLower)) return 'dall-e-2';
+  }
+
+  // Whisper models
+  if (/whisper/.test(nameLower)) return 'whisper-1';
+
+  // TTS models
+  if (/tts/.test(nameLower)) {
+    if (/hd/.test(nameLower)) return 'tts-1-hd';
+    return 'tts-1';
+  }
+
+  if (knownModels.includes(nameLower)) return nameLower;
+
+  // No heuristic match found - log warning and use deployment name
+  if (!failedResolutionCache.has(deploymentName)) {
+    logger.warn(
+      `⚠️ No heuristic match for Azure deployment: ${deploymentName}. Using deployment name for pricing. Consider adding pattern to azure-model-resolver.ts`
+    );
+    failedResolutionCache.add(deploymentName);
+  }
+  return deploymentName;
+}
+
+/**
+ * Clear the model name cache
+ * Useful for testing or when deployment configurations change
+ */
+export function clearModelNameCache(): void {
+  modelNameCache.clear();
+  failedResolutionCache.clear();
+  getLogger().debug('Model name cache cleared');
+}
+
+/**
+ * Get cache statistics for monitoring
+ */
+export function getModelNameCacheStats(): {
+  cacheSize: number;
+  failedResolutionCount: number;
+  cacheEntries: Array<{ deployment: string; resolved: string }>;
+} {
+  return {
+    cacheSize: modelNameCache.size,
+    failedResolutionCount: failedResolutionCache.size,
+    cacheEntries: Array.from(modelNameCache.entries()).map(([deployment, resolved]) => ({
+      deployment,
+      resolved,
+    })),
+  };
+}
+
+/**
+ * Batch resolve multiple deployment names
+ * Useful for pre-warming cache or bulk operations
+ *
+ * @param deploymentNames - Array of deployment names to resolve
+ * @returns Map of deployment name to resolved model name
+ */
+export function batchResolveModelNames(deploymentNames: string[]): Map<string, string> {
+  const results = new Map<string, string>();
+  logger.debug('Batch resolving model names', {
+    count: deploymentNames.length,
+    deployments: deploymentNames,
+  });
+
+  for (const deployment of deploymentNames) {
+    try {
+      const resolved = resolveAzureModelName(deployment);
+      results.set(deployment, resolved);
+    } catch (error) {
+      logger.error('Error in batch resolution', {
+        deployment,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      results.set(deployment, deployment); // Fallback to original name
+    }
+  }
+  return results;
+}
+
+/**
+ * Check if a deployment name would be resolved to a different model name
+ * Useful for validation and testing
+ *
+ * @param deploymentName - Azure deployment name
+ * @returns true if the deployment name would be transformed
+ */
+export function wouldTransformDeploymentName(deploymentName: string): boolean {
+  const resolved = resolveAzureModelName(deploymentName, false); // Don't use cache for this check
+  return resolved !== deploymentName;
+}

package/src/utils/constants.ts

@@ -0,0 +1,21 @@
+// Direct match check for known LiteLLM model names
+export const knownModels = [
+'gpt-4o',
+'gpt-4o-mini',
+'gpt-4',
+'gpt-4-turbo',
+'gpt-4-vision-preview',
+'gpt-3.5-turbo',
+'gpt-3.5-turbo-instruct',
+'text-embedding-3-large',
+'text-embedding-3-small',
+'text-embedding-ada-002',
+'dall-e-3',
+'dall-e-2',
+'whisper-1',
+'tts-1',
+'tts-1-hd'
+];
+
+export const MESSAGE_PATTERNS_TYPE_NETWORK = ["network", "timeout", "ECONNRESET"];
+export const ERROR_MESSAGE_PATTERNS_TYPE_CONFIG = ["config", "key", "unauthorized"];