family-ai-agent 1.0.0

package/src/index.ts

@@ -0,0 +1,104 @@
+/**
+ * Family AI Agent - Multi-Agent AI System
+ *
+ * A production-ready multi-agent AI system with:
+ * - Supervisor architecture for task routing
+ * - Specialized agents (Research, Coding, Automation, Chat)
+ * - Long-term memory with vector search
+ * - Knowledge base with RAG
+ * - Safety guardrails
+ *
+ * @module family-ai-agent
+ */
+
+// Core exports
+export { BaseAgent } from './core/agents/base-agent.js';
+export { ChatAgent, createChatAgent } from './core/agents/personalities/chat.js';
+export { ResearchAgent, createResearchAgent } from './core/agents/personalities/research.js';
+export { CodingAgent, createCodingAgent } from './core/agents/personalities/coding.js';
+export { AutomationAgent, createAutomationAgent } from './core/agents/personalities/automation.js';
+export { AgentFactory, getAgentFactory } from './core/agents/agent-factory.js';
+export type {
+  AgentRole,
+  AgentStatus,
+  AgentIdentity,
+  AgentConfig,
+  AgentState,
+  TaskDefinition,
+  TaskResult,
+  RetrievedMemory,
+} from './core/agents/types.js';
+
+// Orchestrator exports
+export {
+  createOrchestratorGraph,
+  getOrchestratorGraph,
+  runOrchestrator,
+  streamOrchestrator,
+} from './core/orchestrator/graph.js';
+
+// Memory exports
+export { VectorStore, getVectorStore } from './memory/longterm/vector-store.js';
+export { ConversationMemory, getConversationMemory } from './memory/conversation/index.js';
+export { KnowledgeBase, getKnowledgeBase } from './memory/knowledge-base/index.js';
+
+// LLM exports
+export { OpenRouterClient, getOpenRouterClient } from './llm/openrouter-client.js';
+
+// Safety exports
+export { InputGuardrail, getInputGuardrail, validateInput } from './safety/guardrails/input-guardrail.js';
+export { OutputGuardrail, getOutputGuardrail, validateOutput } from './safety/guardrails/output-guardrail.js';
+export { AuditLogger, getAuditLogger } from './safety/audit-logger.js';
+
+// Database exports
+export { initDatabase, closePool, query, transaction } from './database/client.js';
+
+// Config exports
+export { config, getDatabaseUrl, getRedisUrl, isProduction, isDevelopment } from './config/index.js';
+export { AVAILABLE_MODELS, getModelConfig, getRecommendedModel } from './config/models.js';
+
+// Utility exports
+export { logger, createLogger } from './utils/logger.js';
+export * from './utils/errors.js';
+
+// Version
+export const VERSION = '1.0.0';
+
+// Quick start function
+import { initDatabase } from './database/client.js';
+import { runOrchestrator } from './core/orchestrator/graph.js';
+import { getVectorStore } from './memory/longterm/vector-store.js';
+
+export async function quickStart(): Promise<{
+  ask: (input: string) => Promise<string>;
+  remember: (content: string) => Promise<string>;
+  search: (query: string) => Promise<RetrievedMemory[]>;
+  shutdown: () => Promise<void>;
+}> {
+  await initDatabase();
+
+  const vectorStore = getVectorStore();
+
+  return {
+    async ask(input: string): Promise<string> {
+      const memories = await vectorStore.search(input, { limit: 3 });
+      const result = await runOrchestrator(input, {}, memories);
+      return result.response;
+    },
+
+    async remember(content: string): Promise<string> {
+      return vectorStore.store(content, 'semantic');
+    },
+
+    async search(query: string): Promise<RetrievedMemory[]> {
+      return vectorStore.search(query);
+    },
+
+    async shutdown(): Promise<void> {
+      const { closePool } = await import('./database/client.js');
+      await closePool();
+    },
+  };
+}
+
+import type { RetrievedMemory } from './core/agents/types.js';

package/src/llm/openrouter-client.ts

@@ -0,0 +1,218 @@
+import { ChatOpenAI } from '@langchain/openai';
+import { OpenAIEmbeddings } from '@langchain/openai';
+import { config } from '../config/index.js';
+import { getModelConfig, type ModelConfig } from '../config/models.js';
+import { LLMError } from '../utils/errors.js';
+import { createLogger } from '../utils/logger.js';
+import type { BaseMessage } from '@langchain/core/messages';
+
+const logger = createLogger('OpenRouterClient');
+
+export interface ChatOptions {
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  frequencyPenalty?: number;
+  presencePenalty?: number;
+  stop?: string[];
+  streaming?: boolean;
+}
+
+export interface CompletionResult {
+  content: string;
+  model: string;
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  finishReason: string;
+}
+
+export class OpenRouterClient {
+  private defaultModel: string;
+  private fastModel: string;
+  private embeddingModel: string;
+  private chatModels: Map<string, ChatOpenAI> = new Map();
+  private embeddings: OpenAIEmbeddings | null = null;
+
+  constructor() {
+    this.defaultModel = config.DEFAULT_MODEL;
+    this.fastModel = config.FAST_MODEL;
+    this.embeddingModel = config.EMBEDDING_MODEL;
+  }
+
+  private getChatModel(modelId: string, options: ChatOptions = {}): ChatOpenAI {
+    const cacheKey = `${modelId}-${JSON.stringify(options)}`;
+
+    if (!this.chatModels.has(cacheKey)) {
+      const modelConfig = getModelConfig(modelId);
+
+      const chatModel = new ChatOpenAI({
+        modelName: modelId,
+        openAIApiKey: config.OPENROUTER_API_KEY,
+        temperature: options.temperature ?? 0.7,
+        maxTokens: options.maxTokens ?? modelConfig?.maxOutput ?? 4096,
+        topP: options.topP,
+        frequencyPenalty: options.frequencyPenalty,
+        presencePenalty: options.presencePenalty,
+        stop: options.stop,
+        streaming: options.streaming ?? false,
+        configuration: {
+          baseURL: config.OPENROUTER_BASE_URL,
+          defaultHeaders: {
+            'HTTP-Referer': 'https://family-ai-agent.local',
+            'X-Title': 'Family AI Agent',
+          },
+        },
+      });
+
+      this.chatModels.set(cacheKey, chatModel);
+    }
+
+    return this.chatModels.get(cacheKey)!;
+  }
+
+  getEmbeddings(): OpenAIEmbeddings {
+    if (!this.embeddings) {
+      this.embeddings = new OpenAIEmbeddings({
+        modelName: this.embeddingModel,
+        openAIApiKey: config.OPENROUTER_API_KEY,
+        configuration: {
+          baseURL: config.OPENROUTER_BASE_URL,
+        },
+      });
+    }
+    return this.embeddings;
+  }
+
+  // Get a LangChain ChatModel for use with agents
+  getChatModelForAgent(options: ChatOptions = {}): ChatOpenAI {
+    const modelId = options.model ?? this.defaultModel;
+    return this.getChatModel(modelId, {
+      ...options,
+      streaming: true, // Enable streaming for agents
+    });
+  }
+
+  // Get a fast model for quick operations
+  getFastModel(options: ChatOptions = {}): ChatOpenAI {
+    return this.getChatModel(this.fastModel, options);
+  }
+
+  // Simple completion method
+  async complete(
+    messages: BaseMessage[],
+    options: ChatOptions = {}
+  ): Promise<CompletionResult> {
+    const modelId = options.model ?? this.defaultModel;
+    const model = this.getChatModel(modelId, options);
+
+    try {
+      logger.debug('Sending completion request', { model: modelId });
+      const startTime = Date.now();
+
+      const response = await model.invoke(messages);
+
+      const duration = Date.now() - startTime;
+      logger.debug('Completion received', { model: modelId, duration });
+
+      return {
+        content: typeof response.content === 'string'
+          ? response.content
+          : JSON.stringify(response.content),
+        model: modelId,
+        usage: {
+          promptTokens: response.usage_metadata?.input_tokens ?? 0,
+          completionTokens: response.usage_metadata?.output_tokens ?? 0,
+          totalTokens: response.usage_metadata?.total_tokens ?? 0,
+        },
+        finishReason: response.response_metadata?.finish_reason ?? 'stop',
+      };
+    } catch (error) {
+      logger.error('Completion failed', { model: modelId, error });
+      throw new LLMError(
+        `Failed to get completion from ${modelId}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        { model: modelId, originalError: String(error) }
+      );
+    }
+  }
+
+  // Stream completion
+  async *streamComplete(
+    messages: BaseMessage[],
+    options: ChatOptions = {}
+  ): AsyncGenerator<string, void, unknown> {
+    const modelId = options.model ?? this.defaultModel;
+    const model = this.getChatModel(modelId, { ...options, streaming: true });
+
+    try {
+      logger.debug('Starting stream completion', { model: modelId });
+
+      const stream = await model.stream(messages);
+
+      for await (const chunk of stream) {
+        if (typeof chunk.content === 'string') {
+          yield chunk.content;
+        }
+      }
+    } catch (error) {
+      logger.error('Stream completion failed', { model: modelId, error });
+      throw new LLMError(
+        `Failed to stream completion from ${modelId}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        { model: modelId, originalError: String(error) }
+      );
+    }
+  }
+
+  // Generate embeddings for text
+  async embed(texts: string[]): Promise<number[][]> {
+    try {
+      const embeddings = this.getEmbeddings();
+      return await embeddings.embedDocuments(texts);
+    } catch (error) {
+      logger.error('Embedding generation failed', { error });
+      throw new LLMError(
+        `Failed to generate embeddings: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        { originalError: String(error) }
+      );
+    }
+  }
+
+  // Generate single embedding
+  async embedQuery(text: string): Promise<number[]> {
+    try {
+      const embeddings = this.getEmbeddings();
+      return await embeddings.embedQuery(text);
+    } catch (error) {
+      logger.error('Query embedding failed', { error });
+      throw new LLMError(
+        `Failed to generate query embedding: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        { originalError: String(error) }
+      );
+    }
+  }
+
+  // Get model info
+  getModelInfo(modelId?: string): ModelConfig | undefined {
+    return getModelConfig(modelId ?? this.defaultModel);
+  }
+
+  // List available models
+  getAvailableModels(): string[] {
+    return [this.defaultModel, this.fastModel];
+  }
+}
+
+// Singleton instance
+let clientInstance: OpenRouterClient | null = null;
+
+export function getOpenRouterClient(): OpenRouterClient {
+  if (!clientInstance) {
+    clientInstance = new OpenRouterClient();
+  }
+  return clientInstance;
+}
+
+export default OpenRouterClient;

package/src/memory/conversation/index.ts

@@ -0,0 +1,313 @@
+import { query } from '../../database/client.js';
+import { createLogger, logMemoryOperation } from '../../utils/logger.js';
+import { MemoryError } from '../../utils/errors.js';
+import type { BaseMessage } from '@langchain/core/messages';
+import { HumanMessage, AIMessage, SystemMessage } from '@langchain/core/messages';
+
+const logger = createLogger('ConversationMemory');
+
+export interface Conversation {
+  id: string;
+  threadId: string;
+  userId?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface Message {
+  id: string;
+  conversationId: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  metadata: Record<string, unknown>;
+  createdAt: Date;
+}
+
+export class ConversationMemory {
+  // Create a new conversation
+  async createConversation(threadId: string, userId?: string): Promise<string> {
+    try {
+      const result = await query<{ id: string }>(
+        `INSERT INTO conversations (thread_id, user_id)
+         VALUES ($1, $2)
+         RETURNING id`,
+        [threadId, userId ?? null]
+      );
+
+      const conversationId = result.rows[0]?.id;
+      if (!conversationId) {
+        throw new MemoryError('Failed to create conversation');
+      }
+
+      logMemoryOperation('write', 'conversation', {
+        conversationId,
+        threadId,
+      });
+
+      return conversationId;
+    } catch (error) {
+      logger.error('Failed to create conversation', { error });
+      throw new MemoryError(
+        `Failed to create conversation: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+
+  // Get conversation by thread ID
+  async getConversation(threadId: string): Promise<Conversation | null> {
+    try {
+      const result = await query<{
+        id: string;
+        thread_id: string;
+        user_id: string | null;
+        created_at: Date;
+        updated_at: Date;
+      }>(
+        `SELECT id, thread_id, user_id, created_at, updated_at
+         FROM conversations WHERE thread_id = $1`,
+        [threadId]
+      );
+
+      if (result.rows.length === 0) {
+        return null;
+      }
+
+      const row = result.rows[0]!;
+      return {
+        id: row.id,
+        threadId: row.thread_id,
+        userId: row.user_id ?? undefined,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+      };
+    } catch (error) {
+      logger.error('Failed to get conversation', { error });
+      throw new MemoryError(
+        `Failed to get conversation: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+
+  // Get or create conversation
+  async getOrCreateConversation(threadId: string, userId?: string): Promise<string> {
+    const existing = await this.getConversation(threadId);
+    if (existing) {
+      return existing.id;
+    }
+    return this.createConversation(threadId, userId);
+  }
+
+  // Add message to conversation
+  async addMessage(
+    conversationId: string,
+    role: 'user' | 'assistant' | 'system',
+    content: string,
+    metadata: Record<string, unknown> = {}
+  ): Promise<string> {
+    try {
+      const result = await query<{ id: string }>(
+        `INSERT INTO messages (conversation_id, role, content, metadata)
+         VALUES ($1, $2, $3, $4)
+         RETURNING id`,
+        [conversationId, role, content, JSON.stringify(metadata)]
+      );
+
+      const messageId = result.rows[0]?.id;
+      if (!messageId) {
+        throw new MemoryError('Failed to add message');
+      }
+
+      // Update conversation timestamp
+      await query(
+        'UPDATE conversations SET updated_at = NOW() WHERE id = $1',
+        [conversationId]
+      );
+
+      return messageId;
+    } catch (error) {
+      logger.error('Failed to add message', { error });
+      throw new MemoryError(
+        `Failed to add message: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+
+  // Get messages for a conversation
+  async getMessages(
+    conversationId: string,
+    options: { limit?: number; offset?: number } = {}
+  ): Promise<Message[]> {
+    const { limit = 50, offset = 0 } = options;
+
+    try {
+      const result = await query<{
+        id: string;
+        conversation_id: string;
+        role: 'user' | 'assistant' | 'system';
+        content: string;
+        metadata: Record<string, unknown>;
+        created_at: Date;
+      }>(
+        `SELECT id, conversation_id, role, content, metadata, created_at
+         FROM messages
+         WHERE conversation_id = $1
+         ORDER BY created_at ASC
+         LIMIT $2 OFFSET $3`,
+        [conversationId, limit, offset]
+      );
+
+      return result.rows.map((row) => ({
+        id: row.id,
+        conversationId: row.conversation_id,
+        role: row.role,
+        content: row.content,
+        metadata: row.metadata,
+        createdAt: row.created_at,
+      }));
+    } catch (error) {
+      logger.error('Failed to get messages', { error });
+      throw new MemoryError(
+        `Failed to get messages: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+
+  // Convert messages to LangChain format
+  async getMessagesAsLangChain(conversationId: string): Promise<BaseMessage[]> {
+    const messages = await this.getMessages(conversationId);
+
+    return messages.map((msg) => {
+      switch (msg.role) {
+        case 'user':
+          return new HumanMessage({ content: msg.content });
+        case 'assistant':
+          return new AIMessage({ content: msg.content });
+        case 'system':
+          return new SystemMessage({ content: msg.content });
+        default:
+          return new HumanMessage({ content: msg.content });
+      }
+    });
+  }
+
+  // Get recent messages (for context window)
+  async getRecentMessages(
+    conversationId: string,
+    maxMessages: number = 10
+  ): Promise<Message[]> {
+    try {
+      const result = await query<{
+        id: string;
+        conversation_id: string;
+        role: 'user' | 'assistant' | 'system';
+        content: string;
+        metadata: Record<string, unknown>;
+        created_at: Date;
+      }>(
+        `SELECT id, conversation_id, role, content, metadata, created_at
+         FROM messages
+         WHERE conversation_id = $1
+         ORDER BY created_at DESC
+         LIMIT $2`,
+        [conversationId, maxMessages]
+      );
+
+      // Reverse to get chronological order
+      return result.rows.reverse().map((row) => ({
+        id: row.id,
+        conversationId: row.conversation_id,
+        role: row.role,
+        content: row.content,
+        metadata: row.metadata,
+        createdAt: row.created_at,
+      }));
+    } catch (error) {
+      logger.error('Failed to get recent messages', { error });
+      throw new MemoryError(
+        `Failed to get recent messages: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+
+  // Delete conversation and all messages
+  async deleteConversation(conversationId: string): Promise<void> {
+    try {
+      await query('DELETE FROM conversations WHERE id = $1', [conversationId]);
+      logMemoryOperation('write', 'conversation', {
+        conversationId,
+        action: 'delete',
+      });
+    } catch (error) {
+      logger.error('Failed to delete conversation', { error });
+      throw new MemoryError(
+        `Failed to delete conversation: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+
+  // Get conversation count for user
+  async getConversationCount(userId: string): Promise<number> {
+    try {
+      const result = await query<{ count: string }>(
+        'SELECT COUNT(*) as count FROM conversations WHERE user_id = $1',
+        [userId]
+      );
+      return parseInt(result.rows[0]?.count ?? '0', 10);
+    } catch (error) {
+      logger.error('Failed to get conversation count', { error });
+      throw new MemoryError(
+        `Failed to get conversation count: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+
+  // List user's conversations
+  async listConversations(
+    userId: string,
+    options: { limit?: number; offset?: number } = {}
+  ): Promise<Conversation[]> {
+    const { limit = 20, offset = 0 } = options;
+
+    try {
+      const result = await query<{
+        id: string;
+        thread_id: string;
+        user_id: string | null;
+        created_at: Date;
+        updated_at: Date;
+      }>(
+        `SELECT id, thread_id, user_id, created_at, updated_at
+         FROM conversations
+         WHERE user_id = $1
+         ORDER BY updated_at DESC
+         LIMIT $2 OFFSET $3`,
+        [userId, limit, offset]
+      );
+
+      return result.rows.map((row) => ({
+        id: row.id,
+        threadId: row.thread_id,
+        userId: row.user_id ?? undefined,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+      }));
+    } catch (error) {
+      logger.error('Failed to list conversations', { error });
+      throw new MemoryError(
+        `Failed to list conversations: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  }
+}
+
+// Singleton instance
+let memoryInstance: ConversationMemory | null = null;
+
+export function getConversationMemory(): ConversationMemory {
+  if (!memoryInstance) {
+    memoryInstance = new ConversationMemory();
+  }
+  return memoryInstance;
+}
+
+export default ConversationMemory;

package/src/memory/index.ts

@@ -0,0 +1,23 @@
+// Memory module exports
+export {
+  VectorStore,
+  getVectorStore,
+  type MemoryType,
+  type MemoryEntry,
+  type SearchOptions,
+} from './longterm/vector-store.js';
+
+export {
+  ConversationMemory,
+  getConversationMemory,
+  type Conversation,
+  type Message,
+} from './conversation/index.js';
+
+export {
+  KnowledgeBase,
+  getKnowledgeBase,
+  type Document,
+  type DocumentChunk,
+  type SearchResult,
+} from './knowledge-base/index.js';