@game_ryo/lsji 0.1.0 → 0.3.0

package/src/llm/llm-agent.js

@@ -0,0 +1,357 @@
+/**
+ * LLM Agent
+ * 
+ * Production-grade LLM-based agent with ReAct pattern, tools, memory,
+ * HITL approval, budget control, and durability.
+ */
+
+import { createProvider } from './providers/base.js';
+import { createToolRegistry } from './tools/registry.js';
+import { createConversationMemory } from './memory/conversation.js';
+import { createSemanticMemory } from './memory/semantic.js';
+import { createEpisodicMemory } from './memory/episodic.js';
+import { createPromptManager } from './prompt-manager.js';
+import { createExecutionEngine } from '../execution/engine.js';
+import { createApprovalGate } from '../execution/hitl/approval-gate.js';
+import { createBudgetController } from '../execution/budget/index.js';
+import { IdempotencyStore } from '../execution/idempotency.js';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * LLM Agent Configuration
+ * @typedef {Object} LLMAgentConfig
+ * @property {Object} llm - LLM provider config { provider, model, apiKey, ... }
+ * @property {Object} [tools] - Tool registry config
+ * @property {Object} [memory] - Memory config { conversation, semantic, episodic }
+ * @property {Object} [execution] - Execution engine config
+ * @property {Object} [hitl] - HITL approval config
+ * @property {Object} [budget] - Budget control config
+ * @property {Object} [idempotency] - Idempotency config
+ */
+
+/**
+ * LLM Agent - Main agent class
+ */
+export class LLMAgent {
+  constructor(config = {}) {
+    this.config = config;
+    this.llm = null;
+    this.tools = null;
+    this.memory = {};
+    this.execution = null;
+    this.hitl = null;
+    this.budget = null;
+    this.idempotency = null;
+    this.promptManager = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize all components
+   */
+  async initialize() {
+    if (this.initialized) return;
+    
+    // Initialize LLM provider
+    this.llm = await createProvider(this.config.llm || { provider: 'openai', model: 'gpt-4o-mini' });
+    
+    // Validate LLM
+    const valid = await this.llm.validate();
+    if (!valid.valid) {
+      throw new Error(`LLM validation failed: ${valid.error}`);
+    }
+    
+    // Initialize tool registry
+    this.tools = createToolRegistry({
+      idempotencyStore: this.idempotency,
+      approvalGate: this.hitl,
+    });
+    
+    // Initialize memory systems
+    if (this.config.memory?.conversation !== false) {
+      this.memory.conversation = await createConversationMemory(this.config.memory?.conversation);
+      await this.memory.conversation.startSession(this.config.sessionId);
+    }
+    
+    if (this.config.memory?.semantic) {
+      this.memory.semantic = await createSemanticMemory(this.config.memory.semantic);
+    }
+    
+    if (this.config.memory?.episodic) {
+      this.memory.episodic = await createEpisodicMemory(this.config.memory.episodic);
+    }
+    
+    // Initialize execution engine
+    this.execution = await createExecutionEngine(this.config.execution);
+    
+    // Initialize HITL
+    if (this.config.hitl?.enabled !== false) {
+      this.hitl = await createApprovalGate(this.config.hitl);
+      // Update tool registry with HITL
+      this.tools.approvalGate = this.hitl;
+    }
+    
+    // Initialize budget
+    this.budget = createBudgetController(this.config.budget);
+    
+    // Initialize idempotency
+    this.idempotency = await IdempotencyStore.create(this.config.idempotency);
+    this.tools.idempotencyStore = this.idempotency;
+    
+    // Initialize prompt manager
+    this.promptManager = await createPromptManager(this.config.prompts);
+    
+    this.initialized = true;
+  }
+
+  /**
+   * Run the agent on a task
+   */
+  async run(task, options = {}) {
+    await this.initialize();
+    
+    const runId = options.runId || `run_${Date.now()}_${uuidv4().slice(0, 8)}`;
+    const budgetId = options.budgetId || runId;
+    const checkpointId = options.checkpointId;
+    const hitlRequired = options.hitlRequired || [];
+    const maxSteps = options.maxSteps || 50;
+    
+    // Start episodic memory
+    let episodeId = null;
+    if (this.memory.episodic) {
+      episodeId = await this.memory.episodic.startEpisode(task, { runId, options });
+    }
+    
+    // Get system prompt
+    const systemPrompt = await this.promptManager.render('system:react', {
+      tools: JSON.stringify(this.tools.getDefinitions(), null, 2),
+      task,
+    });
+    
+    // Build initial messages
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: task },
+    ];
+    
+    // Add conversation history if available
+    if (this.memory.conversation) {
+      const history = await this.memory.conversation.getMessagesForLLM(50000);
+      messages.splice(1, 0, ...history);
+    }
+    
+    let step = 0;
+    let finalAnswer = null;
+    
+    try {
+      while (step < maxSteps) {
+        step++;
+        
+        // Check budget before each step
+        const budgetCheck = await this.budget.checkBudget(budgetId, 0, 0);
+        if (!budgetCheck.allowed) {
+          throw new Error(`Budget exceeded: ${budgetCheck.errors.map(e => e.type).join(', ')}`);
+        }
+        
+        // Generate response
+        const response = await this.llm.generate(messages, {
+          tools: this.tools.getDefinitions(),
+          toolChoice: 'auto',
+          temperature: 0.7,
+          maxTokens: 4096,
+        });
+        
+        // Record token usage
+        if (this.memory.episodic) {
+          this.memory.episodic.recordTokens(response.usage?.totalTokens || 0);
+        }
+        this.budget.recordCost({
+          budgetId,
+          ...response.usage,
+          model: this.llm.getModel(),
+          provider: this.config.llm?.provider || 'openai',
+          cost: this.llm.calculateCost?.(response.usage) || 0,
+        });
+        
+        // Add assistant message
+        messages.push({
+          role: 'assistant',
+          content: response.content,
+          tool_calls: response.toolCalls,
+        });
+        
+        if (this.memory.conversation) {
+          await this.memory.conversation.addMessage(messages[messages.length - 1]);
+        }
+        
+        // Check for tool calls
+        if (response.toolCalls && response.toolCalls.length > 0) {
+          for (const toolCall of response.toolCalls) {
+            const toolName = toolCall.function.name;
+            const toolArgs = JSON.parse(toolCall.function.arguments);
+            
+            // Check if tool requires HITL
+            const tool = this.tools.get(toolName);
+            if (tool?.requiresApproval && hitlRequired.includes(toolName)) {
+              // Request approval
+              try {
+                await this.hitl.requestApproval({
+                  action: toolName,
+                  context: { params: toolArgs, runId },
+                  requester: 'agent',
+                });
+              } catch (error) {
+                // Approval denied or timeout
+                const errorMsg = `Tool ${toolName} requires approval: ${error.message}`;
+                messages.push({
+                  role: 'tool',
+                  tool_call_id: toolCall.id,
+                  content: errorMsg,
+                });
+                continue;
+              }
+            }
+            
+            // Execute tool
+            let result;
+            try {
+              result = await this.tools.execute(toolName, toolArgs, { runId, budgetId });
+            } catch (error) {
+              result = { error: error.message };
+            }
+            
+            // Record tool execution in episodic memory
+            if (this.memory.episodic) {
+              await this.memory.episodic.addStep({
+                type: 'tool',
+                tool: toolName,
+                params: toolArgs,
+                result,
+              });
+            }
+            
+            // Add tool result
+            messages.push({
+              role: 'tool',
+              tool_call_id: toolCall.id,
+              content: JSON.stringify(result),
+            });
+            
+            if (this.memory.conversation) {
+              await this.memory.conversation.addMessage(messages[messages.length - 1]);
+            }
+          }
+          
+          // Continue loop for next LLM call
+          continue;
+        }
+        
+        // No tool calls - check if final answer
+        if (response.content && !response.content.includes('THOUGHT:') && !response.content.includes('ACTION:')) {
+          finalAnswer = response.content;
+          break;
+        }
+        
+        // Parse ReAct format if present
+        if (response.content.includes('THOUGHT:') || response.content.includes('ACTION:')) {
+          // This is a ReAct formatted response without tool calls
+          // Continue to next iteration
+          continue;
+        }
+        
+        // Default: treat as final answer
+        finalAnswer = response.content;
+        break;
+      }
+      
+      // End episode
+      if (this.memory.episodic) {
+        await this.memory.episodic.endEpisode(finalAnswer ? 'success' : 'partial', { answer: finalAnswer, steps: step });
+      }
+      
+      return {
+        success: !!finalAnswer,
+        answer: finalAnswer,
+        runId,
+        steps: step,
+        budget: this.budget.getStatus(budgetId),
+      };
+      
+    } catch (error) {
+      if (this.memory.episodic) {
+        await this.memory.episodic.endEpisode('failure', { error: error.message, steps: step });
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Run with durability (checkpointing)
+   */
+  async runDurable(task, options = {}) {
+    await this.initialize();
+    
+    const workflowId = options.workflowId || `workflow_${Date.now()}`;
+    
+    return this.execution.execute({
+      id: workflowId,
+      name: task,
+      execute: async (context) => {
+        return this.run(task, { ...options, ...context });
+      },
+    }, {
+      workflowId,
+      checkpointEvery: options.checkpointEvery || 3,
+      idempotencyKey: options.idempotencyKey,
+      resumeFrom: options.resumeFrom,
+    });
+  }
+
+  /**
+   * Resume from checkpoint
+   */
+  async resume(checkpointId) {
+    await this.initialize();
+    return this.execution.execute({ id: 'resume', execute: async () => {} }, { resumeFrom: checkpointId });
+  }
+
+  /**
+   * Get agent status
+   */
+  getStatus() {
+    return {
+      initialized: this.initialized,
+      llm: this.llm?.getModel(),
+      tools: this.tools?.getAll().map(t => t.name) || [],
+      memory: {
+        conversation: this.memory.conversation?.getSummary(),
+        semantic: this.memory.semantic ? 'enabled' : 'disabled',
+        episodic: this.memory.episodic ? 'enabled' : 'disabled',
+      },
+      budget: this.budget?.getStatus(),
+      hitl: this.hitl ? 'enabled' : 'disabled',
+    };
+  }
+
+  /**
+   * Shutdown
+   */
+  async shutdown() {
+    if (this.memory.conversation) {
+      await this.memory.conversation.clear();
+    }
+    if (this.execution?.storage) {
+      await this.execution.storage.close();
+    }
+    this.initialized = false;
+  }
+}
+
+/**
+ * Create LLM agent from config
+ */
+export async function createLLMAgent(config = {}) {
+  const agent = new LLMAgent(config);
+  await agent.initialize();
+  return agent;
+}

package/src/llm/memory/conversation.js

@@ -0,0 +1,271 @@
+/**
+ * Conversation Memory
+ * 
+ * Manages conversation history for LLM agents.
+ * Supports token-aware truncation and persistence.
+ */
+
+import { createStorage } from '../../index.js';
+
+/**
+ * Conversation message
+ * @typedef {Object} Message
+ * @property {string} role - 'system' | 'user' | 'assistant' | 'tool'
+ * @property {string} content - Message content
+ * @property {string} [name] - Name for tool messages
+ * @property {string} [tool_call_id] - Tool call ID
+ * @property {Array} [tool_calls] - Tool calls from assistant
+ * @property {Date} [timestamp] - Message timestamp
+ */
+
+/**
+ * Conversation Memory - Stores and manages conversation history
+ */
+export class ConversationMemory {
+  constructor({ storage, maxTokens = 100000, tokenCounter } = {}) {
+    this.storage = storage;
+    this.maxTokens = maxTokens;
+    this.tokenCounter = tokenCounter;
+    this.messages = [];
+    this.sessionId = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize conversation table
+   */
+  async initialize() {
+    if (this.initialized) return;
+    
+    if (this.storage.db) {
+      await this.storage.db.exec(`
+        CREATE TABLE IF NOT EXISTS conversations (
+          id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          role TEXT NOT NULL,
+          content TEXT NOT NULL,
+          name TEXT,
+          tool_call_id TEXT,
+          tool_calls TEXT,
+          tokens INTEGER,
+          created_at TEXT NOT NULL
+        )
+      `);
+      
+      await this.storage.db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_conversations_session ON conversations(session_id)
+      `);
+      
+      await this.storage.db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_conversations_created ON conversations(created_at)
+      `);
+    }
+    
+    this.initialized = true;
+  }
+
+  /**
+   * Start a new conversation session
+   */
+  async startSession(sessionId = null) {
+    await this.initialize();
+    this.sessionId = sessionId || `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    this.messages = [];
+    
+    if (!sessionId) {
+      // Load existing if sessionId provided
+      await this.loadSession(this.sessionId);
+    }
+    
+    return this.sessionId;
+  }
+
+  /**
+   * Load conversation from storage
+   */
+  async loadSession(sessionId) {
+    await this.initialize();
+    
+    if (this.storage.db) {
+      const rows = await this.storage.db.all(
+        'SELECT * FROM conversations WHERE session_id = ? ORDER BY created_at ASC',
+        [sessionId]
+      );
+      
+      this.messages = rows.map(row => ({
+        role: row.role,
+        content: row.content,
+        name: row.name,
+        tool_call_id: row.tool_call_id,
+        tool_calls: row.tool_calls ? JSON.parse(row.tool_calls) : undefined,
+        timestamp: row.created_at,
+      }));
+    }
+    
+    return this.messages;
+  }
+
+  /**
+   * Add a message to conversation
+   */
+  async addMessage(message) {
+    await this.initialize();
+    
+    const msg = {
+      role: message.role,
+      content: message.content,
+      name: message.name,
+      tool_call_id: message.tool_call_id,
+      tool_calls: message.tool_calls,
+      timestamp: message.timestamp || new Date().toISOString(),
+    };
+    
+    this.messages.push(msg);
+    
+    // Persist to storage
+    if (this.storage.db && this.sessionId) {
+      const tokens = this.tokenCounter 
+        ? await this.tokenCounter.estimateTokens([msg], { provider: 'openai', model: 'gpt-4o-mini' })
+        : 0;
+      
+      await this.storage.db.run(
+        `INSERT INTO conversations (id, session_id, role, content, name, tool_call_id, tool_calls, tokens, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+          this.sessionId,
+          msg.role,
+          msg.content,
+          msg.name || null,
+          msg.tool_call_id || null,
+          msg.tool_calls ? JSON.stringify(msg.tool_calls) : null,
+          tokens,
+          msg.timestamp,
+        ]
+      );
+    }
+    
+    // Trim if needed
+    await this.trimIfNeeded();
+    
+    return msg;
+  }
+
+  /**
+   * Add multiple messages
+   */
+  async addMessages(messages) {
+    for (const msg of messages) {
+      await this.addMessage(msg);
+    }
+  }
+
+  /**
+   * Get all messages
+   */
+  getMessages() {
+    return [...this.messages];
+  }
+
+  /**
+   * Get messages for LLM (with token limit)
+   */
+  async getMessagesForLLM(maxTokens = null) {
+    const limit = maxTokens || this.maxTokens;
+    let totalTokens = 0;
+    const result = [];
+    
+    // Add messages from newest to oldest until token limit
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const msg = this.messages[i];
+      const msgTokens = this.tokenCounter
+        ? await this.tokenCounter.estimateTokens([msg], { provider: 'openai', model: 'gpt-4o-mini' })
+        : Math.ceil(msg.content.length / 4);
+      
+      if (totalTokens + msgTokens > limit && result.length > 0) {
+        break;
+      }
+      
+      totalTokens += msgTokens;
+      result.unshift(msg);
+    }
+    
+    return result;
+  }
+
+  /**
+   * Trim old messages if over token limit
+   */
+  async trimIfNeeded() {
+    if (!this.tokenCounter) return;
+    
+    const tokens = await this.tokenCounter.estimateTokens(
+      this.messages, 
+      { provider: 'openai', model: 'gpt-4o-mini' }
+    );
+    
+    if (tokens > this.maxTokens) {
+      // Remove oldest messages (but keep system message)
+      const systemMessages = this.messages.filter(m => m.role === 'system');
+      const otherMessages = this.messages.filter(m => m.role !== 'system');
+      
+      // Keep removing oldest non-system messages until under limit
+      while (otherMessages.length > 0) {
+        otherMessages.shift();
+        const remainingTokens = await this.tokenCounter.estimateTokens(
+          [...systemMessages, ...otherMessages],
+          { provider: 'openai', model: 'gpt-4o-mini' }
+        );
+        if (remainingTokens <= this.maxTokens) break;
+      }
+      
+      this.messages = [...systemMessages, ...otherMessages];
+    }
+  }
+
+  /**
+   * Clear conversation
+   */
+  async clear() {
+    this.messages = [];
+    
+    if (this.storage.db && this.sessionId) {
+      await this.storage.db.run(
+        'DELETE FROM conversations WHERE session_id = ?',
+        [this.sessionId]
+      );
+    }
+  }
+
+  /**
+   * Get conversation summary
+   */
+  getSummary() {
+    return {
+      sessionId: this.sessionId,
+      messageCount: this.messages.length,
+      roles: this.messages.reduce((acc, m) => {
+        acc[m.role] = (acc[m.role] || 0) + 1;
+        return acc;
+      }, {}),
+      firstMessage: this.messages[0]?.timestamp,
+      lastMessage: this.messages[this.messages.length - 1]?.timestamp,
+    };
+  }
+}
+
+/**
+ * Create conversation memory from config
+ */
+export async function createConversationMemory(config = {}) {
+  const storage = await createStorage(
+    config.storage?.type || 'sqlite',
+    config.storage?.options || {}
+  );
+  
+  return new ConversationMemory({
+    storage,
+    maxTokens: config.maxTokens || 100000,
+    tokenCounter: config.tokenCounter,
+  });
+}