@game_ryo/lsji 0.1.0 → 0.3.0

package/src/llm/providers/openai.js

@@ -0,0 +1,212 @@
+/**
+ * OpenAI Provider Implementation
+ * 
+ * Supports OpenAI API (GPT-4, GPT-3.5, etc.)
+ * Compatible with OpenAI-compatible endpoints (e.g., Azure, local proxies)
+ */
+
+import { LLMProvider } from './base.js';
+
+// OpenAI pricing (USD per 1M tokens) - as of 2026
+const PRICING = {
+  'gpt-4o': { input: 5.00, output: 15.00 },
+  'gpt-4o-mini': { input: 0.15, output: 0.60 },
+  'gpt-4-turbo': { input: 10.00, output: 30.00 },
+  'gpt-4': { input: 30.00, output: 60.00 },
+  'gpt-3.5-turbo': { input: 0.50, output: 1.50 },
+  'o1-preview': { input: 15.00, output: 60.00 },
+  'o1-mini': { input: 3.00, output: 12.00 },
+};
+
+export class OpenAIProvider extends LLMProvider {
+  constructor(config = {}) {
+    super({
+      model: config.model || 'gpt-4o-mini',
+      apiKey: config.apiKey || process.env.OPENAI_API_KEY,
+      baseUrl: config.baseUrl || 'https://api.openai.com/v1',
+      defaultParams: config.defaultParams || {},
+    });
+    
+    this.pricing = PRICING[this.model] || PRICING['gpt-4o-mini'];
+    this.client = null;
+  }
+
+  /**
+   * Lazy-load OpenAI client
+   */
+  async getClient() {
+    if (!this.client) {
+      const { default: OpenAI } = await import('openai');
+      this.client = new OpenAI({
+        apiKey: this.apiKey,
+        baseURL: this.baseUrl,
+      });
+    }
+    return this.client;
+  }
+
+  /**
+   * Generate completion from OpenAI
+   */
+  async generate(messages, options = {}) {
+    const client = await this.getClient();
+    
+    const params = {
+      model: this.model,
+      messages: this.formatMessages(messages),
+      temperature: options.temperature ?? this.defaultParams.temperature ?? 0.7,
+      max_tokens: options.maxTokens ?? this.defaultParams.maxTokens ?? 4096,
+      ...this.defaultParams,
+    };
+
+    if (options.tools && options.tools.length > 0) {
+      params.tools = this.formatTools(options.tools);
+      params.tool_choice = options.toolChoice || 'auto';
+    }
+
+    const response = await client.chat.completions.create(params);
+    
+    return this.parseResponse(response);
+  }
+
+  /**
+   * Generate streaming completion
+   */
+  async *generateStream(messages, options = {}) {
+    const client = await this.getClient();
+    
+    const params = {
+      model: this.model,
+      messages: this.formatMessages(messages),
+      temperature: options.temperature ?? this.defaultParams.temperature ?? 0.7,
+      max_tokens: options.maxTokens ?? this.defaultParams.maxTokens ?? 4096,
+      stream: true,
+      ...this.defaultParams,
+    };
+
+    if (options.tools && options.tools.length > 0) {
+      params.tools = this.formatTools(options.tools);
+      params.tool_choice = options.toolChoice || 'auto';
+    }
+
+    const stream = await client.chat.completions.create(params);
+    
+    for await (const chunk of stream) {
+      yield this.parseStreamChunk(chunk);
+    }
+  }
+
+  /**
+   * Format messages for OpenAI API
+   */
+  formatMessages(messages) {
+    return messages.map(msg => ({
+      role: msg.role,
+      content: msg.content,
+      name: msg.name,
+      tool_call_id: msg.tool_call_id,
+      tool_calls: msg.tool_calls,
+    }));
+  }
+
+  /**
+   * Format tools for OpenAI API
+   */
+  formatTools(tools) {
+    return tools.map(tool => ({
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+      },
+    }));
+  }
+
+  /**
+   * Parse OpenAI response
+   */
+  parseResponse(response) {
+    const choice = response.choices[0];
+    const message = choice.message;
+    
+    return {
+      content: message.content || '',
+      toolCalls: message.tool_calls || [],
+      usage: {
+        inputTokens: response.usage?.prompt_tokens || 0,
+        outputTokens: response.usage?.completion_tokens || 0,
+        totalTokens: response.usage?.total_tokens || 0,
+      },
+      finishReason: choice.finish_reason,
+      model: response.model,
+    };
+  }
+
+  /**
+   * Parse streaming chunk
+   */
+  parseStreamChunk(chunk) {
+    const choice = chunk.choices[0];
+    const delta = choice.delta;
+    
+    return {
+      content: delta.content || '',
+      toolCalls: delta.tool_calls || [],
+      usage: chunk.usage ? {
+        inputTokens: chunk.usage.prompt_tokens || 0,
+        outputTokens: chunk.usage.completion_tokens || 0,
+        totalTokens: chunk.usage.total_tokens || 0,
+      } : null,
+      finishReason: choice.finish_reason,
+    };
+  }
+
+  /**
+   * Calculate cost for usage
+   */
+  calculateCost(usage) {
+    const inputCost = (usage.inputTokens / 1_000_000) * this.pricing.input;
+    const outputCost = (usage.outputTokens / 1_000_000) * this.pricing.output;
+    return inputCost + outputCost;
+  }
+
+  /**
+   * Get pricing info for current model
+   */
+  getPricing() {
+    return { ...this.pricing };
+  }
+
+  /**
+   * Check if provider supports function calling
+   */
+  supportsTools() {
+    // Most OpenAI models support function calling
+    return !this.model.includes('o1-mini') && !this.model.includes('o1-preview');
+  }
+
+  /**
+   * Check if provider supports streaming
+   */
+  supportsStreaming() {
+    return true;
+  }
+
+  /**
+   * Validate configuration
+   */
+  async validate() {
+    if (!this.apiKey) {
+      return { valid: false, error: 'OpenAI API key is required' };
+    }
+    
+    try {
+      const client = await this.getClient();
+      await client.models.list();
+      return { valid: true };
+    } catch (e) {
+      return { valid: false, error: e.message };
+    }
+  }
+}

package/src/llm/tools/registry.js

@@ -0,0 +1,342 @@
+/**
+ * Tool Registry
+ * 
+ * Manages tool/function definitions for LLM agents.
+ * Provides registration, lookup, and execution with idempotency.
+ */
+
+import { IdempotencyStore } from '../../execution/idempotency.js';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * Tool definition
+ * @typedef {Object} ToolDefinition
+ * @property {string} name - Unique tool name
+ * @property {string} description - Human-readable description
+ * @property {Object} parameters - JSON Schema for parameters
+ * @property {Function} execute - Async function(params, context) -> result
+ * @property {boolean} [requiresApproval] - Whether HITL approval needed
+ * @property {boolean} [idempotent] - Whether to use idempotency
+ */
+
+/**
+ * Tool Registry - Manages available tools
+ */
+export class ToolRegistry {
+  constructor({ idempotencyStore, approvalGate } = {}) {
+    this.tools = new Map();
+    this.idempotencyStore = idempotencyStore;
+    this.approvalGate = approvalGate;
+    this.categories = new Map();
+  }
+
+  /**
+   * Register a tool
+   */
+  register(definition) {
+    if (!definition.name) {
+      throw new Error('Tool must have a name');
+    }
+    if (!definition.execute || typeof definition.execute !== 'function') {
+      throw new Error('Tool must have an execute function');
+    }
+    if (!definition.parameters) {
+      throw new Error('Tool must have parameters schema');
+    }
+    
+    this.tools.set(definition.name, definition);
+    
+    // Categorize
+    const category = definition.category || 'general';
+    if (!this.categories.has(category)) {
+      this.categories.set(category, []);
+    }
+    this.categories.get(category).push(definition.name);
+    
+    return this;
+  }
+
+  /**
+   * Register multiple tools
+   */
+  registerMany(definitions) {
+    for (const def of definitions) {
+      this.register(def);
+    }
+    return this;
+  }
+
+  /**
+   * Get a tool by name
+   */
+  get(name) {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Check if tool exists
+   */
+  has(name) {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Get all tools
+   */
+  getAll() {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Get tools by category
+   */
+  getByCategory(category) {
+    const names = this.categories.get(category) || [];
+    return names.map(n => this.tools.get(n)).filter(Boolean);
+  }
+
+  /**
+   * Get tool definitions for LLM (OpenAI/Anthropic format)
+   */
+  getDefinitions(category = null) {
+    const tools = category ? this.getByCategory(category) : this.getAll();
+    return tools.map(tool => ({
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+      },
+    }));
+  }
+
+  /**
+   * Execute a tool with idempotency and approval
+   */
+  async execute(name, params, context = {}) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new Error(`Tool not found: ${name}`);
+    }
+    
+    // Check approval requirement
+    if (tool.requiresApproval && this.approvalGate) {
+      const approval = await this.approvalGate.requestApproval({
+        action: name,
+        context: { params, ...context },
+        requester: context.requester || 'agent',
+      });
+      
+      if (approval.status !== 'approved') {
+        throw new Error(`Tool ${name} was ${approval.status}: ${approval.reason}`);
+      }
+    }
+    
+    // Execute with idempotency if enabled
+    if (tool.idempotent && this.idempotencyStore) {
+      const key = `${name}_${uuidv4()}`;
+      return this.idempotencyStore.execute(key, name, params, () => tool.execute(params, context));
+    }
+    
+    return tool.execute(params, context);
+  }
+
+  /**
+   * Execute multiple tools in parallel
+   */
+  async executeAll(calls, context = {}) {
+    return Promise.all(calls.map(({ name, params }) => this.execute(name, params, context)));
+  }
+}
+
+/**
+ * Create tool registry with built-in tools
+ */
+export function createToolRegistry(config = {}) {
+  const registry = new ToolRegistry(config);
+  
+  // Register built-in tools
+  registry.registerMany(getBuiltinTools(config));
+  
+  return registry;
+}
+
+/**
+ * Get built-in tool definitions
+ */
+function getBuiltinTools(config = {}) {
+  const tools = [];
+  
+  // Web search tool
+  tools.push({
+    name: 'web_search',
+    description: 'Search the web for current information',
+    category: 'research',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        maxResults: { type: 'number', description: 'Maximum results', default: 5 },
+      },
+      required: ['query'],
+    },
+    requiresApproval: false,
+    idempotent: true,
+    async execute({ query, maxResults = 5 }, context) {
+      // This would integrate with actual search API
+      return { query, results: [], note: 'Web search not configured' };
+    },
+  });
+  
+  // File read tool
+  tools.push({
+    name: 'file_read',
+    description: 'Read a file from the filesystem',
+    category: 'filesystem',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path' },
+        encoding: { type: 'string', description: 'Encoding', default: 'utf-8' },
+      },
+      required: ['path'],
+    },
+    requiresApproval: false,
+    idempotent: true,
+    async execute({ path, encoding = 'utf-8' }, context) {
+      const fs = await import('fs/promises');
+      return fs.readFile(path, encoding);
+    },
+  });
+  
+  // File write tool
+  tools.push({
+    name: 'file_write',
+    description: 'Write a file to the filesystem',
+    category: 'filesystem',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path' },
+        content: { type: 'string', description: 'File content' },
+        encoding: { type: 'string', description: 'Encoding', default: 'utf-8' },
+      },
+      required: ['path', 'content'],
+    },
+    requiresApproval: true, // Requires HITL approval
+    idempotent: true,
+    async execute({ path, content, encoding = 'utf-8' }, context) {
+      const fs = await import('fs/promises');
+      await fs.writeFile(path, content, encoding);
+      return { path, bytesWritten: Buffer.byteLength(content, encoding) };
+    },
+  });
+  
+  // Code execution tool
+  tools.push({
+    name: 'code_exec',
+    description: 'Execute code in a sandboxed environment',
+    category: 'code',
+    parameters: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', description: 'Code to execute' },
+        language: { type: 'string', description: 'Language', default: 'javascript' },
+        timeout: { type: 'number', description: 'Timeout in ms', default: 30000 },
+      },
+      required: ['code'],
+    },
+    requiresApproval: true, // Requires HITL approval
+    idempotent: false,
+    async execute({ code, language = 'javascript', timeout = 30000 }, context) {
+      // This would integrate with a sandbox like Pyodide, QuickJS, etc.
+      return { output: 'Code execution not configured', language };
+    },
+  });
+  
+  // API call tool
+  tools.push({
+    name: 'api_call',
+    description: 'Make an HTTP API call',
+    category: 'network',
+    parameters: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'API URL' },
+        method: { type: 'string', description: 'HTTP method', default: 'GET' },
+        headers: { type: 'object', description: 'Headers' },
+        body: { type: 'object', description: 'Request body' },
+        timeout: { type: 'number', description: 'Timeout in ms', default: 30000 },
+      },
+      required: ['url'],
+    },
+    requiresApproval: true, // Requires HITL approval
+    idempotent: true,
+    async execute({ url, method = 'GET', headers = {}, body, timeout = 30000 }, context) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+      
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: { 'Content-Type': 'application/json', ...headers },
+          body: body ? JSON.stringify(body) : undefined,
+          signal: controller.signal,
+        });
+        
+        clearTimeout(timeoutId);
+        const data = await response.json();
+        return { status: response.status, data };
+      } catch (error) {
+        clearTimeout(timeoutId);
+        throw error;
+      }
+    },
+  });
+  
+  // Email send tool
+  tools.push({
+    name: 'send_email',
+    description: 'Send an email',
+    category: 'communication',
+    parameters: {
+      type: 'object',
+      properties: {
+        to: { type: 'string', description: 'Recipient email' },
+        subject: { type: 'string', description: 'Email subject' },
+        body: { type: 'string', description: 'Email body' },
+        html: { type: 'string', description: 'HTML body' },
+      },
+      required: ['to', 'subject', 'body'],
+    },
+    requiresApproval: true, // Requires HITL approval
+    idempotent: true,
+    async execute({ to, subject, body, html }, context) {
+      // This would integrate with actual email service
+      return { to, subject, sent: false, note: 'Email service not configured' };
+    },
+  });
+  
+  // Database query tool
+  tools.push({
+    name: 'db_query',
+    description: 'Execute a database query',
+    category: 'data',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'SQL query' },
+        params: { type: 'array', description: 'Query parameters' },
+      },
+      required: ['query'],
+    },
+    requiresApproval: true, // Requires HITL approval
+    idempotent: false,
+    async execute({ query, params = [] }, context) {
+      // This would use the existing storage
+      return { query, results: [], note: 'DB query not configured' };
+    },
+  });
+  
+  return tools;
+}