family-ai-agent 1.0.0

package/src/core/agents/personalities/research.ts

@@ -0,0 +1,177 @@
+import { nanoid } from 'nanoid';
+import { BaseAgent } from '../base-agent.js';
+import type {
+  AgentConfig,
+  AgentState,
+  TaskResult,
+  RetrievedMemory,
+  HandoffDecision,
+} from '../types.js';
+import { getRecommendedModel } from '../../../config/models.js';
+
+const RESEARCH_SYSTEM_PROMPT = `You are an expert Research Agent in the Family AI Agent system, specializing in information gathering and analysis.
+
+Your identity: Research Specialist
+Your personality:
+- Thorough and methodical
+- Fact-focused and objective
+- Clear in presenting findings
+- Good at synthesizing information from multiple sources
+
+Your capabilities:
+- Web search and information retrieval
+- Fact-checking and verification
+- Summarizing complex topics
+- Comparing and analyzing data
+- Creating research reports
+
+Research methodology:
+1. Understand the research question clearly
+2. Identify key search terms and concepts
+3. Gather information from multiple sources
+4. Verify facts and cross-reference
+5. Synthesize findings into coherent summaries
+6. Cite sources when possible
+
+Guidelines:
+- Always prioritize accuracy over speed
+- Clearly distinguish between facts and opinions
+- Note any uncertainties or conflicting information
+- Provide sources for claims when available
+- Ask for clarification if the research question is ambiguous
+
+When presenting findings:
+- Start with a brief summary/answer
+- Provide supporting details and evidence
+- List sources and references
+- Note any limitations or areas needing further research`;
+
+export class ResearchAgent extends BaseAgent {
+  constructor(tools: AgentConfig['tools'] = []) {
+    super({
+      identity: {
+        id: `research-${nanoid(8)}`,
+        name: 'Researcher',
+        role: 'research',
+        description: 'Expert research and information gathering agent',
+        capabilities: [
+          'web_search',
+          'fact_checking',
+          'summarization',
+          'analysis',
+          'report_writing',
+          'data_comparison',
+          'source_verification',
+        ],
+      },
+      model: getRecommendedModel('research'),
+      temperature: 0.3, // Lower temperature for factual accuracy
+      systemPrompt: RESEARCH_SYSTEM_PROMPT,
+      tools,
+      maxIterations: 15, // More iterations for thorough research
+      timeout: 180000, // 3 minutes for research tasks
+    });
+  }
+
+  protected buildSystemPrompt(
+    context: Record<string, unknown>,
+    memories: RetrievedMemory[]
+  ): string {
+    let prompt = this.systemPrompt;
+
+    // Add previous research findings from memory
+    const researchMemories = memories.filter(
+      (m) => m.type === 'episodic' || m.type === 'semantic'
+    );
+
+    if (researchMemories.length > 0) {
+      prompt += '\n\n## Previous Research Findings\n';
+      for (const memory of researchMemories) {
+        prompt += `- ${memory.content} (relevance: ${(memory.relevanceScore * 100).toFixed(0)}%)\n`;
+      }
+    }
+
+    // Add research context
+    if (context.researchTopic) {
+      prompt += `\n\n## Current Research Topic\n${context.researchTopic}`;
+    }
+
+    if (context.researchConstraints) {
+      prompt += `\n\n## Research Constraints\n`;
+      prompt += JSON.stringify(context.researchConstraints, null, 2);
+    }
+
+    return prompt;
+  }
+
+  protected async shouldHandoff(
+    state: AgentState,
+    result: TaskResult
+  ): Promise<HandoffDecision> {
+    const output = String(result.output).toLowerCase();
+
+    // Check if implementation is needed
+    if (
+      output.includes('to implement this') ||
+      output.includes('code needed') ||
+      output.includes('write the code')
+    ) {
+      return {
+        shouldHandoff: true,
+        targetAgent: 'coding',
+        reason: 'Research complete, implementation needed',
+        context: {
+          researchFindings: result.output,
+        },
+      };
+    }
+
+    // Check if automation is suggested
+    if (
+      output.includes('automate this process') ||
+      output.includes('schedule regular')
+    ) {
+      return {
+        shouldHandoff: true,
+        targetAgent: 'automation',
+        reason: 'Research suggests automation solution',
+        context: {
+          researchFindings: result.output,
+        },
+      };
+    }
+
+    return {
+      shouldHandoff: false,
+      reason: 'Research task complete',
+    };
+  }
+
+  // Additional research-specific methods
+  async summarize(content: string, maxLength: number = 500): Promise<TaskResult> {
+    return this.execute(
+      `Summarize the following content in ${maxLength} words or less:\n\n${content}`,
+      { task: 'summarization' }
+    );
+  }
+
+  async factCheck(claim: string): Promise<TaskResult> {
+    return this.execute(
+      `Fact-check the following claim and provide evidence:\n\n"${claim}"`,
+      { task: 'fact_checking' }
+    );
+  }
+
+  async compare(items: string[]): Promise<TaskResult> {
+    return this.execute(
+      `Compare and analyze the following items:\n\n${items.map((i, idx) => `${idx + 1}. ${i}`).join('\n')}`,
+      { task: 'comparison' }
+    );
+  }
+}
+
+export function createResearchAgent(tools: AgentConfig['tools'] = []): ResearchAgent {
+  return new ResearchAgent(tools);
+}
+
+export default ResearchAgent;

package/src/core/agents/types.ts

@@ -0,0 +1,124 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { StructuredTool } from '@langchain/core/tools';
+
+export type AgentRole = 'supervisor' | 'research' | 'coding' | 'automation' | 'chat';
+
+export type AgentStatus = 'idle' | 'thinking' | 'executing' | 'waiting' | 'completed' | 'error';
+
+export interface AgentIdentity {
+  id: string;
+  name: string;
+  role: AgentRole;
+  description: string;
+  capabilities: string[];
+}
+
+export interface AgentConfig {
+  identity: AgentIdentity;
+  model: string;
+  temperature?: number;
+  maxTokens?: number;
+  systemPrompt: string;
+  tools: StructuredTool[];
+  maxIterations?: number;
+  timeout?: number;
+}
+
+export interface AgentState {
+  messages: BaseMessage[];
+  currentTask?: TaskDefinition;
+  activeAgents: AgentIdentity[];
+  sharedContext: Record<string, unknown>;
+  taskResults: TaskResult[];
+  nextAgent: string | null;
+  memories: RetrievedMemory[];
+  iterationCount: number;
+  status: AgentStatus;
+}
+
+export interface TaskDefinition {
+  id: string;
+  type: 'research' | 'coding' | 'automation' | 'chat' | 'complex';
+  description: string;
+  input: string;
+  priority: 'low' | 'normal' | 'high' | 'critical';
+  requiredCapabilities: string[];
+  context?: Record<string, unknown>;
+  parentTaskId?: string;
+  subtasks?: TaskDefinition[];
+  deadline?: Date;
+}
+
+export interface TaskResult {
+  taskId: string;
+  agentId: string;
+  status: 'success' | 'partial' | 'failed';
+  output: unknown;
+  error?: string;
+  executionTimeMs: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RetrievedMemory {
+  id: string;
+  type: 'semantic' | 'episodic' | 'procedural';
+  content: string;
+  relevanceScore: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentMessage {
+  id: string;
+  timestamp: Date;
+  sender: AgentIdentity;
+  recipient: AgentIdentity | 'supervisor' | 'broadcast';
+  type: 'request' | 'response' | 'handoff' | 'status' | 'error';
+  payload: {
+    task?: TaskDefinition;
+    result?: TaskResult;
+    context?: Record<string, unknown>;
+    reason?: string;
+  };
+  metadata: {
+    priority: 'low' | 'normal' | 'high' | 'critical';
+    threadId: string;
+    parentMessageId?: string;
+  };
+}
+
+export interface HandoffDecision {
+  shouldHandoff: boolean;
+  targetAgent?: AgentRole;
+  reason: string;
+  context?: Record<string, unknown>;
+}
+
+export interface RoutingDecision {
+  selectedAgents: AgentRole[];
+  executionMode: 'single' | 'sequential' | 'parallel';
+  reasoning: string;
+}
+
+// Tool result types
+export interface ToolResult {
+  success: boolean;
+  output: unknown;
+  error?: string;
+}
+
+// Agent events for logging/monitoring
+export type AgentEventType =
+  | 'started'
+  | 'thinking'
+  | 'tool_call'
+  | 'tool_result'
+  | 'handoff'
+  | 'completed'
+  | 'error';
+
+export interface AgentEvent {
+  type: AgentEventType;
+  agentId: string;
+  timestamp: Date;
+  data: Record<string, unknown>;
+}

package/src/core/orchestrator/graph.ts

@@ -0,0 +1,305 @@
+import { StateGraph, Annotation, END, START } from '@langchain/langgraph';
+import { BaseMessage, HumanMessage, AIMessage, SystemMessage } from '@langchain/core/messages';
+import { nanoid } from 'nanoid';
+
+import { getAgentFactory } from '../agents/agent-factory.js';
+import type {
+  AgentRole,
+  AgentState,
+  TaskDefinition,
+  TaskResult,
+  RetrievedMemory,
+  AgentIdentity,
+} from '../agents/types.js';
+import { createLogger } from '../../utils/logger.js';
+
+const logger = createLogger('OrchestratorGraph');
+
+// Define the state annotation for LangGraph
+export const AgentStateAnnotation = Annotation.Root({
+  // Messages in the conversation
+  messages: Annotation<BaseMessage[]>({
+    reducer: (prev, next) => [...prev, ...next],
+    default: () => [],
+  }),
+
+  // Current user input
+  input: Annotation<string>({
+    reducer: (_, next) => next,
+    default: () => '',
+  }),
+
+  // Current task being processed
+  currentTask: Annotation<TaskDefinition | null>({
+    reducer: (_, next) => next,
+    default: () => null,
+  }),
+
+  // Active agents in this workflow
+  activeAgents: Annotation<AgentIdentity[]>({
+    reducer: (prev, next) => {
+      // Merge unique agents
+      const existing = new Set(prev.map((a) => a.id));
+      return [...prev, ...next.filter((a) => !existing.has(a.id))];
+    },
+    default: () => [],
+  }),
+
+  // Shared context for multi-agent coordination
+  sharedContext: Annotation<Record<string, unknown>>({
+    reducer: (prev, next) => ({ ...prev, ...next }),
+    default: () => ({}),
+  }),
+
+  // Results from completed tasks
+  taskResults: Annotation<TaskResult[]>({
+    reducer: (prev, next) => [...prev, ...next],
+    default: () => [],
+  }),
+
+  // Retrieved memories for context
+  memories: Annotation<RetrievedMemory[]>({
+    reducer: (_, next) => next,
+    default: () => [],
+  }),
+
+  // Next agent to route to
+  nextAgent: Annotation<AgentRole | 'end' | null>({
+    reducer: (_, next) => next,
+    default: () => null,
+  }),
+
+  // Final response to user
+  response: Annotation<string>({
+    reducer: (_, next) => next,
+    default: () => '',
+  }),
+
+  // Error state
+  error: Annotation<string | null>({
+    reducer: (_, next) => next,
+    default: () => null,
+  }),
+});
+
+export type GraphState = typeof AgentStateAnnotation.State;
+
+// Supervisor node - analyzes and routes tasks
+async function supervisorNode(state: GraphState): Promise<Partial<GraphState>> {
+  logger.debug('Supervisor analyzing task', { input: state.input?.slice(0, 100) });
+
+  const input = state.input.toLowerCase();
+
+  // Simple routing logic based on keywords
+  let nextAgent: AgentRole = 'chat';
+
+  // Research patterns
+  if (
+    input.includes('search') ||
+    input.includes('find') ||
+    input.includes('research') ||
+    input.includes('look up') ||
+    input.includes('what is') ||
+    input.includes('who is') ||
+    input.includes('investigate')
+  ) {
+    nextAgent = 'research';
+  }
+  // Coding patterns
+  else if (
+    input.includes('code') ||
+    input.includes('program') ||
+    input.includes('function') ||
+    input.includes('debug') ||
+    input.includes('fix bug') ||
+    input.includes('implement') ||
+    input.includes('write a script') ||
+    input.includes('refactor')
+  ) {
+    nextAgent = 'coding';
+  }
+  // Automation patterns
+  else if (
+    input.includes('automate') ||
+    input.includes('schedule') ||
+    input.includes('every day') ||
+    input.includes('every hour') ||
+    input.includes('batch') ||
+    input.includes('workflow') ||
+    input.includes('recurring')
+  ) {
+    nextAgent = 'automation';
+  }
+
+  const task: TaskDefinition = {
+    id: nanoid(),
+    type: nextAgent === 'chat' ? 'chat' : nextAgent === 'coding' ? 'coding' : nextAgent === 'research' ? 'research' : 'automation',
+    description: state.input,
+    input: state.input,
+    priority: 'normal',
+    requiredCapabilities: [],
+  };
+
+  logger.info('Task routed', { taskId: task.id, targetAgent: nextAgent });
+
+  return {
+    currentTask: task,
+    nextAgent,
+    sharedContext: {
+      routedAt: new Date().toISOString(),
+      routingReason: `Routed to ${nextAgent} based on input analysis`,
+    },
+  };
+}
+
+// Generic agent execution node
+async function agentNode(
+  role: AgentRole
+): Promise<(state: GraphState) => Promise<Partial<GraphState>>> {
+  return async (state: GraphState): Promise<Partial<GraphState>> => {
+    logger.debug(`${role} agent executing`, { taskId: state.currentTask?.id });
+
+    const factory = getAgentFactory();
+    const agent = factory.getAgent(role);
+
+    try {
+      const result = await agent.execute(
+        state.input,
+        state.sharedContext,
+        state.memories
+      );
+
+      const aiMessage = new AIMessage({
+        content: String(result.output),
+        name: agent.name,
+      });
+
+      return {
+        messages: [aiMessage],
+        taskResults: [result],
+        response: String(result.output),
+        activeAgents: [agent.getInfo()],
+        nextAgent: 'end',
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      logger.error(`${role} agent failed`, { error: errorMessage });
+
+      return {
+        error: errorMessage,
+        response: `Sorry, I encountered an error: ${errorMessage}`,
+        nextAgent: 'end',
+      };
+    } finally {
+      factory.releaseAgent(agent.id);
+    }
+  };
+}
+
+// Create agent nodes
+const chatAgentNode = await agentNode('chat');
+const researchAgentNode = await agentNode('research');
+const codingAgentNode = await agentNode('coding');
+const automationAgentNode = await agentNode('automation');
+
+// Routing function
+function routeToAgent(state: GraphState): AgentRole | 'end' {
+  if (state.error) {
+    return 'end';
+  }
+  return state.nextAgent ?? 'chat';
+}
+
+// Build the graph
+export function createOrchestratorGraph() {
+  const workflow = new StateGraph(AgentStateAnnotation)
+    // Add nodes
+    .addNode('supervisor', supervisorNode)
+    .addNode('chat', chatAgentNode)
+    .addNode('research', researchAgentNode)
+    .addNode('coding', codingAgentNode)
+    .addNode('automation', automationAgentNode)
+
+    // Entry point
+    .addEdge(START, 'supervisor')
+
+    // Conditional routing from supervisor
+    .addConditionalEdges('supervisor', routeToAgent, {
+      chat: 'chat',
+      research: 'research',
+      coding: 'coding',
+      automation: 'automation',
+      end: END,
+    })
+
+    // All agents go to END after execution
+    .addEdge('chat', END)
+    .addEdge('research', END)
+    .addEdge('coding', END)
+    .addEdge('automation', END);
+
+  return workflow.compile();
+}
+
+// Singleton graph instance
+let graphInstance: ReturnType<typeof createOrchestratorGraph> | null = null;
+
+export function getOrchestratorGraph() {
+  if (!graphInstance) {
+    graphInstance = createOrchestratorGraph();
+  }
+  return graphInstance;
+}
+
+// Helper function to run the orchestrator
+export async function runOrchestrator(
+  input: string,
+  context: Record<string, unknown> = {},
+  memories: RetrievedMemory[] = []
+): Promise<GraphState> {
+  const graph = getOrchestratorGraph();
+
+  const initialState: Partial<GraphState> = {
+    input,
+    messages: [new HumanMessage(input)],
+    sharedContext: context,
+    memories,
+  };
+
+  logger.info('Orchestrator started', { input: input.slice(0, 100) });
+
+  const result = await graph.invoke(initialState);
+
+  logger.info('Orchestrator completed', {
+    response: result.response?.slice(0, 100),
+    agentsUsed: result.activeAgents?.map((a) => a.name),
+  });
+
+  return result as GraphState;
+}
+
+// Stream execution
+export async function* streamOrchestrator(
+  input: string,
+  context: Record<string, unknown> = {},
+  memories: RetrievedMemory[] = []
+): AsyncGenerator<{ node: string; state: Partial<GraphState> }, void, unknown> {
+  const graph = getOrchestratorGraph();
+
+  const initialState: Partial<GraphState> = {
+    input,
+    messages: [new HumanMessage(input)],
+    sharedContext: context,
+    memories,
+  };
+
+  const stream = await graph.stream(initialState);
+
+  for await (const chunk of stream) {
+    for (const [node, state] of Object.entries(chunk)) {
+      yield { node, state: state as Partial<GraphState> };
+    }
+  }
+}
+
+export default { createOrchestratorGraph, getOrchestratorGraph, runOrchestrator, streamOrchestrator };

package/src/database/client.ts

@@ -0,0 +1,109 @@
+import pg from 'pg';
+import { getDatabaseUrl } from '../config/index.js';
+import { createLogger } from '../utils/logger.js';
+import { MemoryError } from '../utils/errors.js';
+
+const { Pool } = pg;
+const logger = createLogger('Database');
+
+let pool: pg.Pool | null = null;
+
+export function getPool(): pg.Pool {
+  if (!pool) {
+    pool = new Pool({
+      connectionString: getDatabaseUrl(),
+      max: 20,
+      idleTimeoutMillis: 30000,
+      connectionTimeoutMillis: 5000,
+    });
+
+    pool.on('error', (err) => {
+      logger.error('Unexpected pool error', { error: err.message });
+    });
+
+    pool.on('connect', () => {
+      logger.debug('New client connected to pool');
+    });
+  }
+
+  return pool;
+}
+
+export async function query<T extends pg.QueryResultRow = pg.QueryResultRow>(
+  text: string,
+  params?: unknown[]
+): Promise<pg.QueryResult<T>> {
+  const pool = getPool();
+  const start = Date.now();
+
+  try {
+    const result = await pool.query<T>(text, params);
+    const duration = Date.now() - start;
+    logger.debug('Query executed', { duration, rows: result.rowCount });
+    return result;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    logger.error('Query failed', { error: errorMessage, query: text.slice(0, 100) });
+    throw new MemoryError(`Database query failed: ${errorMessage}`);
+  }
+}
+
+export async function getClient(): Promise<pg.PoolClient> {
+  const pool = getPool();
+  return pool.connect();
+}
+
+export async function transaction<T>(
+  callback: (client: pg.PoolClient) => Promise<T>
+): Promise<T> {
+  const client = await getClient();
+
+  try {
+    await client.query('BEGIN');
+    const result = await callback(client);
+    await client.query('COMMIT');
+    return result;
+  } catch (error) {
+    await client.query('ROLLBACK');
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+export async function healthCheck(): Promise<boolean> {
+  try {
+    const result = await query('SELECT 1 as health');
+    return result.rows.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export async function closePool(): Promise<void> {
+  if (pool) {
+    await pool.end();
+    pool = null;
+    logger.info('Database pool closed');
+  }
+}
+
+// Initialize the database connection
+export async function initDatabase(): Promise<void> {
+  const healthy = await healthCheck();
+  if (healthy) {
+    logger.info('Database connection established');
+  } else {
+    throw new MemoryError('Failed to connect to database');
+  }
+}
+
+export default {
+  getPool,
+  query,
+  getClient,
+  transaction,
+  healthCheck,
+  closePool,
+  initDatabase,
+};