@superatomai/sdk-node 0.0.48 → 0.0.49-mds

package/dist/index.d.mts

@@ -59,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;
 
@@ -623,19 +634,19 @@ declare const ComponentSchema: z.ZodObject<{
     type: z.ZodString;
     description: z.ZodString;
     props: z.ZodObject<{
-        query: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+        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.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+        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.ZodUnion<[z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+        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>>;
@@ -650,7 +661,7 @@ declare const ComponentSchema: z.ZodObject<{
     description: string;
     props: {
         description?: string | undefined;
-        query?: string | {} | undefined;
+        query?: string | {} | null | undefined;
         title?: string | undefined;
         config?: Record<string, unknown> | undefined;
         actions?: any[] | undefined;
@@ -668,7 +679,7 @@ declare const ComponentSchema: z.ZodObject<{
     description: string;
     props: {
         description?: string | undefined;
-        query?: string | {} | undefined;
+        query?: string | {} | null | undefined;
         title?: string | undefined;
         config?: Record<string, unknown> | undefined;
         actions?: any[] | undefined;
@@ -730,6 +741,10 @@ 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<{
@@ -762,12 +777,22 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     }>>;
+    /** Cache policy. `false` = never cache (live data, write ops). Mirrors HTTP `Cache-Control: no-store`. */
+    cache: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<false>, z.ZodObject<{
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        ttlMs?: number | undefined;
+    }, {
+        ttlMs?: number | undefined;
+    }>]>>;
 }, "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: {
@@ -776,12 +801,17 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | 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: {
@@ -790,6 +820,9 @@ declare const ToolSchema: z.ZodObject<{
             description: string;
         }[];
     } | undefined;
+    cache?: false | {
+        ttlMs?: number | undefined;
+    } | undefined;
 }>;
 type Tool$1 = z.infer<typeof ToolSchema>;
 type CollectionOperation = 'getMany' | 'getOne' | 'query' | 'mutation' | 'updateOne' | 'deleteOne' | 'createOne';
@@ -841,27 +874,61 @@ interface SuperatomSDKConfig {
      * - '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">>;
-    createdBy: z.ZodOptional<z.ZodNumber>;
+    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?: number | undefined;
+    createdBy?: string | undefined;
     tags?: string[] | undefined;
 }, {
+    type?: "query" | "user" | "global" | undefined;
     query?: string | undefined;
     category?: string | undefined;
-    createdBy?: number | undefined;
+    createdBy?: string | undefined;
     tags?: string[] | undefined;
 }>;
 type KbNodesQueryFilters = z.infer<typeof KbNodesQueryFiltersSchema>;
@@ -873,106 +940,118 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
         content: z.ZodOptional<z.ZodString>;
         category: z.ZodOptional<z.ZodString>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        createdBy: z.ZodOptional<z.ZodNumber>;
-        updatedBy: z.ZodOptional<z.ZodNumber>;
-        userId: z.ZodOptional<z.ZodNumber>;
+        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">>;
-            createdBy: z.ZodOptional<z.ZodNumber>;
+            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?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         }, {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | 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?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
-        offset?: number | undefined;
     }, {
         id?: number | undefined;
+        type?: "query" | "user" | "global" | undefined;
         query?: string | undefined;
         title?: string | undefined;
         category?: string | undefined;
-        userId?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
-        offset?: number | 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?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
-        offset?: number | 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?: number | undefined;
+        userId?: string | undefined;
         limit?: number | undefined;
         filters?: {
+            type?: "query" | "user" | "global" | undefined;
             query?: string | undefined;
             category?: string | undefined;
-            createdBy?: number | undefined;
+            createdBy?: string | undefined;
             tags?: string[] | undefined;
         } | undefined;
-        createdBy?: number | undefined;
-        updatedBy?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        offset?: number | undefined;
         tags?: string[] | undefined;
         content?: string | undefined;
-        offset?: number | undefined;
     } | undefined;
 }>;
 type KbNodesRequestPayload = z.infer<typeof KbNodesRequestPayloadSchema>;
@@ -1241,6 +1320,360 @@ declare class ReportManager {
     getReportCount(): number;
 }
 
+/**
+ * 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;
+}
+
+/**
+ * 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 for the last successful query (backward compat) */
+    executedTool: ExecutedToolInfo;
+    /** All successful tool executions (primary + follow-up queries) */
+    allExecutedTools?: 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;
+}
+/**
+ * A pre-built, multi-step UI flow registered with the SDK.
+ *
+ * When the main agent decides a user's question matches a workflow's whenToUse
+ * trigger, it picks the workflow instead of running source agents / generating
+ * dashboard components. The LLM extracts the workflow's required props from the
+ * prompt (using `propsSchema` as the tool input_schema) and the SDK returns the
+ * workflow component directly — no analysis text, no chart generation. The
+ * frontend renders the registered workflow component with the LLM-extracted
+ * props.
+ */
+interface WorkflowDescriptor {
+    /** Unique workflow id (used as the LLM tool name) */
+    id: string;
+    /** Component name on the frontend (matches the registered React component) */
+    name: string;
+    /** Short human-readable description of what this workflow does */
+    description: string;
+    /**
+     * 1–2 sentence trigger condition. The LLM uses this to decide if the
+     * user's prompt matches this workflow. Be specific — e.g.
+     * "User wants to *initiate* an inventory transfer (review + submit POs),
+     * not just see analysis or charts."
+     */
+    whenToUse: string;
+    /**
+     * JSON-schema-style description of the props the workflow needs. Becomes
+     * the LLM tool's input_schema, so the model fills these from the prompt.
+     * Use the same shape as `params` on direct tools — string descriptors with
+     * an optional "(optional)" suffix.
+     *
+     * Example:
+     * ```
+     * {
+     *   selectedStore: 'object — { id, name } of the source branch',
+     *   minROI: 'number (optional) — only show transfers with ROI ≥ this',
+     * }
+     * ```
+     */
+    propsSchema: Record<string, string>;
+    /**
+     * Optional: static prop defaults merged with LLM-extracted props before
+     * the component is returned. Useful for things like the embedded
+     * `externalTool` config that the workflow uses to fetch its own data.
+     */
+    defaultProps?: Record<string, any>;
+}
+/**
+ * The workflow selection captured during a routing call.
+ * Set on AgentResponse when the LLM picks a workflow tool.
+ */
+interface SelectedWorkflow {
+    /** Component name (matches WorkflowDescriptor.name) */
+    name: string;
+    /** Props extracted from the prompt + merged with workflow.defaultProps */
+    props: Record<string, any>;
+}
+/**
+ * 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[];
+    /**
+     * Set when the LLM routed the question to a registered workflow component.
+     * When present, the upstream caller should skip component generation and
+     * return this workflow as the response.
+     */
+    workflow?: SelectedWorkflow;
+}
+/**
+ * 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 workflows;
+    private config;
+    private streamBuffer;
+    constructor(externalTools: ExternalTool[], config: AgentConfig, streamBuffer?: StreamBuffer, workflows?: WorkflowDescriptor[]);
+    /**
+     * 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, direct tool descriptions,
+     * and workflow component 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;
+    /**
+     * Capture a workflow selection. We do NOT execute anything — the LLM has
+     * already extracted the props it wants the workflow rendered with. We
+     * record the selection (via the capture callback) and return a short
+     * acknowledgement so the LLM ends its turn cleanly without writing
+     * analysis text or calling more tools.
+     */
+    private handleWorkflow;
+    /**
+     * Build LLM tool definitions for workflow components. The workflow's
+     * propsSchema becomes the tool's input_schema so the LLM extracts props
+     * directly from the prompt — same mechanic as direct tools.
+     */
+    private buildWorkflowToolDefinitions;
+    /**
+     * 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[];
+}
+
+/**
+ * Represents an action that can be performed on a UIBlock
+ */
+interface Action {
+    id: string;
+    name: string;
+    type: string;
+    [key: string]: any;
+}
+
 type SystemPrompt = string | Anthropic.Messages.TextBlockParam[];
 interface LLMMessages {
     sys: SystemPrompt;
@@ -1253,6 +1686,7 @@ interface LLMOptions {
     temperature?: number;
     topP?: number;
     apiKey?: string;
+    baseURL?: string;
     partial?: (chunk: string) => void;
 }
 interface Tool {
@@ -1275,6 +1709,16 @@ declare class LLM {
      * @returns Normalized system prompt for Anthropic API
      */
     private static _normalizeSystemPrompt;
+    /**
+     * Strip unpaired UTF-16 surrogates from every text field of a message set.
+     *
+     * A lone surrogate (from mid-pair string slicing or corrupt source data)
+     * serializes to a bare `\udXXX` escape that strict JSON parsers — including
+     * the one on Anthropic's API — reject with "no low surrogate in string",
+     * failing the whole request. Sanitizing here, at the single boundary every
+     * provider call flows through, guarantees no request can carry one.
+     */
+    private static _sanitizeMessages;
     /**
      * Log cache usage metrics from Anthropic API response
      * Shows cache hits, costs, and savings
@@ -1291,6 +1735,15 @@ declare class LLM {
      * "claude-sonnet-4-5" → ["anthropic", "claude-sonnet-4-5"] (default)
      */
     private static _parseModel;
+    /**
+     * Map an Anthropic model id (e.g. "claude-sonnet-4-5-20250929") to the OpenRouter slug
+     * (e.g. "claude-sonnet-4.5"). OpenRouter slugs drop the date suffix and use dotted versions.
+     */
+    private static _toOpenRouterSlug;
+    private static _openrouterOptions;
+    private static _openrouterText;
+    private static _openrouterStream;
+    private static _openrouterStreamWithTools;
     private static _anthropicText;
     private static _anthropicStream;
     private static _anthropicStreamWithTools;
@@ -1298,6 +1751,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;
@@ -1390,16 +1848,6 @@ declare class UILogCollector {
     setUIBlockId(uiBlockId: string): void;
 }
 
-/**
- * Represents an action that can be performed on a UIBlock
- */
-interface Action {
-    id: string;
-    name: string;
-    type: string;
-    [key: string]: any;
-}
-
 /**
  * UIBlock represents a single user and assistant message block in a thread
  * Contains user question, component metadata, component data, text response, and available actions
@@ -1582,12 +2030,20 @@ declare class Thread {
 
 /**
  * ThreadManager manages all threads globally
- * Provides methods to create, retrieve, and delete threads
+ * Provides methods to create, retrieve, and delete threads.
+ * Includes automatic cleanup to prevent unbounded memory growth.
  */
 declare class ThreadManager {
     private static instance;
     private threads;
+    private cleanupInterval;
+    private readonly threadTtlMs;
     private constructor();
+    /**
+     * Periodically remove threads older than 7 days.
+     * Runs every hour to avoid frequent iteration over the map.
+     */
+    private startCleanup;
     /**
      * Get singleton instance of ThreadManager
      */
@@ -1986,6 +2442,92 @@ declare function rerankConversationResults<T extends {
     bm25Score: number;
 }>;
 
+/**
+ * QueryExecutionService - Handles all query execution, validation, and retry logic
+ * Extracted from BaseLLM for better separation of concerns
+ */
+
+/**
+ * Context for component when requesting query fix
+ */
+interface ComponentContext {
+    name: string;
+    type: string;
+    title?: string;
+}
+/**
+ * Result of query validation
+ */
+interface QueryValidationResult {
+    component: Component | null;
+    queryKey: string;
+    result: any;
+    validated: boolean;
+}
+/**
+ * Result of batch query validation
+ */
+interface BatchValidationResult {
+    components: Component[];
+    queryResults: Map<string, any>;
+}
+/**
+ * Configuration for QueryExecutionService
+ */
+interface QueryExecutionServiceConfig {
+    defaultLimit: number;
+    getModelForTask: (taskType: 'simple' | 'complex') => string;
+    getApiKey: (apiKey?: string) => string | undefined;
+    providerName: string;
+}
+/**
+ * QueryExecutionService handles all query-related operations
+ */
+declare class QueryExecutionService {
+    private config;
+    constructor(config: QueryExecutionServiceConfig);
+    /**
+     * Get the cache key for a query
+     * This ensures the cache key matches what the frontend will send
+     */
+    getQueryCacheKey(query: any): string;
+    /**
+     * Execute a query against the database
+     * @param query - The SQL query to execute (string or object with sql/values)
+     * @param collections - Collections object containing database execute function
+     * @returns Object with result data and cache key
+     */
+    executeQuery(query: any, collections: any): Promise<{
+        result: any;
+        cacheKey: string;
+    }>;
+    /**
+     * Request the LLM to fix a failed SQL query
+     * @param failedQuery - The query that failed execution
+     * @param errorMessage - The error message from the failed execution
+     * @param componentContext - Context about the component
+     * @param apiKey - Optional API key
+     * @returns Fixed query string
+     */
+    requestQueryFix(failedQuery: string, errorMessage: string, componentContext: ComponentContext, apiKey?: string): Promise<string>;
+    /**
+     * Validate a single component's query with retry logic
+     * @param component - The component to validate
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Validation result with component, query key, and result
+     */
+    validateSingleQuery(component: Component, collections: any, apiKey?: string): Promise<QueryValidationResult>;
+    /**
+     * Validate multiple component queries in parallel
+     * @param components - Array of components with potential queries
+     * @param collections - Collections object containing database execute function
+     * @param apiKey - Optional API key for LLM calls
+     * @returns Object with validated components and query results map
+     */
+    validateComponentQueries(components: Component[], collections: any, apiKey?: string): Promise<BatchValidationResult>;
+}
+
 /**
  * Task types for model selection
  * - 'complex': Text generation, component matching, parameter adaptation (uses best model in balanced mode)
@@ -2004,6 +2546,7 @@ interface BaseLLMConfig {
      * - '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
@@ -2015,6 +2558,8 @@ declare abstract class BaseLLM {
     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
@@ -2032,6 +2577,16 @@ declare abstract class BaseLLM {
      * @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)
      */
@@ -2067,11 +2622,10 @@ declare abstract class BaseLLM {
      * @param analysisContent - The text response containing component suggestions
      * @param components - List of available components
      * @param apiKey - Optional API key
-     * @param logCollector - Optional log collector
      * @param componentStreamCallback - Optional callback to stream primary KPI component as soon as it's identified
      * @returns Object containing matched components, layout title/description, and follow-up actions
      */
-    matchComponentsFromAnalysis(analysisContent: string, components: Component[], apiKey?: string, logCollector?: any, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[]): Promise<{
+    matchComponentsFromAnalysis(analysisContent: string, components: Component[], userPrompt: string, apiKey?: string, componentStreamCallback?: (component: Component) => void, deferredTools?: any[], executedTools?: any[], collections?: any, userId?: string): Promise<{
         components: Component[];
         layoutTitle: string;
         layoutDescription: string;
@@ -2081,7 +2635,7 @@ declare abstract class BaseLLM {
      * Classify user question into category and detect external tools needed
      * Determines if question is for data analysis, requires external tools, or needs text response
      */
-    classifyQuestionCategory(userPrompt: string, apiKey?: string, logCollector?: any, conversationHistory?: string, externalTools?: any[]): Promise<{
+    classifyQuestionCategory(userPrompt: string, apiKey?: string, conversationHistory?: string, externalTools?: any[]): Promise<{
         category: 'data_analysis' | 'data_modification' | 'general';
         externalTools: Array<{
             type: string;
@@ -2098,7 +2652,7 @@ declare abstract class BaseLLM {
      * Takes a matched UI block from semantic search and modifies its props to answer the new question
      * Also adapts the cached text response to match the new question
      */
-    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, logCollector?: any, cachedTextResponse?: string): Promise<{
+    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, cachedTextResponse?: string): Promise<{
         success: boolean;
         adaptedComponent?: Component;
         adaptedTextResponse?: string;
@@ -2113,13 +2667,8 @@ declare abstract class BaseLLM {
      * This provides conversational text responses instead of component generation
      * Supports tool calling for query execution with automatic retry on errors (max 3 attempts)
      * After generating text response, if components are provided, matches suggested components
-     * @param streamCallback - Optional callback function to receive text chunks as they stream
-     * @param collections - Collection registry for executing database queries via database.execute
-     * @param components - Optional list of available components for matching suggestions
-     * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called
-     * @param category - Question category ('data_analysis' | 'data_modification' | 'general'). For data_modification, answer component streaming is skipped. For general, component generation is skipped entirely.
      */
-    generateTextResponse(userPrompt: string, apiKey?: string, logCollector?: any, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general'): Promise<T_RESPONSE>;
+    generateTextResponse(userPrompt: string, apiKey?: string, conversationHistory?: string, streamCallback?: (chunk: string) => void, collections?: any, components?: Component[], externalTools?: any[], category?: 'data_analysis' | 'data_modification' | 'general', userId?: string): Promise<T_RESPONSE>;
     /**
      * Main orchestration function with semantic search and multi-step classification
      * NEW FLOW (Recommended):
@@ -2127,19 +2676,14 @@ declare abstract class BaseLLM {
      *    - If match found → Adapt UI block parameters and return
      * 2. Category classification: Determine if data_analysis, requires_external_tools, or text_response
      * 3. Route appropriately based on category and response mode
-     *
-     * @param responseMode - 'component' for component generation (default), 'text' for text responses
-     * @param streamCallback - Optional callback function to receive text chunks as they stream (only for text mode)
-     * @param collections - Collection registry for executing database queries (required for text mode)
-     * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called (only for text mode)
      */
-    handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, logCollector?: any, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
+    handleUserRequest(userPrompt: string, components: Component[], apiKey?: string, conversationHistory?: string, responseMode?: 'component' | 'text', streamCallback?: (chunk: string) => void, collections?: any, externalTools?: any[], userId?: string): Promise<T_RESPONSE>;
     /**
      * Generate next questions that the user might ask based on the original prompt and generated component
      * This helps provide intelligent suggestions for follow-up queries
      * For general/conversational questions without components, pass textResponse instead
      */
-    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, logCollector?: any, conversationHistory?: string, textResponse?: string): Promise<string[]>;
+    generateNextQuestions(originalUserPrompt: string, component?: Component | null, componentData?: Record<string, unknown>, apiKey?: string, conversationHistory?: string, textResponse?: string): Promise<string[]>;
 }
 
 interface AnthropicLLMConfig extends BaseLLMConfig {
@@ -2198,7 +2742,153 @@ declare class OpenAILLM extends BaseLLM {
 }
 declare const openaiLLM: OpenAILLM;
 
-declare const SDK_VERSION = "0.0.8";
+/**
+ * Query Cache — Two mechanisms:
+ *
+ * 1. `cache` (query string → result data) — TTL-based with max size, for avoiding re-execution
+ *    of recently validated queries. True LRU eviction: reads bubble entries to the back via
+ *    delete+re-set so the oldest *unused* entry is evicted, not the oldest *inserted*.
+ *
+ * 2. Encrypted queryId tokens — SQL is encrypted into the queryId itself (self-contained).
+ *    No server-side storage needed for SQL mappings. The token is decrypted on each request.
+ *    This eliminates the unbounded queryIdCache that previously grew forever and caused
+ *    memory bloat (hundreds of MBs after thousands of queries).
+ *
+ *    Result data can still be cached temporarily via the data cache (mechanism 1).
+ */
+declare class QueryCache {
+    private cache;
+    private ttlMs;
+    private maxCacheSize;
+    private cleanupInterval;
+    private readonly algorithm;
+    private encryptionKey;
+    constructor();
+    /**
+     * Set the cache TTL (Time To Live)
+     * @param minutes - TTL in minutes (default: 10)
+     */
+    setTTL(minutes: number): void;
+    /**
+     * Get the current TTL in minutes
+     */
+    getTTL(): number;
+    /**
+     * Store query result in data cache.
+     * If the key already exists, it's removed first so the re-insert places it
+     * at the back of the iteration order (LRU). Eviction only fires when adding
+     * a genuinely new key past the size limit.
+     */
+    set(query: string, data: any): void;
+    /**
+     * Get cached result if exists and not expired.
+     * On hit, re-inserts the entry so it moves to the back of the Map's
+     * iteration order — turning FIFO eviction into true LRU.
+     */
+    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;
+        queryIdCount: number;
+        oldestEntryAge: number | null;
+    };
+    /**
+     * Start periodic cleanup of expired data cache entries.
+     */
+    private startCleanup;
+    /**
+     * Encrypt a payload into a self-contained token.
+     */
+    private encrypt;
+    /**
+     * Decrypt a token back to the original payload.
+     */
+    private decrypt;
+    /**
+     * Store a query by generating an encrypted token as queryId.
+     * The SQL is encrypted INTO the token — nothing stored in memory.
+     * If data is provided, it's cached temporarily in the data cache.
+     */
+    storeQuery(query: any, data?: any): string;
+    /**
+     * Get a stored query by decrypting its token.
+     * Returns the SQL + any cached result data.
+     */
+    getQuery(queryId: string): {
+        query: any;
+        data: any;
+    } | null;
+    /**
+     * Update cached data for a queryId token
+     */
+    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;
+
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
     private ws;
@@ -2215,6 +2905,7 @@ declare class SuperatomSDK {
     private collections;
     private components;
     private tools;
+    private workflows;
     private anthropicApiKey;
     private groqApiKey;
     private geminiApiKey;
@@ -2222,6 +2913,10 @@ declare class SuperatomSDK {
     private llmProviders;
     private databaseType;
     private modelStrategy;
+    private mainAgentModel;
+    private sourceAgentModel;
+    private dashCompModels?;
+    private conversationSimilarityThreshold;
     private userManager;
     private dashboardManager;
     private reportManager;
@@ -2268,9 +2963,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
      */
@@ -2318,6 +3015,19 @@ declare class SuperatomSDK {
      * Get the stored tools
      */
     getTools(): Tool$1[];
+    /**
+     * Register workflow components for the SDK instance.
+     *
+     * Workflows are pre-built multi-step UI flows the main agent can pick when
+     * the user's prompt matches a workflow's `whenToUse` trigger. Picking a
+     * workflow short-circuits analysis text + dashboard component generation —
+     * the workflow component is returned directly, with the LLM-extracted props.
+     */
+    setWorkflows(workflows: WorkflowDescriptor[]): void;
+    /**
+     * Get the registered workflow components.
+     */
+    getWorkflows(): WorkflowDescriptor[];
     /**
      * Apply model strategy to all LLM provider singletons
      * @param strategy - 'best', 'fast', or 'balanced'
@@ -2332,6 +3042,20 @@ declare class SuperatomSDK {
      * 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, BM25L, type BM25LOptions, type BaseLLMConfig, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, type Message, type ModelStrategy, type OutputField, type RerankedResult, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, anthropicLLM, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };
+export { type Action, 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, type SelectedWorkflow, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, anthropicLLM, dashboardConversationHistory, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, queryCache, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };