@superatomai/sdk-node 0.0.62 → 0.0.63

package/dist/index.d.mts

@@ -864,6 +864,12 @@ interface SuperatomSDKConfig {
      * Default: 0.8
      */
     conversationSimilarityThreshold?: number;
+    /**
+     * Query cache TTL (Time To Live) in minutes
+     * Cached query results expire after this duration
+     * Default: 5 minutes
+     */
+    queryCacheTTL?: number;
 }
 
 declare const KbNodesQueryFiltersSchema: z.ZodObject<{
@@ -2037,11 +2043,6 @@ interface BaseLLMConfig {
      * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
      */
     modelStrategy?: ModelStrategy;
-    /**
-     * Similarity threshold for conversation search (semantic matching)
-     * Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
-     * Default: 0.8
-     */
     conversationSimilarityThreshold?: number;
 }
 /**
@@ -2109,6 +2110,29 @@ declare abstract class BaseLLM {
      * This checks both single Form components and Forms inside MultiComponentContainer
      */
     protected containsFormComponent(component: any): boolean;
+    /**
+     * 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
+     */
+    private getQueryCacheKey;
+    /**
+     * 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
+     */
+    private executeQueryForValidation;
+    /**
+     * 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
+     */
+    private requestQueryFix;
     /**
      * 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
@@ -2127,6 +2151,15 @@ declare abstract class BaseLLM {
         layoutDescription: string;
         actions: Action[];
     }>;
+    /**
+     * 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
+     */
+    private validateAndRetryComponentQueries;
     /**
      * Classify user question into category and detect external tools needed
      * Determines if question is for data analysis, requires external tools, or needs text response
@@ -2163,12 +2196,6 @@ declare abstract class BaseLLM {
      * 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
      */
     generateTextResponse(userPrompt: string, apiKey?: string, logCollector?: any, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general', userId?: string): Promise<T_RESPONSE>;
     /**
@@ -2178,11 +2205,6 @@ declare abstract class BaseLLM {
      *    - 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)
      */
     handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, logCollector?: any, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
     /**
@@ -2249,6 +2271,63 @@ declare class OpenAILLM extends BaseLLM {
 }
 declare const openaiLLM: OpenAILLM;
 
+/**
+ * Query Cache - Stores query results with configurable TTL
+ * Used to avoid re-executing queries that were already validated
+ */
+declare class QueryCache {
+    private cache;
+    private ttlMs;
+    private cleanupInterval;
+    constructor();
+    /**
+     * Set the cache TTL (Time To Live)
+     * @param minutes - TTL in minutes (default: 5)
+     */
+    setTTL(minutes: number): void;
+    /**
+     * Get the current TTL in minutes
+     */
+    getTTL(): number;
+    /**
+     * Store query result in cache
+     * Key is the exact query string (or JSON for parameterized queries)
+     */
+    set(query: string, data: any): void;
+    /**
+     * Get cached result if exists and not expired
+     */
+    get(query: string): any | null;
+    /**
+     * Check if query exists in cache (not expired)
+     */
+    has(query: string): boolean;
+    /**
+     * Remove a specific query from cache
+     */
+    delete(query: string): void;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        oldestEntryAge: number | null;
+    };
+    /**
+     * Start periodic cleanup of expired entries
+     */
+    private startCleanup;
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    destroy(): void;
+}
+declare const queryCache: QueryCache;
+
 declare const SDK_VERSION = "0.0.8";
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
@@ -2400,4 +2479,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, type Message, type ModelStrategy, type OutputField, type RerankedResult, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, anthropicLLM, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };
+export { type Action, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, type Message, type ModelStrategy, type OutputField, type RerankedResult, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, anthropicLLM, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };

package/dist/index.d.ts

@@ -864,6 +864,12 @@ interface SuperatomSDKConfig {
      * Default: 0.8
      */
     conversationSimilarityThreshold?: number;
+    /**
+     * Query cache TTL (Time To Live) in minutes
+     * Cached query results expire after this duration
+     * Default: 5 minutes
+     */
+    queryCacheTTL?: number;
 }
 
 declare const KbNodesQueryFiltersSchema: z.ZodObject<{
@@ -2037,11 +2043,6 @@ interface BaseLLMConfig {
      * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
      */
     modelStrategy?: ModelStrategy;
-    /**
-     * Similarity threshold for conversation search (semantic matching)
-     * Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
-     * Default: 0.8
-     */
     conversationSimilarityThreshold?: number;
 }
 /**
@@ -2109,6 +2110,29 @@ declare abstract class BaseLLM {
      * This checks both single Form components and Forms inside MultiComponentContainer
      */
     protected containsFormComponent(component: any): boolean;
+    /**
+     * 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
+     */
+    private getQueryCacheKey;
+    /**
+     * 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
+     */
+    private executeQueryForValidation;
+    /**
+     * 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
+     */
+    private requestQueryFix;
     /**
      * 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
@@ -2127,6 +2151,15 @@ declare abstract class BaseLLM {
         layoutDescription: string;
         actions: Action[];
     }>;
+    /**
+     * 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
+     */
+    private validateAndRetryComponentQueries;
     /**
      * Classify user question into category and detect external tools needed
      * Determines if question is for data analysis, requires external tools, or needs text response
@@ -2163,12 +2196,6 @@ declare abstract class BaseLLM {
      * 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
      */
     generateTextResponse(userPrompt: string, apiKey?: string, logCollector?: any, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general', userId?: string): Promise<T_RESPONSE>;
     /**
@@ -2178,11 +2205,6 @@ declare abstract class BaseLLM {
      *    - 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)
      */
     handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, logCollector?: any, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
     /**
@@ -2249,6 +2271,63 @@ declare class OpenAILLM extends BaseLLM {
 }
 declare const openaiLLM: OpenAILLM;
 
+/**
+ * Query Cache - Stores query results with configurable TTL
+ * Used to avoid re-executing queries that were already validated
+ */
+declare class QueryCache {
+    private cache;
+    private ttlMs;
+    private cleanupInterval;
+    constructor();
+    /**
+     * Set the cache TTL (Time To Live)
+     * @param minutes - TTL in minutes (default: 5)
+     */
+    setTTL(minutes: number): void;
+    /**
+     * Get the current TTL in minutes
+     */
+    getTTL(): number;
+    /**
+     * Store query result in cache
+     * Key is the exact query string (or JSON for parameterized queries)
+     */
+    set(query: string, data: any): void;
+    /**
+     * Get cached result if exists and not expired
+     */
+    get(query: string): any | null;
+    /**
+     * Check if query exists in cache (not expired)
+     */
+    has(query: string): boolean;
+    /**
+     * Remove a specific query from cache
+     */
+    delete(query: string): void;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        oldestEntryAge: number | null;
+    };
+    /**
+     * Start periodic cleanup of expired entries
+     */
+    private startCleanup;
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    destroy(): void;
+}
+declare const queryCache: QueryCache;
+
 declare const SDK_VERSION = "0.0.8";
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
@@ -2400,4 +2479,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, type Message, type ModelStrategy, type OutputField, type RerankedResult, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, anthropicLLM, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };
+export { type Action, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, type Message, type ModelStrategy, type OutputField, type RerankedResult, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, anthropicLLM, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };