@superatomai/sdk-node 0.0.19 → 0.0.20-mds

package/dist/index.d.ts

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
 
+/**
+ * Unified UIBlock structure for database storage
+ * Used in both bookmarks and user-conversations tables
+ */
+interface DBUIBlock {
+    id: string;
+    component: Record<string, any> | null;
+    analysis: string | null;
+    user_prompt: string;
+}
+
 /**
  * Log levels in hierarchical order
  * - errors: only error logs
@@ -48,7 +59,18 @@ declare class Logger {
      * Log debug message (only shown for verbose level)
      */
     debug(...args: any[]): void;
+    /**
+     * Write to log file
+     */
     file(...args: any[]): void;
+    /**
+     * Clear the log file (call at start of new user request)
+     */
+    clearFile(): void;
+    /**
+     * Log LLM method prompts with clear labeling
+     */
+    logLLMPrompt(methodName: string, promptType: 'system' | 'user', content: string | object | any[]): void;
 }
 declare const logger: Logger;
 
@@ -79,7 +101,27 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             deps?: string[] | undefined;
         }>, "many">>;
         data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-        render: z.ZodType<any, z.ZodTypeDef, any>;
+        render: z.ZodOptional<z.ZodType<any, z.ZodTypeDef, any>>;
+        pages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            order: z.ZodNumber;
+            icon: z.ZodOptional<z.ZodString>;
+            render: z.ZodType<any, z.ZodTypeDef, any>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            name: string;
+            order: number;
+            icon?: string | undefined;
+            render?: any;
+        }, {
+            id: string;
+            name: string;
+            order: number;
+            icon?: string | undefined;
+            render?: any;
+        }>, "many">>;
+        defaultPageId: z.ZodOptional<z.ZodString>;
         query: z.ZodOptional<z.ZodObject<{
             graphql: z.ZodOptional<z.ZodString>;
             sql: z.ZodOptional<z.ZodString>;
@@ -118,6 +160,7 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
+        render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
             fn: string;
@@ -128,7 +171,14 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
+        pages?: {
+            id: string;
+            name: string;
+            order: number;
+            icon?: string | undefined;
+            render?: any;
+        }[] | undefined;
+        defaultPageId?: string | undefined;
     }, {
         id: string;
         name?: string | undefined;
@@ -142,6 +192,7 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
+        render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
             fn: string;
@@ -152,7 +203,14 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
+        pages?: {
+            id: string;
+            name: string;
+            order: number;
+            icon?: string | undefined;
+            render?: any;
+        }[] | undefined;
+        defaultPageId?: string | undefined;
     }>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -170,6 +228,7 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
+        render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
             fn: string;
@@ -180,7 +239,14 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
+        pages?: {
+            id: string;
+            name: string;
+            order: number;
+            icon?: string | undefined;
+            render?: any;
+        }[] | undefined;
+        defaultPageId?: string | undefined;
     };
     data?: Record<string, any> | undefined;
     context?: Record<string, any> | undefined;
@@ -198,6 +264,7 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
+        render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
             fn: string;
@@ -208,7 +275,14 @@ declare const DSLRendererPropsSchema$1: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
+        pages?: {
+            id: string;
+            name: string;
+            order: number;
+            icon?: string | undefined;
+            render?: any;
+        }[] | undefined;
+        defaultPageId?: string | undefined;
     };
     data?: Record<string, any> | undefined;
     context?: Record<string, any> | undefined;
@@ -281,6 +355,7 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
+        render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
             fn: string;
@@ -291,7 +366,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
     }, {
         id: string;
         name?: string | undefined;
@@ -305,6 +379,7 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
+        render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
             fn: string;
@@ -315,7 +390,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
     }>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -333,6 +407,7 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
+        render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
             fn: string;
@@ -343,7 +418,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
     };
     data?: Record<string, any> | undefined;
     context?: Record<string, any> | undefined;
@@ -361,6 +435,7 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             dependencies?: string[] | undefined;
         } | undefined;
         props?: Record<string, any> | undefined;
+        render?: any;
         states?: Record<string, any> | undefined;
         methods?: Record<string, {
             fn: string;
@@ -371,7 +446,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
     };
     data?: Record<string, any> | undefined;
     context?: Record<string, any> | undefined;
@@ -384,6 +458,7 @@ declare const UserSchema: z.ZodObject<{
     password: z.ZodString;
     fullname: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodString>;
+    userInfo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     wsIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     username: string;
@@ -391,6 +466,7 @@ declare const UserSchema: z.ZodObject<{
     email?: string | undefined;
     fullname?: string | undefined;
     role?: string | undefined;
+    userInfo?: Record<string, unknown> | undefined;
     wsIds?: string[] | undefined;
 }, {
     username: string;
@@ -398,6 +474,7 @@ declare const UserSchema: z.ZodObject<{
     email?: string | undefined;
     fullname?: string | undefined;
     role?: string | undefined;
+    userInfo?: Record<string, unknown> | undefined;
     wsIds?: string[] | undefined;
 }>;
 type User = z.infer<typeof UserSchema>;
@@ -408,6 +485,7 @@ declare const UsersDataSchema: z.ZodObject<{
         password: z.ZodString;
         fullname: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodString>;
+        userInfo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         wsIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
         username: string;
@@ -415,6 +493,7 @@ declare const UsersDataSchema: z.ZodObject<{
         email?: string | undefined;
         fullname?: string | undefined;
         role?: string | undefined;
+        userInfo?: Record<string, unknown> | undefined;
         wsIds?: string[] | undefined;
     }, {
         username: string;
@@ -422,6 +501,7 @@ declare const UsersDataSchema: z.ZodObject<{
         email?: string | undefined;
         fullname?: string | undefined;
         role?: string | undefined;
+        userInfo?: Record<string, unknown> | undefined;
         wsIds?: string[] | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -431,6 +511,7 @@ declare const UsersDataSchema: z.ZodObject<{
         email?: string | undefined;
         fullname?: string | undefined;
         role?: string | undefined;
+        userInfo?: Record<string, unknown> | undefined;
         wsIds?: string[] | undefined;
     }[];
 }, {
@@ -440,6 +521,7 @@ declare const UsersDataSchema: z.ZodObject<{
         email?: string | undefined;
         fullname?: string | undefined;
         role?: string | undefined;
+        userInfo?: Record<string, unknown> | undefined;
         wsIds?: string[] | undefined;
     }[];
 }>;
@@ -544,44 +626,425 @@ declare const IncomingMessageSchema: z.ZodObject<{
     payload?: unknown;
 }>;
 type IncomingMessage = z.infer<typeof IncomingMessageSchema>;
+declare const ComponentSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    isDisplayComp: z.ZodOptional<z.ZodBoolean>;
+    type: z.ZodString;
+    description: z.ZodString;
+    props: z.ZodObject<{
+        query: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>>;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        query: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>>;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        query: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>>;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    }, z.ZodTypeAny, "passthrough">>;
+    category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    type: string;
+    name: string;
+    description: string;
+    props: {
+        description?: string | undefined;
+        query?: string | {} | null | undefined;
+        title?: string | undefined;
+        config?: Record<string, unknown> | undefined;
+        actions?: any[] | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+    displayName?: string | undefined;
+    isDisplayComp?: boolean | undefined;
+    category?: string | undefined;
+    keywords?: string[] | undefined;
+}, {
+    id: string;
+    type: string;
+    name: string;
+    description: string;
+    props: {
+        description?: string | undefined;
+        query?: string | {} | null | undefined;
+        title?: string | undefined;
+        config?: Record<string, unknown> | undefined;
+        actions?: any[] | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+    displayName?: string | undefined;
+    isDisplayComp?: boolean | undefined;
+    category?: string | undefined;
+    keywords?: string[] | undefined;
+}>;
+type Component = z.infer<typeof ComponentSchema>;
+declare const OutputFieldSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<["string", "number", "boolean", "date"]>;
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "string" | "number" | "boolean" | "date";
+    name: string;
+    description: string;
+}, {
+    type: "string" | "number" | "boolean" | "date";
+    name: string;
+    description: string;
+}>;
+type OutputField = z.infer<typeof OutputFieldSchema>;
+declare const OutputSchema: z.ZodObject<{
+    description: z.ZodString;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["string", "number", "boolean", "date"]>;
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "string" | "number" | "boolean" | "date";
+        name: string;
+        description: string;
+    }, {
+        type: "string" | "number" | "boolean" | "date";
+        name: string;
+        description: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    fields: {
+        type: "string" | "number" | "boolean" | "date";
+        name: string;
+        description: string;
+    }[];
+}, {
+    description: string;
+    fields: {
+        type: "string" | "number" | "boolean" | "date";
+        name: string;
+        description: string;
+    }[];
+}>;
+type ToolOutputSchema = z.infer<typeof OutputSchema>;
 declare const ToolSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     description: z.ZodString;
+    /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
+    toolType: z.ZodOptional<z.ZodEnum<["source", "direct"]>>;
+    /** Full untruncated schema for source agent (all columns visible) */
+    fullSchema: z.ZodOptional<z.ZodString>;
     params: z.ZodRecord<z.ZodString, z.ZodString>;
     fn: z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodAny>;
+    outputSchema: z.ZodOptional<z.ZodObject<{
+        description: z.ZodString;
+        fields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodEnum<["string", "number", "boolean", "date"]>;
+            description: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            type: "string" | "number" | "boolean" | "date";
+            name: string;
+            description: string;
+        }, {
+            type: "string" | "number" | "boolean" | "date";
+            name: string;
+            description: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        fields: {
+            type: "string" | "number" | "boolean" | "date";
+            name: string;
+            description: string;
+        }[];
+    }, {
+        description: string;
+        fields: {
+            type: "string" | "number" | "boolean" | "date";
+            name: string;
+            description: string;
+        }[];
+    }>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     params: Record<string, string>;
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
+    outputSchema?: {
+        description: string;
+        fields: {
+            type: "string" | "number" | "boolean" | "date";
+            name: string;
+            description: string;
+        }[];
+    } | undefined;
 }, {
     id: string;
     params: Record<string, string>;
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
+    outputSchema?: {
+        description: string;
+        fields: {
+            type: "string" | "number" | "boolean" | "date";
+            name: string;
+            description: string;
+        }[];
+    } | undefined;
 }>;
 type Tool$1 = z.infer<typeof ToolSchema>;
 type CollectionOperation = 'getMany' | 'getOne' | 'query' | 'mutation' | 'updateOne' | 'deleteOne' | 'createOne';
 type CollectionHandler<TParams = any, TResult = any> = (params: TParams) => Promise<TResult> | TResult;
 type LLMProvider = 'anthropic' | 'groq' | 'gemini' | 'openai';
 
+type DatabaseType = 'postgresql' | 'mssql' | 'snowflake' | 'mysql';
+/**
+ * Model strategy for controlling which models are used for different tasks
+ * - 'best': Use the best model (e.g., Sonnet) for all tasks - highest quality, higher cost
+ * - 'fast': Use the fast model (e.g., Haiku) for all tasks - lower quality, lower cost
+ * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
+ */
+type ModelStrategy = 'best' | 'fast' | 'balanced';
+/**
+ * Model configuration for DASH_COMP flow (dashboard component picking)
+ * Allows separate control of models used for component selection
+ */
+interface DashCompModelConfig {
+    /**
+     * Primary model for DASH_COMP requests
+     * Format: "provider/model-name" (e.g., "anthropic/claude-sonnet-4-5-20250929")
+     */
+    model?: string;
+    /**
+     * Fast model for simpler DASH_COMP tasks (optional)
+     * Format: "provider/model-name" (e.g., "anthropic/claude-haiku-4-5-20251001")
+     */
+    fastModel?: string;
+}
 interface SuperatomSDKConfig {
     url?: string;
     apiKey?: string;
     projectId: string;
-    userId?: string;
     type?: string;
     bundleDir?: string;
     promptsDir?: string;
+    databaseType?: DatabaseType;
     ANTHROPIC_API_KEY?: string;
     GROQ_API_KEY?: string;
     GEMINI_API_KEY?: string;
     OPENAI_API_KEY?: string;
     LLM_PROVIDERS?: LLMProvider[];
     logLevel?: LogLevel;
+    /**
+     * Model selection strategy for LLM API calls:
+     * - 'best': Use best model for all tasks (highest quality, higher cost)
+     * - 'fast': Use fast model for all tasks (lower quality, lower cost)
+     * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
+     */
+    modelStrategy?: ModelStrategy;
+    /**
+     * Model for the main agent (routing + analysis).
+     * Format: "provider/model-name" (e.g., "anthropic/claude-haiku-4-5-20251001")
+     * If not set, uses the provider's default model.
+     */
+    mainAgentModel?: string;
+    /**
+     * Model for source agents (per-source query generation).
+     * Format: "provider/model-name" (e.g., "anthropic/claude-haiku-4-5-20251001")
+     * If not set, uses the provider's default model.
+     */
+    sourceAgentModel?: string;
+    /**
+     * Separate model configuration for DASH_COMP flow (dashboard component picking)
+     * If not provided, falls back to provider-based model selection
+     */
+    dashCompModels?: DashCompModelConfig;
+    /**
+     * Similarity threshold for conversation search (semantic matching)
+     * Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     * Higher values require closer matches, lower values allow more distant matches
+     * 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;
+    /**
+     * Dashboard conversation history TTL (Time To Live) in minutes
+     * Per-dashboard conversation histories expire after this duration
+     * Default: 30 minutes
+     */
+    dashboardHistoryTTL?: number;
+}
+
+declare const KbNodesQueryFiltersSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
+    createdBy: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type?: "query" | "user" | "global" | undefined;
+    query?: string | undefined;
+    category?: string | undefined;
+    createdBy?: string | undefined;
+    tags?: string[] | undefined;
+}, {
+    type?: "query" | "user" | "global" | undefined;
+    query?: string | undefined;
+    category?: string | undefined;
+    createdBy?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+type KbNodesQueryFilters = z.infer<typeof KbNodesQueryFiltersSchema>;
+declare const KbNodesRequestPayloadSchema: z.ZodObject<{
+    operation: z.ZodEnum<["create", "update", "delete", "getAll", "getOne", "search", "getByCategory", "getByUser", "getCategories", "getTags"]>;
+    data: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+        content: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
+        createdBy: z.ZodOptional<z.ZodString>;
+        updatedBy: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
+        query: z.ZodOptional<z.ZodString>;
+        filters: z.ZodOptional<z.ZodObject<{
+            query: z.ZodOptional<z.ZodString>;
+            category: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            type: z.ZodOptional<z.ZodEnum<["global", "user", "query"]>>;
+            createdBy: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type?: "query" | "user" | "global" | undefined;
+            query?: string | undefined;
+            category?: string | undefined;
+            createdBy?: string | undefined;
+            tags?: string[] | undefined;
+        }, {
+            type?: "query" | "user" | "global" | undefined;
+            query?: string | undefined;
+            category?: string | undefined;
+            createdBy?: string | undefined;
+            tags?: string[] | undefined;
+        }>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        offset: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
+        query?: string | undefined;
+        title?: string | undefined;
+        category?: string | undefined;
+        userId?: string | undefined;
+        limit?: number | undefined;
+        filters?: {
+            type?: "query" | "user" | "global" | undefined;
+            query?: string | undefined;
+            category?: string | undefined;
+            createdBy?: string | undefined;
+            tags?: string[] | undefined;
+        } | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
+        tags?: string[] | undefined;
+        content?: string | undefined;
+    }, {
+        id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
+        query?: string | undefined;
+        title?: string | undefined;
+        category?: string | undefined;
+        userId?: string | undefined;
+        limit?: number | undefined;
+        filters?: {
+            type?: "query" | "user" | "global" | undefined;
+            query?: string | undefined;
+            category?: string | undefined;
+            createdBy?: string | undefined;
+            tags?: string[] | undefined;
+        } | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
+        tags?: string[] | undefined;
+        content?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    operation: "create" | "getOne" | "update" | "delete" | "getAll" | "search" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
+    data?: {
+        id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
+        query?: string | undefined;
+        title?: string | undefined;
+        category?: string | undefined;
+        userId?: string | undefined;
+        limit?: number | undefined;
+        filters?: {
+            type?: "query" | "user" | "global" | undefined;
+            query?: string | undefined;
+            category?: string | undefined;
+            createdBy?: string | undefined;
+            tags?: string[] | undefined;
+        } | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
+        tags?: string[] | undefined;
+        content?: string | undefined;
+    } | undefined;
+}, {
+    operation: "create" | "getOne" | "update" | "delete" | "getAll" | "search" | "getByCategory" | "getByUser" | "getCategories" | "getTags";
+    data?: {
+        id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
+        query?: string | undefined;
+        title?: string | undefined;
+        category?: string | undefined;
+        userId?: string | undefined;
+        limit?: number | undefined;
+        filters?: {
+            type?: "query" | "user" | "global" | undefined;
+            query?: string | undefined;
+            category?: string | undefined;
+            createdBy?: string | undefined;
+            tags?: string[] | undefined;
+        } | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
+        tags?: string[] | undefined;
+        content?: string | undefined;
+    } | undefined;
+}>;
+type KbNodesRequestPayload = z.infer<typeof KbNodesRequestPayloadSchema>;
+interface T_RESPONSE {
+    success: boolean;
+    data?: any;
+    errors: string[];
 }
 
 /**
@@ -847,6 +1310,7 @@ type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
 interface LLMMessages {
     sys: SystemPrompt;
     user: string;
+    prefill?: string;
 }
 interface LLMOptions {
     model?: string;
@@ -899,6 +1363,11 @@ declare class LLM {
     private static _groqStream;
     private static _geminiText;
     private static _geminiStream;
+    /**
+     * Recursively strip unsupported JSON Schema properties for Gemini
+     * Gemini doesn't support: additionalProperties, $schema, etc.
+     */
+    private static _cleanSchemaForGemini;
     private static _geminiStreamWithTools;
     private static _openaiText;
     private static _openaiStream;
@@ -1318,15 +1787,17 @@ declare const STORAGE_CONFIG: {
      */
     MAX_ROWS_PER_BLOCK: number;
     /**
-     * Maximum size in bytes per UIBlock (1MB)
+     * Maximum size in bytes per UIBlock (500KB - reduced to save memory)
      */
     MAX_SIZE_PER_BLOCK_BYTES: number;
     /**
      * Number of days to keep threads before cleanup
+     * Note: This is for in-memory storage. Conversations are also persisted to database.
      */
     THREAD_RETENTION_DAYS: number;
     /**
      * Number of days to keep UIBlocks before cleanup
+     * Note: This is for in-memory storage. Data is also persisted to database.
      */
     UIBLOCK_RETENTION_DAYS: number;
 };
@@ -1343,14 +1814,941 @@ declare const CONTEXT_CONFIG: {
     MAX_CONVERSATION_CONTEXT_BLOCKS: number;
 };
 
-declare const SDK_VERSION = "0.0.8";
+/**
+ * LLM Usage Logger - Tracks token usage, costs, and timing for all LLM API calls
+ */
+interface LLMUsageEntry {
+    timestamp: string;
+    requestId: string;
+    provider: string;
+    model: string;
+    method: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    totalTokens: number;
+    costUSD: number;
+    durationMs: number;
+    toolCalls?: number;
+    success: boolean;
+    error?: string;
+}
+declare class LLMUsageLogger {
+    private logStream;
+    private logPath;
+    private enabled;
+    private sessionStats;
+    constructor();
+    private initLogStream;
+    private writeHeader;
+    /**
+     * Calculate cost based on token usage and model
+     */
+    calculateCost(model: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number): number;
+    /**
+     * Log an LLM API call
+     */
+    log(entry: LLMUsageEntry): void;
+    /**
+     * Log session summary (call at end of request)
+     */
+    logSessionSummary(requestContext?: string): void;
+    /**
+     * Reset session stats (call at start of new user request)
+     */
+    resetSession(): void;
+    /**
+     * Reset the log file for a new request (clears previous logs)
+     * Call this at the start of each USER_PROMPT_REQ
+     */
+    resetLogFile(requestContext?: string): void;
+    /**
+     * Get current session stats
+     */
+    getSessionStats(): {
+        totalCalls: number;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalCacheReadTokens: number;
+        totalCacheWriteTokens: number;
+        totalCostUSD: number;
+        totalDurationMs: number;
+    };
+    /**
+     * Generate a unique request ID
+     */
+    generateRequestId(): string;
+}
+declare const llmUsageLogger: LLMUsageLogger;
+
+/**
+ * User Prompt Error Logger - Captures detailed errors for USER_PROMPT_REQ
+ * Logs full error details including raw strings for parse failures
+ */
+declare class UserPromptErrorLogger {
+    private logStream;
+    private logPath;
+    private enabled;
+    private hasErrors;
+    constructor();
+    /**
+     * Reset the error log file for a new request
+     */
+    resetLogFile(requestContext?: string): void;
+    /**
+     * Log a JSON parse error with the raw string that failed
+     */
+    logJsonParseError(context: string, rawString: string, error: Error): void;
+    /**
+     * Log a general error with full details
+     */
+    logError(context: string, error: Error | string, additionalData?: Record<string, any>): void;
+    /**
+     * Log a SQL query error with the full query
+     */
+    logSqlError(query: string, error: Error | string, params?: any[]): void;
+    /**
+     * Log an LLM API error
+     */
+    logLlmError(provider: string, model: string, method: string, error: Error | string, requestData?: any): void;
+    /**
+     * Log tool execution error
+     */
+    logToolError(toolName: string, toolInput: any, error: Error | string): void;
+    /**
+     * Write final summary if there were errors
+     */
+    writeSummary(): void;
+    /**
+     * Check if any errors were logged
+     */
+    hadErrors(): boolean;
+    private write;
+}
+declare const userPromptErrorLogger: UserPromptErrorLogger;
+
+/**
+ * BM25L Reranker for hybrid semantic search
+ *
+ * BM25L is an improved variant of BM25 that provides better handling of
+ * long documents and term frequency saturation. This implementation is
+ * designed to rerank semantic search results from ChromaDB.
+ *
+ * The hybrid approach combines:
+ * 1. Semantic similarity from ChromaDB embeddings (dense vectors)
+ * 2. Lexical matching from BM25L (sparse, keyword-based)
+ *
+ * This addresses the weakness of pure semantic search which may miss
+ * exact keyword matches that are important for user intent.
+ */
+interface BM25LOptions {
+    /** Term frequency saturation parameter (default: 1.5) */
+    k1?: number;
+    /** Length normalization parameter (default: 0.75) */
+    b?: number;
+    /** Lower-bound adjustment from BM25L paper (default: 0.5) */
+    delta?: number;
+}
+interface RerankedResult<T> {
+    item: T;
+    originalIndex: number;
+    semanticScore: number;
+    bm25Score: number;
+    hybridScore: number;
+}
+interface HybridSearchOptions extends BM25LOptions {
+    /** Weight for semantic score (0-1, default: 0.7) */
+    semanticWeight?: number;
+    /** Weight for BM25 score (0-1, default: 0.3) */
+    bm25Weight?: number;
+    /** Minimum hybrid score threshold (0-1, default: 0) */
+    minScore?: number;
+}
+/**
+ * BM25L implementation for lexical scoring
+ */
+declare class BM25L {
+    private k1;
+    private b;
+    private delta;
+    private documents;
+    private docLengths;
+    private avgDocLength;
+    private termDocFreq;
+    /**
+     * @param documents - Array of raw documents (strings)
+     * @param opts - Optional BM25L parameters
+     */
+    constructor(documents?: string[], opts?: BM25LOptions);
+    /**
+     * Tokenize text into lowercase alphanumeric tokens
+     */
+    tokenize(text: string): string[];
+    /**
+     * Compute IDF (Inverse Document Frequency) with smoothing
+     */
+    private idf;
+    /**
+     * Compute BM25L score for a single document
+     */
+    score(query: string, docIndex: number): number;
+    /**
+     * Search and rank all documents
+     */
+    search(query: string): Array<{
+        index: number;
+        score: number;
+    }>;
+}
+/**
+ * Hybrid reranker that combines semantic and BM25L scores
+ *
+ * @param query - The search query
+ * @param items - Array of items to rerank
+ * @param getDocument - Function to extract document text from an item
+ * @param getSemanticScore - Function to extract semantic similarity score from an item
+ * @param options - Hybrid search options
+ * @returns Reranked items with hybrid scores
+ */
+declare function hybridRerank<T>(query: string, items: T[], getDocument: (item: T) => string, getSemanticScore: (item: T) => number, options?: HybridSearchOptions): RerankedResult<T>[];
+/**
+ * Simple reranking function for ChromaDB results
+ *
+ * This is a convenience wrapper for reranking ChromaDB query results
+ * that follow the standard { ids, documents, metadatas, distances } format.
+ *
+ * @param query - The search query
+ * @param chromaResults - ChromaDB query results
+ * @param options - Hybrid search options
+ * @returns Reranked results with hybrid scores
+ */
+declare function rerankChromaResults(query: string, chromaResults: {
+    ids: string[][];
+    documents: (string | null)[][];
+    metadatas: Record<string, any>[][];
+    distances: number[][];
+}, options?: HybridSearchOptions): Array<{
+    id: string;
+    document: string | null;
+    metadata: Record<string, any>;
+    distance: number;
+    semanticScore: number;
+    bm25Score: number;
+    hybridScore: number;
+}>;
+/**
+ * Rerank conversation search results specifically
+ *
+ * This function is designed to work with the conversation-history.search collection
+ * where we need to fetch more results initially and then rerank them.
+ *
+ * @param query - The user's search query
+ * @param results - Array of conversation search results from ChromaDB
+ * @param options - Hybrid search options
+ * @returns Reranked results sorted by hybrid score
+ */
+declare function rerankConversationResults<T extends {
+    userPrompt?: string;
+    similarity?: number;
+}>(query: string, results: T[], options?: HybridSearchOptions): Array<T & {
+    hybridScore: number;
+    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>;
+}
+
+/**
+ * StreamBuffer - Buffered streaming utility for smoother text delivery
+ * Batches small chunks together and flushes at regular intervals
+ */
+type StreamCallback = (chunk: string) => void;
+/**
+ * StreamBuffer class for managing buffered streaming output
+ * Provides smooth text delivery by batching small chunks
+ */
+declare class StreamBuffer {
+    private buffer;
+    private flushTimer;
+    private callback;
+    private fullText;
+    constructor(callback?: StreamCallback);
+    /**
+     * Check if the buffer has a callback configured
+     */
+    hasCallback(): boolean;
+    /**
+     * Get all text that has been written (including already flushed)
+     */
+    getFullText(): string;
+    /**
+     * Write a chunk to the buffer
+     * Large chunks or chunks with newlines are flushed immediately
+     * Small chunks are batched and flushed after a short interval
+     *
+     * @param chunk - Text chunk to write
+     */
+    write(chunk: string): void;
+    /**
+     * Flush the buffer immediately
+     * Call this before tool execution or other operations that need clean output
+     */
+    flush(): void;
+    /**
+     * Internal flush implementation
+     */
+    private flushNow;
+    /**
+     * Clean up resources
+     * Call this when done with the buffer
+     */
+    dispose(): void;
+}
+
+/**
+ * ToolExecutorService - Handles execution of SQL queries and external tools
+ * Extracted from BaseLLM.generateTextResponse for better separation of concerns
+ */
+
+/**
+ * External tool definition
+ */
+interface ExternalTool {
+    id: string;
+    name: string;
+    description?: string;
+    /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
+    toolType?: 'source' | 'direct';
+    /** Full untruncated schema for source agent (all columns visible) */
+    fullSchema?: string;
+    /** Schema size tier: small (≤50 tables), medium (51-200), large (201-500), very_large (500+) */
+    schemaTier?: string;
+    /** Schema search function for very_large tier — keyword search over entities */
+    schemaSearchFn?: (keywords: string[]) => string;
+    fn: (input: any) => Promise<any>;
+    limit?: number;
+    outputSchema?: any;
+    executionType?: 'immediate' | 'deferred';
+    userProvidedData?: any;
+    params?: Record<string, any>;
+}
+/**
+ * Executed tool tracking info
+ */
+interface ExecutedToolInfo {
+    id: string;
+    name: string;
+    params: any;
+    result: {
+        _totalRecords: number;
+        _recordsShown: number;
+        _metadata?: any;
+        _sampleData: any[];
+    };
+    outputSchema?: any;
+    sourceSchema?: string;
+    sourceType?: string;
+}
+
+/**
+ * Task types for model selection
+ * - 'complex': Text generation, component matching, parameter adaptation (uses best model in balanced mode)
+ * - 'simple': Classification, action generation (uses fast model in balanced mode)
+ */
+type TaskType = 'complex' | 'simple';
+interface BaseLLMConfig {
+    model?: string;
+    fastModel?: string;
+    defaultLimit?: number;
+    apiKey?: string;
+    /**
+     * Model selection strategy:
+     * - 'best': Use best model for all tasks (highest quality, higher cost)
+     * - 'fast': Use fast model for all tasks (lower quality, lower cost)
+     * - 'balanced': Use best model for complex tasks, fast model for simple tasks (default)
+     */
+    modelStrategy?: ModelStrategy;
+    conversationSimilarityThreshold?: number;
+}
+/**
+ * BaseLLM abstract class for AI-powered component generation and matching
+ * Provides common functionality for all LLM providers
+ */
+declare abstract class BaseLLM {
+    protected model: string;
+    protected fastModel: string;
+    protected defaultLimit: number;
+    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
+     * @param taskType - 'complex' for text generation/matching, 'simple' for classification/actions
+     * @returns The model string to use for this task
+     */
+    protected getModelForTask(taskType: TaskType): string;
+    /**
+     * Set the model strategy at runtime
+     * @param strategy - 'best', 'fast', or 'balanced'
+     */
+    setModelStrategy(strategy: ModelStrategy): void;
+    /**
+     * Get the current model strategy
+     * @returns The current model strategy
+     */
+    getModelStrategy(): ModelStrategy;
+    /**
+     * Set the conversation similarity threshold at runtime
+     * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     */
+    setConversationSimilarityThreshold(threshold: number): void;
+    /**
+     * Get the current conversation similarity threshold
+     * @returns The current threshold value
+     */
+    getConversationSimilarityThreshold(): number;
+    /**
+     * Get the default model for this provider (used for complex tasks like text generation)
+     */
+    protected abstract getDefaultModel(): string;
+    /**
+     * Get the default fast model for this provider (used for simple tasks: classification, matching, actions)
+     * Should return a cheaper/faster model like Haiku for Anthropic
+     */
+    protected abstract getDefaultFastModel(): string;
+    /**
+     * Get the default API key from environment
+     */
+    protected abstract getDefaultApiKey(): string | undefined;
+    /**
+     * Get the provider name (for logging)
+     */
+    protected abstract getProviderName(): string;
+    /**
+     * Get the API key (from instance, parameter, or environment)
+     */
+    protected getApiKey(apiKey?: string): string | undefined;
+    /**
+     * Check if a component contains a Form (data_modification component)
+     * Forms have hardcoded defaultValues that become stale when cached
+     * This checks both single Form components and Forms inside MultiComponentContainer
+     */
+    protected containsFormComponent(component: any): boolean;
+    /**
+     * 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
+     * Also generates title, description, and intelligent follow-up questions (actions) based on the analysis
+     * All components are placed in a default MultiComponentContainer layout
+     * @param analysisContent - The text response containing component suggestions
+     * @param components - List of available components
+     * @param apiKey - Optional API key
+     * @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, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
+        components: Component[];
+        layoutTitle: string;
+        layoutDescription: string;
+        actions: Action[];
+    }>;
+    /**
+     * 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, conversationHistory?: string, externalTools?: any[]): Promise<{
+        category: 'data_analysis' | 'data_modification' | 'general';
+        externalTools: Array<{
+            type: string;
+            name: string;
+            description: string;
+            parameters: Record<string, any>;
+        }>;
+        dataAnalysisType?: 'visualization' | 'calculation' | 'comparison' | 'trend';
+        reasoning: string;
+        confidence: number;
+    }>;
+    /**
+     * Adapt UI block parameters based on current user question
+     * 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, cachedTextResponse?: string): Promise<{
+        success: boolean;
+        adaptedComponent?: Component;
+        adaptedTextResponse?: string;
+        parametersChanged?: Array<{
+            field: string;
+            reason: string;
+        }>;
+        explanation: string;
+    }>;
+    /**
+     * Generate text-based response for user question
+     * 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
+     */
+    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):
+     * 1. Semantic search: Check previous conversations (>60% match)
+     *    - 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
+     */
+    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, conversationHistory?: string, textResponse?: string): Promise<string[]>;
+}
+
+interface AnthropicLLMConfig extends BaseLLMConfig {
+}
+/**
+ * AnthropicLLM class for handling AI-powered component generation and matching using Anthropic Claude
+ */
+declare class AnthropicLLM extends BaseLLM {
+    constructor(config?: AnthropicLLMConfig);
+    protected getDefaultModel(): string;
+    protected getDefaultFastModel(): string;
+    protected getDefaultApiKey(): string | undefined;
+    protected getProviderName(): string;
+}
+declare const anthropicLLM: AnthropicLLM;
+
+interface GroqLLMConfig extends BaseLLMConfig {
+}
+/**
+ * GroqLLM class for handling AI-powered component generation and matching using Groq
+ */
+declare class GroqLLM extends BaseLLM {
+    constructor(config?: GroqLLMConfig);
+    protected getDefaultModel(): string;
+    protected getDefaultFastModel(): string;
+    protected getDefaultApiKey(): string | undefined;
+    protected getProviderName(): string;
+}
+declare const groqLLM: GroqLLM;
+
+interface GeminiLLMConfig extends BaseLLMConfig {
+}
+/**
+ * GeminiLLM class for handling AI-powered component generation and matching using Google Gemini
+ */
+declare class GeminiLLM extends BaseLLM {
+    constructor(config?: GeminiLLMConfig);
+    protected getDefaultModel(): string;
+    protected getDefaultFastModel(): string;
+    protected getDefaultApiKey(): string | undefined;
+    protected getProviderName(): string;
+}
+declare const geminiLLM: GeminiLLM;
+
+interface OpenAILLMConfig extends BaseLLMConfig {
+}
+/**
+ * OpenAILLM class for handling AI-powered component generation and matching using OpenAI GPT models
+ */
+declare class OpenAILLM extends BaseLLM {
+    constructor(config?: OpenAILLMConfig);
+    protected getDefaultModel(): string;
+    protected getDefaultFastModel(): string;
+    protected getDefaultApiKey(): string | undefined;
+    protected getProviderName(): string;
+}
+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 queryIdCache;
+    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;
+    /**
+     * Generate a unique query ID
+     */
+    private generateQueryId;
+    /**
+     * Store a query by ID. Returns the generated queryId.
+     * The query is stored server-side; only the queryId is sent to the frontend.
+     */
+    storeQuery(query: any, data?: any): string;
+    /**
+     * Get a stored query by its ID (not expired)
+     */
+    getQuery(queryId: string): {
+        query: any;
+        data: any;
+    } | null;
+    /**
+     * Update cached data for a queryId
+     */
+    setQueryData(queryId: string, data: any): void;
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    destroy(): void;
+}
+declare const queryCache: QueryCache;
+
+/**
+ * Manages conversation history scoped per user + dashboard.
+ * Each user-dashboard pair has its own isolated history that expires after a configurable TTL.
+ */
+declare class DashboardConversationHistory {
+    private histories;
+    private ttlMs;
+    private maxEntries;
+    private cleanupInterval;
+    constructor();
+    /**
+     * Set the TTL for dashboard histories
+     * @param minutes - TTL in minutes
+     */
+    setTTL(minutes: number): void;
+    /**
+     * Set max entries per dashboard
+     */
+    setMaxEntries(max: number): void;
+    /**
+     * Add a conversation entry for a user's dashboard
+     */
+    addEntry(dashboardId: string, userPrompt: string, componentSummary: string, userId?: string): void;
+    /**
+     * Get formatted conversation history for a user's dashboard
+     */
+    getHistory(dashboardId: string, userId?: string): string;
+    /**
+     * Clear history for a specific user's dashboard
+     */
+    clearDashboard(dashboardId: string, userId?: string): void;
+    /**
+     * Clear all dashboard histories
+     */
+    clearAll(): void;
+    /**
+     * Start periodic cleanup of expired histories
+     */
+    private startCleanup;
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    destroy(): void;
+}
+declare const dashboardConversationHistory: DashboardConversationHistory;
+
+/**
+ * Multi-Agent Architecture Types
+ *
+ * Defines interfaces for the hierarchical agent system:
+ * - Main Agent: ONE LLM.streamWithTools() call with source agent tools
+ * - Source Agents: independent agents that query individual data sources
+ *
+ * The main agent sees only source summaries. When it calls a source tool,
+ * the SourceAgent runs independently (own LLM, own retries) and returns clean data.
+ */
+
+/**
+ * Per-entity detail: name, row count, and column names.
+ * Gives the main agent enough context to route to the right source.
+ */
+interface EntityDetail {
+    /** Entity name (table, sheet, endpoint) */
+    name: string;
+    /** Approximate row count */
+    rowCount?: number;
+    /** Column/field names */
+    columns: string[];
+}
+/**
+ * Representation of a data source for the main agent.
+ * Contains entity names WITH column names so the LLM can route accurately.
+ */
+interface SourceSummary {
+    /** Source ID (matches tool ID prefix) */
+    id: string;
+    /** Human-readable source name */
+    name: string;
+    /** Source type: postgres, excel, rest_api, etc. */
+    type: string;
+    /** Brief description of what data this source contains */
+    description: string;
+    /** Detailed entity info with column names for routing */
+    entityDetails: EntityDetail[];
+    /** The tool ID associated with this source */
+    toolId: string;
+}
+/**
+ * What a source agent returns after querying its data source.
+ * The main agent uses this to analyze and compose the final response.
+ */
+interface SourceAgentResult {
+    /** Source ID */
+    sourceId: string;
+    /** Source name */
+    sourceName: string;
+    /** Whether the query succeeded */
+    success: boolean;
+    /** Result data rows */
+    data: any[];
+    /** Metadata about the query execution */
+    metadata: SourceAgentMetadata;
+    /** Tool execution info (reused for component generation) */
+    executedTool: ExecutedToolInfo;
+    /** Error message if failed */
+    error?: string;
+}
+interface SourceAgentMetadata {
+    /** Total rows that matched the query (before limit) */
+    totalRowsMatched: number;
+    /** Rows actually returned (after limit) */
+    rowsReturned: number;
+    /** Whether the result was truncated by the row limit */
+    isLimited: boolean;
+    /** The query/params that were executed */
+    queryExecuted?: string;
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * The complete response from the multi-agent system.
+ * Contains everything needed for text display + component generation.
+ */
+interface AgentResponse {
+    /** Generated text response (analysis of the data) */
+    text: string;
+    /** All executed tools across all source agents (for component generation) */
+    executedTools: ExecutedToolInfo[];
+    /** Individual results from each source agent */
+    sourceResults: SourceAgentResult[];
+}
+/**
+ * Configuration for the multi-agent system.
+ * Controls limits, models, and behavior.
+ */
+interface AgentConfig {
+    /** Max rows a source agent can return (default: 50) */
+    maxRowsPerSource: number;
+    /** Model for the main agent (routing + analysis in one LLM call) */
+    mainAgentModel: string;
+    /** Model for source agent query generation */
+    sourceAgentModel: string;
+    /** API key for LLM calls */
+    apiKey?: string;
+    /** Max retry attempts per source agent */
+    maxRetries: number;
+    /** Max tool calling iterations for the main agent loop */
+    maxIterations: number;
+    /** Global knowledge base context (static, same for all users/questions — cached in system prompt) */
+    globalKnowledgeBase?: string;
+    /** Per-request knowledge base context (user-specific + query-matched — dynamic, not cached) */
+    knowledgeBaseContext?: string;
+}
+/**
+ * Default agent configuration
+ */
+declare const DEFAULT_AGENT_CONFIG: AgentConfig;
+
+/**
+ * Main Agent (Orchestrator)
+ *
+ * A single LLM.streamWithTools() call that handles everything:
+ * - Routing: decides which source(s) to query based on summaries
+ * - Querying: calls source tools (each wraps an independent SourceAgent)
+ * - Direct tools: calls pre-built function tools directly with LLM-provided params
+ * - Re-querying: if data is wrong/incomplete, calls tools again with modified intent
+ * - Analysis: generates final text response from the data
+ *
+ * Two tool types:
+ * - "source" tools: main agent sees summaries, SourceAgent handles SQL generation independently
+ * - "direct" tools: main agent calls fn() directly with structured params (no SourceAgent)
+ */
+
+declare class MainAgent {
+    private externalTools;
+    private config;
+    private streamBuffer;
+    constructor(externalTools: ExternalTool[], config: AgentConfig, streamBuffer?: StreamBuffer);
+    /**
+     * Handle a user question using the multi-agent system.
+     *
+     * This is ONE LLM.streamWithTools() call. The LLM:
+     * 1. Sees source summaries + direct tool descriptions in system prompt
+     * 2. Decides which tool(s) to call (routing)
+     * 3. Source tools → SourceAgent runs independently → returns data
+     * 4. Direct tools → fn() called directly with LLM params → returns data
+     * 5. Generates final analysis text
+     */
+    handleQuestion(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void): Promise<AgentResponse>;
+    /**
+     * Execute a direct tool — call fn() with LLM-provided params, no SourceAgent.
+     */
+    private handleDirectTool;
+    /**
+     * Build the main agent's system prompt with source summaries and direct tool descriptions.
+     */
+    private buildSystemPrompt;
+    /**
+     * Build tool definitions for source tools — summary-only descriptions.
+     * The full schema is inside the SourceAgent which runs independently.
+     */
+    private buildSourceToolDefinitions;
+    /**
+     * Build tool definitions for direct tools — expose their actual params.
+     * These are called directly by the main agent LLM, no SourceAgent.
+     */
+    private buildDirectToolDefinitions;
+    /**
+     * Format a source agent's result as a clean string for the main agent LLM.
+     */
+    private formatResultForMainAgent;
+    /**
+     * Get source summaries (for external inspection/debugging).
+     */
+    getSourceSummaries(): SourceSummary[];
+}
+
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
     private url;
     private apiKey?;
     private projectId;
-    private userId;
     private type;
     private bundleDir;
     private messageHandlers;
@@ -1366,9 +2764,18 @@ declare class SuperatomSDK {
     private geminiApiKey;
     private openaiApiKey;
     private llmProviders;
+    private databaseType;
+    private modelStrategy;
+    private mainAgentModel;
+    private sourceAgentModel;
+    private conversationSimilarityThreshold;
     private userManager;
     private dashboardManager;
     private reportManager;
+    private pingInterval;
+    private lastPong;
+    private readonly PING_INTERVAL_MS;
+    private readonly PONG_TIMEOUT_MS;
     constructor(config: SuperatomSDKConfig);
     /**
      * Initialize PromptLoader and load prompts into memory
@@ -1408,9 +2815,11 @@ declare class SuperatomSDK {
      */
     private handleMessage;
     /**
-     * Send a message to the Superatom service
+     * Send a message to the Superatom service.
+     * Returns true if the message was sent, false if the WebSocket is not connected.
+     * Does NOT throw on closed connections — callers can check the return value if needed.
      */
-    send(message: Message): void;
+    send(message: Message): boolean;
     /**
      * Register a message handler to receive all messages
      */
@@ -1436,6 +2845,19 @@ declare class SuperatomSDK {
      */
     addCollection<TParams = any, TResult = any>(collectionName: string, operation: CollectionOperation | string, handler: CollectionHandler<TParams, TResult>): void;
     private handleReconnect;
+    /**
+     * Start heartbeat to keep WebSocket connection alive
+     * Sends PING every 3 minutes to prevent idle timeout from cloud infrastructure
+     */
+    private startHeartbeat;
+    /**
+     * Stop the heartbeat interval
+     */
+    private stopHeartbeat;
+    /**
+     * Handle PONG response from server
+     */
+    private handlePong;
     private storeComponents;
     /**
      * Set tools for the SDK instance
@@ -1445,6 +2867,34 @@ declare class SuperatomSDK {
      * Get the stored tools
      */
     getTools(): Tool$1[];
+    /**
+     * Apply model strategy to all LLM provider singletons
+     * @param strategy - 'best', 'fast', or 'balanced'
+     */
+    private applyModelStrategy;
+    /**
+     * Set model strategy at runtime
+     * @param strategy - 'best', 'fast', or 'balanced'
+     */
+    setModelStrategy(strategy: ModelStrategy): void;
+    /**
+     * Get current model strategy
+     */
+    getModelStrategy(): ModelStrategy;
+    /**
+     * Apply conversation similarity threshold to all LLM provider singletons
+     * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     */
+    private applyConversationSimilarityThreshold;
+    /**
+     * Set conversation similarity threshold at runtime
+     * @param threshold - Value between 0 and 1 (e.g., 0.8 = 80% similarity required)
+     */
+    setConversationSimilarityThreshold(threshold: number): void;
+    /**
+     * Get current conversation similarity threshold
+     */
+    getConversationSimilarityThreshold(): number;
 }
 
-export { type Action, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type IncomingMessage, LLM, type LogLevel, type Message, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, Thread, ThreadManager, type Tool$1 as Tool, UIBlock, UILogCollector, type User, UserManager, type UsersData, logger };
+export { type Action, type AgentConfig, type AgentResponse, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, 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, dashboardConversationHistory, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };