@yamo/memory-mesh 2.3.1 → 3.0.0

package/lib/llm/client.ts

@@ -0,0 +1,413 @@
+/**
+ * LLM Client - Multi-provider LLM API client for reflection generation
+ *
+ * Supports:
+ * - OpenAI (GPT-4, GPT-4o-mini, etc.)
+ * - Anthropic (Claude)
+ * - Ollama (local models)
+ * - Graceful fallback when LLM unavailable
+ */
+
+import { createLogger } from "../utils/logger.js";
+
+const logger = createLogger("llm-client");
+
+export interface LLMConfig {
+  provider?: string;
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+  maxTokens?: number;
+}
+
+export interface ReflectionResult {
+  reflection: string;
+  confidence: number;
+}
+
+export interface LLMStats {
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  fallbackCount: number;
+}
+
+/**
+ * LLMClient provides unified interface for calling various LLM providers
+ * to generate reflections from memory contexts.
+ */
+export class LLMClient {
+  provider: string;
+  apiKey: string;
+  model: string;
+  baseUrl: string;
+  timeout: number;
+  maxRetries: number;
+  maxTokens: number;
+  stats: LLMStats;
+
+  /**
+   * Create a new LLMClient instance
+   */
+  constructor(config: LLMConfig = {}) {
+    this.provider = config.provider || process.env.LLM_PROVIDER || "openai";
+    this.apiKey = config.apiKey || process.env.LLM_API_KEY || "";
+    this.model =
+      config.model || process.env.LLM_MODEL || this._getDefaultModel();
+    this.baseUrl =
+      config.baseUrl || process.env.LLM_BASE_URL || this._getDefaultBaseUrl();
+    this.maxTokens = config.maxTokens || 2000;
+    this.timeout = config.timeout || (this.maxTokens >= 4000 ? 300000 : 60000);
+    this.maxRetries = config.maxRetries || 2;
+
+    // Statistics
+    this.stats = {
+      totalRequests: 0,
+      successfulRequests: 0,
+      failedRequests: 0,
+      fallbackCount: 0,
+    };
+  }
+
+  /**
+   * Get default model for provider
+   * @private
+   */
+  _getDefaultModel(): string {
+    const defaults: Record<string, string> = {
+      openai: "gpt-4o-mini",
+      anthropic: "claude-3-5-haiku-20241022",
+      ollama: "llama3.2",
+    };
+    return defaults[this.provider] || "gpt-4o-mini";
+  }
+
+  /**
+   * Get default base URL for provider
+   * @private
+   */
+  _getDefaultBaseUrl(): string {
+    const defaults: Record<string, string> = {
+      openai: "https://api.openai.com/v1",
+      anthropic: "https://api.anthropic.com/v1",
+      ollama: "http://localhost:11434",
+    };
+    return defaults[this.provider] || "https://api.openai.com/v1";
+  }
+
+  /**
+   * Generate reflection from memories
+   * Main entry point for reflection generation
+   */
+  async reflect(prompt: string, memories: any[]): Promise<ReflectionResult> {
+    this.stats.totalRequests++;
+
+    if (!memories || memories.length === 0) {
+      return this._fallback("No memories provided");
+    }
+
+    const systemPrompt = `You are a reflective AI agent. Review the provided memories and synthesize a high-level insight, belief, or observation.
+Respond ONLY in JSON format with exactly these keys:
+{
+  "reflection": "a concise insight or observation derived from the memories",
+  "confidence": 0.0 to 1.0
+}
+
+Keep the reflection brief (1-2 sentences) and actionable.`;
+
+    const userContent = this._formatMemoriesForLLM(prompt, memories);
+
+    try {
+      const response = await this._callWithRetry(systemPrompt, userContent);
+      const parsed = JSON.parse(response);
+
+      // Validate response structure
+      if (!parsed.reflection || typeof parsed.confidence !== "number") {
+        throw new Error("Invalid LLM response format");
+      }
+
+      // Clamp confidence to valid range
+      parsed.confidence = Math.max(0, Math.min(1, parsed.confidence));
+
+      this.stats.successfulRequests++;
+      return parsed as ReflectionResult;
+    } catch (error) {
+      this.stats.failedRequests++;
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logger.debug({ err: error, errorMessage }, "LLM call failed");
+      return this._fallback("LLM error", memories);
+    }
+  }
+
+  /**
+   * Format memories for LLM consumption
+   * @private
+   */
+  _formatMemoriesForLLM(prompt: string, memories: any[]): string {
+    const memoryList = memories
+      .map((m, i) => `${i + 1}. ${m.content}`)
+      .join("\n");
+
+    return `Prompt: ${prompt}\n\nMemories:\n${memoryList}\n\nBased on these memories, provide a brief reflective insight.`;
+  }
+
+  /**
+   * Call LLM with retry logic
+   * @private
+   */
+  async _callWithRetry(
+    systemPrompt: string,
+    userContent: string,
+  ): Promise<string> {
+    let lastError: any = null;
+
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await this._callLLM(systemPrompt, userContent);
+      } catch (error) {
+        lastError = error;
+        if (attempt < this.maxRetries) {
+          const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+          await this._sleep(delay);
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Call LLM based on provider
+   * @private
+   */
+  async _callLLM(systemPrompt: string, userContent: string): Promise<string> {
+    switch (this.provider) {
+      case "openai":
+        return this._callOpenAI(systemPrompt, userContent);
+      case "anthropic":
+        return this._callAnthropic(systemPrompt, userContent);
+      case "ollama":
+        return this._callOllama(systemPrompt, userContent);
+      default:
+        throw new Error(`Unsupported provider: ${this.provider}`);
+    }
+  }
+
+  /**
+   * Call OpenAI API
+   * @private
+   */
+  async _callOpenAI(
+    systemPrompt: string,
+    userContent: string,
+  ): Promise<string> {
+    if (!this.apiKey) {
+      throw new Error("OpenAI API key not configured");
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: this.model,
+          messages: [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userContent },
+          ],
+          temperature: 0.7,
+          max_tokens: this.maxTokens,
+        }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`OpenAI API error: ${response.status} - ${error}`);
+      }
+
+      const data = await response.json();
+      return data.choices[0].message.content;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error("Request timeout");
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Call Anthropic (Claude) API
+   * @private
+   */
+  async _callAnthropic(
+    systemPrompt: string,
+    userContent: string,
+  ): Promise<string> {
+    if (!this.apiKey) {
+      throw new Error("Anthropic API key not configured");
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}/messages`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({
+          model: this.model,
+          max_tokens: this.maxTokens,
+          system: systemPrompt,
+          messages: [{ role: "user", content: userContent }],
+        }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Anthropic API error: ${response.status} - ${error}`);
+      }
+
+      const data = await response.json();
+      return data.content[0].text;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error("Request timeout");
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Call Ollama (local) API
+   * @private
+   */
+  async _callOllama(
+    systemPrompt: string,
+    userContent: string,
+  ): Promise<string> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}/api/chat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model: this.model,
+          messages: [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userContent },
+          ],
+          stream: false,
+          options: {
+            num_predict: this.maxTokens,
+          },
+        }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Ollama API error: ${response.status} - ${error}`);
+      }
+
+      const data = await response.json();
+      return data.message.content;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error("Request timeout");
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Fallback when LLM fails
+   * @private
+   */
+  _fallback(reason: string, memories: any[] = []): ReflectionResult {
+    this.stats.fallbackCount++;
+
+    if (memories && memories.length > 0) {
+      // Simple aggregation fallback
+      const contents = memories.map((m) => m.content);
+      const combined = contents.join("; ");
+      const preview =
+        combined.length > 200 ? `${combined.substring(0, 200)}...` : combined;
+
+      return {
+        reflection: `Aggregated from ${memories.length} memories: ${preview}`,
+        confidence: 0.5,
+      };
+    }
+
+    return {
+      reflection: `Reflection generation unavailable: ${reason}`,
+      confidence: 0.3,
+    };
+  }
+
+  /**
+   * Sleep utility
+   * @private
+   */
+  _sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Get client statistics
+   * @returns {Object} Statistics
+   */
+  getStats(): any {
+    return {
+      ...this.stats,
+      successRate:
+        this.stats.totalRequests > 0
+          ? (this.stats.successfulRequests / this.stats.totalRequests).toFixed(
+              2,
+            )
+          : "0.00",
+    };
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void {
+    this.stats = {
+      totalRequests: 0,
+      successfulRequests: 0,
+      failedRequests: 0,
+      fallbackCount: 0,
+    };
+  }
+}
+
+export default LLMClient;

package/lib/llm/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * YAMO LLM Module
+ * Large Language Model client abstraction
+ */
+export { LLMClient } from "./client.js";
+/**
+ * Self-RefiningExtractor is now implemented as a YAMO skill.
+ * Use: skill-self-refining-extractor.yamo
+ *
+ * Example:
+ *   _kernel_execute({
+ *     skill: 'skill-self-refining-extractor.yamo',
+ *     skill_path: 'skills/skill-super.yamo',
+ *     max_iterations: 5
+ *   })
+ */
+export declare const SELF_REFINING_EXTRACTOR = "skill-self-refining-extractor.yamo";

package/lib/llm/index.js

@@ -1,10 +1,17 @@
 /**
- * LLM Module - LLM client support for yamo-memory-mesh
- * Exports multi-provider LLM client for reflection generation
+ * YAMO LLM Module
+ * Large Language Model client abstraction
  */
-
-export { LLMClient } from './client.js';
-
-export default {
-  LLMClient: (await import('./client.js')).LLMClient
-};
+export { LLMClient } from "./client.js";
+/**
+ * Self-RefiningExtractor is now implemented as a YAMO skill.
+ * Use: skill-self-refining-extractor.yamo
+ *
+ * Example:
+ *   _kernel_execute({
+ *     skill: 'skill-self-refining-extractor.yamo',
+ *     skill_path: 'skills/skill-super.yamo',
+ *     max_iterations: 5
+ *   })
+ */
+export const SELF_REFINING_EXTRACTOR = "skill-self-refining-extractor.yamo";

package/lib/llm/index.ts

@@ -0,0 +1,19 @@
+/**
+ * YAMO LLM Module
+ * Large Language Model client abstraction
+ */
+
+export { LLMClient } from "./client.js";
+
+/**
+ * Self-RefiningExtractor is now implemented as a YAMO skill.
+ * Use: skill-self-refining-extractor.yamo
+ *
+ * Example:
+ *   _kernel_execute({
+ *     skill: 'skill-self-refining-extractor.yamo',
+ *     skill_path: 'skills/skill-super.yamo',
+ *     max_iterations: 5
+ *   })
+ */
+export const SELF_REFINING_EXTRACTOR = "skill-self-refining-extractor.yamo";

package/lib/memory/adapters/client.d.ts

@@ -0,0 +1,183 @@
+/**
+ * LanceDB Client Wrapper
+ *
+ * A comprehensive wrapper around LanceDB JavaScript SDK providing:
+ * - Connection management with pooling and retries
+ * - CRUD operations for memory entries
+ * - Vector similarity search with filtering
+ * - Database statistics and monitoring
+ *
+ * @class LanceDBClient
+ */
+import * as lancedb from "@lancedb/lancedb";
+/**
+ * LanceDB driver interface for dependency injection/testing
+ */
+export interface LanceDBDriver {
+    connect(uri: string): Promise<lancedb.Connection>;
+}
+export interface ClientConfig {
+    uri?: string;
+    tableName?: string;
+    maxRetries?: number;
+    retryDelay?: number;
+    vectorDimension?: number;
+    driver?: LanceDBDriver;
+}
+export interface MemoryEntry {
+    id: string;
+    vector: number[];
+    content: string;
+    metadata?: string | Record<string, any> | null;
+    created_at?: Date | string;
+    updated_at?: Date | string;
+}
+export interface SearchResult extends MemoryEntry {
+    score?: number;
+}
+export interface SearchOptions {
+    limit?: number;
+    metric?: string;
+    nprobes?: number;
+    filter?: string | null;
+}
+export interface Stats {
+    tableName: string;
+    uri: string;
+    count: number;
+    isConnected: boolean;
+}
+/**
+ * LanceDB Client wrapper class
+ */
+export declare class LanceDBClient {
+    uri: string;
+    tableName: string;
+    maxRetries: number;
+    retryDelay: number;
+    vectorDimension: number;
+    driver: LanceDBDriver;
+    db: lancedb.Connection | null;
+    table: lancedb.Table | null;
+    isConnected: boolean;
+    private tempDir?;
+    /**
+     * Create a new LanceDBClient instance
+     * @param {Object} [config={}] - Configuration object
+     */
+    constructor(config?: ClientConfig);
+    /**
+     * Connect to LanceDB and initialize table
+     * Creates the database directory and table if they don't exist
+     * @returns {Promise<void>}
+     * @throws {StorageError} If connection fails after retries
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from LanceDB
+     * @returns {Promise<void>}
+     */
+    disconnect(): void;
+    /**
+     * Add a single memory entry
+     * @param {Object} data - Entry data
+     * @returns {Promise<Object>} Result with id and success status
+     * @throws {StorageError} If add operation fails
+     */
+    add(data: MemoryEntry): Promise<{
+        id: string;
+        success: boolean;
+    }>;
+    /**
+     * Add multiple memory entries in batch
+     * @param {Array<Object>} records - Array of entry data objects
+     * @returns {Promise<Object>} Result with count of added records
+     * @throws {StorageError} If batch add fails
+     */
+    addBatch(records: MemoryEntry[]): Promise<{
+        count: number;
+        success: boolean;
+    }>;
+    /**
+     * Search for similar vectors
+     * @param {Array<number>} vector - Query vector (384 dimensions)
+     * @param {Object} options - Search options
+     * @returns {Promise<Array<Object>>} Array of search results with scores
+     * @throws {QueryError} If search fails
+     */
+    search(vector: number[], options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Get a record by ID
+     * @param {string} id - Record ID
+     * @returns {Promise<Object|null>} Record object or null if not found
+     * @throws {QueryError} If query fails
+     */
+    getById(id: string): Promise<MemoryEntry | null>;
+    /**
+     * Get all records from the database
+     * @param {Object} options - Options
+     * @returns {Promise<Array<Object>>} Array of all records
+     */
+    getAll(options?: {
+        limit?: number;
+    }): Promise<MemoryEntry[]>;
+    /**
+     * Delete a record by ID
+     * @param {string} id - Record ID to delete
+     * @returns {Promise<Object>} Result with success status
+     * @throws {StorageError} If delete fails
+     */
+    delete(id: string): Promise<{
+        id: string;
+        success: boolean;
+    }>;
+    /**
+     * Update an existing record
+     * @param {string} id - Record ID to update
+     * @param {Object} data - Updated data fields
+     * @returns {Promise<Object>} Result with success status
+     * @throws {StorageError} If update fails
+     */
+    update(id: string, data: Partial<MemoryEntry>): Promise<{
+        id: string;
+        success: boolean;
+    }>;
+    /**
+     * Get database statistics
+     * @returns {Promise<Object>} Statistics including count, size, etc.
+     * @throws {QueryError} If stats query fails
+     */
+    getStats(): Promise<Stats>;
+    /**
+     * Sanitize an ID to prevent SQL injection
+     * Removes any characters that aren't alphanumeric, underscore, or hyphen
+     * @private
+     */
+    _sanitizeId(id: string): string;
+    /**
+     * Validate a record object
+     * @private
+     */
+    _validateRecord(record: any): void;
+    /**
+     * Validate a vector array
+     * @private
+     */
+    _validateVector(vector: any): void;
+    /**
+     * Sleep for a specified duration
+     * @private
+     */
+    _sleep(ms: number): Promise<void>;
+    /**
+     * Check if an error is retryable (transient network/connection issues)
+     * @private
+     */
+    _isRetryableError(error: any): boolean;
+    /**
+     * Retry an operation with exponential backoff
+     * @private
+     */
+    _retryOperation<T>(operation: () => Promise<T>, maxRetries?: number, baseDelay?: number): Promise<T>;
+}
+export default LanceDBClient;