@superatomai/sdk-node 0.0.11 → 0.0.12-mds

package/dist/index.d.mts

@@ -1,4 +1,16 @@
 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
@@ -47,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;
 
@@ -78,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>;
@@ -117,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;
@@ -127,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;
@@ -141,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;
@@ -151,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>>;
@@ -169,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;
@@ -179,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;
@@ -197,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;
@@ -207,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;
@@ -280,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;
@@ -290,7 +366,6 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
             deps?: string[] | undefined;
         }[] | undefined;
         data?: Record<string, any> | undefined;
-        render?: any;
     }, {
         id: string;
         name?: string | undefined;
@@ -304,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;
@@ -314,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>>;
@@ -332,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;
@@ -342,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;
@@ -360,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;
@@ -370,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;
@@ -383,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;
@@ -390,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;
@@ -397,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>;
@@ -407,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;
@@ -414,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;
@@ -421,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, {
@@ -430,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;
     }[];
 }, {
@@ -439,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;
     }[];
 }>;
@@ -543,22 +626,407 @@ 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';
+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;
+    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;
+    /**
+     * 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;
+}
+
+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[];
 }
 
 /**
@@ -820,9 +1288,11 @@ declare class ReportManager {
     getReportCount(): number;
 }
 
+type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
 interface LLMMessages {
-    sys: string;
+    sys: SystemPrompt;
     user: string;
+    prefill?: string;
 }
 interface LLMOptions {
     model?: string;
@@ -845,6 +1315,18 @@ declare class LLM {
     static text(messages: LLMMessages, options?: LLMOptions): Promise<string>;
     static stream<T = string>(messages: LLMMessages, options?: LLMOptions, json?: boolean): Promise<T extends string ? string : any>;
     static streamWithTools(messages: LLMMessages, tools: Tool[], toolHandler: (toolName: string, toolInput: any) => Promise<any>, options?: LLMOptions, maxIterations?: number): Promise<string>;
+    /**
+     * Normalize system prompt to Anthropic format
+     * Converts string to array format if needed
+     * @param sys - System prompt (string or array of blocks)
+     * @returns Normalized system prompt for Anthropic API
+     */
+    private static _normalizeSystemPrompt;
+    /**
+     * Log cache usage metrics from Anthropic API response
+     * Shows cache hits, costs, and savings
+     */
+    private static _logCacheUsage;
     /**
      * Parse model string to extract provider and model name
      * @param modelString - Format: "provider/model-name" or just "model-name"
@@ -861,6 +1343,17 @@ declare class LLM {
     private static _anthropicStreamWithTools;
     private static _groqText;
     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;
+    private static _openaiStreamWithTools;
     /**
      * Parse JSON string, handling markdown code blocks and surrounding text
      * Enhanced version with jsonrepair to handle malformed JSON from LLMs
@@ -1276,15 +1769,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;
 };
@@ -1301,14 +1796,632 @@ 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>;
+}
+
+/**
+ * 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;
+
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
     private url;
-    private apiKey;
+    private apiKey?;
     private projectId;
-    private userId;
     private type;
     private bundleDir;
     private messageHandlers;
@@ -1318,12 +2431,22 @@ declare class SuperatomSDK {
     private maxReconnectAttempts;
     private collections;
     private components;
+    private tools;
     private anthropicApiKey;
     private groqApiKey;
+    private geminiApiKey;
+    private openaiApiKey;
     private llmProviders;
+    private databaseType;
+    private modelStrategy;
+    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
@@ -1363,9 +2486,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
      */
@@ -1391,7 +2516,56 @@ 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
+     */
+    setTools(tools: Tool$1[]): void;
+    /**
+     * 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, UIBlock, UILogCollector, type User, UserManager, type UsersData, logger };
+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 };