@superatomai/sdk-node 0.0.61 → 0.0.63

package/dist/index.js

@@ -1963,6 +1963,7 @@ __export(index_exports, {
   llmUsageLogger: () => llmUsageLogger,
   logger: () => logger,
   openaiLLM: () => openaiLLM,
+  queryCache: () => queryCache,
   rerankChromaResults: () => rerankChromaResults,
   rerankConversationResults: () => rerankConversationResults,
   userPromptErrorLogger: () => userPromptErrorLogger
@@ -3174,7 +3175,136 @@ var ThreadManager = class _ThreadManager {
   }
 };
 
+// src/utils/query-cache.ts
+init_logger();
+var QueryCache = class {
+  constructor() {
+    this.cache = /* @__PURE__ */ new Map();
+    this.ttlMs = 5 * 60 * 1e3;
+    // Default: 5 minutes
+    this.cleanupInterval = null;
+    this.startCleanup();
+  }
+  /**
+   * Set the cache TTL (Time To Live)
+   * @param minutes - TTL in minutes (default: 5)
+   */
+  setTTL(minutes) {
+    this.ttlMs = minutes * 60 * 1e3;
+    logger.info(`[QueryCache] TTL set to ${minutes} minutes`);
+  }
+  /**
+   * Get the current TTL in minutes
+   */
+  getTTL() {
+    return this.ttlMs / 60 / 1e3;
+  }
+  /**
+   * Store query result in cache
+   * Key is the exact query string (or JSON for parameterized queries)
+   */
+  set(query, data) {
+    this.cache.set(query, {
+      query,
+      data,
+      timestamp: Date.now()
+    });
+    logger.debug(`[QueryCache] Stored result for query (${query.substring(0, 50)}...)`);
+  }
+  /**
+   * Get cached result if exists and not expired
+   */
+  get(query) {
+    const entry = this.cache.get(query);
+    if (!entry) {
+      return null;
+    }
+    if (Date.now() - entry.timestamp > this.ttlMs) {
+      this.cache.delete(query);
+      logger.debug(`[QueryCache] Entry expired for query (${query.substring(0, 50)}...)`);
+      return null;
+    }
+    logger.info(`[QueryCache] Cache HIT for query (${query.substring(0, 50)}...)`);
+    return entry.data;
+  }
+  /**
+   * Check if query exists in cache (not expired)
+   */
+  has(query) {
+    return this.get(query) !== null;
+  }
+  /**
+   * Remove a specific query from cache
+   */
+  delete(query) {
+    this.cache.delete(query);
+  }
+  /**
+   * Clear all cached entries
+   */
+  clear() {
+    this.cache.clear();
+    logger.info("[QueryCache] Cache cleared");
+  }
+  /**
+   * Get cache statistics
+   */
+  getStats() {
+    let oldestTimestamp = null;
+    for (const entry of this.cache.values()) {
+      if (oldestTimestamp === null || entry.timestamp < oldestTimestamp) {
+        oldestTimestamp = entry.timestamp;
+      }
+    }
+    return {
+      size: this.cache.size,
+      oldestEntryAge: oldestTimestamp ? Date.now() - oldestTimestamp : null
+    };
+  }
+  /**
+   * Start periodic cleanup of expired entries
+   */
+  startCleanup() {
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      let expiredCount = 0;
+      for (const [key, entry] of this.cache.entries()) {
+        if (now - entry.timestamp > this.ttlMs) {
+          this.cache.delete(key);
+          expiredCount++;
+        }
+      }
+      if (expiredCount > 0) {
+        logger.debug(`[QueryCache] Cleaned up ${expiredCount} expired entries`);
+      }
+    }, 2 * 60 * 1e3);
+  }
+  /**
+   * Stop cleanup interval (for graceful shutdown)
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.cache.clear();
+  }
+};
+var queryCache = new QueryCache();
+
 // src/handlers/data-request.ts
+function getQueryCacheKey(query) {
+  if (typeof query === "string") {
+    return query;
+  } else if (query?.sql) {
+    const values = query.values || query.params;
+    if (values && Object.keys(values).length > 0) {
+      return JSON.stringify({ sql: query.sql, values });
+    }
+    return query.sql;
+  }
+  return "";
+}
 async function handleDataRequest(data, collections, sendMessage) {
   try {
     const dataRequest = DataRequestMessageSchema.parse(data);
@@ -3193,10 +3323,37 @@ async function handleDataRequest(data, collections, sendMessage) {
       return;
     }
     const startTime = performance.now();
-    const handler = collections[collection][op];
-    const result = await handler(params || {});
+    let result;
+    let fromCache = false;
+    if (collection === "database" && op === "execute" && params?.sql) {
+      const cacheKey = getQueryCacheKey(params.sql);
+      if (cacheKey) {
+        const cachedResult = queryCache.get(cacheKey);
+        if (cachedResult !== null) {
+          result = cachedResult;
+          fromCache = true;
+          logger.info(`[QueryCache] Returning cached result for database.execute`);
+        }
+      }
+    }
+    if (!fromCache) {
+      const handler = collections[collection][op];
+      let handlerParams = params || {};
+      if (collection === "database" && op === "execute" && params?.sql && typeof params.sql !== "string") {
+        const cacheKey = getQueryCacheKey(params.sql);
+        handlerParams = { ...params, sql: cacheKey };
+        logger.debug(`[data-request] Converted object query to JSON string for database handler`);
+      }
+      result = await handler(handlerParams);
+      if (collection === "database" && op === "execute" && params?.sql && result) {
+        const cacheKey = getQueryCacheKey(params.sql);
+        if (cacheKey) {
+          queryCache.set(cacheKey, result);
+        }
+      }
+    }
     const executionMs = Math.round(performance.now() - startTime);
-    logger.info(`Executed ${collection}.${op} in ${executionMs}ms`);
+    logger.info(`Executed ${collection}.${op} in ${executionMs}ms${fromCache ? " (from cache)" : ""}`);
     if (SA_RUNTIME && typeof SA_RUNTIME === "object" && "uiBlockId" in SA_RUNTIME) {
       const uiBlockId = SA_RUNTIME.uiBlockId;
       const threadId = SA_RUNTIME.threadId;
@@ -6010,6 +6167,7 @@ var BaseLLM = class {
     this.defaultLimit = config?.defaultLimit || 50;
     this.apiKey = config?.apiKey;
     this.modelStrategy = config?.modelStrategy || "fast";
+    this.conversationSimilarityThreshold = config?.conversationSimilarityThreshold || 0.8;
   }
   /**
    * Get the appropriate model based on task type and model strategy
@@ -6042,6 +6200,26 @@ var BaseLLM = class {
   getModelStrategy() {
     return this.modelStrategy;
   }
+  /**
+   * Set the conversation similarity threshold at runtime
+   * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+   */
+  setConversationSimilarityThreshold(threshold) {
+    if (threshold < 0 || threshold > 1) {
+      logger.warn(`[${this.getProviderName()}] Invalid threshold ${threshold}, must be between 0 and 1. Using default 0.8`);
+      this.conversationSimilarityThreshold = 0.8;
+      return;
+    }
+    this.conversationSimilarityThreshold = threshold;
+    logger.info(`[${this.getProviderName()}] Conversation similarity threshold set to: ${threshold}`);
+  }
+  /**
+   * Get the current conversation similarity threshold
+   * @returns The current threshold value
+   */
+  getConversationSimilarityThreshold() {
+    return this.conversationSimilarityThreshold;
+  }
   /**
    * Get the API key (from instance, parameter, or environment)
    */
@@ -6068,6 +6246,96 @@ var BaseLLM = class {
     }
     return false;
   }
+  /**
+   * Get the cache key for a query (the exact sql param that would be sent to execute)
+   * This ensures the cache key matches what the frontend will send
+   * Used for both caching and internal deduplication
+   */
+  getQueryCacheKey(query) {
+    if (typeof query === "string") {
+      return query;
+    } else if (query?.sql) {
+      const values = query.values || query.params;
+      if (values && Object.keys(values).length > 0) {
+        return JSON.stringify({ sql: query.sql, values });
+      } else {
+        return query.sql;
+      }
+    }
+    return "";
+  }
+  /**
+   * Execute a query against the database for validation and caching
+   * @param query - The SQL query to execute (string or object with sql/values)
+   * @param collections - Collections object containing database execute function
+   * @returns Object with result data and cache key
+   * @throws Error if query execution fails
+   */
+  async executeQueryForValidation(query, collections) {
+    const cacheKey = this.getQueryCacheKey(query);
+    if (!cacheKey) {
+      throw new Error("Invalid query format: expected string or object with sql property");
+    }
+    const result = await collections["database"]["execute"]({ sql: cacheKey });
+    return { result, cacheKey };
+  }
+  /**
+   * Request the LLM to fix a failed SQL query
+   * @param failedQuery - The query that failed execution
+   * @param errorMessage - The error message from the failed execution
+   * @param componentContext - Context about the component (name, type, title)
+   * @param apiKey - Optional API key
+   * @returns Fixed query string
+   */
+  async requestQueryFix(failedQuery, errorMessage, componentContext, apiKey) {
+    const schemaDoc = schema.generateSchemaDocumentation();
+    const databaseRules = await promptLoader.loadDatabaseRules();
+    const prompt = `You are a SQL expert. Fix the following SQL query that failed execution.
+
+## Database Schema
+${schemaDoc}
+
+## Database-Specific SQL Rules
+${databaseRules}
+
+## Component Context
+- Component Name: ${componentContext.name}
+- Component Type: ${componentContext.type}
+- Title: ${componentContext.title || "N/A"}
+
+## Failed Query
+\`\`\`sql
+${failedQuery}
+\`\`\`
+
+## Error Message
+${errorMessage}
+
+## Instructions
+1. Analyze the error message and identify what caused the query to fail
+2. Fix the query to resolve the error while preserving the original intent
+3. Ensure the fixed query follows the database-specific SQL rules above
+4. Return ONLY the fixed SQL query, no explanations or markdown
+
+Fixed SQL query:`;
+    const response = await LLM.text(
+      {
+        sys: "You are a SQL expert. Return only the fixed SQL query with no additional text, explanations, or markdown formatting.",
+        user: prompt
+      },
+      {
+        model: this.getModelForTask("simple"),
+        maxTokens: 2048,
+        temperature: 0.1,
+        apiKey: this.getApiKey(apiKey)
+      }
+    );
+    let fixedQuery = response.trim();
+    fixedQuery = fixedQuery.replace(/^```sql\s*/i, "").replace(/\s*```$/i, "");
+    fixedQuery = fixedQuery.replace(/^```\s*/i, "").replace(/\s*```$/i, "");
+    const { query: validatedQuery } = validateAndFixSqlQuery(fixedQuery);
+    return validatedQuery;
+  }
   /**
    * Match components from text response suggestions and generate follow-up questions
    * Takes a text response with component suggestions (c1:type format) and matches with available components
@@ -6428,10 +6696,34 @@ ${executedToolsText}`);
           }
         };
       }).filter(Boolean);
+      let validatedComponents = finalComponents;
+      if (collections?.["database"]?.["execute"]) {
+        logger.info(`[${this.getProviderName()}] Starting query validation for ${finalComponents.length} components...`);
+        logCollector?.info(`Validating queries for ${finalComponents.length} components...`);
+        try {
+          const validationResult = await this.validateAndRetryComponentQueries(
+            finalComponents,
+            collections,
+            apiKey,
+            logCollector
+          );
+          validatedComponents = validationResult.components;
+          const queriedComponents = finalComponents.filter((c) => c.props?.query);
+          const validatedQueries = validatedComponents.filter((c) => c.props?.query);
+          logger.info(`[${this.getProviderName()}] Query validation complete: ${validatedQueries.length}/${queriedComponents.length} queries validated`);
+          logCollector?.info(`Query validation complete: ${validatedQueries.length}/${queriedComponents.length} queries validated`);
+        } catch (validationError) {
+          const validationErrorMsg = validationError instanceof Error ? validationError.message : String(validationError);
+          logger.error(`[${this.getProviderName()}] Query validation error: ${validationErrorMsg}`);
+          logCollector?.error(`Query validation error: ${validationErrorMsg}`);
+        }
+      } else {
+        logger.debug(`[${this.getProviderName()}] Skipping query validation - database execute function not available`);
+      }
       const methodDuration = Date.now() - methodStartTime;
-      logger.info(`[${this.getProviderName()}] [TIMING] DONE ${methodName} in ${methodDuration}ms | components: ${finalComponents.length} | actions: ${actions.length}`);
+      logger.info(`[${this.getProviderName()}] [TIMING] DONE ${methodName} in ${methodDuration}ms | components: ${validatedComponents.length} | actions: ${actions.length}`);
       return {
-        components: finalComponents,
+        components: validatedComponents,
         layoutTitle,
         layoutDescription,
         actions
@@ -6449,6 +6741,117 @@ ${executedToolsText}`);
       };
     }
   }
+  /**
+   * Validate component queries against the database and retry with LLM fixes if they fail
+   * @param components - Array of components with potential queries
+   * @param collections - Collections object containing database execute function
+   * @param apiKey - Optional API key for LLM calls
+   * @param logCollector - Optional log collector for logging
+   * @returns Object with validated components and a map of query results
+   */
+  async validateAndRetryComponentQueries(components, collections, apiKey, logCollector) {
+    const MAX_RETRIES = 3;
+    const queryResults = /* @__PURE__ */ new Map();
+    const validatedComponents = [];
+    const queryAttempts = /* @__PURE__ */ new Map();
+    const queryValidationStatus = /* @__PURE__ */ new Map();
+    for (const component of components) {
+      const query = component.props?.query;
+      if (!query) {
+        validatedComponents.push(component);
+        continue;
+      }
+      const queryKey = this.getQueryCacheKey(query);
+      const queryStr = typeof query === "string" ? query : query?.sql || "";
+      if (queryValidationStatus.has(queryKey)) {
+        if (queryValidationStatus.get(queryKey)) {
+          validatedComponents.push(component);
+          if (queryResults.has(queryKey)) {
+            queryResults.set(`${component.id}:${queryKey}`, queryResults.get(queryKey));
+          }
+        } else {
+          logger.warn(`[${this.getProviderName()}] Component ${component.name} has previously failed query, keeping as-is`);
+          validatedComponents.push(component);
+        }
+        continue;
+      }
+      let attempts = queryAttempts.get(queryKey) || 0;
+      let currentQuery = typeof query === "string" ? query : { sql: query?.sql || "", values: query?.values, params: query?.params };
+      let currentQueryStr = queryStr;
+      let validated = false;
+      let lastError = "";
+      logger.info(`[${this.getProviderName()}] Validating query for component: ${component.name} (${component.type})`);
+      while (attempts < MAX_RETRIES && !validated) {
+        attempts++;
+        queryAttempts.set(queryKey, attempts);
+        try {
+          logger.debug(`[${this.getProviderName()}] Query validation attempt ${attempts}/${MAX_RETRIES} for ${component.name}`);
+          const { result, cacheKey } = await this.executeQueryForValidation(currentQuery, collections);
+          validated = true;
+          queryValidationStatus.set(queryKey, true);
+          queryResults.set(queryKey, result);
+          queryResults.set(`${component.id}:${queryKey}`, result);
+          queryCache.set(cacheKey, result);
+          logger.info(`[${this.getProviderName()}] \u2713 Query validated for ${component.name} (attempt ${attempts}) - cached for frontend`);
+          logCollector?.info(`\u2713 Query validated for ${component.name}`);
+          if (currentQueryStr !== queryStr) {
+            component.props = {
+              ...component.props,
+              query: typeof query === "string" ? currentQueryStr : { ...query, sql: currentQueryStr }
+            };
+            logger.info(`[${this.getProviderName()}] Updated ${component.name} with fixed query`);
+          }
+        } catch (error) {
+          lastError = error instanceof Error ? error.message : String(error);
+          logger.warn(`[${this.getProviderName()}] Query validation failed for ${component.name} (attempt ${attempts}/${MAX_RETRIES}): ${lastError}`);
+          logCollector?.warn(`Query validation failed for ${component.name}: ${lastError}`);
+          if (attempts >= MAX_RETRIES) {
+            logger.error(`[${this.getProviderName()}] \u2717 Max retries reached for ${component.name}, keeping original component`);
+            logCollector?.error(`Max retries reached for ${component.name}, query may fail at runtime`);
+            queryValidationStatus.set(queryKey, false);
+            break;
+          }
+          logger.info(`[${this.getProviderName()}] Requesting query fix from LLM for ${component.name}...`);
+          logCollector?.info(`Requesting query fix for ${component.name}...`);
+          try {
+            const fixedQueryStr = await this.requestQueryFix(
+              currentQueryStr,
+              lastError,
+              {
+                name: component.name,
+                type: component.type,
+                title: component.props?.title
+              },
+              apiKey
+            );
+            if (fixedQueryStr && fixedQueryStr !== currentQueryStr) {
+              logger.info(`[${this.getProviderName()}] Received fixed query for ${component.name}, retrying...`);
+              currentQueryStr = fixedQueryStr;
+              if (typeof currentQuery === "string") {
+                currentQuery = fixedQueryStr;
+              } else {
+                currentQuery = { ...currentQuery, sql: fixedQueryStr };
+              }
+            } else {
+              logger.warn(`[${this.getProviderName()}] LLM returned same or empty query, stopping retries`);
+              queryValidationStatus.set(queryKey, false);
+              break;
+            }
+          } catch (fixError) {
+            const fixErrorMsg = fixError instanceof Error ? fixError.message : String(fixError);
+            logger.error(`[${this.getProviderName()}] Failed to get query fix from LLM: ${fixErrorMsg}`);
+            queryValidationStatus.set(queryKey, false);
+            break;
+          }
+        }
+      }
+      validatedComponents.push(component);
+    }
+    return {
+      components: validatedComponents,
+      queryResults
+    };
+  }
   /**
    * Classify user question into category and detect external tools needed
    * Determines if question is for data analysis, requires external tools, or needs text response
@@ -6630,12 +7033,6 @@ ${executedToolsText}`);
    * This provides conversational text responses instead of component generation
    * Supports tool calling for query execution with automatic retry on errors (max 3 attempts)
    * After generating text response, if components are provided, matches suggested components
-   * @param streamCallback - Optional callback function to receive text chunks as they stream
-   * @param collections - Collection registry for executing database queries via database.execute
-   * @param components - Optional list of available components for matching suggestions
-   * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called
-   * @param category - Question category ('data_analysis' | 'data_modification' | 'general'). For data_modification, answer component streaming is skipped. For general, component generation is skipped entirely.
-   * @param userId - Optional user ID for fetching user-specific knowledge base nodes
    */
   async generateTextResponse(userPrompt, apiKey, logCollector, conversationHistory, streamCallback, collections, components, externalTools, category, userId) {
     const methodStartTime = Date.now();
@@ -7325,11 +7722,6 @@ ${errorMsg}
    *    - If match found → Adapt UI block parameters and return
    * 2. Category classification: Determine if data_analysis, requires_external_tools, or text_response
    * 3. Route appropriately based on category and response mode
-   *
-   * @param responseMode - 'component' for component generation (default), 'text' for text responses
-   * @param streamCallback - Optional callback function to receive text chunks as they stream (only for text mode)
-   * @param collections - Collection registry for executing database queries (required for text mode)
-   * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called (only for text mode)
    */
   async handleUserRequest(userPrompt, components, apiKey, logCollector, conversationHistory, responseMode = "text", streamCallback, collections, externalTools, userId) {
     const startTime = Date.now();
@@ -7343,8 +7735,7 @@ ${errorMsg}
         userPrompt,
         collections,
         userId,
-        similarityThreshold: 0.8
-        // 80% threshold
+        similarityThreshold: 0.99
       });
       if (conversationMatch) {
         logger.info(`[${this.getProviderName()}] \u2713 Found matching conversation with ${(conversationMatch.similarity * 100).toFixed(2)}% similarity`);
@@ -7495,16 +7886,6 @@ ${errorMsg}
           };
         }) || [];
       }
-      if (categoryClassification.category === "general") {
-        logger.info(`[${this.getProviderName()}] Routing to general conversation (no database operations)`);
-        logCollector?.info("Routing to general conversation...");
-      } else if (categoryClassification.category === "data_analysis") {
-        logger.info(`[${this.getProviderName()}] Routing to data analysis (SELECT operations)`);
-        logCollector?.info("Routing to data analysis...");
-      } else if (categoryClassification.category === "data_modification") {
-        logger.info(`[${this.getProviderName()}] Routing to data modification (INSERT/UPDATE/DELETE operations)`);
-        logCollector?.info("Routing to data modification...");
-      }
       const textResponse = await this.generateTextResponse(
         userPrompt,
         apiKey,
@@ -12924,8 +13305,13 @@ var SuperatomSDK = class {
     this.llmProviders = config.LLM_PROVIDERS || getLLMProviders();
     this.databaseType = config.databaseType || "postgresql";
     this.modelStrategy = config.modelStrategy || "fast";
+    this.conversationSimilarityThreshold = config.conversationSimilarityThreshold ?? 0.8;
     this.applyModelStrategy(this.modelStrategy);
-    logger.info(`Initializing Superatom SDK v${SDK_VERSION} for project ${this.projectId}, llm providers: ${this.llmProviders.join(", ")}, database type: ${this.databaseType}, model strategy: ${this.modelStrategy}`);
+    this.applyConversationSimilarityThreshold(this.conversationSimilarityThreshold);
+    if (config.queryCacheTTL !== void 0) {
+      queryCache.setTTL(config.queryCacheTTL);
+    }
+    logger.info(`Initializing Superatom SDK v${SDK_VERSION} for project ${this.projectId}, llm providers: ${this.llmProviders.join(", ")}, database type: ${this.databaseType}, model strategy: ${this.modelStrategy}, conversation similarity threshold: ${this.conversationSimilarityThreshold}, query cache TTL: ${queryCache.getTTL()} minutes`);
     this.userManager = new UserManager(this.projectId, 5e3);
     this.dashboardManager = new DashboardManager(this.projectId);
     this.reportManager = new ReportManager(this.projectId);
@@ -13338,6 +13724,31 @@ var SuperatomSDK = class {
   getModelStrategy() {
     return this.modelStrategy;
   }
+  /**
+   * Apply conversation similarity threshold to all LLM provider singletons
+   * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+   */
+  applyConversationSimilarityThreshold(threshold) {
+    anthropicLLM.setConversationSimilarityThreshold(threshold);
+    groqLLM.setConversationSimilarityThreshold(threshold);
+    geminiLLM.setConversationSimilarityThreshold(threshold);
+    openaiLLM.setConversationSimilarityThreshold(threshold);
+    logger.info(`Conversation similarity threshold '${threshold}' applied to all LLM providers`);
+  }
+  /**
+   * Set conversation similarity threshold at runtime
+   * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+   */
+  setConversationSimilarityThreshold(threshold) {
+    this.conversationSimilarityThreshold = threshold;
+    this.applyConversationSimilarityThreshold(threshold);
+  }
+  /**
+   * Get current conversation similarity threshold
+   */
+  getConversationSimilarityThreshold() {
+    return this.conversationSimilarityThreshold;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -13360,6 +13771,7 @@ var SuperatomSDK = class {
   llmUsageLogger,
   logger,
   openaiLLM,
+  queryCache,
   rerankChromaResults,
   rerankConversationResults,
   userPromptErrorLogger