@peopl-health/nexus 4.5.27 → 4.5.29

package/lib/index.js

@@ -4,6 +4,7 @@ const { createStorage } = require('./storage/registry');
 const { MessageParser } = require('./core/MessageParser');
 const { createLLMProvider } = require('./providers/createLLMProvider');
 const { OpenAIResponsesProvider } = require('./providers/OpenAIResponsesProvider');
+const { OpenRouterProvider } = require('./providers/OpenRouterProvider');
 const { logger } = require('./utils/logger');
 const runtimeConfig = require('./config/runtimeConfig');
 const llmConfigModule = require('./config/llmConfig');
@@ -197,6 +198,7 @@ module.exports = {
   MessageParser,
   createLLMProvider,
   OpenAIResponsesProvider,
+  OpenRouterProvider,
   BaseAssistant,
   registerAssistant,
   overrideGetAssistantById,

package/lib/providers/BaseLLMProvider.js

@@ -0,0 +1,275 @@
+const runtimeConfig = require('../config/runtimeConfig');
+const { logger } = require('../utils/logger');
+const { getCurrentMexicoDateTime } = require('../utils/dateUtils');
+const { isJsonBlob } = require('../utils/formatUtils');
+
+const { DefaultMemoryManager } = require('../memory/DefaultMemoryManager');
+
+const { getMessages } = require('../services/messageService');
+
+const { logBugReportToAirtable } = require('../controllers/bugReportController');
+
+const DEFAULT_MAX_CONVERSATION_RETRIES = 3;
+
+class BaseLLMProvider {
+  constructor(options = {}) {
+    if (new.target === BaseLLMProvider) {
+      throw new Error('BaseLLMProvider is abstract and cannot be instantiated directly');
+    }
+    const { conversationManager, sessionManager, maxConversationRetries } = options;
+    this.client = null;
+    this.variant = null;
+    this.conversationManager = conversationManager || new DefaultMemoryManager();
+    this.sessionManager = sessionManager || null;
+    const retries = parseInt(maxConversationRetries, 10);
+    this.maxConversationRetries = retries > 0 ? retries : DEFAULT_MAX_CONVERSATION_RETRIES;
+  }
+
+  getVariant() { return this.variant; }
+  getClient() { return this.client; }
+
+  async _executeConversation() {
+    throw new Error(`${this.constructor.name} must implement _executeConversation()`);
+  }
+
+  async createConversation() {
+    throw new Error(`createConversation is not supported by ${this.constructor.name}`);
+  }
+
+  async addMessage() {
+    throw new Error(`addMessage is not supported by ${this.constructor.name}`);
+  }
+
+  async listMessages() {
+    throw new Error(`listMessages is not supported by ${this.constructor.name}`);
+  }
+
+  async transcribeAudio() {
+    throw new Error(`transcribeAudio is not supported by ${this.constructor.name}`);
+  }
+
+  async executeRun({ thread, assistant, message = null, tools = [], config = {} }) {
+    const { conversationId, assistantId } = this._normalizeThread(thread);
+    const promptVersion = thread?.version || null;
+    const presetId = thread?.preset_id || null;
+    const presetVersion = thread?.preset_version || null;
+
+    logger.info('[executeRun] Starting', { conversationId, assistantId, promptVersion });
+
+    try {
+      const context = await this.conversationManager.buildContext({
+        thread,
+        message,
+        config: {
+          ...config,
+          threadId: conversationId,
+          assistantId,
+        }
+      });
+
+      const [lastMessage] = await getMessages({ numero: thread.code }, { sort: { createdAt: -1 }, limit: 1 });
+      const phiProcessor = config.phiProcessor;
+      const maskedCode = phiProcessor ? phiProcessor.hashCode(thread.code) : thread.code;
+      const metadata = {
+        numero: maskedCode,
+        message_id: message?.message_id || lastMessage?.message_id || null
+      };
+
+      logger.info('[executeRun] Context built', { conversationId, messageCount: context?.length || 0 });
+
+      const override = config.clinicalData;
+      const hasOverride = override && typeof override === 'object' && Object.keys(override).length > 0;
+      const clinicalData = hasOverride ? override : await this.conversationManager.getClinicalData(thread.code);
+      const promptVariables = {
+        clinical_context: clinicalData?.clinicalContext ?? '',
+        last_symptoms: clinicalData?.lastSymptoms ?? '',
+        current_date: getCurrentMexicoDateTime(),
+        patient_memories: clinicalData?.patientMemories ?? '',
+        conversation_summaries: clinicalData?.conversationSummaries ?? '',
+      };
+
+      const result = await this.runConversation({
+        threadId: conversationId,
+        assistantId,
+        presetId,
+        presetVersion,
+        tools,
+        context,
+        promptVariables,
+        promptVersion,
+        assistant,
+        metadata,
+        ...config
+      });
+
+      await this.conversationManager.processResponse(result, thread, config);
+      this.sessionManager?.recordActivity(thread.code);
+
+      const completed = result.status === 'completed';
+      const output = result.output_text || this._extractMessageOutput(result);
+      const toolsExecuted = result.tools_executed?.length || 0;
+
+      logger.info('[executeRun] Complete', {
+        runId: result.id,
+        completed,
+        outputLength: output?.length || 0,
+        toolsExecuted
+      });
+
+      return { run: result, completed, output, tools_executed: result.tools_executed || [], retries: result.retries || 0 };
+    } catch (error) {
+      logger.error('[executeRun] Failed', { conversationId, assistantId, error: error.message });
+      throw error;
+    }
+  }
+
+  async runConversation(config = {}) {
+    const { threadId, assistantId } = config;
+    const maxRetries = this.maxConversationRetries;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        logger.info('[runConversation] Attempt', { attempt, maxRetries, threadId, assistantId });
+
+        const result = await this._executeConversation(config);
+        const extractedOutput = this._extractMessageOutput(result);
+
+        if (extractedOutput?.trim()) {
+          result.output_text = extractedOutput;
+          logger.info('[runConversation] Success', {
+            attempt,
+            outputLength: extractedOutput.length,
+            toolsExecuted: result.tools_executed?.length || 0
+          });
+          return result;
+        }
+
+        logger.warn('[runConversation] Empty output', { attempt });
+        if (attempt === maxRetries) {
+          throw new Error(`Conversation failed after ${attempt} attempts - no valid output`);
+        }
+        await new Promise(r => setTimeout(r, 500));
+      } catch (error) {
+        logger.error('[runConversation] Attempt failed', { attempt, error: error.message });
+        if (attempt === maxRetries) throw error;
+        await new Promise(r => setTimeout(r, 500));
+      }
+    }
+  }
+
+  _normalizeThread(thread) {
+    return {
+      conversationId: thread.conversation_id || thread.getConversationId?.(),
+      assistantId: thread.prompt_id || thread.getAssistantId?.()
+    };
+  }
+
+  _convertItemsToApiFormat(items) {
+    return items.map(item => {
+      const type = item.type || 'message';
+      if (type === 'function_call' || type === 'function_call_output') {
+        return { ...item, type };
+      }
+      return {
+        role: item.role || 'user',
+        type,
+        content: this._normalizeContent(item.content)
+      };
+    });
+  }
+
+  _normalizeContent(content) {
+    if (typeof content === 'string') return content;
+    if (Array.isArray(content)) return content;
+    if (content?.text) return content.text;
+    if (content && typeof content === 'object') return JSON.stringify(content);
+    return content || '';
+  }
+
+  _contentPartToText(part) {
+    if (part == null || typeof part !== 'object') return '';
+    return typeof part.text === 'string' ? part.text : (typeof part.text?.value === 'string' ? part.text.value : '');
+  }
+
+  _messageItemToText(item) {
+    if (!item) return '';
+    if (Array.isArray(item.content)) {
+      return item.content.map(c => this._contentPartToText(c)).filter(Boolean).join('').trim();
+    }
+    if (typeof item.content === 'string') return item.content.trim();
+    return '';
+  }
+
+  _extractMessageOutput(result) {
+    if (result == null || typeof result !== 'object') return '';
+
+    if (result.output && Array.isArray(result.output)) {
+      const messageItems = result.output.filter(item => item && item.type === 'message');
+      if (messageItems.length > 0) {
+        const texts = messageItems.map(item => this._messageItemToText(item)).filter(Boolean);
+        const proseTexts = texts.filter(text => !isJsonBlob(text));
+        const jsonDiscarded = texts.length - proseTexts.length;
+        const keptOne = proseTexts.length > 0 ? 1 : 0;
+
+        if (messageItems.length > 1 || jsonDiscarded > 0) {
+          const hasFunctionCalls = result.output.some(item => item?.type === 'function_call');
+          logger.warn(`[${this.constructor.name}] Multiple/structured message items in response; keeping the first natural-language reply (likely OpenAI multi-output bug)`, {
+            discarded: messageItems.length - keptOne,
+            jsonDiscarded,
+            responseId: result.id,
+            model: result.model,
+            hasFunctionCalls
+          });
+          logBugReportToAirtable({
+            reporter: 'system',
+            description: [
+              `Responses API (${this.constructor.name}) returned multiple message items in a single response.`,
+              'Suspected upstream bug (model failed to emit stop-of-message token).',
+              `Discarded ${messageItems.length - keptOne} extra message(s); kept the first natural-language reply as the canonical reply.`,
+              jsonDiscarded > 0 ? `${jsonDiscarded} discarded item(s) were raw JSON/structured output that must never reach the patient.` : null,
+              `Response ID: ${result.id || 'unknown'}`,
+              `Model: ${result.model || 'unknown'}`,
+              `Function calls present: ${hasFunctionCalls ? 'yes' : 'no'}`
+            ].filter(Boolean).join('\n'),
+            severity: 'medium',
+            status: 'Open',
+            clasificacion: 'alucinaciones',
+            bugType: 'backend',
+            owner: ['ariana'],
+            request_id: result.id || null,
+            server: runtimeConfig.get('SERVICE_NAME') || 'nexus'
+          }).catch((err) => logger.warn(`[${this.constructor.name}] Bug report logger failed`, { error: err.message }));
+        }
+
+        if (proseTexts.length > 0) return proseTexts[0];
+      }
+    }
+    if (result.output_text) return this._extractMessageFromConcatenatedOutput(result.output_text);
+    return '';
+  }
+
+  _extractMessageFromConcatenatedOutput(outputText) {
+    if (!outputText || typeof outputText !== 'string') return '';
+    if (!/^\s*assistant\s*\n/i.test(outputText)) return outputText.trim();
+
+    const segments = outputText
+      .split(/\n\s*assistant\s*\n/i)
+      .map(s => s.replace(/^assistant\s*\n?/i, '').trim())
+      .filter(Boolean);
+
+    if (segments.length === 0) return '';
+    if (segments.length > 1) logger.debug(`[${this.constructor.name}] Concatenated transcript detected, using last segment`, { segmentCount: segments.length });
+    return segments[segments.length - 1].trim();
+  }
+
+  _ensureId(value) {
+    if (!value) throw new Error('Identifier value is required');
+    if (typeof value === 'string') return value;
+    if (value?.id) return value.id;
+    throw new Error('Unable to resolve identifier value');
+  }
+}
+
+module.exports = {
+  BaseLLMProvider,
+};

package/lib/providers/OpenAIResponsesProvider.js

@@ -1,18 +1,12 @@
 const { OpenAI } = require('openai');
 
-const runtimeConfig = require('../config/runtimeConfig');
 const { retryWithBackoff } = require('../utils/retryUtils');
 const { logger } = require('../utils/logger');
-const { getCurrentMexicoDateTime } = require('../utils/dateUtils');
-const { isJsonBlob } = require('../utils/formatUtils');
-
-const { DefaultMemoryManager } = require('../memory/DefaultMemoryManager');
 
 const { composePrompt, resolveTools } = require('../services/promptComposerService');
 const { getToolSchemas: getRegistrySchemas } = require('../services/toolRegistryService');
-const { getMessages } = require('../services/messageService');
 
-const { logBugReportToAirtable } = require('../controllers/bugReportController');
+const { BaseLLMProvider } = require('./BaseLLMProvider');
 const { handleFunctionCalls } = require('./OpenAIResponsesProviderTools');
 
 const CONVERSATION_PREFIX = 'conv_';
@@ -20,19 +14,16 @@ const RESPONSE_PREFIX = 'resp_';
 const MAX_ITEMS_ON_CREATE = 20;
 const MAX_ITEMS_PER_BATCH = 20;
 const DEFAULT_MAX_HISTORICAL_MESSAGES = parseInt(process.env.MAX_HISTORICAL_MESSAGES || '50', 10);
-const MAX_CONVERSATION_RETRIES = parseInt(process.env.MAX_CONVERSATION_RETRIES || '3', 10);
 const MAX_FUNCTION_ROUNDS = parseInt(process.env.MAX_FUNCTION_ROUNDS || '5', 10);
-const PROVIDER_NAME = 'OpenAIResponsesProvider';
 
-class OpenAIResponsesProvider {
+class OpenAIResponsesProvider extends BaseLLMProvider {
   constructor(options = {}) {
+    super(options);
     const {
       apiKey = process.env.OPENAI_API_KEY,
       organization,
       client,
       defaultModels = {},
-      conversationManager,
-      sessionManager,
     } = options;
 
     if (!client && !apiKey) {
@@ -51,16 +42,12 @@ class OpenAIResponsesProvider {
     };
 
     this.variant = 'responses';
-    this.conversationManager = conversationManager || new DefaultMemoryManager();
-    this.sessionManager = sessionManager || null;
+    this.supportsPromptRegistry = true;
 
     this.responses = this.client.responses;
     this.conversations = this.client.conversations;
   }
 
-  getVariant() { return this.variant; }
-  getClient() { return this.client; }
-
   async createConversation({ metadata, messages = [], toolResources } = {}) {
     const capped = messages.length > DEFAULT_MAX_HISTORICAL_MESSAGES;
     const messagesToProcess = capped ? messages.slice(-DEFAULT_MAX_HISTORICAL_MESSAGES) : messages;
@@ -97,7 +84,7 @@ class OpenAIResponsesProvider {
     };
     const { result } = await retryWithBackoff(
       () => this.conversations.create(payload),
-      { providerName: PROVIDER_NAME }
+      { providerName: this.constructor.name }
     );
     return result;
   }
@@ -110,34 +97,12 @@ class OpenAIResponsesProvider {
       const batch = this._convertItemsToApiFormat(items.slice(i, i + batchSize));
       await retryWithBackoff(
         () => this.conversations.items.create(id, { items: batch }),
-        { providerName: PROVIDER_NAME }
+        { providerName: this.constructor.name }
       );
     }
     logger.info(`[_addItemsInBatches] Added ${items.length} messages in ${Math.ceil(items.length / batchSize)} batches`);
   }
 
-  _convertItemsToApiFormat(items) {
-    return items.map(item => {
-      const type = item.type || 'message';
-      if (type === 'function_call' || type === 'function_call_output') {
-        return { ...item, type };
-      }
-      return {
-        role: item.role || 'user',
-        type,
-        content: this._normalizeContent(item.content)
-      };
-    });
-  }
-
-  _normalizeContent(content) {
-    if (typeof content === 'string') return content;
-    if (Array.isArray(content)) return content;
-    if (content?.text) return content.text;
-    if (content && typeof content === 'object') return JSON.stringify(content);
-    return content || '';
-  }
-
   async addMessage({ threadId, messages, role = 'user', content, metadata }) {
     const id = this._ensurethreadId(threadId);
     const messagesToAdd = messages || [{ role, content, metadata }];
@@ -156,199 +121,6 @@ class OpenAIResponsesProvider {
     );
   }
 
-  _normalizeThread(thread) {
-    return {
-      conversationId: thread.conversation_id || thread.getConversationId?.(),
-      assistantId: thread.prompt_id || thread.getAssistantId?.()
-    };
-  }
-
-  _contentPartToText(part) {
-    if (part == null || typeof part !== 'object') return '';
-    return typeof part.text === 'string' ? part.text : (typeof part.text?.value === 'string' ? part.text.value : '');
-  }
-
-  _messageItemToText(item) {
-    if (!item) return '';
-    if (Array.isArray(item.content)) {
-      return item.content.map(c => this._contentPartToText(c)).filter(Boolean).join('').trim();
-    }
-    if (typeof item.content === 'string') return item.content.trim();
-    return '';
-  }
-
-  _extractMessageOutput(result) {
-    if (result == null || typeof result !== 'object') return '';
-
-    if (result.output && Array.isArray(result.output)) {
-      const messageItems = result.output.filter(item => item && item.type === 'message');
-      if (messageItems.length > 0) {
-        const texts = messageItems.map(item => this._messageItemToText(item)).filter(Boolean);
-        const proseTexts = texts.filter(text => !isJsonBlob(text));
-        const jsonDiscarded = texts.length - proseTexts.length;
-        const keptOne = proseTexts.length > 0 ? 1 : 0;
-
-        if (messageItems.length > 1 || jsonDiscarded > 0) {
-          const hasFunctionCalls = result.output.some(item => item?.type === 'function_call');
-          logger.warn('[OpenAIResponsesProvider] Multiple/structured message items in response; keeping the first natural-language reply (likely OpenAI multi-output bug)', {
-            discarded: messageItems.length - keptOne,
-            jsonDiscarded,
-            responseId: result.id,
-            model: result.model,
-            hasFunctionCalls
-          });
-          logBugReportToAirtable({
-            reporter: 'system',
-            description: [
-              'OpenAI Responses API returned multiple message items in a single response.',
-              'Suspected upstream bug (model failed to emit stop-of-message token).',
-              `Discarded ${messageItems.length - keptOne} extra message(s); kept the first natural-language reply as the canonical reply.`,
-              jsonDiscarded > 0 ? `${jsonDiscarded} discarded item(s) were raw JSON/structured output that must never reach the patient.` : null,
-              `Response ID: ${result.id || 'unknown'}`,
-              `Model: ${result.model || 'unknown'}`,
-              `Function calls present: ${hasFunctionCalls ? 'yes' : 'no'}`
-            ].filter(Boolean).join('\n'),
-            severity: 'medium',
-            status: 'Open',
-            clasificacion: 'alucinaciones',
-            bugType: 'backend',
-            owner: ['ariana'],
-            request_id: result.id || null,
-            server: runtimeConfig.get('SERVICE_NAME') || 'nexus'
-          }).catch((err) => logger.warn('[OpenAIResponsesProvider] Bug report logger failed', { error: err.message }));
-        }
-
-        if (proseTexts.length > 0) return proseTexts[0];
-      }
-    }
-    if (result.output_text) return this._extractMessageFromConcatenatedOutput(result.output_text);
-    return '';
-  }
-
-  _extractMessageFromConcatenatedOutput(outputText) {
-    if (!outputText || typeof outputText !== 'string') return '';
-    if (!/^\s*assistant\s*\n/i.test(outputText)) return outputText.trim();
-
-    const segments = outputText
-      .split(/\n\s*assistant\s*\n/i)
-      .map(s => s.replace(/^assistant\s*\n?/i, '').trim())
-      .filter(Boolean);
-
-    if (segments.length === 0) return '';
-    if (segments.length > 1) logger.debug('[OpenAIResponsesProvider] Concatenated transcript detected, using last segment', { segmentCount: segments.length });
-    return segments[segments.length - 1].trim();
-  }
-
-  async executeRun({ thread, assistant, message = null, tools = [], config = {} }) {
-    const { conversationId, assistantId } = this._normalizeThread(thread);
-    const promptVersion = thread?.version || null;
-    const presetId = thread?.preset_id || null;
-    const presetVersion = thread?.preset_version || null;
-
-    logger.info('[executeRun] Starting', { conversationId, assistantId, promptVersion });
-
-    try {
-      const context = await this.conversationManager.buildContext({
-        thread,
-        message,
-        config: {
-          ...config,
-          threadId: conversationId,
-          assistantId,
-        }
-      });
-
-      const [lastMessage] = await getMessages({ numero: thread.code }, { sort: { createdAt: -1 }, limit: 1 });
-      const phiProcessor = config.phiProcessor;
-      const maskedCode = phiProcessor ? phiProcessor.hashCode(thread.code) : thread.code;
-      const metadata = {
-        numero: maskedCode,
-        message_id: message?.message_id || lastMessage?.message_id || null
-      };
-
-      logger.info('[executeRun] Context built', { conversationId, messageCount: context?.length || 0 });
-
-      // config.clinicalData, when given, fully replaces the fetched bundle (all four fields).
-      // Must be a complete, non-empty object; anything else falls through to the normal fetch.
-      const override = config.clinicalData;
-      const hasOverride = override && typeof override === 'object' && Object.keys(override).length > 0;
-      const clinicalData = hasOverride ? override : await this.conversationManager.getClinicalData(thread.code);
-      const promptVariables = {
-        clinical_context: clinicalData?.clinicalContext ?? '',
-        last_symptoms: clinicalData?.lastSymptoms ?? '',
-        current_date: getCurrentMexicoDateTime(),
-        patient_memories: clinicalData?.patientMemories ?? '',
-        conversation_summaries: clinicalData?.conversationSummaries ?? '',
-      };
-
-      const result = await this.runConversation({
-        threadId: conversationId,
-        assistantId,
-        presetId,
-        presetVersion,
-        tools,
-        context,
-        promptVariables,
-        promptVersion,
-        assistant,
-        metadata,
-        ...config
-      });
-
-      await this.conversationManager.processResponse(result, thread, config);
-      this.sessionManager?.recordActivity(thread.code);
-
-      const completed = result.status === 'completed';
-      const output = result.output_text || this._extractMessageOutput(result);
-      const toolsExecuted = result.tools_executed?.length || 0;
-
-      logger.info('[executeRun] Complete', {
-        runId: result.id,
-        completed,
-        outputLength: output?.length || 0,
-        toolsExecuted
-      });
-
-      return { run: result, completed, output, tools_executed: result.tools_executed || [], retries: result.retries || 0 };
-    } catch (error) {
-      logger.error('[executeRun] Failed', { conversationId, assistantId, error: error.message });
-      throw error;
-    }
-  }
-
-  async runConversation(config = {}) {
-    const { threadId, assistantId } = config;
-
-    for (let attempt = 1; attempt <= MAX_CONVERSATION_RETRIES; attempt++) {
-      try {
-        logger.info('[runConversation] Attempt', { attempt, maxRetries: MAX_CONVERSATION_RETRIES, threadId, assistantId });
-
-        const result = await this._executeConversation(config);
-        const extractedOutput = this._extractMessageOutput(result);
-
-        if (extractedOutput?.trim()) {
-          result.output_text = extractedOutput;
-          logger.info('[runConversation] Success', { 
-            attempt,
-            outputLength: extractedOutput.length,
-            toolsExecuted: result.tools_executed?.length || 0
-          });
-          return result;
-        }
-
-        logger.warn('[runConversation] Empty output', { attempt });
-        if (attempt === MAX_CONVERSATION_RETRIES) {
-          throw new Error(`Conversation failed after ${attempt} attempts - no valid output`);
-        }
-        await new Promise(r => setTimeout(r, 500));
-      } catch (error) {
-        logger.error('[runConversation] Attempt failed', { attempt, error: error.message });
-        if (attempt === MAX_CONVERSATION_RETRIES) throw error;
-        await new Promise(r => setTimeout(r, 500));
-      }
-    }
-  }
-
   async _executeConversation(config = {}) {
     const {
       threadId, assistantId, presetId = null, presetVersion = null, additionalMessages = [], context = null,
@@ -439,13 +211,13 @@ class OpenAIResponsesProvider {
     if (promptVersion) promptConfig.version = String(promptVersion);
 
     const apiCallConfig = {
-      ...modelConfig,
+      ...this._mapModelConfig(modelConfig),
       instructions: instructions || additionalInstructions || devContent || '',
       metadata,
       tool_choice: prePromptResult?.toolChoice || toolChoice
     };
 
-    if (!resolvedPresetId) {
+    if (!resolvedPresetId && this.supportsPromptRegistry) {
       apiCallConfig.prompt = promptConfig;
     }
     if (activeToolSchemas.length > 0) {
@@ -460,7 +232,7 @@ class OpenAIResponsesProvider {
 
     const makeAPICall = (inputData) => retryWithBackoff(
       () => this.client.responses.create({ input: inputData, ...apiCallConfig }),
-      { providerName: PROVIDER_NAME }
+      { providerName: this.constructor.name }
     );
 
     const { result: response, retries } = await makeAPICall(input);
@@ -471,7 +243,6 @@ class OpenAIResponsesProvider {
     if (assistant && response.output) {
       let currentInput = [...input];
 
-      // Follow-up calls always use the default tool_choice.
       apiCallConfig.tool_choice = toolChoice;
 
       for (let round = 1; round <= MAX_FUNCTION_ROUNDS; round++) {
@@ -509,6 +280,10 @@ class OpenAIResponsesProvider {
     return result;
   }
 
+  _mapModelConfig(modelConfig) {
+    return modelConfig;
+  }
+
   async transcribeAudio({ file, model, language, responseFormat, temperature, prompt } = {}) {
     return this.client.audio.transcriptions.create({
       model: model || this.defaults.transcriptionModel,
@@ -532,13 +307,6 @@ class OpenAIResponsesProvider {
     return id;
   }
 
-  _ensureId(value) {
-    if (!value) throw new Error('Identifier value is required');
-    if (typeof value === 'string') return value;
-    if (value?.id) return value.id;
-    throw new Error('Unable to resolve identifier value');
-  }
-
   async _post(path, body, options = {}) { return this.client.post(path, { ...options, body }); }
   async _get(path, query, options = {}) { return this.client.get(path, { ...options, query }); }
   async _delete(path, options = {}) { return this.client.delete(path, options); }

package/lib/providers/OpenRouterProvider.js

@@ -0,0 +1,67 @@
+const { OpenAI } = require('openai');
+
+const { OpenAIResponsesProvider } = require('./OpenAIResponsesProvider');
+
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+const DEFAULT_MODEL_VENDOR = 'openai';
+
+class OpenRouterProvider extends OpenAIResponsesProvider {
+  constructor(options = {}) {
+    const {
+      apiKey = process.env.OPENROUTER_API_KEY,
+      baseURL = OPENROUTER_BASE_URL,
+      client,
+    } = options;
+
+    if (!client && !apiKey) {
+      throw new Error('OpenRouterProvider requires an API key or a preconfigured client');
+    }
+
+    super({ ...options, client: client || new OpenAI({ apiKey, baseURL }) });
+
+    this.variant = 'openrouter';
+    this.supportsPromptRegistry = false;
+    this.transcriptionClient = null;
+  }
+
+  _mapModelConfig(modelConfig) {
+    const mapped = { ...modelConfig };
+    mapped.model = this._toOpenRouterModel(mapped.model || this.defaults.responseModel);
+    return mapped;
+  }
+
+  _toOpenRouterModel(model) {
+    if (!model || model.includes('/')) return model;
+    return `${DEFAULT_MODEL_VENDOR}/${model}`;
+  }
+
+  async transcribeAudio({ file, model, language, responseFormat, temperature, prompt } = {}) {
+    if (!this.transcriptionClient) {
+      const apiKey = process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        throw new Error('transcribeAudio requires OPENAI_API_KEY; OpenRouter does not offer audio transcription');
+      }
+      this.transcriptionClient = new OpenAI({ apiKey });
+    }
+    return this.transcriptionClient.audio.transcriptions.create({
+      model: model || this.defaults.transcriptionModel,
+      file, language, response_format: responseFormat, temperature, prompt,
+    });
+  }
+
+  async createConversation() {
+    throw new Error('createConversation is not supported by OpenRouterProvider');
+  }
+
+  async addMessage() {
+    throw new Error('addMessage is not supported by OpenRouterProvider');
+  }
+
+  async listMessages() {
+    throw new Error('listMessages is not supported by OpenRouterProvider');
+  }
+}
+
+module.exports = {
+  OpenRouterProvider,
+};

package/lib/providers/createLLMProvider.js

@@ -4,9 +4,11 @@ const { EnhancedMemoryManager } = require('../memory/EnhancedMemoryManager');
 const { SessionManager } = require('../memory/SessionManager');
 
 const { OpenAIResponsesProvider } = require('./OpenAIResponsesProvider');
+const { OpenRouterProvider } = require('./OpenRouterProvider');
 
 const PROVIDER_VARIANTS = {
   responses: OpenAIResponsesProvider,
+  openrouter: OpenRouterProvider,
 };
 
 function createLLMProvider(config = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "4.5.27",
+  "version": "4.5.29",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",