@superatomai/sdk-node 0.0.39 → 0.0.41

package/dist/index.d.mts

@@ -615,6 +615,68 @@ 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.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">>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        query?: string | {} | undefined;
+        title?: string | undefined;
+        config?: Record<string, unknown> | undefined;
+        actions?: any[] | undefined;
+    }, {
+        description?: string | undefined;
+        query?: string | {} | undefined;
+        title?: string | undefined;
+        config?: Record<string, unknown> | undefined;
+        actions?: any[] | undefined;
+    }>;
+    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 | {} | undefined;
+        title?: string | undefined;
+        config?: Record<string, unknown> | undefined;
+        actions?: any[] | undefined;
+    };
+    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 | {} | undefined;
+        title?: string | undefined;
+        config?: Record<string, unknown> | undefined;
+        actions?: any[] | undefined;
+    };
+    displayName?: string | undefined;
+    isDisplayComp?: boolean | undefined;
+    category?: string | undefined;
+    keywords?: string[] | undefined;
+}>;
+type Component = z.infer<typeof ComponentSchema>;
 declare const ToolSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -640,6 +702,13 @@ type CollectionHandler<TParams = any, TResult = any> = (params: TParams) => Prom
 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';
 interface SuperatomSDKConfig {
     url?: string;
     apiKey?: string;
@@ -655,6 +724,13 @@ interface SuperatomSDKConfig {
     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;
 }
 
 declare const KbNodesQueryFiltersSchema: z.ZodObject<{
@@ -785,6 +861,11 @@ declare const KbNodesRequestPayloadSchema: z.ZodObject<{
     } | undefined;
 }>;
 type KbNodesRequestPayload = z.infer<typeof KbNodesRequestPayloadSchema>;
+interface T_RESPONSE {
+    success: boolean;
+    data?: any;
+    errors: string[];
+}
 
 /**
  * UserManager class to handle CRUD operations on users with file persistence
@@ -1548,6 +1629,120 @@ declare const CONTEXT_CONFIG: {
     MAX_CONVERSATION_CONTEXT_BLOCKS: number;
 };
 
+/**
+ * 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
  *
@@ -1676,6 +1871,216 @@ declare function rerankConversationResults<T extends {
     bm25Score: number;
 }>;
 
+/**
+ * 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;
+}
+/**
+ * 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;
+    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;
+    /**
+     * 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 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<{
+        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, logCollector?: any, 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
+     */
+    adaptUIBlockParameters(currentUserPrompt: string, originalUserPrompt: string, matchedUIBlock: any, apiKey?: string, logCollector?: any): Promise<{
+        success: boolean;
+        adaptedComponent?: Component;
+        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
+     * @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>;
+    /**
+     * 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
+     *
+     * @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>;
+    /**
+     * 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[]>;
+}
+
+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;
+
 declare const SDK_VERSION = "0.0.8";
 type MessageTypeHandler = (message: IncomingMessage) => void | Promise<void>;
 declare class SuperatomSDK {
@@ -1700,6 +2105,7 @@ declare class SuperatomSDK {
     private openaiApiKey;
     private llmProviders;
     private databaseType;
+    private modelStrategy;
     private userManager;
     private dashboardManager;
     private reportManager;
@@ -1796,6 +2202,20 @@ declare class SuperatomSDK {
      * Get the stored tools
      */
     getTools(): Tool$1[];
+    /**
+     * Apply model strategy to all LLM provider singletons
+     * @param strategy - 'best', 'fast', or 'balanced'
+     */
+    private applyModelStrategy;
+    /**
+     * Set model strategy at runtime
+     * @param strategy - 'best', 'fast', or 'balanced'
+     */
+    setModelStrategy(strategy: ModelStrategy): void;
+    /**
+     * Get current model strategy
+     */
+    getModelStrategy(): ModelStrategy;
 }
 
-export { type Action, BM25L, type BM25LOptions, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type DBUIBlock, type DatabaseType, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LogLevel, type Message, type RerankedResult, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, Thread, ThreadManager, type Tool$1 as Tool, UIBlock, UILogCollector, type User, UserManager, type UsersData, hybridRerank, logger, rerankChromaResults, rerankConversationResults };
+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 RerankedResult, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, UIBlock, UILogCollector, type User, UserManager, type UsersData, anthropicLLM, geminiLLM, groqLLM, hybridRerank, llmUsageLogger, logger, openaiLLM, rerankChromaResults, rerankConversationResults, userPromptErrorLogger };