@superatomai/sdk-node 0.0.71 → 0.0.74

package/dist/index.d.mts

@@ -2025,6 +2025,92 @@ declare function rerankConversationResults<T extends {
     bm25Score: number;
 }>;
 
+/**
+ * QueryExecutionService - Handles all query execution, validation, and retry logic
+ * Extracted from BaseLLM for better separation of concerns
+ */
+
+/**
+ * Context for component when requesting query fix
+ */
+interface ComponentContext {
+    name: string;
+    type: string;
+    title?: string;
+}
+/**
+ * Result of query validation
+ */
+interface QueryValidationResult {
+    component: Component | null;
+    queryKey: string;
+    result: any;
+    validated: boolean;
+}
+/**
+ * Result of batch query validation
+ */
+interface BatchValidationResult {
+    components: Component[];
+    queryResults: Map<string, any>;
+}
+/**
+ * Configuration for QueryExecutionService
+ */
+interface QueryExecutionServiceConfig {
+    defaultLimit: number;
+    getModelForTask: (taskType: 'simple' | 'complex') => string;
+    getApiKey: (apiKey?: string) => string | undefined;
+    providerName: string;
+}
+/**
+ * QueryExecutionService handles all query-related operations
+ */
+declare class QueryExecutionService {
+    private config;
+    constructor(config: QueryExecutionServiceConfig);
+    /**
+     * Get the cache key for a query
+     * This ensures the cache key matches what the frontend will send
+     */
+    getQueryCacheKey(query: any): string;
+    /**
+     * Execute a query against the database
+     * @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
+     */
+    executeQuery(query: any, collections: any): Promise<{
+        result: any;
+        cacheKey: string;
+    }>;
+    /**
+     * 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
+     * @param apiKey - Optional API key
+     * @returns Fixed query string
+     */
+    requestQueryFix(failedQuery: string, errorMessage: string, componentContext: ComponentContext, apiKey?: string): Promise<string>;
+    /**
+     * Validate a single component's query with retry logic
+     * @param component - The component to validate
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Validation result with component, query key, and result
+     */
+    validateSingleQuery(component: Component, collections: any, apiKey?: string): Promise<QueryValidationResult>;
+    /**
+     * Validate multiple component queries in parallel
+     * @param components - Array of components with potential queries
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Object with validated components and query results map
+     */
+    validateComponentQueries(components: Component[], collections: any, apiKey?: string): Promise<BatchValidationResult>;
+}
+
 /**
  * Task types for model selection
  * - 'complex': Text generation, component matching, parameter adaptation (uses best model in balanced mode)
@@ -2056,6 +2142,7 @@ declare abstract class BaseLLM {
     protected apiKey?: string;
     protected modelStrategy: ModelStrategy;
     protected conversationSimilarityThreshold: number;
+    protected queryService: QueryExecutionService;
     constructor(config?: BaseLLMConfig);
     /**
      * Get the appropriate model based on task type and model strategy
@@ -2110,29 +2197,6 @@ 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
@@ -2141,40 +2205,20 @@ declare abstract class BaseLLM {
      * @param analysisContent - The text response containing component suggestions
      * @param components - List of available components
      * @param apiKey - Optional API key
-     * @param logCollector - Optional log collector
      * @param componentStreamCallback - Optional callback to stream primary KPI component as soon as it's identified
      * @returns Object containing matched components, layout title/description, and follow-up actions
      */
-    matchComponentsFromAnalysis(analysisContent: string, components: Component[], userPrompt: string, apiKey?: string, logCollector?: any, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
+    matchComponentsFromAnalysis(analysisContent: string, components: Component[], userPrompt: string, apiKey?: string, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
         components: Component[];
         layoutTitle: string;
         layoutDescription: string;
         actions: Action[];
     }>;
-    /**
-     * Validate a single component's query with retry logic
-     * @param component - The component to validate
-     * @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 component (or null if failed) and query result
-     */
-    private validateSingleComponentQuery;
-    /**
-     * Validate component queries against the database and retry with LLM fixes if they fail
-     * Uses parallel execution for faster validation
-     * @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
      */
-    classifyQuestionCategory(userPrompt: string, apiKey?: string, logCollector?: any, conversationHistory?: string, externalTools?: any[]): Promise<{
+    classifyQuestionCategory(userPrompt: string, apiKey?: string, conversationHistory?: string, externalTools?: any[]): Promise<{
         category: 'data_analysis' | 'data_modification' | 'general';
         externalTools: Array<{
             type: string;
@@ -2191,7 +2235,7 @@ declare abstract class BaseLLM {
      * Takes a matched UI block from semantic search and modifies its props to answer the new question
      * Also adapts the cached text response to match the new question
      */
-    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, logCollector?: any, cachedTextResponse?: string): Promise<{
+    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, cachedTextResponse?: string): Promise<{
         success: boolean;
         adaptedComponent?: Component;
         adaptedTextResponse?: string;
@@ -2207,7 +2251,7 @@ declare abstract class BaseLLM {
      * 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
      */
-    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>;
+    generateTextResponse(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general', userId?: string): Promise<T_RESPONSE>;
     /**
      * Main orchestration function with semantic search and multi-step classification
      * NEW FLOW (Recommended):
@@ -2216,13 +2260,13 @@ declare abstract class BaseLLM {
      * 2. Category classification: Determine if data_analysis, requires_external_tools, or text_response
      * 3. Route appropriately based on category and response 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>;
+    handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
     /**
      * Generate next questions that the user might ask based on the original prompt and generated component
      * This helps provide intelligent suggestions for follow-up queries
      * For general/conversational questions without components, pass textResponse instead
      */
-    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, logCollector?: any, conversationHistory?: string, textResponse?: string): Promise<string[]>;
+    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string): Promise<string[]>;
 }
 
 interface AnthropicLLMConfig extends BaseLLMConfig {
@@ -2338,7 +2382,6 @@ declare class QueryCache {
 }
 declare const queryCache: QueryCache;
 
-declare const SDK_VERSION = "0.0.8";
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
@@ -2489,4 +2532,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, queryCache, 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, 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

@@ -2025,6 +2025,92 @@ declare function rerankConversationResults<T extends {
     bm25Score: number;
 }>;
 
+/**
+ * QueryExecutionService - Handles all query execution, validation, and retry logic
+ * Extracted from BaseLLM for better separation of concerns
+ */
+
+/**
+ * Context for component when requesting query fix
+ */
+interface ComponentContext {
+    name: string;
+    type: string;
+    title?: string;
+}
+/**
+ * Result of query validation
+ */
+interface QueryValidationResult {
+    component: Component | null;
+    queryKey: string;
+    result: any;
+    validated: boolean;
+}
+/**
+ * Result of batch query validation
+ */
+interface BatchValidationResult {
+    components: Component[];
+    queryResults: Map<string, any>;
+}
+/**
+ * Configuration for QueryExecutionService
+ */
+interface QueryExecutionServiceConfig {
+    defaultLimit: number;
+    getModelForTask: (taskType: 'simple' | 'complex') => string;
+    getApiKey: (apiKey?: string) => string | undefined;
+    providerName: string;
+}
+/**
+ * QueryExecutionService handles all query-related operations
+ */
+declare class QueryExecutionService {
+    private config;
+    constructor(config: QueryExecutionServiceConfig);
+    /**
+     * Get the cache key for a query
+     * This ensures the cache key matches what the frontend will send
+     */
+    getQueryCacheKey(query: any): string;
+    /**
+     * Execute a query against the database
+     * @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
+     */
+    executeQuery(query: any, collections: any): Promise<{
+        result: any;
+        cacheKey: string;
+    }>;
+    /**
+     * 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
+     * @param apiKey - Optional API key
+     * @returns Fixed query string
+     */
+    requestQueryFix(failedQuery: string, errorMessage: string, componentContext: ComponentContext, apiKey?: string): Promise<string>;
+    /**
+     * Validate a single component's query with retry logic
+     * @param component - The component to validate
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Validation result with component, query key, and result
+     */
+    validateSingleQuery(component: Component, collections: any, apiKey?: string): Promise<QueryValidationResult>;
+    /**
+     * Validate multiple component queries in parallel
+     * @param components - Array of components with potential queries
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Object with validated components and query results map
+     */
+    validateComponentQueries(components: Component[], collections: any, apiKey?: string): Promise<BatchValidationResult>;
+}
+
 /**
  * Task types for model selection
  * - 'complex': Text generation, component matching, parameter adaptation (uses best model in balanced mode)
@@ -2056,6 +2142,7 @@ declare abstract class BaseLLM {
     protected apiKey?: string;
     protected modelStrategy: ModelStrategy;
     protected conversationSimilarityThreshold: number;
+    protected queryService: QueryExecutionService;
     constructor(config?: BaseLLMConfig);
     /**
      * Get the appropriate model based on task type and model strategy
@@ -2110,29 +2197,6 @@ 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
@@ -2141,40 +2205,20 @@ declare abstract class BaseLLM {
      * @param analysisContent - The text response containing component suggestions
      * @param components - List of available components
      * @param apiKey - Optional API key
-     * @param logCollector - Optional log collector
      * @param componentStreamCallback - Optional callback to stream primary KPI component as soon as it's identified
      * @returns Object containing matched components, layout title/description, and follow-up actions
      */
-    matchComponentsFromAnalysis(analysisContent: string, components: Component[], userPrompt: string, apiKey?: string, logCollector?: any, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
+    matchComponentsFromAnalysis(analysisContent: string, components: Component[], userPrompt: string, apiKey?: string, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
         components: Component[];
         layoutTitle: string;
         layoutDescription: string;
         actions: Action[];
     }>;
-    /**
-     * Validate a single component's query with retry logic
-     * @param component - The component to validate
-     * @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 component (or null if failed) and query result
-     */
-    private validateSingleComponentQuery;
-    /**
-     * Validate component queries against the database and retry with LLM fixes if they fail
-     * Uses parallel execution for faster validation
-     * @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
      */
-    classifyQuestionCategory(userPrompt: string, apiKey?: string, logCollector?: any, conversationHistory?: string, externalTools?: any[]): Promise<{
+    classifyQuestionCategory(userPrompt: string, apiKey?: string, conversationHistory?: string, externalTools?: any[]): Promise<{
         category: 'data_analysis' | 'data_modification' | 'general';
         externalTools: Array<{
             type: string;
@@ -2191,7 +2235,7 @@ declare abstract class BaseLLM {
      * Takes a matched UI block from semantic search and modifies its props to answer the new question
      * Also adapts the cached text response to match the new question
      */
-    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, logCollector?: any, cachedTextResponse?: string): Promise<{
+    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, cachedTextResponse?: string): Promise<{
         success: boolean;
         adaptedComponent?: Component;
         adaptedTextResponse?: string;
@@ -2207,7 +2251,7 @@ declare abstract class BaseLLM {
      * 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
      */
-    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>;
+    generateTextResponse(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general', userId?: string): Promise<T_RESPONSE>;
     /**
      * Main orchestration function with semantic search and multi-step classification
      * NEW FLOW (Recommended):
@@ -2216,13 +2260,13 @@ declare abstract class BaseLLM {
      * 2. Category classification: Determine if data_analysis, requires_external_tools, or text_response
      * 3. Route appropriately based on category and response 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>;
+    handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
     /**
      * Generate next questions that the user might ask based on the original prompt and generated component
      * This helps provide intelligent suggestions for follow-up queries
      * For general/conversational questions without components, pass textResponse instead
      */
-    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, logCollector?: any, conversationHistory?: string, textResponse?: string): Promise<string[]>;
+    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string): Promise<string[]>;
 }
 
 interface AnthropicLLMConfig extends BaseLLMConfig {
@@ -2338,7 +2382,6 @@ declare class QueryCache {
 }
 declare const queryCache: QueryCache;
 
-declare const SDK_VERSION = "0.0.8";
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
@@ -2489,4 +2532,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, queryCache, 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, 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 };