@peopl-health/nexus 2.2.1 → 2.2.3

package/examples/basic-usage.js

@@ -1,10 +1,19 @@
 const express = require('express');
 require('dotenv').config();
-const { Nexus, setupDefaultRoutes } = require('@peopl-health/nexus');
+const { Nexus, setupDefaultRoutes, BaseAssistant } = require('@peopl-health/nexus');
 
 const app = express();
 app.use(express.json());
 
+// Define a General Assistant
+class GeneralAssistant extends BaseAssistant {
+  constructor(options = {}) {
+    super(options);
+    // You can add custom tools or setup here
+    // Example: this.registerTool('toolName', schema, handler);
+  }
+}
+
 async function startServer() {
   // Initialize Nexus with all services and batching enabled
   const nexus = new Nexus({
@@ -33,6 +42,21 @@ async function startServer() {
     media: {
       bucketName: process.env.AWS_S3_BUCKET_NAME,
       region: process.env.AWS_REGION || 'us-east-1'
+    },
+
+    // LLM configuration (required for assistants)
+    llm: 'openai',
+    llmConfig: {
+      apiKey: process.env.OPENAI_API_KEY
+    },
+
+    // Assistants configuration
+    assistants: {
+      registry: {
+        // Register the general assistant with its OpenAI assistant ID
+        'asst_O6mAXAhf0xyVj3t4DHRs26uT': GeneralAssistant,
+        'pmpt_68f844cd975481979c080431bde74f6e0adf01a52110813b': GeneralAssistant,
+      }
     }
   });
 

package/lib/assistants/BaseAssistant.js

@@ -209,8 +209,8 @@ class BaseAssistant {
           const formattedText = formatMessage(message);
           return formattedText ? { role: message.from_me ? 'assistant' : 'user', content: formattedText } : null;
         })
-        .filter(message => message !== null); // Remove any null entries
-
+        .filter(message => message !== null);
+      
       console.log(`[buildInitialMessages] Built ${formattedMessages.length} initial messages for ${code}`);
       
       return formattedMessages;

package/lib/config/llmConfig.js

@@ -4,7 +4,7 @@ const { createProvider } = require('../providers/createProvider');
 let anthropicClient = null;
 let openaiClient = null;
 let providerInstance = null;
-let providerVariant = 'assistants';
+let providerVariant = process.env.VARIANT || 'assistants';
 
 const setOpenAIClient = (client) => {
   openaiClient = client || null;
@@ -12,7 +12,6 @@ const setOpenAIClient = (client) => {
   if (!client) {
     providerInstance = null;
     module.exports.providerInstance = null;
-    providerVariant = 'assistants';
     module.exports.providerVariant = providerVariant;
   }
 };
@@ -20,8 +19,7 @@ const setOpenAIClient = (client) => {
 const setOpenAIProvider = (provider) => {
   providerInstance = provider || null;
   module.exports.providerInstance = providerInstance;
-  providerVariant = provider?.variant || providerVariant || 'assistants';
-  module.exports.providerVariant = providerVariant;
+  module.exports.providerVariant = provider?.variant || providerVariant;
 
   if (!provider) {
     setOpenAIClient(null);
@@ -37,11 +35,11 @@ const setOpenAIProvider = (provider) => {
   }
 };
 
-const getOpenAIProvider = ({ instantiate = true } = {}) => {
+const getOpenAIProvider = ({ instantiate = true, variant = providerVariant } = {}) => {
   if (providerInstance) return providerInstance;
   if (!instantiate) return null;
   if (!openaiClient) return null;
-  const provider = createProvider({ client: openaiClient, variant: providerVariant });
+  const provider = createProvider({ client: openaiClient, variant });
   setOpenAIProvider(provider);
   return provider;
 };

package/lib/controllers/conversationController.js

@@ -615,7 +615,7 @@ const getOpenAIThreadMessagesController = async (req, res) => {
     const conversationId = thread.getConversationId();
     console.log('Thread found - Conversation ID:', conversationId);
     
-    const provider = llmConfig.getOpenAIProvider({ instantiate: true });
+    const provider = llmConfig.getOpenAIProvider({ instantiate: true, variant });
     if (!provider) {
       throw new Error('OpenAI provider not initialized');
     }

package/lib/helpers/assistantHelper.js

@@ -114,20 +114,39 @@ const getPatientRoleAndName = (reply, numbers) => {
 
 function formatMessage(reply) {
   try {
-    // Validate timestamp exists
     if (!reply.timestamp) {
       return null;
     }
     
+    // Normalize timestamp: convert any format to a Date object, then to ISO string
+    let dateObj;
+    
+    if (reply.timestamp instanceof Date) {
+      dateObj = reply.timestamp;
+    } else if (typeof reply.timestamp === 'number') {
+      const ms = reply.timestamp < 1e12 ? reply.timestamp * 1000 : reply.timestamp;
+      dateObj = new Date(ms);
+    } else {
+      dateObj = new Date(reply.timestamp);
+    }
+    
+    if (isNaN(dateObj.getTime())) {
+      console.warn('[formatMessage] Invalid timestamp:', reply.timestamp);
+      return null;
+    }
+    
+    const isoString = dateObj.toISOString();
+    
     // Convert timestamp to Mexico City timezone with Spanish format
     // Format: martes, 30 de septiembre de 2025 a las 8:30 AM
-    const mexicoCityTime = moment(reply.timestamp)
+    const mexicoCityTime = moment(isoString)
       .tz('America/Mexico_City')
       .locale('es')
       .format('dddd, D [de] MMMM [de] YYYY [a las] h:mm A');
     
     return `[${mexicoCityTime}] ${reply.body}`;
-  } catch {
+  } catch (error) {
+    console.error('[formatMessage] Error formatting message:', error?.message || error, 'timestamp:', reply.timestamp);
     return null;
   } 
 }

package/lib/providers/OpenAIAssistantsProvider.js

@@ -40,11 +40,45 @@ class OpenAIAssistantsProvider {
     return this.client;
   }
 
+  /**
+   * Retry helper for rate limit errors
+   * Extracts wait time from error message and retries with exponential backoff
+   */
+  async _retryWithRateLimit(operation, maxRetries = 3, retryCount = 0) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (error?.status === 429 || error?.code === 'rate_limit_exceeded') {
+        if (retryCount >= maxRetries) {
+          throw new Error(`Rate limit exceeded after ${maxRetries} retries: ${error.message}`);
+        }
+
+        let waitTime = 60;
+        const waitMatch = error?.error?.message?.match(/after (\d+\.?\d*) seconds?/i) || 
+                         error?.message?.match(/after (\d+\.?\d*) seconds?/i);
+        if (waitMatch) {
+          waitTime = Math.ceil(parseFloat(waitMatch[1])) + 1; // Add 1 second buffer
+        } else {
+          waitTime = 60 * Math.pow(2, retryCount);
+        }
+
+        console.log(`[OpenAIAssistantsProvider] Rate limit exceeded. Waiting ${waitTime} seconds before retry ${retryCount + 1}/${maxRetries}`);
+        await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
+
+        return this._retryWithRateLimit(operation, maxRetries, retryCount + 1);
+      }
+
+      throw error;
+    }
+  }
+
   async createConversation({ metadata, messages = [], toolResources } = {}) {
-    const thread = await this.client.beta.threads.create({
-      metadata,
-      tool_resources: toolResources,
-    });
+    const thread = await this._retryWithRateLimit(() => 
+      this.client.beta.threads.create({
+        metadata,
+        tool_resources: toolResources,
+      })
+    );
 
     if (Array.isArray(messages) && messages.length > 0) {
       for (const message of messages) {
@@ -72,7 +106,9 @@ class OpenAIAssistantsProvider {
       delete payload.metadata;
     }
 
-    return this.client.beta.threads.messages.create(this._ensureId(threadId), payload);
+    return this._retryWithRateLimit(() => 
+      this.client.beta.threads.messages.create(this._ensureId(threadId), payload)
+    );
   }
 
   async listMessages({ threadId, runId, order = 'desc', limit } = {}) {
@@ -153,7 +189,9 @@ class OpenAIAssistantsProvider {
       }
     });
 
-    return this.client.beta.threads.runs.create(this._ensureId(threadId), payload);
+    return this._retryWithRateLimit(() => 
+      this.client.beta.threads.runs.create(this._ensureId(threadId), payload)
+    );
   }
 
   async getRun({ threadId, runId }) {

package/lib/providers/OpenAIResponsesProvider.js

@@ -3,6 +3,9 @@ const { OpenAI } = require('openai');
 const CONVERSATION_PREFIX = 'conv_';
 const RESPONSE_PREFIX = 'resp_';
 const DEFAULT_MAX_RETRIES = parseInt(process.env.MAX_RETRIES || '10', 10);
+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);
 
 /**
  * Provider wrapper that targets the Conversations + Responses API surface.
@@ -43,21 +46,153 @@ class OpenAIResponsesProvider {
     return this.client;
   }
 
+  /**
+   * Retry helper for rate limit errors
+   * Extracts wait time from error message and retries with exponential backoff
+   */
+  async _retryWithRateLimit(operation, maxRetries = 3, retryCount = 0) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (error?.status === 429 || error?.code === 'rate_limit_exceeded') {
+        if (retryCount >= maxRetries) {
+          throw new Error(`Rate limit exceeded after ${maxRetries} retries: ${error.message}`);
+        }
+
+        let waitTime = 60;
+        const waitMatch = error?.error?.message?.match(/after (\d+\.?\d*) seconds?/i) || 
+                         error?.message?.match(/after (\d+\.?\d*) seconds?/i);
+        if (waitMatch) {
+          waitTime = Math.ceil(parseFloat(waitMatch[1])) + 1; // Add 1 second buffer
+        } else {
+          waitTime = 60 * Math.pow(2, retryCount);
+        }
+
+        console.log(`[OpenAIResponsesProvider] Rate limit exceeded. Waiting ${waitTime} seconds before retry ${retryCount + 1}/${maxRetries}`);
+        await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
+
+        return this._retryWithRateLimit(operation, maxRetries, retryCount + 1);
+      }
+
+      throw error;
+    }
+  }
+
   /**
    * Conversations helpers
    */
   async createConversation({ metadata, messages = [], toolResources } = {}) {
+    const messagesToProcess = messages.length > DEFAULT_MAX_HISTORICAL_MESSAGES 
+      ? messages.slice(-DEFAULT_MAX_HISTORICAL_MESSAGES)
+      : messages;
+    
+    if (messages.length > DEFAULT_MAX_HISTORICAL_MESSAGES) {
+      console.warn(`[OpenAIResponsesProvider] Capped ${messages.length} → ${DEFAULT_MAX_HISTORICAL_MESSAGES} messages`);
+    }
+    
+    const allItems = this._conversationItems(messagesToProcess);
+    const totalItems = allItems.length;
+    
+    // Create empty conversation if no messages
+    if (totalItems === 0) {
+      const payload = this._cleanObject({
+        metadata,
+        tool_resources: toolResources,
+      });
+      
+      return this._retryWithRateLimit(async () => {
+        if (this.conversations && typeof this.conversations.create === 'function') {
+          return await this.conversations.create(payload);
+        }
+        return await this._post('/conversations', payload);
+      });
+    }
+    
+    // Split items: first batch for initial creation, rest to add in batches
+    const initialItems = allItems.slice(0, MAX_ITEMS_ON_CREATE);
+    const remainingItems = allItems.slice(MAX_ITEMS_ON_CREATE);
+    const totalBatches = Math.ceil(remainingItems.length / MAX_ITEMS_PER_BATCH);
+    
+    // Concise batch summary
+    console.log(`[OpenAIResponsesProvider] Batching: ${initialItems.length} (create) + ${remainingItems.length} (${totalBatches} batches) = ${totalItems} total`);
+
     const payload = this._cleanObject({
       metadata,
-      items: this._conversationItems(messages),
+      items: initialItems,
       tool_resources: toolResources,
     });
 
-    if (this.conversations && typeof this.conversations.create === 'function') {
-      return await this.conversations.create(payload);
+    let conversation;
+    try {
+      conversation = await this._retryWithRateLimit(async () => {
+        if (this.conversations && typeof this.conversations.create === 'function') {
+          return await this.conversations.create(payload);
+        }
+        return await this._post('/conversations', payload);
+      });
+    } catch (error) {
+      console.error('[OpenAIResponsesProvider] Failed to create conversation:', error?.message || error);
+      throw error;
+    }
+
+    // Add remaining messages in batches (maintains chronological order)
+    if (remainingItems.length > 0) {
+      try {
+        await this._addItemsInBatches(conversation.id, remainingItems);
+      } catch (error) {
+        console.error('[OpenAIResponsesProvider] Failed to add remaining messages. Conversation created with partial history:', error?.message || error);
+      }
+    }
+
+    return conversation;
+  }
+
+  /**
+   * Add items to a conversation in batches
+   * Items are converted to API format with type: 'message' for the items.create endpoint
+   * @private
+   */
+  async _addItemsInBatches(threadId, items, batchSize = MAX_ITEMS_PER_BATCH) {
+    if (!items || items.length === 0) {
+      return;
+    }
+
+    const id = this._ensurethreadId(threadId);
+    const totalBatches = Math.ceil(items.length / batchSize);
+    
+    for (let i = 0; i < items.length; i += batchSize) {
+      const batch = items.slice(i, i + batchSize);
+      const batchNumber = Math.floor(i / batchSize) + 1;
+      
+      const batchPayload = this._convertItemsToApiFormat(batch);
+
+      try {
+        await this._retryWithRateLimit(async () => {
+          if (this.conversations?.items?.create) {
+            return await this.conversations.items.create(id, { items: batchPayload });
+          }
+          return await this._post(`/conversations/${id}/items`, { items: batchPayload });
+        });
+      } catch (error) {
+        console.error(`[OpenAIResponsesProvider] Batch ${batchNumber}/${totalBatches} failed:`, error?.message || error);
+        throw error;
+      }
     }
+    
+    console.log(`[OpenAIResponsesProvider] Successfully added ${items.length} messages in ${totalBatches} batches`);
+  }
 
-    return await this._post('/conversations', payload);
+  /**
+   * Convert conversation items to API format for items.create endpoint
+   * Adds type: 'message' which is required by the items.create API
+   * @private
+   */
+  _convertItemsToApiFormat(items) {
+    return items.map(item => ({
+      role: item.role,
+      content: item.content,
+      type: 'message',
+    }));
   }
 
   async deleteConversation(threadId) {
@@ -79,10 +214,12 @@ class OpenAIResponsesProvider {
     console.log('payload', payload);
 
     if (payload.content) {
-      if (this.conversations?.items?.create) {
-        return await this.conversations.items.create(id, {items: [payload]});
-      }
-      return await this._post(`/conversations/${id}/items`, {items: [payload]});
+      return this._retryWithRateLimit(async () => {
+        if (this.conversations?.items?.create) {
+          return await this.conversations.items.create(id, {items: [payload]});
+        }
+        return await this._post(`/conversations/${id}/items`, {items: [payload]});
+      });
     }
   }
 
@@ -159,7 +296,9 @@ class OpenAIResponsesProvider {
       });
 
       console.log('payload', payload);
-      const response = await this.client.responses.create(payload);
+      const response = await this._retryWithRateLimit(() => 
+        this.client.responses.create(payload)
+      );
       console.log('response', response);
 
       if (response?.status !== 'completed') {

package/lib/providers/createProvider.js

@@ -10,6 +10,7 @@ const PROVIDER_VARIANTS = {
  * Returns the appropriate OpenAI provider implementation for the requested variant.
  */
 function createProvider(config = {}) {
+  console.log('Creating OpenAI provider with config:', config);
   const variant = (config.variant || config.providerVariant || config.llmVariant || 'assistants')
     .toString()
     .toLowerCase();

package/package.json

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