@peopl-health/nexus 1.0.2

package/examples/assistants/BaseAssistant.js

@@ -0,0 +1,242 @@
+/**
+ * Base Assistant class for consumer server extensions
+ * Provides common functionality for AI assistant implementations
+ */
+class BaseAssistant {
+  constructor(config = {}) {
+    this.assistantId = config.assistantId;
+    this.llmClient = config.llmClient;
+    this.storage = config.storage;
+    this.nexus = config.nexus;
+    this.functions = new Map();
+  }
+
+  /**
+   * Register a function that can be called by the assistant
+   * @param {string} name - Function name
+   * @param {Function} handler - Function handler
+   * @param {Object} schema - Function schema for LLM
+   */
+  registerFunction(name, handler, schema) {
+    this.functions.set(name, { handler, schema });
+  }
+
+  /**
+   * Get all registered function schemas for LLM
+   * @returns {Array} Function schemas
+   */
+  getFunctionSchemas() {
+    return Array.from(this.functions.values()).map(f => f.schema);
+  }
+
+  /**
+   * Execute a function call from the assistant
+   * @param {string} name - Function name
+   * @param {Object} args - Function arguments
+   * @returns {Promise<any>} Function result
+   */
+  async executeFunction(name, args) {
+    const func = this.functions.get(name);
+    if (!func) {
+      throw new Error(`Unknown function: ${name}`);
+    }
+    return await func.handler(args);
+  }
+
+  /**
+   * Create a new thread for this assistant
+   * @param {string} userId - User identifier
+   * @param {Array} initialMessages - Initial messages
+   * @returns {Promise<Object>} Thread data
+   */
+  async createThread(userId, initialMessages = []) {
+    if (!this.llmClient) {
+      throw new Error('LLM client not configured');
+    }
+
+    const thread = await this.llmClient.beta.threads.create();
+    
+    // Add initial messages if provided
+    for (const message of initialMessages) {
+      await this.llmClient.beta.threads.messages.create(
+        thread.id, 
+        { role: "assistant", content: message }
+      );
+    }
+
+    const threadData = {
+      code: userId,
+      assistantId: this.assistantId,
+      threadId: thread.id,
+      active: true,
+      createdAt: new Date()
+    };
+
+    // Save to storage if available
+    if (this.storage) {
+      await this.storage.createThread(threadData);
+    }
+
+    return threadData;
+  }
+
+  /**
+   * Send message to assistant and handle response
+   * @param {string} userId - User identifier
+   * @param {string} message - User message
+   * @param {Object} options - Additional options
+   * @returns {Promise<string>} Assistant response
+   */
+  async sendMessage(userId, message, options = {}) {
+    if (!this.llmClient) {
+      throw new Error('LLM client not configured');
+    }
+
+    // Get or create thread
+    let threadData = null;
+    if (this.storage) {
+      threadData = await this.storage.getThread(userId);
+    }
+
+    if (!threadData) {
+      threadData = await this.createThread(userId);
+    }
+
+    // Add user message to thread
+    await this.llmClient.beta.threads.messages.create(
+      threadData.threadId,
+      { role: "user", content: message }
+    );
+
+    // Create run with function schemas if available
+    const runConfig = {
+      assistant_id: this.assistantId,
+      ...options
+    };
+
+    const functionSchemas = this.getFunctionSchemas();
+    if (functionSchemas.length > 0) {
+      runConfig.tools = functionSchemas;
+    }
+
+    const run = await this.llmClient.beta.threads.runs.create(
+      threadData.threadId,
+      runConfig
+    );
+
+    // Wait for completion and handle function calls
+    const result = await this.waitForCompletion(threadData.threadId, run.id);
+    
+    if (result.status === 'completed') {
+      const messages = await this.llmClient.beta.threads.messages.list(
+        threadData.threadId, 
+        { run_id: run.id }
+      );
+      return messages.data[0]?.content[0]?.text?.value || "";
+    }
+
+    return null;
+  }
+
+  /**
+   * Wait for run completion and handle function calls
+   * @param {string} threadId - Thread ID
+   * @param {string} runId - Run ID
+   * @returns {Promise<Object>} Run result
+   */
+  async waitForCompletion(threadId, runId) {
+    const maxAttempts = 30;
+    let attempts = 0;
+
+    while (attempts < maxAttempts) {
+      const run = await this.llmClient.beta.threads.runs.retrieve(threadId, runId);
+      
+      if (run.status === 'completed') {
+        return { status: 'completed', run };
+      } else if (run.status === 'requires_action') {
+        // Handle function calls
+        const toolOutputs = await this.handleRequiredActions(run);
+        
+        if (toolOutputs.length > 0) {
+          await this.llmClient.beta.threads.runs.submitToolOutputs(
+            threadId,
+            runId,
+            { tool_outputs: toolOutputs }
+          );
+          
+          // Continue waiting for completion
+          attempts = 0; // Reset attempts after submitting outputs
+          await this.delay(2000);
+          continue;
+        }
+      } else if (run.status === 'failed' || run.status === 'cancelled' || run.status === 'expired') {
+        return { status: 'failed', run };
+      }
+
+      await this.delay(2000);
+      attempts++;
+    }
+
+    throw new Error('Assistant run timeout');
+  }
+
+  /**
+   * Handle required actions (function calls)
+   * @param {Object} run - Run object with required actions
+   * @returns {Promise<Array>} Tool outputs
+   */
+  async handleRequiredActions(run) {
+    const toolCalls = run.required_action?.submit_tool_outputs?.tool_calls || [];
+    const toolOutputs = [];
+
+    for (const toolCall of toolCalls) {
+      try {
+        const functionName = toolCall.function.name;
+        const args = JSON.parse(toolCall.function.arguments);
+        
+        const result = await this.executeFunction(functionName, args);
+        
+        toolOutputs.push({
+          tool_call_id: toolCall.id,
+          output: JSON.stringify(result)
+        });
+      } catch (error) {
+        console.error(`Error executing function ${toolCall.function.name}:`, error);
+        toolOutputs.push({
+          tool_call_id: toolCall.id,
+          output: JSON.stringify({ error: error.message })
+        });
+      }
+    }
+
+    return toolOutputs;
+  }
+
+  /**
+   * Send a message through Nexus
+   * @param {string} to - Recipient
+   * @param {string} message - Message text
+   * @param {Object} options - Additional options
+   */
+  async sendNexusMessage(to, message, options = {}) {
+    if (!this.nexus) {
+      throw new Error('Nexus instance not provided');
+    }
+
+    return await this.nexus.sendMessage({
+      to,
+      message,
+      ...options
+    });
+  }
+
+  /**
+   * Utility delay function
+   * @param {number} ms - Milliseconds to delay
+   */
+  delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = { BaseAssistant };

package/examples/assistants/ExampleAssistant.js

@@ -0,0 +1,111 @@
+const { BaseAssistant } = require('./BaseAssistant');
+
+/**
+ * Example Assistant implementation showing how to extend BaseAssistant
+ */
+class ExampleAssistant extends BaseAssistant {
+  constructor(config) {
+    super(config);
+    
+    // Register custom functions
+    this.registerFunction('get_weather', this.getWeather.bind(this), {
+      type: "function",
+      function: {
+        name: "get_weather",
+        description: "Get current weather for a location",
+        parameters: {
+          type: "object",
+          properties: {
+            location: {
+              type: "string",
+              description: "The city and state, e.g. San Francisco, CA"
+            }
+          },
+          required: ["location"]
+        }
+      }
+    });
+
+    this.registerFunction('schedule_reminder', this.scheduleReminder.bind(this), {
+      type: "function",
+      function: {
+        name: "schedule_reminder",
+        description: "Schedule a reminder for the user",
+        parameters: {
+          type: "object",
+          properties: {
+            message: {
+              type: "string",
+              description: "The reminder message"
+            },
+            datetime: {
+              type: "string",
+              description: "When to send the reminder (ISO format)"
+            }
+          },
+          required: ["message", "datetime"]
+        }
+      }
+    });
+  }
+
+  /**
+   * Get weather information (mock implementation)
+   * @param {Object} args - Function arguments
+   * @returns {Promise<Object>} Weather data
+   */
+  async getWeather(args) {
+    const { location } = args;
+    
+    // Mock weather data - replace with actual weather API
+    return {
+      location,
+      temperature: "22°C",
+      condition: "Sunny",
+      humidity: "65%",
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  /**
+   * Schedule a reminder (mock implementation)
+   * @param {Object} args - Function arguments
+   * @returns {Promise<Object>} Scheduling result
+   */
+  async scheduleReminder(args) {
+    const { message, datetime } = args;
+    
+    // Mock scheduling - replace with actual scheduling logic
+    console.log(`Scheduling reminder: "${message}" for ${datetime}`);
+    
+    return {
+      success: true,
+      reminderId: `reminder_${Date.now()}`,
+      scheduledFor: datetime,
+      message
+    };
+  }
+
+  /**
+   * Handle incoming messages with custom logic
+   * @param {string} userId - User identifier
+   * @param {string} message - User message
+   * @returns {Promise<string>} Response
+   */
+  async handleMessage(userId, message) {
+    // Add custom pre-processing logic here
+    console.log(`ExampleAssistant handling message from ${userId}: ${message}`);
+    
+    // Call parent method to handle LLM interaction
+    const response = await this.sendMessage(userId, message);
+    
+    // Add custom post-processing logic here
+    if (response) {
+      console.log(`ExampleAssistant responding to ${userId}: ${response}`);
+    }
+    
+    return response;
+  }
+}
+
+module.exports = { ExampleAssistant };

package/examples/assistants/index.js

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

package/examples/basic-usage.js

@@ -0,0 +1,109 @@
+const { Nexus } = require('@peopl/nexus');
+require('dotenv').config();
+
+async function main() {
+  const nexus = new Nexus();
+
+  try {
+    // Initialize with defaults (twilio provider, mongo storage, openai llm)
+    await nexus.initialize({
+      providerConfig: {
+        accountSid: process.env.TWILIO_ACCOUNT_SID,
+        authToken: process.env.TWILIO_AUTH_TOKEN,
+        phoneNumber: process.env.TWILIO_PHONE_NUMBER
+      },
+      // storage: 'mongo' is default
+      storageConfig: {
+        uri: process.env.MONGODB_URI,
+        dbName: 'nexus_basic'
+      },
+      // parser: 'MessageParser' is default
+      parserConfig: {
+        commandPrefixes: ['/', '!'],
+        keywords: ['help', 'support', 'info'],
+        flowTriggers: ['start survey', 'begin onboarding']
+      },
+      // llm: 'openai' is default (optional for basic usage)
+      llmConfig: {
+        apiKey: process.env.OPENAI_API_KEY
+      }
+    });
+
+    // Set up message handlers
+    nexus.onMessage(async (messageData) => {
+      console.log(`Received message from ${messageData.from}: ${messageData.message}`);
+      
+      // Simple echo response
+      await nexus.sendMessage({
+        to: messageData.from,
+        message: `You said: ${messageData.message}`
+      });
+    });
+
+    nexus.onCommand(async (messageData) => {
+      const { command, args } = messageData.command;
+      
+      switch (command) {
+        case 'help':
+          await nexus.sendMessage({
+            to: messageData.from,
+            message: 'Available commands:\n/help - Show this help\n/status - Check system status\n/echo [text] - Echo your text'
+          });
+          break;
+        case 'status':
+          await nexus.sendMessage({
+            to: messageData.from,
+            message: `System Status: ${nexus.isConnected() ? 'Connected' : 'Disconnected'}`
+          });
+          break;
+        case 'echo':
+          const text = args.join(' ') || 'Nothing to echo!';
+          await nexus.sendMessage({
+            to: messageData.from,
+            message: `Echo: ${text}`
+          });
+          break;
+        default:
+          await nexus.sendMessage({
+            to: messageData.from,
+            message: `Unknown command: ${command}. Type /help for available commands.`
+          });
+      }
+    });
+
+    nexus.onKeyword(async (messageData) => {
+      const keyword = messageData.keyword;
+      
+      switch (keyword) {
+        case 'help':
+        case 'support':
+          await nexus.sendMessage({
+            to: messageData.from,
+            message: 'Hello! I can help you with:\n- Basic messaging\n- Commands (try /help)\n- Keyword responses\n\nWhat would you like to know?'
+          });
+          break;
+        case 'info':
+          await nexus.sendMessage({
+            to: messageData.from,
+            message: 'This is a basic Nexus messaging bot example. It demonstrates simple message handling without AI assistants.'
+          });
+          break;
+      }
+    });
+
+    console.log('Nexus basic example started successfully');
+    console.log('Send messages to your configured phone number to test');
+    
+  } catch (error) {
+    console.error('Error starting Nexus:', error);
+    process.exit(1);
+  }
+}
+
+// Handle graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('\nShutting down gracefully...');
+  process.exit(0);
+});
+
+main().catch(console.error);

package/examples/consumer-server.js

@@ -0,0 +1,206 @@
+const { Nexus } = require('@peopl/nexus');
+const { ExampleAssistant } = require('./assistants/ExampleAssistant');
+const express = require('express');
+require('dotenv').config();
+
+const app = express();
+app.use(express.json());
+app.use(express.urlencoded({ extended: false }));
+
+
+const nexus = new Nexus();
+let assistants = {};
+
+async function initializeNexus() {
+  await nexus.initialize({
+    provider: 'twilio', 
+    providerConfig: {
+      accountSid: process.env.TWILIO_ACCOUNT_SID,
+      authToken: process.env.TWILIO_AUTH_TOKEN,
+      phoneNumber: process.env.TWILIO_PHONE_NUMBER
+    },
+    storageConfig: {
+      uri: process.env.MONGODB_URI,
+      dbName: 'nexus_messaging'
+    },
+    llmConfig: {
+      apiKey: process.env.OPENAI_API_KEY
+    }
+  });
+
+  assistants = {
+    sales: new ExampleAssistant({
+      assistantId: process.env.SALES_ASSISTANT_ID,
+      llmClient: nexus.getLLMProvider().getClient(),
+      storage: nexus.getStorage(),
+      nexus: nexus
+    }),
+    support: new ExampleAssistant({
+      assistantId: process.env.SUPPORT_ASSISTANT_ID,
+      llmClient: nexus.getLLMProvider().getClient(),
+      storage: nexus.getStorage(),
+      nexus: nexus
+    })
+  };
+
+  nexus.onMessage(async (messageData) => {
+    console.log('Received message:', messageData);
+    
+    if (messageData.type === 'text') {
+      const response = await processTextMessage(messageData);
+      if (response) {
+        await nexus.sendMessage({
+          to: messageData.from,
+          message: response
+        });
+      }
+    }
+  });
+
+  nexus.onCommand(async (messageData) => {
+    const { command, args } = messageData.command;
+    
+    switch (command) {
+      case 'help':
+        await nexus.sendMessage({
+          to: messageData.from,
+          message: `🤖 Available Commands:
+/help - Show this help
+/support - Connect to support assistant
+/sales - Connect to sales assistant
+/status - Check system status
+/reset - Reset conversation`
+        });
+        break;
+        
+      case 'support':
+        const supportResponse = await assistants.support.handleMessage(messageData.from, 'Hello, I need support.');
+        if (supportResponse) {
+          await nexus.sendMessage({
+            to: messageData.from,
+            message: supportResponse
+          });
+        }
+        break;
+        
+      case 'sales':
+        const salesResponse = await assistants.sales.handleMessage(messageData.from, 'Hello, I\'m interested in your products.');
+        if (salesResponse) {
+          await nexus.sendMessage({
+            to: messageData.from,
+            message: salesResponse
+          });
+        }
+        break;
+        
+      case 'status':
+        await nexus.sendMessage({
+          to: messageData.from,
+          message: `System Status: ${nexus.isConnected() ? '✅ Connected' : '❌ Disconnected'}`
+        });
+        break;
+        
+      case 'reset':
+        if (nexus.getStorage()) {
+          await nexus.getStorage().clearThread(messageData.from);
+        }
+        await nexus.sendMessage({
+          to: messageData.from,
+          message: 'Conversation reset! You can start fresh now.'
+        });
+        break;
+        
+      default:
+        await nexus.sendMessage({
+          to: messageData.from,
+          message: `Unknown command: /${command}. Type /help for available commands.`
+        });
+    }
+  });
+
+  console.log('🚀 Nexus consumer server initialized successfully');
+}
+
+// Webhook endpoints - provider agnostic
+app.post('/webhook', async (req, res) => {
+  try {
+    await nexus.processMessage(req.body);
+    res.sendStatus(200);
+  } catch (error) {
+    console.error('Webhook error:', error);
+    res.sendStatus(500);
+  }
+});
+
+// API endpoints
+app.post('/api/send-message', async (req, res) => {
+  try {
+    const { to, message, fileUrl, fileType } = req.body;
+    
+    const result = await nexus.sendMessage({
+      to,
+      message,
+      fileUrl,
+      fileType
+    });
+    
+    res.json({ success: true, result });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+app.post('/api/send-template', async (req, res) => {
+  try {
+    const { to, contentSid, variables } = req.body;
+    
+    const result = await nexus.sendMessage({
+      to,
+      contentSid,
+      variables
+    });
+    
+    res.json({ success: true, result });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+app.get('/api/status', (req, res) => {
+  res.json({
+    connected: nexus.isConnected(),
+    provider: process.env.MESSAGING_PROVIDER || 'twilio'
+  });
+});
+
+// Health check
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+// Initialize and start server
+async function start() {
+  try {
+    await initializeNexus();
+    
+    const PORT = process.env.PORT || 3000;
+    app.listen(PORT, () => {
+      const provider = process.env.MESSAGING_PROVIDER || 'twilio';
+      console.log(`🚀 Consumer server running on port ${PORT}`);
+      console.log(`📱 Messaging provider: ${provider}`);
+      console.log(`🔗 Webhook URL: http://localhost:${PORT}/webhook`);
+    });
+  } catch (error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('Shutting down gracefully...');
+  await nexus.disconnect();
+  process.exit(0);
+});
+
+start();