@multiplayer-app/ai-agent-node 0.1.0-beta.1 → 0.1.0-beta.10

package/src/helpers/ConfigHelper.ts

@@ -1,130 +0,0 @@
-import { z } from 'zod';
-import type { AgentAppConfig, AgentTool } from '@multiplayer-app/ai-agent-types';
-import { AgentToolType } from '@multiplayer-app/ai-agent-types';
-import { logger } from '../libs/logger';
-
-export class ConfigHelper {
-
-  static loadConfig(rawConfig: Record<string, any>): AgentAppConfig {
-    try {
-      // Convert to AgentAppConfig format
-      return ConfigHelper.convertToAgentAppConfig(rawConfig);
-    } catch (error) {
-      if (error instanceof SyntaxError) {
-        logger.error(`Failed to parse config.json: ${error.message}`);
-        throw new Error(`Invalid JSON in config file: ${error.message}`);
-      }
-      logger.error(`Failed to load config: ${error}`);
-      throw error;
-    }
-  }
-
-  private static jsonSchemaToZod (schema: any): z.ZodSchema<any> | null {
-    if (!schema) return null;
-    return z.fromJSONSchema(schema);
-  }
-
-  /**
-   * Converts raw JSON config to AgentAppConfig format
-   * Validates structure and converts JSON schemas to Zod schemas
-   */
-  private static convertToAgentAppConfig(rawConfig: any): AgentAppConfig {
-    // Convert agents, transforming JSON schemas to Zod schemas
-    const config: AgentAppConfig = rawConfig.agents.reduce((config: AgentAppConfig, agent: any) => {
-      agent.contextKeys.forEach((contextKey: string) => {
-        if (!config[contextKey]) {
-          config[contextKey] = [];
-        }
-        config[contextKey].push({
-            name: agent.name,
-            description: agent.description,
-            defaultModel: agent.defaultModel,
-            systemPrompt: agent.systemPrompt,
-            temperature: agent.temperature || 0.1,
-            maxTokens: agent.maxTokens || 2000,
-            tools: agent.tools.map((tool: any) => ConfigHelper.convertTool(tool)),
-            outputSchema: agent.outputSchema ? ConfigHelper.jsonSchemaToZod(agent.outputSchema) as any : undefined
-        });
-      });
-      return config;
-    }, {} as AgentAppConfig);
-
-    return config
-  }
-
-  /**
-   * Converts a tool from JSON format (with JSON schemas) to AgentTool format (with Zod schemas)
-   */
-  private static convertTool(tool: any): AgentTool {
-    if (tool.type === AgentToolType.WEB_SEARCH) {
-      return {
-        type: AgentToolType.WEB_SEARCH,
-        data: {
-          title: AgentToolType.WEB_SEARCH,
-        }
-      };
-    }
-
-    if (tool.type === AgentToolType.API_TOOL) {
-      return {
-        type: AgentToolType.API_TOOL,
-        data: {
-          title: tool.data.title,
-          description: tool.data.description,
-          headersToPass: tool.data.headersToPass,
-          method: tool.data.method,
-          url: tool.data.url,
-          body: tool.data.body ? ConfigHelper.jsonSchemaToZod(tool.data.body) as any : undefined,
-          queryParams: tool.data.queryParams ? ConfigHelper.jsonSchemaToZod(tool.data.queryParams) as any : undefined,
-          needsApproval: tool.data.needsApproval ?? false,
-        }
-      };
-    }
-
-    throw new Error(`Unknown tool type: ${tool.type}`);
-  }
-
-
-  /**
-   * Validates the AgentAppConfig structure
-   * @throws Error if validation fails
-   */
-  private static validateConfig(config: AgentAppConfig): void {
-    if (!config.agents || !Array.isArray(config.agents)) {
-      throw new Error('Config must have an "agents" array');
-    }
-
-    if (!config.contexts || typeof config.contexts !== 'object') {
-      throw new Error('Config must have a "contexts" object');
-    }
-
-    // Validate agents
-    const agentNames = new Set<string>();
-    for (const agent of config.agents) {
-      if (!agent.name) {
-        throw new Error('All agents must have a "name" field');
-      }
-      if (agentNames.has(agent.name)) {
-        throw new Error(`Duplicate agent name found: ${agent.name}`);
-      }
-      agentNames.add(agent.name);
-
-      if (!agent.systemPrompt) {
-        throw new Error(`Agent "${agent.name}" must have a "systemPrompt" field`);
-      }
-    }
-
-    // Validate contexts reference valid agents
-    for (const [contextKey, contextAgentNames] of Object.entries(config.contexts)) {
-      if (!Array.isArray(contextAgentNames)) {
-        throw new Error(`Context "${contextKey}" must have an array of agent names`);
-      }
-
-      for (const agentName of contextAgentNames) {
-        if (!agentNames.has(agentName)) {
-          throw new Error(`Context "${contextKey}" references unknown agent: ${agentName}`);
-        }
-      }
-    }
-  }
-}

package/src/helpers/ContextLimiter.ts

@@ -1,228 +0,0 @@
-import { AgentMessage, MessageRole } from '@multiplayer-app/ai-agent-types';
-
-/**
- * Options for limiting chat context
- */
-export interface ContextLimitOptions {
-  /**
-   * Maximum number of messages to include in context.
-   * Default: 50 (common practice: 20-100 messages depending on use case)
-   */
-  maxMessages?: number;
-  
-  /**
-   * Maximum token count (if token counting is implemented).
-   * This is a future enhancement - currently not used.
-   */
-  maxTokens?: number;
-  
-  /**
-   * Whether to always keep the first user message (often contains important context).
-   * Default: true
-   */
-  keepFirstUserMessage?: boolean;
-  
-  /**
-   * Whether to keep all system messages (if any exist).
-   * Default: true
-   */
-  keepSystemMessages?: boolean;
-}
-
-/**
- * Common practices for limiting AI context:
- * 
- * 1. **Message Count Limiting** (implemented here)
- *    - Keep only the last N messages
- *    - Most common and simplest approach
- *    - Typical values: 20-100 messages depending on use case
- * 
- * 2. **Token-Based Limiting** (future enhancement)
- *    - Count tokens and keep messages until hitting token budget
- *    - More accurate for cost control
- *    - Requires token counting library (e.g., tiktoken, @anthropic-ai/tokenizer)
- * 
- * 3. **Hybrid Approach** (future enhancement)
- *    - Combine message count with token budget as safety check
- *    - Best of both worlds
- * 
- * 4. **Sliding Window with Summary** (advanced)
- *    - Keep recent messages + summarize older ones
- *    - Requires summarization step
- * 
- * 5. **Priority-Based** (implemented via keepFirstUserMessage)
- *    - Always keep system messages, first user message, and recent messages
- *    - Preserves important context while limiting size
- */
-export class ContextLimiter {
-  /**
-   * Limits the context by keeping only the most recent messages
-   * while preserving important messages (first user message, system messages).
-   * 
-   * @param messages - All messages from the chat (assumed to be in chronological order)
-   * @param options - Limiting options
-   * @returns Limited array of messages in original order
-   */
-  static limitContext(
-    messages: AgentMessage[],
-    options: ContextLimitOptions = {}
-  ): AgentMessage[] {
-    const {
-      maxMessages = 5,
-      keepFirstUserMessage = true,
-      keepSystemMessages = true,
-    } = options;
-
-    // If we have fewer messages than the limit, return all
-    if (messages.length <= maxMessages) {
-      return messages;
-    }
-
-    // Separate system messages from the rest
-    const systemMessages: AgentMessage[] = [];
-    const nonSystemMessages: AgentMessage[] = [];
-    
-    messages.forEach((msg) => {
-      if (msg.role === MessageRole.System && keepSystemMessages) {
-        systemMessages.push(msg);
-      } else {
-        nonSystemMessages.push(msg);
-      }
-    });
-
-    // Find the first user message (if we need to keep it)
-    const firstUserMessageIndex = keepFirstUserMessage
-      ? nonSystemMessages.findIndex((msg) => msg.role === MessageRole.User)
-      : -1;
-    const firstUserMessage = firstUserMessageIndex >= 0
-      ? nonSystemMessages[firstUserMessageIndex]
-      : undefined;
-
-    // Calculate how many recent messages we can keep
-    // Reserve slots for: system messages
-    let availableSlots = maxMessages - systemMessages.length;
-    const shouldKeepFirstUser = keepFirstUserMessage && firstUserMessage !== undefined;
-
-    // Get the most recent messages (from the end)
-    // We'll check if first user is in recent messages after slicing
-    const recentCount = Math.max(0, availableSlots);
-    const recentStartIndex = Math.max(0, nonSystemMessages.length - recentCount);
-    const recentMessages = nonSystemMessages.slice(recentStartIndex);
-
-    // Check if first user message is already in recent messages
-    const firstUserInRecent = shouldKeepFirstUser && firstUserMessage
-      ? recentMessages.some((msg) => msg.id === firstUserMessage.id)
-      : false;
-
-    // If first user is not in recent and we need to keep it, we need to make room
-    if (shouldKeepFirstUser && firstUserMessage && !firstUserInRecent) {
-      // Remove the oldest recent message to make room for first user message
-      if (recentMessages.length > 0) {
-        recentMessages.shift();
-      }
-    }
-
-    // Build the set of messages to keep
-    const messagesToKeep = new Set<string>();
-    
-    // Add system messages
-    systemMessages.forEach((msg) => messagesToKeep.add(msg.id));
-    
-    // Add first user message if needed
-    if (shouldKeepFirstUser && firstUserMessage) {
-      messagesToKeep.add(firstUserMessage.id);
-    }
-    
-    // Add recent messages
-    recentMessages.forEach((msg) => messagesToKeep.add(msg.id));
-
-    // Reconstruct in original order
-    return messages.filter((msg) => messagesToKeep.has(msg.id));
-  }
-
-  /**
-   * Estimates token count for a message (rough approximation).
-   * For accurate token counting, use a proper tokenizer library.
-   * 
-   * This is a simple approximation: ~4 characters per token for English text.
-   * 
-   * @param message - Message to estimate tokens for
-   * @returns Estimated token count
-   */
-  static estimateTokens(message: AgentMessage): number {
-    const content = typeof message.content === 'string' 
-      ? message.content 
-      : JSON.stringify(message.content);
-    
-    // Rough approximation: 1 token ≈ 4 characters for English
-    // This is a simplified estimate - actual tokenization varies by model
-    const baseTokens = Math.ceil(content.length / 4);
-    
-    // Add overhead for message structure (role, formatting, etc.)
-    const overhead = 10;
-    
-    // Add tokens for tool calls if present
-    const toolCallTokens = message.toolCalls?.reduce((acc, toolCall) => {
-      const inputTokens = Math.ceil(JSON.stringify(toolCall.input).length / 4);
-      const outputTokens = toolCall.output 
-        ? Math.ceil(JSON.stringify(toolCall.output).length / 4)
-        : 0;
-      return acc + inputTokens + outputTokens + 20; // 20 for tool call structure
-    }, 0) || 0;
-    
-    return baseTokens + overhead + toolCallTokens;
-  }
-
-  /**
-   * Limits context by token count (future enhancement).
-   * Currently not implemented - requires proper tokenizer.
-   * 
-   * @param messages - All messages from the chat
-   * @param maxTokens - Maximum token count
-   * @returns Limited array of messages
-   */
-  static limitByTokens(
-    messages: AgentMessage[],
-    maxTokens: number
-  ): AgentMessage[] {
-    // This is a placeholder for token-based limiting
-    // To implement properly, you would:
-    // 1. Install a tokenizer (e.g., tiktoken for OpenAI, @anthropic-ai/tokenizer for Claude)
-    // 2. Count tokens for each message
-    // 3. Keep messages from the end until hitting the token limit
-    // 4. Always keep system messages and optionally first user message
-    
-    let totalTokens = 0;
-    const limitedMessages: AgentMessage[] = [];
-    
-    // Keep system messages first
-    const systemMessages = messages.filter(
-      (msg) => msg.role === MessageRole.System
-    );
-    systemMessages.forEach((msg) => {
-      const tokens = this.estimateTokens(msg);
-      if (totalTokens + tokens <= maxTokens) {
-        limitedMessages.push(msg);
-        totalTokens += tokens;
-      }
-    });
-    
-    // Then keep messages from the end
-    const nonSystemMessages = messages
-      .filter((msg) => msg.role !== MessageRole.System)
-      .reverse();
-    
-    for (const message of nonSystemMessages) {
-      const tokens = this.estimateTokens(message);
-      if (totalTokens + tokens <= maxTokens) {
-        limitedMessages.unshift(message); // Add to beginning to maintain order
-        totalTokens += tokens;
-      } else {
-        break;
-      }
-    }
-    
-    return limitedMessages;
-  }
-}
-

package/src/helpers/FileHelper.ts

@@ -1,197 +0,0 @@
-import type { AgentAttachment } from '@multiplayer-app/ai-agent-types';
-import { AgentAttachmentType } from '@multiplayer-app/ai-agent-types';
-import { s3 } from '../libs/s3';
-import { logger } from '../libs/logger';
-import { PDFParse } from 'pdf-parse';
-import {config} from "../config";
-
-export interface ProcessedAttachment extends AgentAttachment {
-  extractedText?: string;
-  processingStatus?: 'pending' | 'processed' | 'failed';
-}
-
-/**
- * Checks if an attachment is an image
- */
-export function isImage(attachment: AgentAttachment): boolean {
-  if (attachment.type !== AgentAttachmentType.File) return false;
-  const mimeType = attachment.mimeType || '';
-  return mimeType.startsWith('image/');
-}
-
-/**
- * Checks if an attachment is a document that can have text extracted
- */
-export function isDocument(attachment: AgentAttachment): boolean {
-  if (attachment.type !== AgentAttachmentType.File) return false;
-  const mimeType = attachment.mimeType || '';
-  return mimeType.startsWith('text/') || mimeType.startsWith('application/')
-}
-
-/**
- * Extracts text from a document attachment
- */
-export async function extractTextFromDocument(
-  attachment: AgentAttachment
-): Promise<string | undefined> {
-  if (!isDocument(attachment) || attachment.type !== AgentAttachmentType.File) {
-    logger.debug('Attachment is not a document or not a file type', {
-      attachmentId: attachment.id,
-      type: attachment.type,
-      mimeType: attachment.mimeType
-    });
-    return undefined;
-  }
-
-  try {
-    const mimeType = attachment.mimeType || '';
-
-    // All files are stored in S3 (s3Key is in metadata)
-    if (attachment.metadata?.s3Key) {
-      const s3Key = attachment.metadata.s3Key as string;
-      const bucket = config.s3.bucket;
-      if (mimeType === 'application/pdf') {
-        const buffer = await s3.downloadFileAsByteArray(s3Key, bucket);
-        if (buffer) {
-          // Convert Uint8Array to Buffer
-          const nodeBuffer = Buffer.from(buffer);
-          return await extractTextFromPDF(nodeBuffer);
-        }
-      } else if (
-        mimeType === 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
-      ) {
-        const buffer = await s3.downloadFileAsByteArray(s3Key, bucket);
-        if (buffer) {
-          // Convert Uint8Array to Buffer
-          const nodeBuffer = Buffer.from(buffer);
-          return await extractTextFromDOCX(nodeBuffer);
-        }
-      } else {
-        const text = await s3.downloadFileAsString(s3Key, bucket);
-        return text || undefined;
-      }
-    }
-
-    return undefined;
-  } catch (error) {
-    logger.error('Failed to extract text from document', { error, attachmentId: attachment.id });
-    return undefined;
-  }
-}
-
-/**
- * Extracts text from PDF buffer
- */
-async function extractTextFromPDF(buffer: Buffer): Promise<string | undefined> {
-  try {
-    const {PDFParse} = await import('pdf-parse');
-    const parser = new PDFParse({ data: buffer });
-    const text = (await parser.getText()).text || '';
-
-    // Limit extracted text size
-    const maxSize = Number(process.env.MAX_EXTRACTED_TEXT_SIZE) || 51200;
-    return text.length > maxSize ? text.substring(0, maxSize) + '...' : text;
-  } catch (error) {
-    logger.warn('PDF text extraction failed (pdf-parse may not be installed)', { error });
-    return undefined;
-  }
-}
-
-/**
- * Extracts text from DOCX buffer
- */
-async function extractTextFromDOCX(buffer: Buffer): Promise<string | undefined> {
-  try {
-    const mammoth = await import('mammoth');
-    const result = await mammoth.extractRawText({ buffer });
-    const text = result.value || '';
-
-    // Limit extracted text size
-    const maxSize = Number(process.env.MAX_EXTRACTED_TEXT_SIZE) || 51200;
-    return text.length > maxSize ? text.substring(0, maxSize) + '...' : text;
-  } catch (error) {
-    logger.warn('DOCX text extraction failed (mammoth may not be installed)', { error });
-    return undefined;
-  }
-}
-
-/**
- * Processes an attachment and extracts content as needed
- */
-export async function processAttachment(
-  attachment: AgentAttachment
-): Promise<ProcessedAttachment> {
-  const processed: ProcessedAttachment = { ...attachment };
-
-  // Only process file attachments
-  if (attachment.type !== AgentAttachmentType.File) {
-    return processed;
-  }
-
-  // Check if text extraction is enabled
-  const enableTextExtraction = process.env.ENABLE_TEXT_EXTRACTION !== 'false';
-
-  if (enableTextExtraction && isDocument(attachment)) {
-    try {
-      processed.processingStatus = 'pending';
-      const extractedText = await extractTextFromDocument(attachment);
-      if (extractedText) {
-        processed.extractedText = extractedText;
-        processed.processingStatus = 'processed';
-      } else {
-        processed.processingStatus = 'failed';
-      }
-    } catch (error) {
-      logger.error('Failed to process document attachment', { error, attachmentId: attachment.id });
-      processed.processingStatus = 'failed';
-    }
-  }
-
-  return processed;
-}
-
-/**
- * Prepares an image attachment for vision API
- */
-export async function prepareImageForVisionAPI(attachment: AgentAttachment): Promise<{
-  type: 'image_url';
-  image_url: { url: string };
-} | null> {
-  if (!isImage(attachment) || attachment.type !== AgentAttachmentType.File) {
-    return null;
-  }
-
-  // All files are stored in S3 - generate presigned download URL
-  if (attachment.metadata?.s3Key) {
-    try {
-      const s3Key = attachment.metadata.s3Key as string;
-      const bucket = config.s3.bucket;
-      const buffer = await s3.downloadFileAsByteArray(s3Key, bucket);
-      if(!buffer) {
-        return null;
-      }
-      const mimeType = attachment.mimeType || 'image/png';
-      return {
-        type: 'image_url',
-        image_url: {
-          url: `data:${mimeType};base64,${Buffer.from(buffer).toString('base64')}`,
-        },
-      };
-    } catch (error) {
-      logger.error('Failed to generate presigned URL for S3 image', { error, attachmentId: attachment.id });
-      return null;
-    }
-  }
-
-  // Fallback: If we have a URL (backward compatibility)
-  if (attachment.url) {
-    return {
-      type: 'image_url',
-      image_url: {
-        url: attachment.url,
-      },
-    };
-  }
-
-  return null;
-}

package/src/helpers/SetupHelper.ts

@@ -1,35 +0,0 @@
-import { logger } from '../libs/logger';
-import { agentStore, ModelStore } from '../store';
-import { redisService, kafkaService, ModelFetcher } from '../services';
-import { s3 } from "../libs/s3";
-import { config } from "../config";
-import { AgentChatRepository, AgentMessageRepository } from '@multiplayer-app/ai-agent-db';
-
-export async function fetchModels() {
-    try {
-      const modelFetcher = new ModelFetcher();
-      const models = await modelFetcher.fetchAllModels();
-      ModelStore.getInstance().setModels(models);
-    } catch (error) {
-      logger.error('Failed to fetch models on startup:', error);
-      throw error;
-    }
-}
-
-export function startServices(agentChatRepository: AgentChatRepository, agentMessageRepository: AgentMessageRepository) {
-  kafkaService.setRepositories(agentChatRepository, agentMessageRepository);
-
-  return Promise.all([
-    kafkaService.start(),
-    agentStore.initialize(),
-    fetchModels(),
-    s3.ensureBucketExists(config.s3.bucket),
-  ])
-}
-
-export function stopServices() {
-  return Promise.all([
-    redisService.disconnect(),
-    kafkaService.stop()
-  ])
-}

package/src/libs/index.ts

@@ -1,3 +0,0 @@
-export * from './kafka';
-export * from './logger';
-export * from './s3';

package/src/libs/kafka/config.ts

@@ -1,4 +0,0 @@
-export const SERVICE_NAME = process.env.npm_package_name
-export const KAFKA_URI = (process.env.KAFKA_URI as string || 'localhost:9092').split(',')
-export const KAFKA_CLIENT_ID = process.env.KAFKA_CLIENT_ID as string || SERVICE_NAME
-export const KAFKA_SESSION_TIMEOUT = Number.parseInt(process.env.KAFKA_SESSION_TIMEOUT || '30000')