@peopl-health/nexus 1.5.8 → 1.5.10

package/lib/assistants/BaseAssistant.js

@@ -0,0 +1,294 @@
+const llmConfig = require('../config/llmConfig');
+const { Thread } = require('../models/threadModel');
+const { getLastNMessages } = require('../helpers/assistantHelper');
+
+/**
+ * Flexible base assistant implementation that integrates with OpenAI Threads
+ * and supports dynamic tool registration.
+ */
+class BaseAssistant {
+  constructor(input = {}) {
+    const options = this._normalizeOptions(input);
+
+    this.assistantId = options.assistantId || null;
+    this.thread = options.thread || null;
+    this.status = options.status || 'idle';
+    this.replies = null;
+    this.lastMessages = null;
+    this.createdAt = new Date();
+
+    this.client = options.client || llmConfig.openaiClient || null;
+    this.tools = new Map();
+
+    if (Array.isArray(options.tools)) {
+      options.tools.forEach((tool) => this.registerTool(tool));
+    }
+
+    if (options.setup && typeof options.setup === 'function') {
+      options.setup.call(this, options);
+    }
+
+    if (this.assistantId) {
+      console.log(`Assistant ${this.assistantId} initialized.`);
+    }
+  }
+
+  _normalizeOptions(input) {
+    if (!input || typeof input !== 'object') {
+      return { thread: input };
+    }
+
+    if (input && input._id && !input.assistantId && !input.client && !input.tools) {
+      return { thread: input };
+    }
+
+    return input;
+  }
+
+  _ensureClient() {
+    if (!this.client) {
+      throw new Error('LLM client not configured. Ensure openaiClient is initialized.');
+    }
+  }
+
+  async getAssistantId() {
+    return this.assistantId;
+  }
+
+  async getStatus() {
+    return this.status;
+  }
+
+  async getNextAssistant() {
+    return this.nextAssistant || null;
+  }
+
+  setThread(thread) {
+    this.thread = thread;
+  }
+
+  setReplies(replies) {
+    this.replies = replies;
+  }
+
+  registerTool(nameOrConfig, schema, handler) {
+    let name;
+    let definition;
+    let executor;
+
+    if (typeof nameOrConfig === 'object' && nameOrConfig !== null) {
+      name = nameOrConfig.name;
+      definition = nameOrConfig.definition || nameOrConfig.schema || nameOrConfig;
+      executor = nameOrConfig.handler || nameOrConfig.execute || nameOrConfig.run;
+    } else {
+      name = nameOrConfig;
+      definition = schema;
+      executor = handler;
+    }
+
+    if (!name || typeof name !== 'string') {
+      throw new Error('Tool name is required');
+    }
+
+    if (!definition || typeof definition !== 'object') {
+      throw new Error(`Tool definition for '${name}' must be an object`);
+    }
+
+    if (!executor || typeof executor !== 'function') {
+      throw new Error(`Tool handler for '${name}' must be a function`);
+    }
+
+    const toolSchema = {
+      type: 'function',
+      function: {
+        name,
+        description: definition.description || 'Custom assistant tool',
+        parameters: definition.parameters || {
+          type: 'object',
+          properties: {},
+          additionalProperties: true
+        }
+      }
+    };
+
+    this.tools.set(name, {
+      schema: toolSchema,
+      execute: executor
+    });
+  }
+
+  getToolSchemas() {
+    return Array.from(this.tools.values()).map((value) => value.schema);
+  }
+
+  async executeTool(name, args) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new Error(`Unknown tool '${name}' requested by assistant`);
+    }
+    return await tool.execute(args);
+  }
+
+  async createThread(code, context = {}) {
+    return await this.create(code, context);
+  }
+
+  async sendMessage(userId, message, options = {}) {
+    this._ensureClient();
+
+    if (!this.thread || !this.thread.thread_id) {
+      throw new Error('Assistant thread not initialized. Call create() before sendMessage().');
+    }
+
+    await this.client.beta.threads.messages.create(
+      this.thread.thread_id,
+      { role: 'user', content: message }
+    );
+
+    const runConfig = {
+      assistant_id: this.assistantId,
+      ...options
+    };
+
+    const toolSchemas = this.getToolSchemas();
+    if (toolSchemas.length > 0) {
+      runConfig.tools = toolSchemas;
+    }
+
+    const run = await this.client.beta.threads.runs.create(
+      this.thread.thread_id,
+      runConfig
+    );
+
+    return await this.waitForCompletion(this.thread.thread_id, run.id);
+  }
+
+  async waitForCompletion(threadId, runId, { interval = 2000, maxAttempts = 30 } = {}) {
+    this._ensureClient();
+    let attempts = 0;
+
+    while (attempts < maxAttempts) {
+      const run = await this.client.beta.threads.runs.retrieve(threadId, runId);
+
+      if (run.status === 'completed') {
+        return run;
+      }
+
+      if (run.status === 'requires_action') {
+        await this.handleRequiresAction(run);
+      } else if (['failed', 'cancelled', 'expired', 'incomplete'].includes(run.status)) {
+        throw new Error(`Assistant run ended with status '${run.status}'`);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, interval));
+      attempts += 1;
+    }
+
+    throw new Error('Assistant run timeout');
+  }
+
+  async getPreviousMessages(threadDoc) {
+    this._ensureClient();
+    const threadRef = threadDoc || this.thread;
+    if (!threadRef) return [];
+
+    const response = await this.client.beta.threads.messages.list(threadRef.thread_id, { order: 'asc' });
+    return response.data.map((msg) => {
+      const textContents = msg.content
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text.value);
+      const content = textContents.length <= 1 ? textContents[0] || '' : textContents;
+      return { role: msg.role, content };
+    });
+  }
+
+  async create(code, context = {}) {
+    this._ensureClient();
+    this.status = 'active';
+
+    const whatsappId = context?.whatsapp_id || code;
+    if (whatsappId) {
+      this.lastMessages = await getLastNMessages(whatsappId, 20);
+    }
+
+    const initialMessages = await this.buildInitialMessages({ code, context });
+    const threadPayload = {};
+
+    if (initialMessages.length > 0) {
+      threadPayload.messages = initialMessages.map((msg) => ({
+        role: msg.role || 'assistant',
+        content: msg.content
+      }));
+    }
+
+    const thread = await this.client.beta.threads.create(threadPayload);
+    this.thread = thread;
+    return thread;
+  }
+
+  async buildInitialMessages({ code }) {
+    if (!this.lastMessages) return [];
+    return [{
+      role: 'assistant',
+      content: `Últimos mensajes para ${code}:
+${this.lastMessages}`
+    }];
+  }
+
+  async handleRequiresAction(run) {
+    const toolCalls = run?.required_action?.submit_tool_outputs?.tool_calls || [];
+    if (toolCalls.length === 0) {
+      return [];
+    }
+
+    const outputs = [];
+
+    for (const call of toolCalls) {
+      try {
+        const name = call.function?.name;
+        const args = call.function?.arguments ? JSON.parse(call.function.arguments) : {};
+        const result = await this.executeTool(name, args);
+        outputs.push({ tool_call_id: call.id, output: typeof result === 'string' ? result : JSON.stringify(result) });
+      } catch (error) {
+        console.error('[BaseAssistant] Tool execution failed', error);
+        outputs.push({
+          tool_call_id: call.id,
+          output: JSON.stringify({ success: false, error: error?.message || 'Tool execution failed' })
+        });
+      }
+    }
+
+    if (!this.client) {
+      console.warn('[BaseAssistant] Cannot submit tool outputs: client not configured');
+      return outputs;
+    }
+
+    await this.client.beta.threads.runs.submitToolOutputs(
+      run.thread_id,
+      run.id,
+      { tool_outputs: outputs }
+    );
+
+    return outputs;
+  }
+
+  async close() {
+    this.status = 'closed';
+    if (this.thread?.code && this.thread?.assistant_id) {
+      await Thread.updateOne(
+        { code: this.thread.code, assistant_id: this.thread.assistant_id },
+        { $set: { active: false } }
+      );
+    }
+
+    if (this.assistantId) {
+      console.log(`Assistant ${this.assistantId} closed`);
+    }
+
+    return `Assistant ${this.assistantId || ''} successfully closed.`.trim();
+  }
+}
+
+module.exports = {
+  BaseAssistant
+};

package/lib/assistants/index.js

@@ -0,0 +1,5 @@
+const { BaseAssistant } = require('./BaseAssistant');
+
+module.exports = {
+  BaseAssistant
+};

package/lib/index.d.ts

@@ -117,6 +117,48 @@ declare module '@peopl-health/nexus' {
     onFlow?: FlowHandler;
   }
 
+  export interface AssistantToolDefinition {
+    name: string;
+    description?: string;
+    parameters?: any;
+    handler: (args: any) => any;
+  }
+
+  export interface AssistantConfigDefinition {
+    extends?: typeof BaseAssistant;
+    create?: (this: BaseAssistant, code: string, context?: any) => Promise<any>;
+    tools?: Array<AssistantToolDefinition | { name: string; definition?: any; handler: (args: any) => any }>;
+    setup?: (this: BaseAssistant, context: { assistantId: string; thread?: any; options?: any }) => void;
+  }
+
+  export class BaseAssistant {
+    constructor(options?: {
+      assistantId?: string;
+      thread?: any;
+      client?: any;
+      tools?: Array<AssistantToolDefinition | { name: string; definition?: any; handler: (args: any) => any }>;
+      setup?: (context: { assistantId: string; thread?: any; options?: any }) => void;
+      status?: string;
+    } | any);
+    assistantId: string | null;
+    thread: any;
+    status: string;
+    createdAt: Date;
+    registerTool(definition: AssistantToolDefinition | string, schema?: any, handler?: (args: any) => any): void;
+    getToolSchemas(): any[];
+    executeTool(name: string, args: any): Promise<any>;
+    getPreviousMessages(thread?: any): Promise<Array<{ role: string; content: any }>>;
+    createThread(code: string, context?: any): Promise<any>;
+    sendMessage(userId: string, message: string, options?: any): Promise<any>;
+    waitForCompletion(threadId: string, runId: string, opts?: { interval?: number; maxAttempts?: number }): Promise<any>;
+    create(code: string, context?: any): Promise<any>;
+    buildInitialMessages(context: { code: string; [key: string]: any }): Promise<Array<{ role: string; content: string }>>;
+    handleRequiresAction(run: any): Promise<any[]>;
+    close(): Promise<string>;
+    setThread(thread: any): void;
+    setReplies(replies: any): void;
+  }
+
   // Core Classes
   export abstract class MessageProvider {
     constructor(config: any);
@@ -127,6 +169,15 @@ declare module '@peopl-health/nexus' {
     abstract disconnect(): Promise<void>;
   }
 
+  export function registerAssistant(
+    assistantId: string,
+    definition: typeof BaseAssistant | ((thread?: any) => any) | AssistantConfigDefinition
+  ): any;
+
+  export function configureAssistantsLLM(client: any): void;
+  export function overrideGetAssistantById(resolver: (assistantId: string, thread?: any) => any): void;
+  export function configureAssistants(config: any): void;
+
   export class TwilioProvider extends MessageProvider {
     constructor(config: TwilioConfig);
     initialize(): Promise<void>;

package/lib/index.js

@@ -16,6 +16,7 @@ const {
 } = require('./services/assistantService');
 const { TwilioProvider } = require('./adapters/TwilioProvider');
 const { BaileysProvider } = require('./adapters/BaileysProvider');
+const { BaseAssistant: CoreBaseAssistant } = require('./assistants/BaseAssistant');
 
 /**
  * Main Nexus class that orchestrates all components
@@ -312,6 +313,11 @@ module.exports = {
   MongoStorage,
   MessageParser,
   DefaultLLMProvider,
+  BaseAssistant: CoreBaseAssistant,
+  registerAssistant,
+  configureAssistantsLLM,
+  overrideGetAssistantById,
+  configureAssistants: setAssistantsConfig,
   routes,
   setupDefaultRoutes: routes.setupDefaultRoutes,
   createRouter: routes.createRouter,

package/lib/models/messageModel.js

@@ -68,7 +68,8 @@ async function insertMessage(values) {
       reply_id: values.reply_id,
       from_me: values.from_me,
       processed: skipNumbers.includes(values.numero),
-      media: values.media ? values.media : null
+      media: values.media ? values.media : null,
+      content_sid: values.content_sid || null
     };
 
     await Message.findOneAndUpdate(

package/lib/services/assistantService.js

@@ -3,6 +3,8 @@ const AWS = require('../config/awsConfig.js');
 const { combineImagesToPDF, cleanupFiles } = require('../helpers/filesHelper.js');
 const { addRecord } = require('../services/airtableService.js');
 const runtimeConfig = require('../config/runtimeConfig');
+const llmConfig = require('../config/llmConfig');
+const { BaseAssistant } = require('../assistants/BaseAssistant');
 
 let llmProvider = null;
 const configureLLMProvider = (provider) => {
@@ -27,8 +29,54 @@ const configureAssistants = (config) => {
   assistantConfig = config;
 };
 
-const registerAssistant = (assistantId, AssistantClass) => {
-  assistantRegistry[assistantId] = AssistantClass;
+const registerAssistant = (assistantId, definition) => {
+  if (!assistantId || typeof assistantId !== 'string') {
+    throw new Error('registerAssistant requires a string assistantId');
+  }
+
+  if (typeof definition === 'function') {
+    assistantRegistry[assistantId] = definition;
+    return definition;
+  }
+
+  if (definition && typeof definition === 'object') {
+    const {
+      extends: ParentClass = BaseAssistant,
+      create,
+      tools = [],
+      setup
+    } = definition;
+
+    class ConfiguredAssistant extends ParentClass {
+      constructor(options = {}) {
+        super({
+          ...options,
+          assistantId,
+          client: options.client || llmProvider || llmConfig.openaiClient || null,
+          tools: [...tools, ...(options.tools || [])]
+        });
+
+        if (typeof setup === 'function') {
+          setup.call(this, {
+            assistantId,
+            thread: this.thread,
+            options
+          });
+        }
+      }
+    }
+
+    if (typeof create === 'function') {
+      ConfiguredAssistant.prototype.create = async function(code, context) {
+        return await create.call(this, code, context);
+      };
+    }
+
+    assistantRegistry[assistantId] = ConfiguredAssistant;
+    return ConfiguredAssistant;
+  }
+
+  throw new Error('registerAssistant expects a class/function or configuration object');
 };
 
 const overrideGetAssistantById = (resolverFn) => {
@@ -51,8 +99,22 @@ const getAssistantById = (assistant_id, thread) => {
   if (!AssistantClass) {
     throw new Error(`Assistant '${assistant_id}' not found. Available assistants: ${Object.keys(assistantRegistry).join(', ')}`);
   }
-  
-  return new AssistantClass(thread);
+
+  const sharedClient = llmProvider || llmConfig.openaiClient || null;
+
+  if (AssistantClass.prototype instanceof BaseAssistant) {
+    return new AssistantClass({
+      assistantId: assistant_id,
+      thread,
+      client: sharedClient
+    });
+  }
+
+  try {
+    return new AssistantClass(thread);
+  } catch (error) {
+    return new AssistantClass({ thread, assistantId: assistant_id, client: sharedClient });
+  }
 };
 
 

package/lib/storage/MongoStorage.js

@@ -66,10 +66,11 @@ class MongoStorage {
         from: messageData?.from,
         provider: messageData?.provider || 'unknown',
         hasRaw: Boolean(messageData?.raw),
-        hasMedia: Boolean(messageData?.media || messageData?.fileUrl)
+        hasMedia: Boolean(messageData?.media || messageData?.fileUrl),
+        hasContentSid: Boolean(messageData?.contentSid)
       });
       const enrichedMessage = await this._enrichTwilioMedia(messageData);
-      const values = this.buildLegacyMessageValues(enrichedMessage);
+      const values = this.buildMessageValues(enrichedMessage);
       const { insertMessage } = require('../models/messageModel');
       await insertMessage(values);
       console.log('[MongoStorage] Message stored', {
@@ -166,7 +167,8 @@ class MongoStorage {
     return trimmed;
   }
 
-  buildLegacyMessageValues(messageData = {}) {
+
+  buildMessageValues(messageData = {}) {
     const numero = messageData.to || messageData.code || messageData.numero || messageData.from;
     const rawNumero = typeof numero === 'string' ? numero : '';
     const normalizedNumero = this.normalizeNumero(rawNumero);
@@ -175,7 +177,16 @@ class MongoStorage {
     const now = new Date();
     const timestamp = now.toISOString();
     const nombre = messageData.nombre_whatsapp || messageData.author || messageData.fromName || runtimeConfig.get('USER_DB_MONGO') || process.env.USER_DB_MONGO || 'Nexus';
-    const textBody = messageData.message || messageData.body || (messageData.contentSid ? `[Template:${messageData.contentSid}]` : isMedia ? `[Media:${messageData.fileType || 'attachment'}]` : '');
+    
+    // Use message body directly (template rendering is now handled by the provider)
+    let textBody = messageData.message || messageData.body;
+    
+    if (!textBody && isMedia) {
+      textBody = `[Media:${messageData.fileType || 'attachment'}]`;
+    } else if (!textBody) {
+      textBody = '';
+    }
+    
     const providerId = messageData.messageId || messageData.sid || messageData.id || messageData._id || `pending-${now.getTime()}-${Math.floor(Math.random()*1000)}`;
 
     const media = messageData.media || (messageData.fileUrl ? {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "1.5.8",
+  "version": "1.5.10",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",
@@ -73,7 +73,7 @@
     "airtable": "^0.12.2",
     "aws-sdk": "2.1674.0",
     "axios": "^1.5.0",
-    "dotenv": "^16.4.7",
+    "dotenv": "^16.6.1",
     "moment-timezone": "^0.5.43",
     "mongoose": "^7.5.0",
     "multer": "1.4.5-lts.1",
@@ -102,4 +102,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}