@superatomai/sdk-node 0.0.13 → 0.0.14

package/dist/index.js

@@ -562,6 +562,25 @@ var ReportsRequestMessageSchema = import_zod3.z.object({
   type: import_zod3.z.literal("REPORTS"),
   payload: ReportsRequestPayloadSchema
 });
+var UIBlockSchema = import_zod3.z.object({
+  id: import_zod3.z.string().optional(),
+  userQuestion: import_zod3.z.string().optional(),
+  text: import_zod3.z.string().optional(),
+  textResponse: import_zod3.z.string().optional(),
+  component: ComponentSchema.optional(),
+  // Legacy field
+  generatedComponentMetadata: ComponentSchema.optional(),
+  // Actual field used by UIBlock class
+  componentData: import_zod3.z.record(import_zod3.z.any()).optional(),
+  actions: import_zod3.z.array(import_zod3.z.any()).optional(),
+  isFetchingActions: import_zod3.z.boolean().optional(),
+  createdAt: import_zod3.z.string().optional(),
+  metadata: import_zod3.z.object({
+    timestamp: import_zod3.z.number().optional(),
+    userPrompt: import_zod3.z.string().optional(),
+    similarity: import_zod3.z.number().optional()
+  }).optional()
+});
 var BookmarkDataSchema = import_zod3.z.object({
   id: import_zod3.z.number().optional(),
   uiblock: import_zod3.z.any(),
@@ -1829,489 +1848,126 @@ var import_path2 = __toESM(require("path"));
 
 // src/userResponse/prompts.ts
 var PROMPTS = {
-  "classify": {
-    system: `You are an expert AI that classifies user questions about data and determines the appropriate visualizations needed.
-
-CRITICAL: You MUST respond with ONLY valid JSON, no other text before or after.
-
-## Previous Conversation
-{{CONVERSATION_HISTORY}}
-
-**Note:** If there is previous conversation history, use it to understand context. For example:
-- If user previously asked about "sales" and now asks "show me trends", understand it refers to sales trends
-- If user asked for "revenue by region" and now says "make it a pie chart", understand they want to modify the previous visualization
-- Use the history to resolve ambiguous references like "that", "it", "them", "the data"
-
-Your task is to analyze the user's question and determine:
-
-1. **Question Type:**
-   - "analytical": Questions asking to VIEW, ANALYZE, or VISUALIZE data
-
-   - "data_modification": Questions asking to CREATE, UPDATE, DELETE, or MODIFY data
-
-   - "general": General questions, greetings, or requests not related to data
-
-2. **Required Visualizations** (only for analytical questions):
-   Determine which visualization type(s) would BEST answer the user's question:
-
-   - **KPICard**: Single metric, total, count, average, percentage, or summary number
-
-   - **LineChart**: Trends over time, time series, growth/decline patterns
-
-
-   - **BarChart**: Comparing categories, rankings, distributions across groups
-
-
-   - **PieChart**: Proportions, percentages, composition, market share
-
-
-   - **DataTable**: Detailed lists, multiple attributes, when user needs to see records
-
-
-3. **Multiple Visualizations:**
-   User may need MULTIPLE visualizations together:
-
-   Common combinations:
-   - KPICard + LineChart
-   - KPICard + BarChart
-   - KPICard + DataTable
-   - BarChart + PieChart:
-   - LineChart + DataTable
-   Set needsMultipleComponents to true if user needs multiple views of the data.
+  "text-response": {
+    system: `You are an intelligent AI assistant that provides helpful, accurate, and contextual text responses to user questions. You have access to a database and can execute SQL queries and external tools to answer user requests.
 
-**Important Guidelines:**
-- If user explicitly mentions a chart type RESPECT that preference
-- If question is vague or needs both summary and detail, suggest KPICard + DataTable
-- Only return visualizations for "analytical" questions
-- For "data_modification" or "general", return empty array for visualizations
+## Your Task
 
-**Output Format:**
-{
-  "questionType": "analytical" | "data_modification" | "general",
-  "visualizations": ["KPICard", "LineChart", ...],  // Empty array if not analytical
-  "reasoning": "Explanation of classification and visualization choices",
-  "needsMultipleComponents": boolean
-}
-`,
-    user: `{{USER_PROMPT}}
-`
-  },
-  "match-component": {
-    system: `You are an expert AI assistant specialized in matching user requests to the most appropriate data visualization components.
+Analyze the user's question and provide a helpful text response. Your response should:
 
-CRITICAL: You MUST respond with ONLY valid JSON, no other text before or after.
+1. **Be Clear and Concise**: Provide direct answers without unnecessary verbosity
+2. **Be Contextual**: Use conversation history to understand what the user is asking about
+3. **Be Accurate**: Provide factually correct information based on the context
+4. **Be Helpful**: Offer additional relevant information or suggestions when appropriate
 
-## Previous Conversation
-{{CONVERSATION_HISTORY}}
+## Available Tools
 
-**Context Instructions:**
-- If there is conversation history, use it to understand what the user is referring to
-- When user says "show that as a chart" or "change it", they are referring to a previous component
-- If user asks to "modify" or "update" something, match to the component they previously saw
-- Use context to resolve ambiguous requests like "show trends for that" or "make it interactive"
-
-Your task is to analyze the user's natural language request and find the BEST matching component from the available list.
-
-Available Components:
-{{COMPONENTS_TEXT}}
-
-**Matching Guidelines:**
-
-1. **Understand User Intent:**
-   - What type of data visualization do they need? (KPI/metric, chart, table, etc.)
-   - What metric or data are they asking about? (revenue, orders, customers, etc.)
-   - Are they asking for a summary (KPI), trend (line chart), distribution (bar/pie), or detailed list (table)?
-   - Do they want to compare categories, see trends over time, or show proportions?
-
-2. **Component Type Matching:**
-   - KPICard: Single metric/number (total, average, count, percentage, rate)
-   - LineChart: Trends over time, time series data
-   - BarChart: Comparing categories, distributions, rankings
-   - PieChart/DonutChart: Proportions, percentages, market share
-   - DataTable: Detailed lists, rankings with multiple attributes
-
-3. **Keyword & Semantic Matching:**
-   - Match user query terms with component keywords
-   - Consider synonyms (e.g., "sales" = "revenue", "items" = "products")
-   - Look for category matches (financial, orders, customers, products, suppliers, logistics, geographic, operations)
-
-4. **Scoring Criteria:**
-   - Exact keyword matches: High priority
-   - Component type alignment: High priority
-   - Category alignment: Medium priority
-   - Semantic similarity: Medium priority
-   - Specificity: Prefer more specific components over generic ones
-
-**Output Requirements:**
-
-Respond with a JSON object containing:
-- componentIndex: the 1-based index of the BEST matching component (or null if confidence < 50%)
-- componentId: the ID of the matched component
-- reasoning: detailed explanation of why this component was chosen
-- confidence: confidence score 0-100 (100 = perfect match)
-- alternativeMatches: array of up to 2 alternative component indices with scores (optional)
-
-Example response:
-{
-  "componentIndex": 5,
-  "componentId": "total_revenue_kpi",
-  "reasoning": "User asks for 'total revenue' which perfectly matches the TotalRevenueKPI component (KPICard type) designed to show total revenue across all orders. Keywords match: 'total revenue', 'sales'.",
-  "confidence": 95,
-  "alternativeMatches": [
-    {"index": 3, "id": "monthly_revenue_kpi", "score": 75, "reason": "Could show monthly revenue if time period was intended"},
-    {"index": 8, "id": "revenue_trend_chart", "score": 60, "reason": "Could show revenue trend if historical view was intended"}
-  ]
-}
+The following external tools are available for this request (if applicable):
 
-**Important:**
-- Only return componentIndex if confidence >= 50%
-- Return null if no reasonable match exists
-- Prefer components that exactly match the user's metric over generic ones
-- Consider the full context of the request, not just individual words`,
-    user: `Current user request: {{USER_PROMPT}}
+{{AVAILABLE_EXTERNAL_TOOLS}}
 
-Find the best matching component considering the conversation history above. Explain your reasoning with a confidence score. Return ONLY valid JSON.`
-  },
-  "modify-props": {
-    system: `You are an AI assistant that validates and modifies component props based on user requests.
+When a tool is needed to complete the user's request:
+1. **Analyze the request** to determine which tool(s) are needed
+2. **Extract parameters** from the user's question that the tool requires
+3. **Execute the tool** by calling it with the extracted parameters
+4. **Present the results** in your response in a clear, user-friendly format
+5. **Combine with other data** if the user's request requires both database queries and external tool results
 
-CRITICAL: You MUST respond with ONLY valid JSON, no other text before or after.
+## Handling Data Questions
 
-Given:
-- A user's natural language request
-- Component name: {{COMPONENT_NAME}}
-- Component type: {{COMPONENT_TYPE}}
-- Component description: {{COMPONENT_DESCRIPTION}}
+When the user asks about data
 
--
-- Current component props with structure:
-  {
-    query?: string,        // SQL query to fetch data
-    title?: string,        // Component title
-    description?: string,  // Component description
-    config?: {            // Additional configuration
-      [key: string]: any
-    }
-  }
+1. **Generate a SQL query** using the database schema provided above
+2. **Use the execute_query tool** to run the query
+3. **If the query fails**, analyze the error and generate a corrected query
+4. **Format the results** in a clear, readable way for the user
 
-  Schema definition for the  prop that must be passed to the component
-  -{{CURRENT_PROPS}}
+**Query Guidelines:**
+- Use correct table and column names from the schema
+- ALWAYS include a LIMIT clause with a MAXIMUM of 32 rows
+- Ensure valid SQL syntax
+- For time-based queries, use appropriate date functions
+- When using subqueries with scalar operators (=, <, >, etc.), add LIMIT 1 to prevent "more than one row" errors
 
-Database Schema:
+## Database Schema
 {{SCHEMA_DOC}}
 
-## Previous Conversation
-{{CONVERSATION_HISTORY}}
-
-**Context Instructions:**
-- Review the conversation history to understand the evolution of the component
-- If user says "add filter for X", understand they want to modify the current query
-- If user says "change to last month" or "filter by Y", apply modifications to existing query
-- Previous questions can clarify what the user means by ambiguous requests like "change that filter"
-- Use context to determine appropriate time ranges if user says "recent" or "latest"
-
-Your task is to intelligently modify the props based on the user's request:
+**Database Type: PostgreSQL**
 
-1. **Query Modification**:
-   - Modify SQL query if user requests different data, filters, time ranges, limits, or aggregations
-   - Use correct table and column names from the schema
-   - Ensure valid SQL syntax
-   - ALWAYS include a LIMIT clause (default: {{DEFAULT_LIMIT}} rows) to prevent large result sets
-   - Preserve the query structure that the component expects (e.g., column aliases)
+**CRITICAL PostgreSQL Query Rules:**
 
-   **CRITICAL - PostgreSQL Query Rules:**
+1. **NO AGGREGATE FUNCTIONS IN WHERE CLAUSE** - This is a fundamental SQL error
+   \u274C WRONG: \`WHERE COUNT(orders) > 0\`
+   \u274C WRONG: \`WHERE SUM(price) > 100\`
+   \u274C WRONG: \`WHERE AVG(rating) > 4.5\`
+   \u274C WRONG: \`WHERE FLOOR(AVG(rating)) = 4\` (aggregate inside any function is still not allowed)
+   \u274C WRONG: \`WHERE ROUND(SUM(price), 2) > 100\`
 
-   **NO AGGREGATE FUNCTIONS IN WHERE CLAUSE:**
-   \u274C WRONG: \`WHERE COUNT(orders) > 0\` or \`WHERE SUM(price) > 100\`
    \u2705 CORRECT: Use HAVING (with GROUP BY), EXISTS, or subquery
+   \u2705 CORRECT: Move aggregate logic to HAVING: \`GROUP BY ... HAVING FLOOR(AVG(rating)) = 4\`
+   \u2705 CORRECT: Use subquery for filtering: \`WHERE product_id IN (SELECT product_id FROM ... GROUP BY ... HAVING AVG(rating) >= 4)\`
 
-
-   **WHERE vs HAVING:**
+2. **WHERE vs HAVING**
    - WHERE filters rows BEFORE grouping (cannot use aggregates)
    - HAVING filters groups AFTER grouping (can use aggregates)
    - If using HAVING, you MUST have GROUP BY
 
-   **Subquery Rules:**
-   - When using a subquery with scalar comparison operators (=, <, >, <=, >=, <>), the subquery MUST return exactly ONE row
-   - ALWAYS add \`LIMIT 1\` to scalar subqueries to prevent "more than one row returned" errors
-   - Example: \`WHERE location_id = (SELECT store_id FROM orders ORDER BY total_amount DESC LIMIT 1)\`
-   - For multiple values, use \`IN\` instead: \`WHERE location_id IN (SELECT store_id FROM orders)\`
-   - Test your subqueries mentally: if they could return multiple rows, add LIMIT 1 or use IN
-
-2. **Title Modification**:
-   - Update title to reflect the user's specific request
-   - Keep it concise and descriptive
-   - Match the tone of the original title
-
-3. **Description Modification**:
-   - Update description to explain what data is shown
-   - Be specific about filters, time ranges, or groupings applied
-
-4. **Config Modification** (based on component type):
-   - For KPICard: formatter, gradient, icon
-   - For Charts: colors, height, xKey, yKey, nameKey, valueKey
-   - For Tables: columns, pageSize, formatters
-
-
-Respond with a JSON object:
-{
-  "props": { /* modified props object with query, title, description, config */ },
-  "isModified": boolean,
-  "reasoning": "brief explanation of changes",
-  "modifications": ["list of specific changes made"]
-}
-
-IMPORTANT:
-- Return the COMPLETE props object, not just modified fields
-- Preserve the structure expected by the component type
-- Ensure query returns columns with expected aliases
-- Keep config properties that aren't affected by the request`,
-    user: `{{USER_PROMPT}}`
-  },
-  "single-component": {
-    system: `You are an expert AI assistant specialized in matching user requests to the most appropriate component from a filtered list.
-
-CRITICAL: You MUST respond with ONLY valid JSON, no other text before or after.
-
-
-## Previous Conversation
-{{CONVERSATION_HISTORY}}
-
-**Context Instructions:**
-- If there is previous conversation history, use it to understand what the user is referring to
-- When user says "show trends", "add filters", "change that", understand they may be building on previous queries
-- Use previous component types and queries as context to inform your current matching
-
-## Available Components (Type: {{COMPONENT_TYPE}})
-The following components have been filtered by type {{COMPONENT_TYPE}}. Select the BEST matching one:
-
-{{COMPONENTS_LIST}}
-
-{{VISUALIZATION_CONSTRAINT}}
-
-**Select the BEST matching component** from the available {{COMPONENT_TYPE}} components listed above that would best answer the user's question.
-
-**Matching Guidelines:**
-1. **Semantic Matching:**
-   - Match based on component name, description, and keywords
-   - Consider what metrics/data the user is asking about
-   - Look for semantic similarity (e.g., "sales" matches "revenue", "orders" matches "purchases")
-
-2. **Query Relevance:**
-   - Consider the component's existing query structure
-   - Does it query the right tables/columns for the user's question?
-   - Can it be modified to answer the user's specific question?
-
-3. **Scoring Criteria:**
-   - Exact keyword matches in name/description: High priority
-   - Semantic similarity to user intent: High priority
-   - Appropriate aggregation/grouping: Medium priority
-   - Category alignment: Medium priority
-
-**Output Requirements:**
-
-Respond with a JSON object:
-{
-  "componentId": "matched_component_id",
-  "componentIndex": 1,  // 1-based index from the filtered list above
-  "reasoning": "Detailed explanation of why this component best matches the user's question",
-  "confidence": 85,  // Confidence score 0-100
-  "canGenerate": true  // false if no suitable component found (confidence < 50)
-}
-
-**Important:**
-- Only set canGenerate to true if confidence >= 50%
-- If no component from the list matches well (all have low relevance), set canGenerate to false
-- Consider the full context of the request and conversation history
-- The component's props (query, title, description, config) will be modified later based on the user's specific request
-- Focus on finding the component that is closest to what the user needs, even if it needs modification`,
-    user: `{{USER_PROMPT}}
-
-`
-  },
-  "mutli-component": {
-    system: `You are an expert data analyst AI that creates comprehensive multi-component analytical dashboards with aesthetically pleasing and balanced layouts.
-
-CRITICAL: You MUST respond with ONLY valid JSON, no other text before or after.
-
-Database Schema:
-{{SCHEMA_DOC}}
-
-## Previous Conversation
-{{CONVERSATION_HISTORY}}
-
-**Context Instructions:**
-- Review the conversation history to understand what the user has asked before
-- If user is building on previous insights (e.g., "now show me X and Y"), use context to inform dashboard design
-- Previous queries can help determine appropriate filters, date ranges, or categories to use
-- If user asks for "comprehensive view" or "dashboard for X", include complementary components based on context
-
-Given a user's analytical question and the required visualization types, your task is to:
-
-1. **Determine Container Metadata:**
-   - title: Clear, descriptive title for the entire dashboard (2-5 words)
-   - description: Brief explanation of what insights this dashboard provides (1-2 sentences)
-
-2. **Generate Props for Each Component:**
-   For each visualization type requested, create tailored props:
-
-   - **query**: SQL query specific to this visualization using the database schema
-     * Use correct table and column names
-     * **DO NOT USE TOP keyword - use LIMIT instead (e.g., LIMIT 20, not TOP 20)**
-     * ALWAYS include LIMIT clause ONCE at the end (default: {{DEFAULT_LIMIT}})
-     * For KPICard: Return single row with column alias "value"
-     * For Charts: Return appropriate columns (name/label and value, or x and y)
-     * For Table: Return relevant columns
-
-   - **title**: Specific title for this component (2-4 words)
-
-   - **description**: What this specific component shows (1 sentence)
-
-   - **config**: Type-specific configuration
-     * KPICard: { gradient, formatter, icon }
-     * BarChart: { xKey, yKey, colors, height }
-     * LineChart: { xKey, yKeys, colors, height }
-     * PieChart: { nameKey, valueKey, colors, height }
-     * DataTable: { pageSize }
-
-3. **CRITICAL: Component Hierarchy and Ordering:**
-   The ORDER of components in the array MUST follow this STRICT hierarchy for proper visual layout:
-
-   **HIERARCHY RULES (MUST FOLLOW IN THIS ORDER):**
-   1. KPICards - ALWAYS FIRST (top of dashboard for summary metrics)
-   2. Charts/Graphs - AFTER KPICards (middle of dashboard for visualizations)
-      * BarChart, LineChart, PieChart, DonutChart
-   3. DataTable - ALWAYS LAST (bottom of dashboard, full width for detailed data)
-
-   **LAYOUT BEHAVIOR (Frontend enforces):**
-   - KPICards: Display in responsive grid (3 columns)
-   - Single Chart (if only 1 chart): Takes FULL WIDTH
-   - Multiple Charts (if 2+ charts): Display in 2-column grid
-   - DataTable (if present): Always spans FULL WIDTH at bottom
-
-
-   **ABSOLUTELY DO NOT deviate from this hierarchy. Always place:**
-   - KPICards first
-   - Charts/Graphs second
-   - DataTable last (if present)
-
-**Important Guidelines:**
-- Each component should answer a DIFFERENT aspect of the user's question
-- Queries should be complementary, not duplicated
-- If user asks "Show total revenue and trend", generate:
-  * KPICard: Single total value (FIRST)
-  * LineChart: Revenue over time (SECOND)
-- Ensure queries use valid columns from the schema
-- Make titles descriptive and specific to what each component shows
-- **Snowflake Syntax MUST be used:**
-  * Use LIMIT (not TOP)
-  * Use DATE_TRUNC, DATEDIFF (not DATEPART)
-  * Include LIMIT only ONCE per query at the end
-
-**Output Format:**
-{
-  "containerTitle": "Dashboard Title",
-  "containerDescription": "Brief description of the dashboard insights",
-  "components": [
-    {
-      "componentType": "KPICard" | "BarChart" | "LineChart" | "PieChart" | "DataTable",
-      "query": "SQL query",
-      "title": "Component title",
-      "description": "Component description",
-      "config": { /* type-specific config */ }
-    },
-    ...
-  ],
-  "reasoning": "Explanation of the dashboard design and component ordering",
-  "canGenerate": boolean
-}`,
-    user: `Current user question: {{USER_PROMPT}}
-
-Required visualization types: {{VISUALIZATION_TYPES}}
-
-Generate a complete multi-component dashboard with appropriate container metadata and tailored props for each component. Consider the conversation history above when designing the dashboard. Return ONLY valid JSON.`
-  },
-  "container-metadata": {
-    system: `You are an expert AI assistant that generates titles and descriptions for multi-component dashboards.
-
-CRITICAL: You MUST respond with ONLY valid JSON, no other text before or after.
-
-## Previous Conversation
-{{CONVERSATION_HISTORY}}
-
-**Context Instructions:**
-- If there is previous conversation history, use it to understand what the user is referring to
-- Use context to create relevant titles and descriptions that align with the user's intent
-
-Your task is to generate a concise title and description for a multi-component dashboard that will contain the following visualization types:
-{{VISUALIZATION_TYPES}}
-
-**Guidelines:**
-
-1. **Title:**
-   - Should be clear and descriptive (3-8 words)
-   - Should reflect what the user is asking about
-   - Should NOT include "Dashboard" suffix (that will be added automatically)
-
-2. **Description:**
-   - Should be a brief summary (1-2 sentences)
-   - Should explain what insights the dashboard provides
-
-**Output Requirements:**
-
-Respond with a JSON object:
-{
-  "title": "Dashboard title without 'Dashboard' suffix",
-  "description": "Brief description of what this dashboard shows"
-}
-
-**Important:**
-- Keep the title concise and meaningful
-- Make the description informative but brief
-- Focus on what insights the user will gain
-`,
-    user: `{{USER_PROMPT}}
-`
-  },
-  "text-response": {
-    system: `You are an intelligent AI assistant that provides helpful, accurate, and contextual text responses to user questions.
-
-## Your Task
-
-Analyze the user's question and provide a helpful text response. Your response should:
+3. **NO NESTED AGGREGATE FUNCTIONS** - PostgreSQL does NOT allow aggregates inside aggregates
+   \u274C WRONG: \`AVG(ROUND(AVG(column), 2))\` or \`SELECT AVG(SUM(price)) FROM ...\`
+   \u2705 CORRECT: \`ROUND(AVG(column), 2)\`
 
-1. **Be Clear and Concise**: Provide direct answers without unnecessary verbosity
-2. **Be Contextual**: Use conversation history to understand what the user is asking about
-3. **Be Accurate**: Provide factually correct information based on the context
-4. **Be Helpful**: Offer additional relevant information or suggestions when appropriate
+4. **GROUP BY Requirements**
+   - ALL non-aggregated columns in SELECT must be in GROUP BY
+   - If you SELECT a column and don't aggregate it, add it to GROUP BY
 
-## Handling Data Questions
+5. **LIMIT Clause**
+   - ALWAYS include LIMIT (max 32 rows)
+   - For scalar subqueries in WHERE/HAVING, add LIMIT 1
 
-When the user asks about data
+6. **String Escaping** - PostgreSQL uses double single-quotes, NOT backslash
+   \u274C WRONG: \`'Children\\'s furniture'\`
+   \u2705 CORRECT: \`'Children''s furniture'\`
 
-1. **Generate a SQL query** using the database schema provided above
-2. **Use the execute_query tool** to run the query
-3. **If the query fails**, analyze the error and generate a corrected query
-4. **Format the results** in a clear, readable way for the user
+7. **Always Use Table Aliases for Column References** - Prevent ambiguous column errors
+   \u274C WRONG: \`SELECT product_id FROM products p JOIN product_variants pv ON p.product_id = pv.product_id\`
+   \u2705 CORRECT: \`SELECT p.product_id FROM products p JOIN product_variants pv ON p.product_id = pv.product_id\`
+   - Always prefix columns with table alias (e.g., \`p.product_id\`, \`c.name\`)
+   - Especially critical in subqueries and joins where multiple tables share column names
 
-**Query Guidelines:**
-- Use correct table and column names from the schema
-- ALWAYS include a LIMIT clause with a MAXIMUM of 32 rows
-- Ensure valid SQL syntax
-- For time-based queries, use appropriate date functions
-- When using subqueries with scalar operators (=, <, >, etc.), add LIMIT 1 to prevent "more than one row" errors
 
 ## Response Guidelines
 
-- If the question is about data, use the execute_query tool to fetch data and present it
+- If the question is about viewing data, use the execute_query tool to fetch data and present it
+- If the question is about creating/updating/deleting data:
+  1. Acknowledge that the system supports this via forms
+  2. **CRITICAL:** Use the database schema to determine which fields are required based on \`nullable\` property
+  3. **CRITICAL:** If the form will have select fields for foreign keys, you MUST fetch the options data using execute_query
+  4. **CRITICAL FOR UPDATE/DELETE OPERATIONS:** If it's an update/edit/modify/delete question:
+     - **NEVER update ID/primary key columns** (e.g., order_id, customer_id, product_id) - these are immutable identifiers
+     - You MUST first fetch the CURRENT values of the record using a SELECT query
+     - Identify the record (from user's question - e.g., "update order 123" or "delete order 123" means order_id = 123)
+     - Execute: \`SELECT * FROM table_name WHERE id = <value> LIMIT 1\`
+     - Present the current values in your response (e.g., "Current order status: Pending, payment method: Credit Card")
+     - For DELETE: These values will be shown in a disabled form as confirmation before deletion
+     - For UPDATE: These values will populate as default values for editing
+  5. Present the options data in your response (e.g., "Available categories: Furniture (id: 1), Kitchen (id: 2), Decor (id: 3)")
+  6. The form component will be generated automatically using this data
 - If the question is general knowledge, provide a helpful conversational response
 - If asking for clarification, provide options or ask specific follow-up questions
 - If you don't have enough information, acknowledge it and ask for more details
 - Keep responses focused and avoid going off-topic
 
+**Example for data modification with foreign keys:**
+User: "I want to create a new product"
+You should:
+1. Execute query: \`SELECT category_id, name FROM categories LIMIT 32\`
+2. Execute query: \`SELECT store_id, name FROM stores LIMIT 32\`
+3. Present: "I can help you create a new product. Available categories: Furniture (id: 1), Kitchen (id: 2)... Available stores: Store A (id: 10), Store B (id: 20)..."
+4. Suggest Form component
+
 ## Component Suggestions
 
-After analyzing the query results, you MUST suggest appropriate dashboard components for displaying the data. Use this format:
+After analyzing the user's question, you MUST suggest appropriate dashboard components. Use this format:
 
 <DashboardComponents>
 **Dashboard Components:**
@@ -2319,12 +1975,22 @@ Format: \`{number}.{component_type} : {clear reasoning}\`
 
 
 **Rules for component suggestions:**
-1. Analyze the query results structure and data type
-2. Suggest components that would best visualize the data
-3. Each component suggestion must be on a new line
+1. If a conclusive answer can be provided based on user question, suggest that as the first component.
+2. ALways suggest context/supporting components that will give the user more information and allow them to explore further.
+3. If the question includes a time range, also explore time-based components for past time ranges.
+4. **For data viewing/analysis questions**: Suggest visualization components (KPICard, BarChart, LineChart, PieChart, DataTable, etc.).
+5. **For data modification questions** (create/add/update/delete):
+   - Always suggest 1-2 context components first to provide relevant information (prefer KPICard for showing key metrics)
+   - Then suggest \`Form\` component for the actual modification
+   - Example: "1.KPICard : Show current order total and status" then "2.Form : To update order details"
+6. Analyze the query results structure and data type
+7. Each component suggestion must be on a new line
 </DashboardComponents>
 
-IMPORTANT: Always wrap component suggestions with <DashboardComponents> tags and include at least one component suggestion when data is returned.
+IMPORTANT:
+- Always wrap component suggestions with <DashboardComponents> tags
+- For data viewing: Include at least one component suggestion when data is returned
+- For data modifications: Always suggest 1-2 context components before Form (e.g., "1.KPICard : Show current order value" then "2.Form : To update order status")
 
 ## Output Format
 
@@ -2339,37 +2005,22 @@ Respond with plain text that includes:
 - Return ONLY plain text (no JSON, no markdown code blocks)
 
 
-You have access to a database and can execute SQL queries to answer data-related questions.
-## Database Schema
-{{SCHEMA_DOC}}
-
-**Database Type: PostgreSQL**
-
-**CRITICAL PostgreSQL Query Rules:**
+You have access to a database and can execute SQL queries to answer data-related questions. For data modifications, the system provides form-based interfaces.
 
-1. **NO AGGREGATE FUNCTIONS IN WHERE CLAUSE** - This is a fundamental SQL error
-   \u274C WRONG: \`WHERE COUNT(orders) > 0\`
-   \u274C WRONG: \`WHERE SUM(price) > 100\`
-   \u274C WRONG: \`WHERE AVG(rating) > 4.5\`
 
-   \u2705 CORRECT: Use HAVING (with GROUP BY), EXISTS, or subquery
+## External Tool Results
 
-2. **WHERE vs HAVING**
-   - WHERE filters rows BEFORE grouping (cannot use aggregates)
-   - HAVING filters groups AFTER grouping (can use aggregates)
-   - If using HAVING, you MUST have GROUP BY
+The following external tools were executed for this request (if applicable):
 
-3. **NO NESTED AGGREGATE FUNCTIONS** - PostgreSQL does NOT allow aggregates inside aggregates
-   \u274C WRONG: \`AVG(ROUND(AVG(column), 2))\` or \`SELECT AVG(SUM(price)) FROM ...\`
-   \u2705 CORRECT: \`ROUND(AVG(column), 2)\`
+{{EXTERNAL_TOOL_CONTEXT}}
 
-4. **GROUP BY Requirements**
-   - ALL non-aggregated columns in SELECT must be in GROUP BY
-   - If you SELECT a column and don't aggregate it, add it to GROUP BY
+Use this external tool data to:
+- Provide information from external sources (emails, calendar, etc.)
+- Present the data in a user-friendly format
+- Combine external data with database queries when relevant
+- Reference specific results in your response
 
-5. **LIMIT Clause**
-   - ALWAYS include LIMIT (max 32 rows)
-   - For scalar subqueries in WHERE/HAVING, add LIMIT 1
+**Note:** If external tools were not needed, this section will indicate "No external tools were used for this request."
 
 
 ## Knowledge Base Context
@@ -2392,10 +2043,8 @@ Use this knowledge base information to:
 ## Previous Conversation
 {{CONVERSATION_HISTORY}}
 
-
 `,
     user: `{{USER_PROMPT}}
-
 `
   },
   "match-text-components": {
@@ -2409,11 +2058,21 @@ You will receive a text response containing:
 3. **Dashboard Components:** suggestions (1:component_type : reasoning format)
 
 Your job is to:
-1. **Parse the component suggestions** from the text response (format: 1:component_type : reasoning)
-2. **Match each suggestion with an actual component** from the available list
-3. **Generate proper props** for each matched component to **visualize the analysis results** that were already fetched
-4. **Generate title and description** for the dashboard container
-5. **Generate intelligent follow-up questions (actions)** that the user might naturally ask next based on the data analysis
+1. **FIRST: Generate a direct answer component** (if the user question can be answered with a single visualization)
+   - Determine the BEST visualization type (KPICard, BarChart, DataTable, PieChart, LineChart, etc.) to directly answer the user's question
+   - Select the matching component from the available components list
+   - Generate complete props for this component (query, title, description, config)
+   - This component will be placed in the \`answerComponent\` field
+   - This component will be streamed to the frontend IMMEDIATELY for instant user feedback
+   - **CRITICAL**: Generate this FIRST in your JSON response
+
+2. **THEN: Parse ALL dashboard component suggestions** from the text response (format: 1:component_type : reasoning)
+3. **Match EACH suggestion with an actual component** from the available list
+4. **CRITICAL**: \`matchedComponents\` must include **ALL** dashboard components suggested in the text, INCLUDING the component you used as \`answerComponent\`
+   - The answerComponent is shown first for quick feedback, but the full dashboard shows everything
+5. **Generate proper props** for each matched component to **visualize the analysis results** that were already fetched
+6. **Generate title and description** for the dashboard container
+7. **Generate intelligent follow-up questions (actions)** that the user might naturally ask next based on the data analysis
 
 **CRITICAL GOAL**: Create dashboard components that display the **same data that was already analyzed** - NOT new data. The queries already ran and got results. You're just creating different visualizations of those results.
 
@@ -2448,7 +2107,8 @@ For each matched component, generate complete props:
 
 **Option B: GENERATE a new query** (when necessary)
 - Only generate new queries when you need DIFFERENT data
-- Use the database schema below to write valid SQL
+- For SELECT queries: Use the database schema below to write valid SQL
+- For mutations (INSERT/UPDATE/DELETE): Only if matching a Form component, generate mutation query with $fieldName placeholders
 
 
 **Decision Logic:**
@@ -2466,8 +2126,12 @@ For each matched component, generate complete props:
    \u274C WRONG: \`WHERE COUNT(orders) > 0\`
    \u274C WRONG: \`WHERE SUM(price) > 100\`
    \u274C WRONG: \`WHERE AVG(rating) > 4.5\`
+   \u274C WRONG: \`WHERE FLOOR(AVG(rating)) = 4\` (aggregate inside any function is still not allowed)
+   \u274C WRONG: \`WHERE ROUND(SUM(price), 2) > 100\`
 
     \u2705 CORRECT: Use HAVING (with GROUP BY), EXISTS, or subquery
+    \u2705 CORRECT: Move aggregate logic to HAVING: \`GROUP BY ... HAVING FLOOR(AVG(rating)) = 4\`
+    \u2705 CORRECT: Use subquery for filtering: \`WHERE product_id IN (SELECT product_id FROM ... GROUP BY ... HAVING AVG(rating) >= 4)\`
 
 2. **NO NESTED AGGREGATE FUNCTIONS** - PostgreSQL does NOT allow aggregates inside aggregates
    \u274C WRONG: \`AVG(ROUND(AVG(column), 2))\`
@@ -2496,6 +2160,16 @@ For each matched component, generate complete props:
    - Subqueries used with =, <, >, etc. must return single value
    - Always add LIMIT 1 to scalar subqueries
 
+8. **String Escaping** - PostgreSQL uses double single-quotes, NOT backslash
+   \u274C WRONG: \`'Children\\'s furniture'\`
+   \u2705 CORRECT: \`'Children''s furniture'\`
+
+9. **Always Use Table Aliases for Column References** - Prevent ambiguous column errors
+   \u274C WRONG: \`SELECT product_id FROM products p JOIN product_variants pv ON p.product_id = pv.product_id\`
+   \u2705 CORRECT: \`SELECT p.product_id FROM products p JOIN product_variants pv ON p.product_id = pv.product_id\`
+   - Always prefix columns with table alias (e.g., \`p.product_id\`, \`c.name\`)
+   - Especially critical in subqueries and joins where multiple tables share column names
+
 **Query Generation Guidelines** (when creating new queries):
 - Use correct table and column names from the schema above
 - ALWAYS include LIMIT clause (max 32 rows)
@@ -2509,7 +2183,7 @@ For each matched component, generate complete props:
 - Brief explanation of what this component displays
 - Why it's useful for this data
 
-### 4. Config
+### 4. Config (for visualization components)
 - **CRITICAL**: Look at the component's "Props Structure" to see what config fields it expects
 - Map query result columns to the appropriate config fields
 - Keep other existing config properties that don't need to change
@@ -2521,40 +2195,167 @@ For each matched component, generate complete props:
 - \`orientation\` = "vertical" or "horizontal" (controls visual direction only)
 - **DO NOT swap xAxisKey/yAxisKey based on orientation** - they always represent category and value respectively
 
-## Follow-Up Questions (Actions) Generation
+### 5. Additional Props (match according to component type)
+- **CRITICAL**: Look at the matched component's "Props Structure" in the available components list
+- Generate props that match EXACTLY what the component expects
 
-After analyzing the text response and matched components, generate 4-5 intelligent follow-up questions that the user might naturally ask next. These questions should:
+**For Form components (type: "Form"):**
 
-1. **Build upon the data analysis** shown in the text response and components
-2. **Explore natural next steps** in the data exploration journey
-3. **Be progressively more detailed or specific** - go deeper into the analysis
-4. **Consider the insights revealed** - suggest questions that help users understand implications
-5. **Be phrased naturally** as if a real user would ask them
-6. **Vary in scope** - include both broad trends and specific details
-7. **Avoid redundancy** - don't ask questions already answered in the text response
+Props structure:
+- **query**: \`{ sql: "INSERT/UPDATE/DELETE query with $fieldName placeholders", params: [] }\`
+  - **For UPDATE queries**: Check the database schema - if the table has an \`updated_at\` or \`last_updated\` column, always include it in the SET clause with \`CURRENT_TIMESTAMP\` (e.g., \`UPDATE table_name SET field = $field, updated_at = CURRENT_TIMESTAMP WHERE id = value\`)
+- **title**: "Update Order 5000", "Create New Product", or "Delete Order 5000"
+- **description**: What the form does
+- **submitButtonText**: Button text (default: "Submit"). For delete: "Delete", "Confirm Delete"
+- **submitButtonColor**: "primary" (blue) or "danger" (red). Use "danger" for DELETE operations
+- **successMessage**: Success message (default: "Form submitted successfully!"). For delete: "Record deleted successfully!"
+- **disableFields**: Set \`true\` for DELETE operations to show current values but prevent editing
+- **fields**: Array of field objects (structure below)
 
+**Field object:**
+\`\`\`json
+{
+  "name": "field_name",           // Matches $field_name in SQL query
+  "description": "Field Label",
+  "type": "text|number|email|date|select|multiselect|checkbox|textarea",
+  "required": true,               // Set based on schema: nullable=false \u2192 required=true, nullable=true \u2192 required=false
+  "defaultValue": "current_value", // For UPDATE: extract from text response
+  "placeholder": "hint text",
+  "options": [...],                // For select/multiselect
+  "validation": {
+    "minLength": { "value": 5, "message": "..." },
+    "maxLength": { "value": 100, "message": "..." },
+    "min": { "value": 18, "message": "..." },
+    "max": { "value": 120, "message": "..." },
+    "pattern": { "value": "regex", "message": "..." }
+  }
+}
+\`\`\`
 
-## Output Format
+**CRITICAL - Set required based on database schema:**
+- Check the column's \`nullable\` property in the database schema
+- If \`nullable: false\` \u2192 set \`required: true\` (field is mandatory)
+- If \`nullable: true\` \u2192 set \`required: false\` (field is optional)
+- Never set fields as required if the schema allows NULL
 
-You MUST respond with ONLY a valid JSON object (no markdown, no code blocks):
+**Default Values for UPDATE:**
+- **NEVER include ID/primary key fields in UPDATE forms** (e.g., order_id, customer_id, product_id) - these cannot be changed
+- Detect UPDATE by checking if SQL contains "UPDATE" keyword
+- Extract current values from text response (look for "Current values:" or SELECT results)
+- Set \`defaultValue\` for each field with the extracted current value
 
-**IMPORTANT JSON FORMATTING RULES:**
-- Put SQL queries on a SINGLE LINE (no newlines in the query string)
-- Escape all quotes in SQL properly (use \\" for quotes inside strings)
-- Remove any newlines, tabs, or special characters from SQL
-- Do NOT use markdown code blocks (no \`\`\`)
-- Return ONLY the JSON object, nothing else
+**CRITICAL - Single field with current value pre-selected:**
+For UPDATE operations, use ONE field with defaultValue set to current value (not two separate fields).
 
+\u2705 CORRECT - Single field, current value pre-selected:
 \`\`\`json
 {
-  "layoutTitle": "Clear, concise title for the overall dashboard/layout (5-10 words)",
-  "layoutDescription": "Brief description of what the dashboard shows and its purpose (1-2 sentences)",
-  "matchedComponents": [
-    {
-      "componentId": "id_from_available_list",
-      "componentName": "name_of_component",
-      "componentType": "type_of_component",
-      "reasoning": "Why this component was selected for this suggestion",
+  "name": "category_id",
+  "type": "select",
+  "defaultValue": 5,
+  "options": [{"id": 1, "name": "Kitchen"}, {"id": 5, "name": "Furniture"}, {"id": 7, "name": "Decor"}]
+}
+\`\`\`
+User sees dropdown with "Furniture" selected, can change to any other category.
+
+\u274C WRONG - Two separate fields:
+\`\`\`json
+[
+  {"name": "current_category", "type": "text", "defaultValue": "Furniture", "disabled": true},
+  {"name": "new_category", "type": "select", "options": [...]}
+]
+\`\`\`
+
+**Options Format:**
+- **Enum/status fields** (non-foreign keys): String array \`["Pending", "Shipped", "Delivered"]\`
+- **Foreign keys** (reference tables): Object array \`[{"id": 1, "name": "Furniture"}, {"id": 2, "name": "Kitchen"}]\`
+- Extract from text response queries and match format to field type
+
+**Example UPDATE form field:**
+\`\`\`json
+{
+  "name": "status",
+  "description": "Order Status",
+  "type": "select",
+  "required": true,
+  "defaultValue": "Pending",  // Current value from database
+  "options": ["Pending", "Processing", "Shipped", "Delivered"]
+}
+\`\`\`
+
+**Example DELETE form props:**
+\`\`\`json
+{
+  "query": { "sql": "DELETE FROM orders WHERE order_id = 123", "params": [] },
+  "title": "Delete Order 123",
+  "description": "Are you sure you want to delete this order?",
+  "submitButtonText": "Confirm Delete",
+  "submitButtonColor": "danger",
+  "successMessage": "Order deleted successfully!",
+  "disableFields": true,
+  "fields": [
+    { "name": "order_id", "description": "Order ID", "type": "text", "defaultValue": "123" },
+    { "name": "status", "description": "Status", "type": "text", "defaultValue": "Pending" }
+  ]
+}
+\`\`\`
+
+**For visualization components (Charts, Tables, KPIs):**
+- **query**: String (SQL SELECT query)
+- **title**, **description**, **config**: As per component's props structure
+- Do NOT include fields array
+
+## Follow-Up Questions (Actions) Generation
+
+After analyzing the text response and matched components, generate 4-5 intelligent follow-up questions that the user might naturally ask next. These questions should:
+
+1. **Build upon the data analysis** shown in the text response and components
+2. **Explore natural next steps** in the data exploration journey
+3. **Be progressively more detailed or specific** - go deeper into the analysis
+4. **Consider the insights revealed** - suggest questions that help users understand implications
+5. **Be phrased naturally** as if a real user would ask them
+6. **Vary in scope** - include both broad trends and specific details
+7. **Avoid redundancy** - don't ask questions already answered in the text response
+
+
+## Output Format
+
+You MUST respond with ONLY a valid JSON object (no markdown, no code blocks):
+
+**IMPORTANT JSON FORMATTING RULES:**
+- Put SQL queries on a SINGLE LINE (no newlines in the query string)
+- Escape all quotes in SQL properly (use \\" for quotes inside strings)
+- Remove any newlines, tabs, or special characters from SQL
+- Do NOT use markdown code blocks (no \`\`\`)
+- Return ONLY the JSON object, nothing else
+
+**Example 1: With answer component** (when user question can be answered with single visualization)
+\`\`\`json
+{
+  "hasAnswerComponent": true,
+  "answerComponent": {
+    "componentId": "id_from_available_list",
+    "componentName": "name_of_component",
+    "componentType": "type_of_component (can be KPICard, BarChart, LineChart, PieChart, DataTable, etc.)",
+    "reasoning": "Why this visualization type best answers the user's question",
+    "props": {
+      "query": "SQL query for this component",
+      "title": "Component title that directly answers the user's question",
+      "description": "Component description",
+      "config": {
+        "field1": "value1",
+        "field2": "value2"
+      }
+    }
+  },
+  "layoutTitle": "Clear, concise title for the overall dashboard/layout (5-10 words)",
+  "layoutDescription": "Brief description of what the dashboard shows and its purpose (1-2 sentences)",
+  "matchedComponents": [
+    {
+      "componentId": "id_from_available_list",
+      "componentName": "name_of_component",
+      "componentType": "type_of_component",
+      "reasoning": "Why this component was selected for the dashboard",
       "originalSuggestion": "c1:table : original reasoning from text",
       "props": {
         "query": "SQL query for this component",
@@ -2577,21 +2378,65 @@ You MUST respond with ONLY a valid JSON object (no markdown, no code blocks):
 }
 \`\`\`
 
+**Example 2: Without answer component** (when user question needs multiple visualizations or dashboard)
+\`\`\`json
+{
+  "hasAnswerComponent": false,
+  "answerComponent": null,
+  "layoutTitle": "Clear, concise title for the overall dashboard/layout (5-10 words)",
+  "layoutDescription": "Brief description of what the dashboard shows and its purpose (1-2 sentences)",
+  "matchedComponents": [
+    {
+      "componentId": "id_from_available_list",
+      "componentName": "name_of_component",
+      "componentType": "type_of_component",
+      "reasoning": "Why this component was selected for the dashboard",
+      "originalSuggestion": "c1:chart : original reasoning from text",
+      "props": {
+        "query": "SQL query for this component",
+        "title": "Component title",
+        "description": "Component description",
+        "config": {
+          "field1": "value1",
+          "field2": "value2"
+        }
+      }
+    }
+  ],
+  "actions": [
+    "Follow-up question 1?",
+    "Follow-up question 2?",
+    "Follow-up question 3?",
+    "Follow-up question 4?",
+    "Follow-up question 5?"
+  ]
+}
+\`\`\`
+
 **CRITICAL:**
-- \`matchedComponents\` MUST include ALL components suggested in the text response
+- **\`hasAnswerComponent\` determines if an answer component exists**
+  - Set to \`true\` if the user question can be answered with a single visualization
+  - Set to \`false\` if the user question can not be answered with single visualisation and  needs multiple visualizations or a dashboard overview
+- **If \`hasAnswerComponent\` is \`true\`:**
+  - \`answerComponent\` MUST be generated FIRST in the JSON before \`layoutTitle\`
+  - Generate complete props (query, title, description, config)
+- **If \`hasAnswerComponent\` is \`false\`:**
+  - Set \`answerComponent\` to \`null\`
+- **\`matchedComponents\` MUST include ALL dashboard components from the text analysis**
+  - **CRITICAL**: Even if you used a component as \`answerComponent\`, you MUST STILL include it in \`matchedComponents\`
+  - The count of matchedComponents should EQUAL the count of dashboard suggestions in the text (e.g., if text has 4 suggestions, matchedComponents should have 4 items)
+  - Do NOT skip the answerComponent from matchedComponents
+- \`matchedComponents\` come from the dashboard component suggestions in the text response
 - \`layoutTitle\` MUST be a clear, concise title (5-10 words) that summarizes what the entire dashboard shows
-  - Examples: "Sales Performance Overview", "Customer Metrics Analysis", "Product Category Breakdown"
 - \`layoutDescription\` MUST be a brief description (1-2 sentences) explaining the purpose and scope of the dashboard
   - Should describe what insights the dashboard provides and what data it shows
 - \`actions\` MUST be an array of 4-5 intelligent follow-up questions based on the analysis
 - Return ONLY valid JSON (no markdown code blocks, no text before/after)
-- Generate complete props for each component including query, title, description, and config
-
-
+- Generate complete props for each component
 `,
-    user: `## Text Response
+    user: `## Analysis Content
 
-{{TEXT_RESPONSE}}
+{{ANALYSIS_CONTENT}}
 
 ---
 
@@ -2638,70 +2483,269 @@ Format your response as a JSON object with this structure:
 
 Return ONLY valid JSON.`
   },
-  "execute-tools": {
-    system: `You are an expert AI assistant that executes external tools to fetch data from external services.
+  "category-classification": {
+    system: `You are an expert AI that categorizes user questions into specific action categories and identifies required tools/resources.
 
-You have access to external tools that can retrieve information like emails, calendar events, and other external data. When the user requests this information, you should call the appropriate tools.
+CRITICAL: You MUST respond with ONLY valid JSON, no other text before or after.
 
 ## Available External Tools
+
 {{AVAILABLE_TOOLS}}
 
-## Your Task
+---
 
-Analyze the user's request and:
-
-1. **Determine if external tools are needed**
-   - Examples that NEED external tools:
-     - "Show me my emails" \u2192 needs email tool
-     - "Get my last 5 Gmail messages" \u2192 needs Gmail tool
-     - "Check my Outlook inbox" \u2192 needs Outlook tool
-
-   - Examples that DON'T need external tools:
-     - "What is the total sales?" \u2192 database query (handled elsewhere)
-     - "Show me revenue trends" \u2192 internal data analysis
-     - "Hello" \u2192 general conversation
-
-2. **Call the appropriate tools**
-   - Use the tool calling mechanism to execute external tools
-   - Extract parameters from the user's request
-   - Use sensible defaults when parameters aren't specified:
-     - For email limit: default to 10
-     - For email address: use "me" for the authenticated user if not specified
-
-3. **Handle errors and retry**
-   - If a tool call fails, analyze the error message
-   - Retry with corrected parameters if possible
-   - You have up to 3 attempts per tool
-
-## Important Guidelines
-
-- **Only call external tools when necessary** - Don't call tools for database queries or general conversation
-- **Choose the right tool** - For email requests, select Gmail vs Outlook based on:
-  - Explicit mention (e.g., "Gmail", "Outlook")
-  - Email domain (e.g., @gmail.com \u2192 Gmail, @company.com \u2192 Outlook)
-- **Extract parameters carefully** - Use the user's exact values when provided
-- **If no tools are needed** - Simply respond that no external tools are required for this request
-
-## Examples
-
-**Example 1 - Gmail Request:**
-User: "Show me my last 5 Gmail messages"
-Action: Call get-gmail-mails tool with parameters: { email: "me", limit: 5 }
-
-**Example 2 - Outlook Request:**
-User: "Get emails from john.doe@company.com"
-Action: Call get-outlook-mails tool with parameters: { email: "john.doe@company.com", limit: 10 }
-
-**Example 3 - No Tools Needed:**
-User: "What is the total sales?"
-Response: This is a database query, not an external tool request. No external tools are needed.
-
-**Example 4 - Error Retry:**
-Tool call fails with: "Invalid email parameter"
-Action: Analyze error, correct the parameter, and retry the tool call
-`,
-    user: `{{USER_PROMPT}}
-`
+Your task is to analyze the user's question and determine:
+
+1. **Question Category:**
+   - "data_analysis": Questions about analyzing, querying, reading, or visualizing data from the database (SELECT operations)
+   - "data_modification": Questions about creating, updating, deleting, or modifying data in the database (INSERT, UPDATE, DELETE operations)
+
+2. **External Tools Required** (for both categories):
+   From the available tools listed above, identify which ones are needed to support the user's request:
+   - Match the tool names/descriptions to what the user is asking for
+   - Extract specific parameters mentioned in the user's question
+
+3. **Tool Parameters** (if tools are identified):
+   Extract specific parameters the user mentioned:
+   - For each identified tool, extract relevant parameters (email, recipient, content, etc.)
+   - Only include parameters the user explicitly or implicitly mentioned
+
+**Important Guidelines:**
+- If user mentions any of the available external tools \u2192 identify those tools and extract their parameters
+- If user asks to "send", "schedule", "create event", "message" \u2192 check if available tools match
+- If user asks to "show", "analyze", "compare", "calculate" data \u2192 "data_analysis"
+- If user asks to modify/create/update/delete data \u2192 "data_modification"
+- Always identify tools from the available tools list (not from generic descriptions)
+- Be precise in identifying tool types and required parameters
+- Only include tools that are explicitly mentioned or clearly needed
+
+**Output Format:**
+\`\`\`json
+{
+  "category": "data_analysis" | "data_modification",
+  "reasoning": "Brief explanation of why this category was chosen",
+  "externalTools": [
+    {
+      "type": "tool_id_from_available_tools",
+      "name": "Tool Display Name",
+      "description": "What this tool will do",
+      "parameters": {
+        "param1": "extracted value",
+        "param2": "extracted value"
+      }
+    }
+  ],
+  "dataAnalysisType": "visualization" | "calculation" | "comparison" | "trend" | null,
+  "confidence": 0-100
+}
+\`\`\`
+
+
+## Previous Conversation
+{{CONVERSATION_HISTORY}}`,
+    user: `{{USER_PROMPT}}`
+  },
+  "adapt-ui-block-params": {
+    system: `You are an expert AI that adapts and modifies UI block component parameters based on the user's current question.
+
+CRITICAL: You MUST respond with ONLY valid JSON, no other text before or after.
+
+## Database Schema Reference
+
+{{SCHEMA_DOC}}
+
+Use this schema to understand available tables, columns, and relationships when modifying SQL queries. Ensure all table and column names you use in adapted queries are valid according to this schema.
+
+## Context
+You are given:
+1. A previous UI Block response (with component and its props) that matched the user's current question with >90% semantic similarity
+2. The user's current question
+3. The component that needs parameter adaptation
+
+Your task is to:
+1. **Analyze the difference** between the original question (from the matched UIBlock) and the current user question
+2. **Identify what parameters need to change** in the component props to answer the current question
+3. **Modify the props** to match the current request while keeping the same component type(s)
+4. **Preserve component structure** - only change props, not the components themselves
+
+## Component Structure Handling
+
+### For Single Components:
+- Modify props directly (config, actions, query, filters, etc.)
+
+### For MultiComponentContainer:
+The component will have structure:
+\`\`\`json
+{
+  "type": "Container",
+  "name": "MultiComponentContainer",
+  "props": {
+    "config": {
+      "components": [...],  // Array of nested components - ADAPT EACH ONE
+      "title": "...",       // Container title - UPDATE based on new question
+      "description": "..."  // Container description - UPDATE based on new question
+    },
+    "actions": [...]        // ADAPT actions if needed
+  }
+}
+\`\`\`
+
+When adapting MultiComponentContainer:
+- Update the container-level \`title\` and \`description\` to reflect the new user question
+- For each component in \`config.components\`:
+  - Identify what data it shows and how the new question changes what's needed
+  - Adapt its query parameters (WHERE clauses, LIMIT, ORDER BY, filters, date ranges)
+  - Update its title/description to match the new context
+  - Update its config settings (colors, sorting, grouping, metrics)
+- Update \`actions\` if the new question requires different actions
+
+## Important Guidelines:
+- Keep the same component type (don't change KPICard to LineChart)
+- Keep the same number of components in the container
+- For each nested component, update:
+  - Query WHERE clauses, LIMIT, ORDER BY, filters, date ranges, metrics
+  - Title and description to reflect the new question
+  - Config settings like colors, sorting, grouping if needed
+- Maintain each component's core purpose while answering the new question
+- If query modification is needed, ensure all table/column names remain valid
+- CRITICAL: Ensure JSON is valid and complete for all nested structures
+
+
+## Output Format:
+
+### For Single Component:
+\`\`\`json
+{
+  "success": true,
+  "adaptedComponent": {
+    "id": "original_component_id",
+    "name": "component_name",
+    "type": "component_type",
+    "description": "updated_description",
+    "props": {
+      "config": { },
+      "actions": [],
+    }
+  },
+  "parametersChanged": [
+    {
+      "field": "query",
+      "reason": "Added Q4 date filter"
+    },
+    {
+      "field": "title",
+      "reason": "Updated to reflect Q4 focus"
+    }
+  ],
+  "explanation": "How the component was adapted to answer the new question"
+}
+\`\`\`
+
+### For MultiComponentContainer:
+\`\`\`json
+{
+  "success": true,
+  "adaptedComponent": {
+    "id": "original_container_id",
+    "name": "MultiComponentContainer",
+    "type": "Container",
+    "description": "updated_container_description",
+    "props": {
+      "config": {
+        "title": "Updated dashboard title based on new question",
+        "description": "Updated description reflecting new question context",
+        "components": [
+          {
+            "id": "component_1_id",
+            "name": "component_1_name",
+            "type": "component_1_type",
+            "description": "updated description for this specific component",
+            "props": {
+              "query": "Modified SQL query with updated WHERE/LIMIT/ORDER BY",
+              "config": { "metric": "updated_metric", "filters": {...} }
+            }
+          },
+          {
+            "id": "component_2_id",
+            "name": "component_2_name",
+            "type": "component_2_type",
+            "description": "updated description for this component",
+            "props": {
+              "query": "Modified SQL query for this component",
+              "config": { "metric": "updated_metric", "filters": {...} }
+            }
+          }
+        ]
+      },
+      "actions": []
+    }
+  },
+  "parametersChanged": [
+    {
+      "field": "container.title",
+      "reason": "Updated to reflect new dashboard focus"
+    },
+    {
+      "field": "components[0].query",
+      "reason": "Modified WHERE clause for new metrics"
+    },
+    {
+      "field": "components[1].config.metric",
+      "reason": "Changed metric from X to Y based on new question"
+    }
+  ],
+  "explanation": "Detailed explanation of how each component was adapted"
+}
+\`\`\`
+
+If adaptation is not possible or would fundamentally change the component:
+\`\`\`json
+{
+  "success": false,
+  "reason": "Cannot adapt component - the new question requires a different visualization type",
+  "explanation": "The original component shows KPI cards but the new question needs a trend chart"
+}
+\`\`\``,
+    user: `## Previous Matched UIBlock
+
+**Original Question:** {{ORIGINAL_USER_PROMPT}}
+
+**Matched UIBlock Component:**
+\`\`\`json
+{{MATCHED_UI_BLOCK_COMPONENT}}
+\`\`\`
+
+**Component Properties:**
+\`\`\`json
+{{COMPONENT_PROPS}}
+\`\`\`
+
+## Current User Question
+{{CURRENT_USER_PROMPT}}
+
+---
+
+## Adaptation Instructions
+
+1. **Analyze the difference** between the original question and the current question
+2. **Identify what data needs to change**:
+   - For single components: adapt the query/config/actions
+   - For MultiComponentContainer: adapt the container title/description AND each nested component's parameters
+
+3. **Modify the parameters**:
+   - **Container level** (if MultiComponentContainer):
+     - Update \`title\` and \`description\` to reflect the new user question
+     - Update \`actions\` if needed
+
+   - **For each component** (single or nested in container):
+     - Identify what it shows (sales, revenue, inventory, etc.)
+     - Adapt SQL queries: modify WHERE clauses, LIMIT, ORDER BY, filters, date ranges
+     - Update component title and description
+     - Update config settings (metrics, colors, sorting, grouping)
+
+4. **Preserve structure**: Keep the same number and type of components
+
+5. **Return complete JSON** with all adapted properties for all components`
   }
 };
 
@@ -2779,9 +2823,10 @@ var PromptLoader = class {
   }
   /**
    * Load both system and user prompts from cache and replace variables
+   * Supports prompt caching by splitting static and dynamic content
    * @param promptName - Name of the prompt
    * @param variables - Variables to replace in the templates
-   * @returns Object containing both system and user prompts
+   * @returns Object containing both system and user prompts (system can be string or array for caching)
    */
   async loadPrompts(promptName, variables) {
     if (!this.isInitialized) {
@@ -2792,6 +2837,26 @@ var PromptLoader = class {
     if (!template) {
       throw new Error(`Prompt template '${promptName}' not found in cache. Available prompts: ${Array.from(this.promptCache.keys()).join(", ")}`);
     }
+    const contextMarker = "---\n\n## CONTEXT";
+    if (template.system.includes(contextMarker)) {
+      const [staticPart, contextPart] = template.system.split(contextMarker);
+      logger.debug(`\u2713 Prompt caching enabled for '${promptName}' (static: ${staticPart.length} chars, context: ${contextPart.length} chars)`);
+      const processedContext = this.replaceVariables(contextMarker + contextPart, variables);
+      return {
+        system: [
+          {
+            type: "text",
+            text: staticPart.trim(),
+            cache_control: { type: "ephemeral" }
+          },
+          {
+            type: "text",
+            text: processedContext.trim()
+          }
+        ],
+        user: this.replaceVariables(template.user, variables)
+      };
+    }
     return {
       system: this.replaceVariables(template.system, variables),
       user: this.replaceVariables(template.user, variables)
@@ -2878,6 +2943,75 @@ var LLM = class {
   // ============================================================
   // PRIVATE HELPER METHODS
   // ============================================================
+  /**
+   * 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
+   */
+  static _normalizeSystemPrompt(sys) {
+    if (typeof sys === "string") {
+      return sys;
+    }
+    return sys;
+  }
+  /**
+   * Log cache usage metrics from Anthropic API response
+   * Shows cache hits, costs, and savings
+   */
+  static _logCacheUsage(usage) {
+    if (!usage) return;
+    const inputTokens = usage.input_tokens || 0;
+    const cacheCreationTokens = usage.cache_creation_input_tokens || 0;
+    const cacheReadTokens = usage.cache_read_input_tokens || 0;
+    const outputTokens = usage.output_tokens || 0;
+    const INPUT_PRICE = 0.8;
+    const OUTPUT_PRICE = 4;
+    const CACHE_WRITE_PRICE = 1;
+    const CACHE_READ_PRICE = 0.08;
+    const regularInputCost = inputTokens / 1e6 * INPUT_PRICE;
+    const cacheWriteCost = cacheCreationTokens / 1e6 * CACHE_WRITE_PRICE;
+    const cacheReadCost = cacheReadTokens / 1e6 * CACHE_READ_PRICE;
+    const outputCost = outputTokens / 1e6 * OUTPUT_PRICE;
+    const totalCost = regularInputCost + cacheWriteCost + cacheReadCost + outputCost;
+    const totalInputTokens = inputTokens + cacheCreationTokens + cacheReadTokens;
+    const costWithoutCache = totalInputTokens / 1e6 * INPUT_PRICE + outputCost;
+    const savings = costWithoutCache - totalCost;
+    const savingsPercent = costWithoutCache > 0 ? savings / costWithoutCache * 100 : 0;
+    console.log("\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+    console.log("\u{1F4B0} PROMPT CACHING METRICS");
+    console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+    console.log("\n\u{1F4CA} Token Usage:");
+    console.log(`   Input (regular):     ${inputTokens.toLocaleString()} tokens`);
+    if (cacheCreationTokens > 0) {
+      console.log(`   Cache write:         ${cacheCreationTokens.toLocaleString()} tokens (first request)`);
+    }
+    if (cacheReadTokens > 0) {
+      console.log(`   Cache read:          ${cacheReadTokens.toLocaleString()} tokens \u26A1 HIT!`);
+    }
+    console.log(`   Output:              ${outputTokens.toLocaleString()} tokens`);
+    console.log(`   Total input:         ${totalInputTokens.toLocaleString()} tokens`);
+    console.log("\n\u{1F4B5} Cost Breakdown:");
+    console.log(`   Input (regular):     $${regularInputCost.toFixed(6)}`);
+    if (cacheCreationTokens > 0) {
+      console.log(`   Cache write:         $${cacheWriteCost.toFixed(6)}`);
+    }
+    if (cacheReadTokens > 0) {
+      console.log(`   Cache read:          $${cacheReadCost.toFixed(6)} (90% off!)`);
+    }
+    console.log(`   Output:              $${outputCost.toFixed(6)}`);
+    console.log(`   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    console.log(`   Total cost:          $${totalCost.toFixed(6)}`);
+    if (cacheReadTokens > 0) {
+      console.log(`
+\u{1F48E} Savings:              $${savings.toFixed(6)} (${savingsPercent.toFixed(1)}% off)`);
+      console.log(`   Without cache:       $${costWithoutCache.toFixed(6)}`);
+    } else if (cacheCreationTokens > 0) {
+      console.log(`
+\u23F1\uFE0F  Cache created - next request will be ~90% cheaper!`);
+    }
+    console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n");
+  }
   /**
    * Parse model string to extract provider and model name
    * @param modelString - Format: "provider/model-name" or just "model-name"
@@ -2912,7 +3046,7 @@ var LLM = class {
       model: modelName,
       max_tokens: options.maxTokens || 1e3,
       temperature: options.temperature,
-      system: messages.sys,
+      system: this._normalizeSystemPrompt(messages.sys),
       messages: [{
         role: "user",
         content: messages.user
@@ -2930,7 +3064,7 @@ var LLM = class {
       model: modelName,
       max_tokens: options.maxTokens || 1e3,
       temperature: options.temperature,
-      system: messages.sys,
+      system: this._normalizeSystemPrompt(messages.sys),
       messages: [{
         role: "user",
         content: messages.user
@@ -2938,6 +3072,7 @@ var LLM = class {
       stream: true
     });
     let fullText = "";
+    let usage = null;
     for await (const chunk of stream) {
       if (chunk.type === "content_block_delta" && chunk.delta.type === "text_delta") {
         const text = chunk.delta.text;
@@ -2945,8 +3080,12 @@ var LLM = class {
         if (options.partial) {
           options.partial(text);
         }
+      } else if (chunk.type === "message_delta" && chunk.usage) {
+        usage = chunk.usage;
       }
     }
+    if (usage) {
+    }
     if (json) {
       return this._parseJSON(fullText);
     }
@@ -2969,7 +3108,7 @@ var LLM = class {
         model: modelName,
         max_tokens: options.maxTokens || 4e3,
         temperature: options.temperature,
-        system: messages.sys,
+        system: this._normalizeSystemPrompt(messages.sys),
         messages: conversationMessages,
         tools,
         stream: true
@@ -2979,6 +3118,7 @@ var LLM = class {
       const contentBlocks = [];
       let currentTextBlock = "";
       let currentToolUse = null;
+      let usage = null;
       for await (const chunk of stream) {
         if (chunk.type === "message_start") {
           contentBlocks.length = 0;
@@ -3029,11 +3169,16 @@ var LLM = class {
         }
         if (chunk.type === "message_delta") {
           stopReason = chunk.delta.stop_reason || stopReason;
+          if (chunk.usage) {
+            usage = chunk.usage;
+          }
         }
         if (chunk.type === "message_stop") {
           break;
         }
       }
+      if (usage) {
+      }
       if (stopReason === "end_turn") {
         break;
       }
@@ -3205,6 +3350,57 @@ var KB = {
 };
 var knowledge_base_default = KB;
 
+// src/userResponse/conversation-search.ts
+var searchConversations = async ({
+  userPrompt,
+  collections,
+  userId,
+  similarityThreshold = 0.6
+}) => {
+  try {
+    if (!collections || !collections["conversation-history"] || !collections["conversation-history"]["search"]) {
+      logger.info("[ConversationSearch] conversation-history.search collection not registered, skipping");
+      return null;
+    }
+    logger.info(`[ConversationSearch] Searching conversations for: "${userPrompt.substring(0, 50)}..."`);
+    logger.info(`[ConversationSearch] Using similarity threshold: ${(similarityThreshold * 100).toFixed(0)}%`);
+    const result = await collections["conversation-history"]["search"]({
+      userPrompt,
+      userId,
+      threshold: similarityThreshold
+    });
+    if (!result) {
+      logger.info("[ConversationSearch] No matching conversations found");
+      return null;
+    }
+    if (!result.uiBlock) {
+      logger.error("[ConversationSearch] No UI block in conversation search result");
+      return null;
+    }
+    const similarity = result.similarity || 0;
+    logger.info(`[ConversationSearch] Best match similarity: ${(similarity * 100).toFixed(2)}%`);
+    if (similarity < similarityThreshold) {
+      logger.info(
+        `[ConversationSearch] Best match has similarity ${(similarity * 100).toFixed(2)}% but below threshold ${(similarityThreshold * 100).toFixed(2)}%`
+      );
+      return null;
+    }
+    logger.info(
+      `[ConversationSearch] Found matching conversation with similarity ${(similarity * 100).toFixed(2)}%`
+    );
+    logger.debug(`[ConversationSearch] Matched prompt: "${result.metadata?.userPrompt?.substring(0, 50)}..."`);
+    return result;
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    logger.warn(`[ConversationSearch] Error searching conversations: ${errorMsg}`);
+    return null;
+  }
+};
+var ConversationSearch = {
+  searchConversations
+};
+var conversation_search_default = ConversationSearch;
+
 // src/userResponse/base-llm.ts
 var BaseLLM = class {
   constructor(config) {
@@ -3218,531 +3414,6 @@ var BaseLLM = class {
   getApiKey(apiKey) {
     return apiKey || this.apiKey || this.getDefaultApiKey();
   }
-  /**
-   * Classify user question to determine the type and required visualizations
-   */
-  async classifyUserQuestion(userPrompt, apiKey, logCollector, conversationHistory) {
-    try {
-      const prompts = await promptLoader.loadPrompts("classify", {
-        USER_PROMPT: userPrompt,
-        CONVERSATION_HISTORY: conversationHistory || "No previous conversation"
-      });
-      const result = await LLM.stream(
-        {
-          sys: prompts.system,
-          user: prompts.user
-        },
-        {
-          model: this.model,
-          maxTokens: 800,
-          temperature: 0.2,
-          apiKey: this.getApiKey(apiKey)
-        },
-        true
-        // Parse as JSON
-      );
-      logCollector?.logExplanation(
-        "User question classified",
-        result.reasoning || "No reasoning provided",
-        {
-          questionType: result.questionType || "general",
-          visualizations: result.visualizations || [],
-          needsMultipleComponents: result.needsMultipleComponents || false
-        }
-      );
-      return {
-        questionType: result.questionType || "general",
-        visualizations: result.visualizations || [],
-        reasoning: result.reasoning || "No reasoning provided",
-        needsMultipleComponents: result.needsMultipleComponents || false
-      };
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error classifying user question: ${errorMsg}`);
-      logger.debug(`[${this.getProviderName()}] Classification error details:`, error);
-      throw error;
-    }
-  }
-  /**
-   * Enhanced function that validates and modifies the entire props object based on user request
-   * This includes query, title, description, and config properties
-   */
-  async validateAndModifyProps(userPrompt, originalProps, componentName, componentType, componentDescription, apiKey, logCollector, conversationHistory) {
-    const schemaDoc = schema.generateSchemaDocumentation();
-    try {
-      const prompts = await promptLoader.loadPrompts("modify-props", {
-        COMPONENT_NAME: componentName,
-        COMPONENT_TYPE: componentType,
-        COMPONENT_DESCRIPTION: componentDescription || "No description",
-        SCHEMA_DOC: schemaDoc || "No schema available",
-        DEFAULT_LIMIT: this.defaultLimit,
-        USER_PROMPT: userPrompt,
-        CURRENT_PROPS: JSON.stringify(originalProps, null, 2),
-        CONVERSATION_HISTORY: conversationHistory || "No previous conversation"
-      });
-      logger.debug("props-modification: System prompt\n", prompts.system.substring(0, 100), "\n\n\n", "User prompt:", prompts.user.substring(0, 50));
-      const result = await LLM.stream(
-        {
-          sys: prompts.system,
-          user: prompts.user
-        },
-        {
-          model: this.model,
-          maxTokens: 2500,
-          temperature: 0.2,
-          apiKey: this.getApiKey(apiKey)
-        },
-        true
-        // Parse as JSON
-      );
-      const props = result.props || originalProps;
-      if (props && props.query) {
-        props.query = fixScalarSubqueries(props.query);
-        props.query = ensureQueryLimit(props.query, this.defaultLimit);
-      }
-      if (props && props.query) {
-        logCollector?.logQuery(
-          "Props query modified",
-          props.query,
-          {
-            modifications: result.modifications || [],
-            reasoning: result.reasoning || "No modifications needed"
-          }
-        );
-      }
-      if (result.reasoning) {
-        logCollector?.logExplanation(
-          "Props modification explanation",
-          result.reasoning,
-          { modifications: result.modifications || [] }
-        );
-      }
-      return {
-        props,
-        isModified: result.isModified || false,
-        reasoning: result.reasoning || "No modifications needed",
-        modifications: result.modifications || []
-      };
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error validating/modifying props: ${errorMsg}`);
-      logger.debug(`[${this.getProviderName()}] Props validation error details:`, error);
-      throw error;
-    }
-  }
-  /**
-   * Match and select a component from available components filtered by type
-   * This picks the best matching component based on user prompt and modifies its props
-   */
-  async generateAnalyticalComponent(userPrompt, components, preferredVisualizationType, apiKey, logCollector, conversationHistory) {
-    try {
-      const filteredComponents = preferredVisualizationType ? components.filter((c) => c.type === preferredVisualizationType) : components;
-      if (filteredComponents.length === 0) {
-        logCollector?.warn(
-          `No components found of type ${preferredVisualizationType}`,
-          "explanation",
-          { reason: "No matching components available for this visualization type" }
-        );
-        return {
-          component: null,
-          reasoning: `No components available of type ${preferredVisualizationType}`,
-          isGenerated: false
-        };
-      }
-      const componentsText = filteredComponents.map((comp, idx) => {
-        const keywords = comp.keywords ? comp.keywords.join(", ") : "";
-        const category = comp.category || "general";
-        const propsPreview = comp.props ? JSON.stringify(comp.props, null, 2) : "No props";
-        return `${idx + 1}. ID: ${comp.id}
-   Name: ${comp.name}
-   Type: ${comp.type}
-   Category: ${category}
-   Description: ${comp.description || "No description"}
-   Keywords: ${keywords}
-   Props Preview: ${propsPreview}`;
-      }).join("\n\n");
-      const visualizationConstraint = preferredVisualizationType ? `
-**IMPORTANT: Components are filtered to type ${preferredVisualizationType}. Select the best match.**
-` : "";
-      const prompts = await promptLoader.loadPrompts("single-component", {
-        COMPONENT_TYPE: preferredVisualizationType || "any",
-        COMPONENTS_LIST: componentsText,
-        VISUALIZATION_CONSTRAINT: visualizationConstraint,
-        USER_PROMPT: userPrompt,
-        CONVERSATION_HISTORY: conversationHistory || "No previous conversation"
-      });
-      logger.debug("single-component: System prompt\n", prompts.system.substring(0, 100), "\n\n\n", "User prompt:", prompts.user.substring(0, 50));
-      const result = await LLM.stream(
-        {
-          sys: prompts.system,
-          user: prompts.user
-        },
-        {
-          model: this.model,
-          maxTokens: 2e3,
-          temperature: 0.2,
-          apiKey: this.getApiKey(apiKey)
-        },
-        true
-        // Parse as JSON
-      );
-      if (!result.canGenerate || result.confidence < 50) {
-        logCollector?.warn(
-          "Cannot match component",
-          "explanation",
-          { reason: result.reasoning || "Unable to find matching component for this question" }
-        );
-        return {
-          component: null,
-          reasoning: result.reasoning || "Unable to find matching component for this question",
-          isGenerated: false
-        };
-      }
-      const componentIndex = result.componentIndex;
-      const componentId = result.componentId;
-      let matchedComponent = null;
-      if (componentId) {
-        matchedComponent = filteredComponents.find((c) => c.id === componentId);
-      }
-      if (!matchedComponent && componentIndex) {
-        matchedComponent = filteredComponents[componentIndex - 1];
-      }
-      if (!matchedComponent) {
-        logCollector?.warn("Component not found in filtered list");
-        return {
-          component: null,
-          reasoning: "Component not found in filtered list",
-          isGenerated: false
-        };
-      }
-      logCollector?.info(`Matched component: ${matchedComponent.name} (confidence: ${result.confidence}%)`);
-      const propsValidation = await this.validateAndModifyProps(
-        userPrompt,
-        matchedComponent.props,
-        matchedComponent.name,
-        matchedComponent.type,
-        matchedComponent.description,
-        apiKey,
-        logCollector,
-        conversationHistory
-      );
-      const modifiedComponent = {
-        ...matchedComponent,
-        props: propsValidation.props
-      };
-      logCollector?.logExplanation(
-        "Analytical component selected and modified",
-        result.reasoning || "Selected component based on analytical question",
-        {
-          componentName: matchedComponent.name,
-          componentType: matchedComponent.type,
-          confidence: result.confidence,
-          propsModified: propsValidation.isModified
-        }
-      );
-      return {
-        component: modifiedComponent,
-        reasoning: result.reasoning || "Selected and modified component based on analytical question",
-        isGenerated: true
-      };
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error generating analytical component: ${errorMsg}`);
-      logger.debug(`[${this.getProviderName()}] Analytical component generation error details:`, error);
-      throw error;
-    }
-  }
-  /**
-   * Generate container metadata (title and description) for multi-component dashboard
-   */
-  async generateContainerMetadata(userPrompt, visualizationTypes, apiKey, logCollector, conversationHistory) {
-    try {
-      const prompts = await promptLoader.loadPrompts("container-metadata", {
-        USER_PROMPT: userPrompt,
-        VISUALIZATION_TYPES: visualizationTypes.join(", "),
-        CONVERSATION_HISTORY: conversationHistory || "No previous conversation"
-      });
-      const result = await LLM.stream(
-        {
-          sys: prompts.system,
-          user: prompts.user
-        },
-        {
-          model: this.model,
-          maxTokens: 500,
-          temperature: 0.3,
-          apiKey: this.getApiKey(apiKey)
-        },
-        true
-        // Parse as JSON
-      );
-      logCollector?.logExplanation(
-        "Container metadata generated",
-        `Generated title and description for multi-component dashboard`,
-        {
-          title: result.title,
-          description: result.description,
-          visualizationTypes
-        }
-      );
-      return {
-        title: result.title || `${userPrompt} - Dashboard`,
-        description: result.description || `Multi-component dashboard showing ${visualizationTypes.join(", ")}`
-      };
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error generating container metadata: ${errorMsg}`);
-      logger.debug(`[${this.getProviderName()}] Container metadata error details:`, error);
-      return {
-        title: `${userPrompt} - Dashboard`,
-        description: `Multi-component dashboard showing ${visualizationTypes.join(", ")}`
-      };
-    }
-  }
-  /**
-   * Match component from a list with enhanced props modification
-   */
-  async matchComponent(userPrompt, components, apiKey, logCollector, conversationHistory) {
-    try {
-      const componentsText = components.map((comp, idx) => {
-        const keywords = comp.keywords ? comp.keywords.join(", ") : "";
-        const category = comp.category || "general";
-        return `${idx + 1}. ID: ${comp.id}
-   Name: ${comp.name}
-   Type: ${comp.type}
-   Category: ${category}
-   Description: ${comp.description || "No description"}
-   Keywords: ${keywords}`;
-      }).join("\n\n");
-      const prompts = await promptLoader.loadPrompts("match-component", {
-        COMPONENTS_TEXT: componentsText,
-        USER_PROMPT: userPrompt,
-        CONVERSATION_HISTORY: conversationHistory || "No previous conversation"
-      });
-      const result = await LLM.stream(
-        {
-          sys: prompts.system,
-          user: prompts.user
-        },
-        {
-          model: this.model,
-          maxTokens: 800,
-          temperature: 0.2,
-          apiKey: this.getApiKey(apiKey)
-        },
-        true
-        // Parse as JSON
-      );
-      const componentIndex = result.componentIndex;
-      const componentId = result.componentId;
-      const confidence = result.confidence || 0;
-      let component = null;
-      if (componentId) {
-        component = components.find((c) => c.id === componentId);
-      }
-      if (!component && componentIndex) {
-        component = components[componentIndex - 1];
-      }
-      const matchedMsg = `${this.getProviderName()} matched component: ${component?.name || "None"}`;
-      logger.info(`[${this.getProviderName()}] \u2713 ${matchedMsg}`);
-      logCollector?.info(matchedMsg);
-      if (result.alternativeMatches && result.alternativeMatches.length > 0) {
-        logger.debug(`[${this.getProviderName()}] Alternative matches found: ${result.alternativeMatches.length}`);
-        const altMatches = result.alternativeMatches.map(
-          (alt) => `${components[alt.index - 1]?.name} (${alt.score}%): ${alt.reason}`
-        ).join(" | ");
-        logCollector?.info(`Alternative matches: ${altMatches}`);
-        result.alternativeMatches.forEach((alt) => {
-          logger.debug(`[${this.getProviderName()}]   - ${components[alt.index - 1]?.name} (${alt.score}%): ${alt.reason}`);
-        });
-      }
-      if (!component) {
-        const noMatchMsg = `No matching component found (confidence: ${confidence}%)`;
-        logger.warn(`[${this.getProviderName()}] \u2717 ${noMatchMsg}`);
-        logCollector?.warn(noMatchMsg);
-        const genMsg = "Attempting to match component from analytical question...";
-        logger.info(`[${this.getProviderName()}] \u2713 ${genMsg}`);
-        logCollector?.info(genMsg);
-        const generatedResult = await this.generateAnalyticalComponent(userPrompt, components, void 0, apiKey, logCollector, conversationHistory);
-        if (generatedResult.component) {
-          const genSuccessMsg = `Successfully matched component: ${generatedResult.component.name}`;
-          logCollector?.info(genSuccessMsg);
-          return {
-            component: generatedResult.component,
-            reasoning: generatedResult.reasoning,
-            method: `${this.getProviderName()}-generated`,
-            confidence: 100,
-            // Generated components are considered 100% match to the question
-            propsModified: false,
-            queryModified: false
-          };
-        }
-        logCollector?.error("Failed to match component");
-        return {
-          component: null,
-          reasoning: result.reasoning || "No matching component found and unable to match component",
-          method: `${this.getProviderName()}-llm`,
-          confidence
-        };
-      }
-      let propsModified = false;
-      let propsModifications = [];
-      let queryModified = false;
-      let queryReasoning = "";
-      if (component && component.props) {
-        const propsValidation = await this.validateAndModifyProps(
-          userPrompt,
-          component.props,
-          component.name,
-          component.type,
-          component.description,
-          apiKey,
-          logCollector,
-          conversationHistory
-        );
-        const originalQuery = component.props.query;
-        const modifiedQuery = propsValidation.props.query;
-        component = {
-          ...component,
-          props: propsValidation.props
-        };
-        propsModified = propsValidation.isModified;
-        propsModifications = propsValidation.modifications;
-        queryModified = originalQuery !== modifiedQuery;
-        queryReasoning = propsValidation.reasoning;
-      }
-      return {
-        component,
-        reasoning: result.reasoning || "No reasoning provided",
-        queryModified,
-        queryReasoning,
-        propsModified,
-        propsModifications,
-        method: `${this.getProviderName()}-llm`,
-        confidence
-      };
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error matching component: ${errorMsg}`);
-      logger.debug(`[${this.getProviderName()}] Component matching error details:`, error);
-      logCollector?.error(`Error matching component: ${errorMsg}`);
-      throw error;
-    }
-  }
-  /**
-   * Match multiple components for analytical questions by visualization types
-   * This is used when the user needs multiple visualizations
-   */
-  async generateMultipleAnalyticalComponents(userPrompt, availableComponents, visualizationTypes, apiKey, logCollector, conversationHistory) {
-    try {
-      console.log("\u2713 Matching multiple components:", visualizationTypes);
-      const components = [];
-      for (const vizType of visualizationTypes) {
-        const result = await this.generateAnalyticalComponent(userPrompt, availableComponents, vizType, apiKey, logCollector, conversationHistory);
-        if (result.component) {
-          components.push(result.component);
-        }
-      }
-      if (components.length === 0) {
-        return {
-          components: [],
-          reasoning: "Failed to match any components",
-          isGenerated: false
-        };
-      }
-      return {
-        components,
-        reasoning: `Matched ${components.length} components: ${visualizationTypes.join(", ")}`,
-        isGenerated: true
-      };
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error matching multiple analytical components: ${errorMsg}`);
-      logger.debug(`[${this.getProviderName()}] Multiple components matching error details:`, error);
-      return {
-        components: [],
-        reasoning: "Error occurred while matching components",
-        isGenerated: false
-      };
-    }
-  }
-  /**
-   * Match multiple components and wrap them in a container
-   */
-  async generateMultiComponentResponse(userPrompt, availableComponents, visualizationTypes, apiKey, logCollector, conversationHistory) {
-    try {
-      const matchResult = await this.generateMultipleAnalyticalComponents(
-        userPrompt,
-        availableComponents,
-        visualizationTypes,
-        apiKey,
-        logCollector,
-        conversationHistory
-      );
-      if (!matchResult.isGenerated || matchResult.components.length === 0) {
-        return {
-          containerComponent: null,
-          reasoning: matchResult.reasoning || "Unable to match multi-component dashboard",
-          isGenerated: false
-        };
-      }
-      const generatedComponents = matchResult.components;
-      generatedComponents.forEach((component, index) => {
-        if (component.props.query) {
-          logCollector?.logQuery(
-            `Multi-component query generated (${index + 1}/${generatedComponents.length})`,
-            component.props.query,
-            {
-              componentType: component.type,
-              title: component.props.title,
-              position: index + 1,
-              totalComponents: generatedComponents.length
-            }
-          );
-        }
-      });
-      const containerTitle = `${userPrompt} - Dashboard`;
-      const containerDescription = `Multi-component dashboard showing ${visualizationTypes.join(", ")}`;
-      logCollector?.logExplanation(
-        "Multi-component dashboard matched",
-        matchResult.reasoning || `Matched ${generatedComponents.length} components for comprehensive analysis`,
-        {
-          totalComponents: generatedComponents.length,
-          componentTypes: generatedComponents.map((c) => c.type),
-          componentNames: generatedComponents.map((c) => c.name),
-          containerTitle,
-          containerDescription
-        }
-      );
-      const containerComponent = {
-        id: `multi_container_${Date.now()}`,
-        name: "MultiComponentContainer",
-        type: "Container",
-        description: containerDescription,
-        category: "dynamic",
-        keywords: ["multi", "container", "dashboard"],
-        props: {
-          config: {
-            components: generatedComponents,
-            layout: "grid",
-            spacing: 24,
-            title: containerTitle,
-            description: containerDescription
-          }
-        }
-      };
-      return {
-        containerComponent,
-        reasoning: matchResult.reasoning || `Matched multi-component dashboard with ${generatedComponents.length} components`,
-        isGenerated: true
-      };
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error generating multi-component response: ${errorMsg}`);
-      logger.debug(`[${this.getProviderName()}] Multi-component response error details:`, error);
-      throw error;
-    }
-  }
   /**
    * 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
@@ -3968,148 +3639,136 @@ var BaseLLM = class {
     }
   }
   /**
-   * Execute external tools based on user request using agentic LLM tool calling
-   * The LLM can directly call tools and retry on errors
-   * @param userPrompt - The user's question/request
-   * @param availableTools - Array of available external tools
-   * @param apiKey - Optional API key for LLM
-   * @param logCollector - Optional log collector
-   * @returns Object containing tool execution results and summary
+   * Classify user question into category and detect external tools needed
+   * Determines if question is for data analysis, requires external tools, or needs text response
    */
-  async executeExternalTools(userPrompt, availableTools, apiKey, logCollector) {
-    const MAX_TOOL_ATTEMPTS = 3;
-    const toolResults = [];
+  async classifyQuestionCategory(userPrompt, apiKey, logCollector, conversationHistory, externalTools) {
     try {
-      logger.debug(`[${this.getProviderName()}] Starting agentic external tool execution`);
-      logger.debug(`[${this.getProviderName()}] Available tools: ${availableTools.map((t) => t.name).join(", ")}`);
-      const llmTools = availableTools.map((tool) => {
-        const properties = {};
-        const required = [];
-        Object.entries(tool.params || {}).forEach(([key, type]) => {
-          properties[key] = {
-            type: String(type).toLowerCase(),
-            description: `${key} parameter`
-          };
-          required.push(key);
-        });
-        return {
-          name: tool.id,
-          description: tool.description,
-          input_schema: {
-            type: "object",
-            properties,
-            required
-          }
-        };
+      const availableToolsDoc = externalTools && externalTools.length > 0 ? externalTools.map((tool) => {
+        const paramsStr = Object.entries(tool.params || {}).map(([key, type]) => `${key}: ${type}`).join(", ");
+        return `- **${tool.name}** (id: ${tool.id})
+  Description: ${tool.description}
+  Parameters: ${paramsStr}`;
+      }).join("\n\n") : "No external tools available";
+      const prompts = await promptLoader.loadPrompts("category-classification", {
+        USER_PROMPT: userPrompt,
+        CONVERSATION_HISTORY: conversationHistory || "No previous conversation",
+        AVAILABLE_TOOLS: availableToolsDoc
       });
-      const toolAttempts = /* @__PURE__ */ new Map();
-      const toolHandler = async (toolName, toolInput) => {
-        const tool = availableTools.find((t) => t.id === toolName);
-        if (!tool) {
-          const errorMsg = `Tool ${toolName} not found in available tools`;
-          logger.error(`[${this.getProviderName()}] ${errorMsg}`);
-          logCollector?.error(errorMsg);
-          throw new Error(errorMsg);
-        }
-        const attempts = (toolAttempts.get(toolName) || 0) + 1;
-        toolAttempts.set(toolName, attempts);
-        logger.info(`[${this.getProviderName()}] Executing tool: ${tool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})`);
-        logCollector?.info(`Executing ${tool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})...`);
-        if (attempts > MAX_TOOL_ATTEMPTS) {
-          const errorMsg = `Maximum attempts (${MAX_TOOL_ATTEMPTS}) reached for tool: ${tool.name}`;
-          logger.error(`[${this.getProviderName()}] ${errorMsg}`);
-          logCollector?.error(errorMsg);
-          toolResults.push({
-            toolName: tool.name,
-            toolId: tool.id,
-            result: null,
-            error: errorMsg
-          });
-          throw new Error(errorMsg);
-        }
-        try {
-          logger.debug(`[${this.getProviderName()}] Tool ${tool.name} parameters:`, toolInput);
-          const result2 = await tool.fn(toolInput);
-          logger.info(`[${this.getProviderName()}] Tool ${tool.name} executed successfully`);
-          logCollector?.info(`\u2713 ${tool.name} completed successfully`);
-          toolResults.push({
-            toolName: tool.name,
-            toolId: tool.id,
-            result: result2
-          });
-          return JSON.stringify(result2, null, 2);
-        } catch (error) {
-          const errorMsg = error instanceof Error ? error.message : String(error);
-          logger.error(`[${this.getProviderName()}] Tool ${tool.name} failed (attempt ${attempts}): ${errorMsg}`);
-          logCollector?.error(`\u2717 ${tool.name} failed: ${errorMsg}`);
-          if (attempts >= MAX_TOOL_ATTEMPTS) {
-            toolResults.push({
-              toolName: tool.name,
-              toolId: tool.id,
-              result: null,
-              error: errorMsg
-            });
-          }
-          throw new Error(`Tool execution failed: ${errorMsg}`);
+      const result = await LLM.stream(
+        {
+          sys: prompts.system,
+          user: prompts.user
+        },
+        {
+          model: this.model,
+          maxTokens: 1e3,
+          temperature: 0.2,
+          apiKey: this.getApiKey(apiKey)
+        },
+        true
+        // Parse as JSON
+      );
+      logCollector?.logExplanation(
+        "Question category classified",
+        result.reasoning || "No reasoning provided",
+        {
+          category: result.category,
+          externalTools: result.externalTools || [],
+          dataAnalysisType: result.dataAnalysisType,
+          confidence: result.confidence
         }
+      );
+      return {
+        category: result.category || "data_analysis",
+        externalTools: result.externalTools || [],
+        dataAnalysisType: result.dataAnalysisType,
+        reasoning: result.reasoning || "No reasoning provided",
+        confidence: result.confidence || 0
       };
-      const prompts = await promptLoader.loadPrompts("execute-tools", {
-        USER_PROMPT: userPrompt,
-        AVAILABLE_TOOLS: availableTools.map((tool, idx) => {
-          const paramsText = Object.entries(tool.params || {}).map(([key, type]) => `  - ${key}: ${type}`).join("\n");
-          return `${idx + 1}. ID: ${tool.id}
-   Name: ${tool.name}
-   Description: ${tool.description}
-   Parameters:
-${paramsText}`;
-        }).join("\n\n")
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      logger.error(`[${this.getProviderName()}] Error classifying question category: ${errorMsg}`);
+      logger.debug(`[${this.getProviderName()}] Category classification error details:`, error);
+      throw error;
+    }
+  }
+  /**
+   * 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
+   */
+  async adaptUIBlockParameters(currentUserPrompt, originalUserPrompt, matchedUIBlock, apiKey, logCollector) {
+    try {
+      if (!matchedUIBlock || !matchedUIBlock.generatedComponentMetadata) {
+        return {
+          success: false,
+          explanation: "No component found in matched UI block"
+        };
+      }
+      const component = matchedUIBlock.generatedComponentMetadata;
+      const schemaDoc = schema.generateSchemaDocumentation();
+      const prompts = await promptLoader.loadPrompts("adapt-ui-block-params", {
+        ORIGINAL_USER_PROMPT: originalUserPrompt,
+        CURRENT_USER_PROMPT: currentUserPrompt,
+        MATCHED_UI_BLOCK_COMPONENT: JSON.stringify(component, null, 2),
+        COMPONENT_PROPS: JSON.stringify(component.props, null, 2),
+        SCHEMA_DOC: schemaDoc || "No schema available"
       });
-      logger.debug(`[${this.getProviderName()}] Using agentic tool calling for external tools`);
-      logCollector?.info("Analyzing request and executing external tools...");
-      const result = await LLM.streamWithTools(
+      const result = await LLM.stream(
         {
           sys: prompts.system,
           user: prompts.user
         },
-        llmTools,
-        toolHandler,
         {
           model: this.model,
           maxTokens: 2e3,
           temperature: 0.2,
           apiKey: this.getApiKey(apiKey)
         },
-        MAX_TOOL_ATTEMPTS + 2
-        // max iterations: allows for retries + final response
+        true
+        // Parse as JSON
       );
-      logger.info(`[${this.getProviderName()}] External tool execution completed`);
-      const successfulTools = toolResults.filter((r) => !r.error);
-      const failedTools = toolResults.filter((r) => r.error);
-      let summary = "";
-      if (successfulTools.length > 0) {
-        summary += `Successfully executed ${successfulTools.length} tool(s): ${successfulTools.map((t) => t.toolName).join(", ")}.
-`;
-      }
-      if (failedTools.length > 0) {
-        summary += `Failed to execute ${failedTools.length} tool(s): ${failedTools.map((t) => t.toolName).join(", ")}.`;
+      if (!result.success) {
+        logger.info(
+          `[${this.getProviderName()}] Could not adapt UI block: ${result.reason}`
+        );
+        logCollector?.warn(
+          "Could not adapt matched UI block",
+          "explanation",
+          { reason: result.reason }
+        );
+        return {
+          success: false,
+          explanation: result.explanation || "Adaptation not possible"
+        };
       }
-      if (toolResults.length === 0) {
-        summary = "No external tools were needed for this request.";
+      if (result.adaptedComponent?.props?.query) {
+        result.adaptedComponent.props.query = ensureQueryLimit(
+          result.adaptedComponent.props.query,
+          this.defaultLimit
+        );
       }
-      logger.info(`[${this.getProviderName()}] Tool execution summary: ${summary}`);
+      logCollector?.logExplanation(
+        "UI block parameters adapted",
+        result.explanation || "Parameters adapted successfully",
+        {
+          parametersChanged: result.parametersChanged || [],
+          componentType: result.adaptedComponent?.type
+        }
+      );
       return {
-        toolResults,
-        summary,
-        hasResults: successfulTools.length > 0
+        success: true,
+        adaptedComponent: result.adaptedComponent,
+        parametersChanged: result.parametersChanged,
+        explanation: result.explanation || "Parameters adapted successfully"
       };
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error in external tool execution: ${errorMsg}`);
-      logCollector?.error(`Error executing external tools: ${errorMsg}`);
+      logger.error(`[${this.getProviderName()}] Error adapting UI block parameters: ${errorMsg}`);
+      logger.debug(`[${this.getProviderName()}] Adaptation error details:`, error);
       return {
-        toolResults,
-        summary: `Error executing external tools: ${errorMsg}`,
-        hasResults: false
+        success: false,
+        explanation: `Error adapting parameters: ${errorMsg}`
       };
     }
   }
@@ -4128,32 +3787,24 @@ ${paramsText}`;
     logger.debug(`[${this.getProviderName()}] Starting text response generation`);
     logger.debug(`[${this.getProviderName()}] User prompt: "${userPrompt.substring(0, 50)}..."`);
     try {
-      let externalToolContext = "No external tools were used for this request.";
+      let availableToolsDoc = "No external tools are available for this request.";
       if (externalTools && externalTools.length > 0) {
-        logger.info(`[${this.getProviderName()}] Executing external tools...`);
-        const toolExecution = await this.executeExternalTools(
-          userPrompt,
-          externalTools,
-          apiKey,
-          logCollector
-        );
-        if (toolExecution.hasResults) {
-          const toolResultsText = toolExecution.toolResults.map((tr) => {
-            if (tr.error) {
-              return `**${tr.toolName}** (Failed): ${tr.error}`;
+        logger.info(`[${this.getProviderName()}] External tools available: ${externalTools.map((t) => t.name).join(", ")}`);
+        availableToolsDoc = "\u26A0\uFE0F **EXECUTE THESE TOOLS IMMEDIATELY** \u26A0\uFE0F\n\nThe following external tools have been identified as necessary for this request. You MUST call them:\n\n" + externalTools.map((tool, idx) => {
+          const paramsText = Object.entries(tool.params || {}).map(([key, value]) => {
+            const valueType = typeof value;
+            if (valueType === "string" && ["string", "number", "integer", "boolean", "array", "object"].includes(String(value).toLowerCase())) {
+              return `- ${key}: ${value}`;
+            } else {
+              return `- ${key}: ${JSON.stringify(value)} (default value - use this)`;
             }
-            return `**${tr.toolName}** (Success):
-${JSON.stringify(tr.result, null, 2)}`;
-          }).join("\n\n");
-          externalToolContext = `## External Tool Results
-
-${toolExecution.summary}
-
-${toolResultsText}`;
-          logger.info(`[${this.getProviderName()}] External tools executed, results available`);
-        } else {
-          logger.info(`[${this.getProviderName()}] No external tools were needed`);
-        }
+          }).join("\n  ");
+          return `${idx + 1}. **${tool.name}** (ID: ${tool.id})
+  Description: ${tool.description}
+  **ACTION REQUIRED**: Call this tool with the parameters below
+  Parameters:
+  ${paramsText}`;
+        }).join("\n\n");
       }
       const schemaDoc = schema.generateSchemaDocumentation();
       const knowledgeBaseContext = await knowledge_base_default.getKnowledgeBase({
@@ -4162,13 +3813,12 @@ ${toolResultsText}`;
         topK: 1
       });
       logger.file("\n=============================\nknowledge base context:", knowledgeBaseContext);
-      logger.file("\n=============================\nexternal tool context:", externalToolContext);
       const prompts = await promptLoader.loadPrompts("text-response", {
         USER_PROMPT: userPrompt,
         CONVERSATION_HISTORY: conversationHistory || "No previous conversation",
         SCHEMA_DOC: schemaDoc,
         KNOWLEDGE_BASE_CONTEXT: knowledgeBaseContext || "No additional knowledge base context available.",
-        EXTERNAL_TOOL_CONTEXT: externalToolContext
+        AVAILABLE_EXTERNAL_TOOLS: availableToolsDoc
       });
       logger.file("\n=============================\nsystem prompt:", prompts.system);
       logger.file("\n=============================\nuser prompt:", prompts.user);
@@ -4190,11 +3840,88 @@ ${toolResultsText}`;
               description: "Brief explanation of what this query does and why it answers the user's question."
             }
           },
-          required: ["query"]
+          required: ["query"],
+          additionalProperties: false
         }
       }];
+      if (externalTools && externalTools.length > 0) {
+        externalTools.forEach((tool) => {
+          logger.info(`[${this.getProviderName()}] Processing external tool:`, JSON.stringify(tool, null, 2));
+          const properties = {};
+          const required = [];
+          Object.entries(tool.params || {}).forEach(([key, typeOrValue]) => {
+            let schemaType;
+            let hasDefaultValue = false;
+            let defaultValue;
+            const valueType = typeof typeOrValue;
+            if (valueType === "number") {
+              schemaType = Number.isInteger(typeOrValue) ? "integer" : "number";
+              hasDefaultValue = true;
+              defaultValue = typeOrValue;
+            } else if (valueType === "boolean") {
+              schemaType = "boolean";
+              hasDefaultValue = true;
+              defaultValue = typeOrValue;
+            } else if (Array.isArray(typeOrValue)) {
+              schemaType = "array";
+              hasDefaultValue = true;
+              defaultValue = typeOrValue;
+            } else if (valueType === "object" && typeOrValue !== null) {
+              schemaType = "object";
+              hasDefaultValue = true;
+              defaultValue = typeOrValue;
+            } else {
+              const typeStr = String(typeOrValue).toLowerCase().trim();
+              if (typeStr === "string" || typeStr === "str") {
+                schemaType = "string";
+              } else if (typeStr === "number" || typeStr === "num" || typeStr === "float" || typeStr === "double") {
+                schemaType = "number";
+              } else if (typeStr === "integer" || typeStr === "int") {
+                schemaType = "integer";
+              } else if (typeStr === "boolean" || typeStr === "bool") {
+                schemaType = "boolean";
+              } else if (typeStr === "array" || typeStr === "list") {
+                schemaType = "array";
+              } else if (typeStr === "object" || typeStr === "dict") {
+                schemaType = "object";
+              } else {
+                schemaType = "string";
+                hasDefaultValue = true;
+                defaultValue = typeOrValue;
+              }
+            }
+            const propertySchema = {
+              type: schemaType,
+              description: `${key} parameter for ${tool.name}`
+            };
+            if (hasDefaultValue) {
+              propertySchema.default = defaultValue;
+            } else {
+              required.push(key);
+            }
+            properties[key] = propertySchema;
+          });
+          const inputSchema = {
+            type: "object",
+            properties,
+            additionalProperties: false
+          };
+          if (required.length > 0) {
+            inputSchema.required = required;
+          }
+          tools.push({
+            name: tool.id,
+            description: tool.description,
+            input_schema: inputSchema
+          });
+        });
+        logger.info(`[${this.getProviderName()}] Added ${externalTools.length} external tools to tool calling capability`);
+        logger.info(`[${this.getProviderName()}] Complete tools array:`, JSON.stringify(tools, null, 2));
+      }
       const queryAttempts = /* @__PURE__ */ new Map();
       const MAX_QUERY_ATTEMPTS = 6;
+      const toolAttempts = /* @__PURE__ */ new Map();
+      const MAX_TOOL_ATTEMPTS = 3;
       let maxAttemptsReached = false;
       let fullStreamedText = "";
       const wrappedStreamCallback = streamCallback ? (chunk) => {
@@ -4336,8 +4063,75 @@ ${errorMsg}
             }
             throw new Error(`Query execution failed: ${errorMsg}`);
           }
+        } else {
+          const externalTool = externalTools?.find((t) => t.id === toolName);
+          if (externalTool) {
+            const attempts = (toolAttempts.get(toolName) || 0) + 1;
+            toolAttempts.set(toolName, attempts);
+            logger.info(`[${this.getProviderName()}] Executing external tool: ${externalTool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})`);
+            logCollector?.info(`Executing external tool: ${externalTool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})...`);
+            if (attempts > MAX_TOOL_ATTEMPTS) {
+              const errorMsg = `Maximum attempts (${MAX_TOOL_ATTEMPTS}) reached for tool: ${externalTool.name}`;
+              logger.error(`[${this.getProviderName()}] ${errorMsg}`);
+              logCollector?.error(errorMsg);
+              if (wrappedStreamCallback) {
+                wrappedStreamCallback(`
+
+\u274C ${errorMsg}
+
+Please try rephrasing your request or contact support.
+
+`);
+              }
+              throw new Error(errorMsg);
+            }
+            try {
+              if (wrappedStreamCallback) {
+                if (attempts === 1) {
+                  wrappedStreamCallback(`
+
+\u{1F517} **Executing ${externalTool.name}...**
+
+`);
+                } else {
+                  wrappedStreamCallback(`
+
+\u{1F504} **Retrying ${externalTool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})...**
+
+`);
+                }
+              }
+              const result2 = await externalTool.fn(toolInput);
+              logger.info(`[${this.getProviderName()}] External tool ${externalTool.name} executed successfully`);
+              logCollector?.info(`\u2713 ${externalTool.name} executed successfully`);
+              if (wrappedStreamCallback) {
+                wrappedStreamCallback(`\u2705 **${externalTool.name} completed successfully**
+
+`);
+              }
+              return JSON.stringify(result2, null, 2);
+            } catch (error) {
+              const errorMsg = error instanceof Error ? error.message : String(error);
+              logger.error(`[${this.getProviderName()}] External tool ${externalTool.name} failed (attempt ${attempts}/${MAX_TOOL_ATTEMPTS}): ${errorMsg}`);
+              logCollector?.error(`\u2717 ${externalTool.name} failed: ${errorMsg}`);
+              if (wrappedStreamCallback) {
+                wrappedStreamCallback(`\u274C **${externalTool.name} failed:**
+\`\`\`
+${errorMsg}
+\`\`\`
+
+`);
+                if (attempts < MAX_TOOL_ATTEMPTS) {
+                  wrappedStreamCallback(`\u{1F527} **Retrying with adjusted parameters...**
+
+`);
+                }
+              }
+              throw new Error(`Tool execution failed: ${errorMsg}`);
+            }
+          }
+          throw new Error(`Unknown tool: ${toolName}`);
         }
-        throw new Error(`Unknown tool: ${toolName}`);
       };
       const result = await LLM.streamWithTools(
         {
@@ -4354,8 +4148,8 @@ ${errorMsg}
           partial: wrappedStreamCallback
           // Pass the wrapped streaming callback to LLM
         },
-        10
-        // max iterations: allows for 6 retries + final response + buffer
+        20
+        // max iterations: allows for 6 query retries + 3 tool retries + final response + buffer
       );
       logger.info(`[${this.getProviderName()}] Text response stream completed`);
       const textResponse = fullStreamedText || result || "I apologize, but I was unable to generate a response.";
@@ -4410,24 +4204,22 @@ ${errorMsg}
       }
       let container_componet = null;
       if (matchedComponents.length > 0) {
+        logger.info(`[${this.getProviderName()}] Created MultiComponentContainer: "${layoutTitle}" with ${matchedComponents.length} components and ${actions.length} actions`);
+        logCollector?.info(`Created dashboard: "${layoutTitle}" with ${matchedComponents.length} components and ${actions.length} actions`);
         container_componet = {
-          id: `multi_container_${Date.now()}`,
+          id: `container_${Date.now()}`,
           name: "MultiComponentContainer",
           type: "Container",
           description: layoutDescription,
-          category: "dynamic",
-          keywords: ["dashboard", "layout", "container"],
           props: {
             config: {
-              components: matchedComponents,
               title: layoutTitle,
-              description: layoutDescription
+              description: layoutDescription,
+              components: matchedComponents
             },
             actions
           }
         };
-        logger.info(`[${this.getProviderName()}] Created MultiComponentContainer: "${layoutTitle}" with ${matchedComponents.length} components and ${actions.length} actions`);
-        logCollector?.info(`Created dashboard: "${layoutTitle}" with ${matchedComponents.length} components and ${actions.length} actions`);
       }
       return {
         success: true,
@@ -4458,201 +4250,134 @@ ${errorMsg}
     }
   }
   /**
-   * Generate component response for user question
-   * This provides conversational component suggestions based on user question
-   * Supports component generation and matching
+   * 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)
    */
-  async generateComponentResponse(userPrompt, components, apiKey, logCollector, conversationHistory) {
-    const errors = [];
+  async handleUserRequest(userPrompt, components, apiKey, logCollector, conversationHistory, responseMode = "text", streamCallback, collections, externalTools, userId) {
+    const startTime = Date.now();
+    logger.info(`[${this.getProviderName()}] handleUserRequest called with responseMode: ${responseMode}`);
+    logCollector?.info(`Starting request processing with mode: ${responseMode}`);
     try {
-      logger.info(`[${this.getProviderName()}] Using component response mode`);
-      const classifyMsg = "Classifying user question...";
-      logCollector?.info(classifyMsg);
-      const classification = await this.classifyUserQuestion(userPrompt, apiKey, logCollector, conversationHistory);
-      const classInfo = `Question type: ${classification.questionType}, Visualizations: ${classification.visualizations.join(", ") || "None"}, Multiple components: ${classification.needsMultipleComponents}`;
-      logCollector?.info(classInfo);
-      if (classification.questionType === "analytical") {
-        if (classification.visualizations.length > 1) {
-          const multiMsg = `Matching ${classification.visualizations.length} components for types: ${classification.visualizations.join(", ")}`;
-          logCollector?.info(multiMsg);
-          const componentPromises = classification.visualizations.map((vizType) => {
-            logCollector?.info(`Matching component for type: ${vizType}`);
-            return this.generateAnalyticalComponent(
-              userPrompt,
-              components,
-              vizType,
-              apiKey,
-              logCollector,
-              conversationHistory
-            ).then((result) => ({ vizType, result }));
-          });
-          const settledResults = await Promise.allSettled(componentPromises);
-          const matchedComponents = [];
-          for (const settledResult of settledResults) {
-            if (settledResult.status === "fulfilled") {
-              const { vizType, result } = settledResult.value;
-              if (result.component) {
-                matchedComponents.push(result.component);
-                logCollector?.info(`Matched: ${result.component.name}`);
-                logger.info("Component : ", result.component.name, " props: ", result.component.props);
-              } else {
-                logCollector?.warn(`Failed to match component for type: ${vizType}`);
-              }
-            } else {
-              logCollector?.warn(`Error matching component: ${settledResult.reason?.message || "Unknown error"}`);
-            }
-          }
-          logger.debug(`[${this.getProviderName()}] Matched ${matchedComponents.length} components for multi-component container`);
-          if (matchedComponents.length === 0) {
-            return {
-              success: true,
-              data: {
-                component: null,
-                reasoning: "Failed to match any components for the requested visualization types",
-                method: "classification-multi-failed",
-                questionType: classification.questionType,
-                needsMultipleComponents: true,
-                propsModified: false,
-                queryModified: false
-              },
-              errors: []
-            };
-          }
-          logCollector?.info("Generating container metadata...");
-          const containerMetadata = await this.generateContainerMetadata(
-            userPrompt,
-            classification.visualizations,
-            apiKey,
-            logCollector,
-            conversationHistory
-          );
-          const containerComponent = {
-            id: `multi_container_${Date.now()}`,
-            name: "MultiComponentContainer",
-            type: "Container",
-            description: containerMetadata.description,
-            category: "dynamic",
-            keywords: ["multi", "container", "dashboard"],
-            props: {
-              config: {
-                components: matchedComponents,
-                layout: "grid",
-                spacing: 24,
-                title: containerMetadata.title,
-                description: containerMetadata.description
-              }
-            }
-          };
-          logCollector?.info(`Created multi-component container with ${matchedComponents.length} components: "${containerMetadata.title}"`);
+      logger.info(`[${this.getProviderName()}] Step 1: Searching previous conversations...`);
+      logCollector?.info("Step 1: Searching for similar previous conversations...");
+      const conversationMatch = await conversation_search_default.searchConversations({
+        userPrompt,
+        collections,
+        userId,
+        similarityThreshold: 0.6
+        // 60% threshold
+      });
+      logger.info("conversationMatch:", conversationMatch);
+      if (conversationMatch) {
+        logger.info(
+          `[${this.getProviderName()}] \u2713 Found matching conversation with ${(conversationMatch.similarity * 100).toFixed(2)}% similarity`
+        );
+        logCollector?.info(
+          `\u2713 Found similar conversation (${(conversationMatch.similarity * 100).toFixed(2)}% match)`
+        );
+        if (conversationMatch.similarity >= 0.99) {
+          const elapsedTime2 = Date.now() - startTime;
+          logger.info(`[${this.getProviderName()}] \u2713 100% match - returning UI block directly without adaptation`);
+          logCollector?.info(`\u2713 Exact match (${(conversationMatch.similarity * 100).toFixed(2)}%) - returning cached result`);
+          logCollector?.info(`Total time taken: ${elapsedTime2}ms (${(elapsedTime2 / 1e3).toFixed(2)}s)`);
+          const component = conversationMatch.uiBlock?.generatedComponentMetadata || conversationMatch.uiBlock?.component;
           return {
             success: true,
             data: {
-              component: containerComponent,
-              reasoning: `Matched ${matchedComponents.length} components for visualization types: ${classification.visualizations.join(", ")}`,
-              method: "classification-multi-generated",
-              questionType: classification.questionType,
-              needsMultipleComponents: true,
-              propsModified: false,
-              queryModified: false
+              component,
+              reasoning: `Exact match from previous conversation (${(conversationMatch.similarity * 100).toFixed(2)}% similarity)`,
+              method: `${this.getProviderName()}-semantic-match-exact`,
+              semanticSimilarity: conversationMatch.similarity
             },
             errors: []
           };
-        } else if (classification.visualizations.length === 1) {
-          const vizType = classification.visualizations[0];
-          logCollector?.info(`Matching single component for type: ${vizType}`);
-          const result = await this.generateAnalyticalComponent(userPrompt, components, vizType, apiKey, logCollector, conversationHistory);
+        }
+        logCollector?.info(`Adapting parameters for similar question...`);
+        const originalPrompt = conversationMatch.metadata?.userPrompt || "Previous question";
+        const adaptResult = await this.adaptUIBlockParameters(
+          userPrompt,
+          originalPrompt,
+          conversationMatch.uiBlock,
+          apiKey,
+          logCollector
+        );
+        if (adaptResult.success && adaptResult.adaptedComponent) {
+          const elapsedTime2 = Date.now() - startTime;
+          logger.info(`[${this.getProviderName()}] \u2713 Successfully adapted UI block parameters`);
+          logger.info(`[${this.getProviderName()}] Total time taken: ${elapsedTime2}ms (${(elapsedTime2 / 1e3).toFixed(2)}s)`);
+          logCollector?.info(`\u2713 UI block adapted successfully`);
+          logCollector?.info(`Total time taken: ${elapsedTime2}ms (${(elapsedTime2 / 1e3).toFixed(2)}s)`);
           return {
             success: true,
             data: {
-              component: result.component,
-              reasoning: result.reasoning,
-              method: "classification-generated",
-              questionType: classification.questionType,
-              needsMultipleComponents: false,
-              propsModified: false,
-              queryModified: false
+              component: adaptResult.adaptedComponent,
+              reasoning: `Adapted from previous conversation: ${originalPrompt}`,
+              method: `${this.getProviderName()}-semantic-match`,
+              semanticSimilarity: conversationMatch.similarity,
+              parametersChanged: adaptResult.parametersChanged
             },
             errors: []
           };
         } else {
-          logCollector?.info("No specific visualization type - matching from all components");
-          const result = await this.generateAnalyticalComponent(userPrompt, components, void 0, apiKey, logCollector, conversationHistory);
-          return {
-            success: true,
-            data: {
-              component: result.component,
-              reasoning: result.reasoning,
-              method: "classification-generated-auto",
-              questionType: classification.questionType,
-              needsMultipleComponents: false,
-              propsModified: false,
-              queryModified: false
-            },
-            errors: []
-          };
+          logger.info(`[${this.getProviderName()}] Could not adapt matched conversation, continuing to category classification`);
+          logCollector?.warn(`Could not adapt matched conversation: ${adaptResult.explanation}`);
         }
-      } else if (classification.questionType === "data_modification" || classification.questionType === "general") {
-        const matchMsg = "Using component matching for data modification...";
-        logCollector?.info(matchMsg);
-        const matchResult = await this.matchComponent(userPrompt, components, apiKey, logCollector, conversationHistory);
-        return {
-          success: true,
-          data: {
-            component: matchResult.component,
-            reasoning: matchResult.reasoning,
-            method: "classification-matched",
-            questionType: classification.questionType,
-            needsMultipleComponents: false,
-            propsModified: matchResult.propsModified,
-            queryModified: matchResult.queryModified
-          },
-          errors: []
-        };
       } else {
-        logCollector?.info("General question - no component needed");
-        return {
-          success: true,
-          data: {
-            component: null,
-            reasoning: "General question - no component needed",
-            method: "classification-general",
-            questionType: classification.questionType,
-            needsMultipleComponents: false,
-            propsModified: false,
-            queryModified: false
-          },
-          errors: []
-        };
+        logger.info(`[${this.getProviderName()}] No matching previous conversations found, proceeding to category classification`);
+        logCollector?.info("No similar previous conversations found. Proceeding to category classification...");
+      }
+      logger.info(`[${this.getProviderName()}] Step 2: Classifying question category...`);
+      logCollector?.info("Step 2: Classifying question category...");
+      const categoryClassification = await this.classifyQuestionCategory(
+        userPrompt,
+        apiKey,
+        logCollector,
+        conversationHistory,
+        externalTools
+      );
+      logger.info(
+        `[${this.getProviderName()}] Question classified as: ${categoryClassification.category} (confidence: ${categoryClassification.confidence}%)`
+      );
+      logCollector?.info(
+        `Category: ${categoryClassification.category} | Confidence: ${categoryClassification.confidence}%`
+      );
+      let toolsToUse = [];
+      if (categoryClassification.externalTools && categoryClassification.externalTools.length > 0) {
+        logger.info(`[${this.getProviderName()}] Identified ${categoryClassification.externalTools.length} external tools needed`);
+        logCollector?.info(`Identified external tools: ${categoryClassification.externalTools.map((t) => t.name || t.type).join(", ")}`);
+        toolsToUse = categoryClassification.externalTools?.map((t) => ({
+          id: t.type,
+          name: t.name,
+          description: t.description,
+          params: t.parameters || {},
+          fn: (() => {
+            const realTool = externalTools?.find((tool) => tool.id === t.type);
+            if (realTool) {
+              logger.info(`[${this.getProviderName()}] Using real tool implementation for ${t.type}`);
+              return realTool.fn;
+            } else {
+              logger.warn(`[${this.getProviderName()}] Tool ${t.type} not found in registered tools`);
+              return async () => ({ success: false, message: `Tool ${t.name || t.type} not registered` });
+            }
+          })()
+        })) || [];
+      }
+      if (categoryClassification.category === "data_analysis") {
+        logger.info(`[${this.getProviderName()}] Routing to data analysis (SELECT operations)`);
+        logCollector?.info("Routing to data analysis...");
+      } else if (categoryClassification.category === "data_modification") {
+        logger.info(`[${this.getProviderName()}] Routing to data modification (INSERT/UPDATE/DELETE operations)`);
+        logCollector?.info("Routing to data modification...");
       }
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      logger.error(`[${this.getProviderName()}] Error generating component response: ${errorMsg}`);
-      logger.debug(`[${this.getProviderName()}] Component response generation error details:`, error);
-      logCollector?.error(`Error generating component response: ${errorMsg}`);
-      errors.push(errorMsg);
-      return {
-        success: false,
-        errors,
-        data: void 0
-      };
-    }
-  }
-  /**
-   * Main orchestration function that classifies question and routes to appropriate handler
-   * This is the NEW recommended entry point for handling user requests
-   * Supports both component generation and text response modes
-   *
-   * @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)
-   */
-  async handleUserRequest(userPrompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) {
-    const startTime = Date.now();
-    logger.info(`[${this.getProviderName()}] handleUserRequest called with responseMode: ${responseMode}`);
-    if (responseMode === "text") {
-      logger.info(`[${this.getProviderName()}] Using text response mode`);
-      logCollector?.info("Generating text response...");
       const textResponse = await this.generateTextResponse(
         userPrompt,
         apiKey,
@@ -4661,40 +4386,29 @@ ${errorMsg}
         streamCallback,
         collections,
         components,
-        externalTools
+        toolsToUse
       );
-      if (!textResponse.success) {
-        const elapsedTime3 = Date.now() - startTime;
-        logger.error(`[${this.getProviderName()}] Text response generation failed`);
-        logger.info(`[${this.getProviderName()}] Total time taken: ${elapsedTime3}ms (${(elapsedTime3 / 1e3).toFixed(2)}s)`);
-        logCollector?.info(`Total time taken: ${elapsedTime3}ms (${(elapsedTime3 / 1e3).toFixed(2)}s)`);
-        return textResponse;
-      }
-      const elapsedTime2 = Date.now() - startTime;
-      logger.info(`[${this.getProviderName()}] Text response generated successfully`);
-      logger.info(`[${this.getProviderName()}] Total time taken: ${elapsedTime2}ms (${(elapsedTime2 / 1e3).toFixed(2)}s)`);
-      logCollector?.info(`Total time taken: ${elapsedTime2}ms (${(elapsedTime2 / 1e3).toFixed(2)}s)`);
+      const elapsedTime = Date.now() - startTime;
+      logger.info(`[${this.getProviderName()}] Total time taken: ${elapsedTime}ms (${(elapsedTime / 1e3).toFixed(2)}s)`);
+      logCollector?.info(`Total time taken: ${elapsedTime}ms (${(elapsedTime / 1e3).toFixed(2)}s)`);
       return textResponse;
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      logger.error(`[${this.getProviderName()}] Error in handleUserRequest: ${errorMsg}`);
+      logger.debug(`[${this.getProviderName()}] Error details:`, error);
+      logCollector?.error(`Error processing request: ${errorMsg}`);
+      const elapsedTime = Date.now() - startTime;
+      logger.info(`[${this.getProviderName()}] Total time taken: ${elapsedTime}ms (${(elapsedTime / 1e3).toFixed(2)}s)`);
+      logCollector?.info(`Total time taken: ${elapsedTime}ms (${(elapsedTime / 1e3).toFixed(2)}s)`);
+      return {
+        success: false,
+        errors: [errorMsg],
+        data: {
+          text: "I apologize, but I encountered an error processing your request. Please try again.",
+          method: `${this.getProviderName()}-orchestration-error`
+        }
+      };
     }
-    const componentResponse = await this.generateComponentResponse(
-      userPrompt,
-      components,
-      apiKey,
-      logCollector,
-      conversationHistory
-    );
-    if (!componentResponse.success) {
-      const elapsedTime2 = Date.now() - startTime;
-      logger.error(`[${this.getProviderName()}] Component response generation failed`);
-      logger.info(`[${this.getProviderName()}] Total time taken: ${elapsedTime2}ms (${(elapsedTime2 / 1e3).toFixed(2)}s)`);
-      logCollector?.info(`Total time taken: ${elapsedTime2}ms (${(elapsedTime2 / 1e3).toFixed(2)}s)`);
-      return componentResponse;
-    }
-    const elapsedTime = Date.now() - startTime;
-    logger.info(`[${this.getProviderName()}] Component response generated successfully`);
-    logger.info(`[${this.getProviderName()}] Total time taken: ${elapsedTime}ms (${(elapsedTime / 1e3).toFixed(2)}s)`);
-    logCollector?.info(`Total time taken: ${elapsedTime}ms (${(elapsedTime / 1e3).toFixed(2)}s)`);
-    return componentResponse;
   }
   /**
    * Generate next questions that the user might ask based on the original prompt and generated component
@@ -4807,7 +4521,7 @@ function getLLMProviders() {
     return DEFAULT_PROVIDERS;
   }
 }
-var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
+var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools, userId) => {
   logger.debug("[useAnthropicMethod] Initializing Anthropic Claude matching method");
   logger.debug(`[useAnthropicMethod] Response mode: ${responseMode}`);
   const msg = `Using Anthropic Claude ${responseMode === "text" ? "text response" : "matching"} method...`;
@@ -4819,11 +4533,11 @@ var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conver
     return { success: false, errors: [emptyMsg] };
   }
   logger.debug(`[useAnthropicMethod] Processing with ${components.length} components`);
-  const matchResult = await anthropicLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
+  const matchResult = await anthropicLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools, userId);
   logger.info(`[useAnthropicMethod] Successfully generated ${responseMode} using Anthropic`);
   return matchResult;
 };
-var useGroqMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
+var useGroqMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools, userId) => {
   logger.debug("[useGroqMethod] Initializing Groq LLM matching method");
   logger.debug(`[useGroqMethod] Response mode: ${responseMode}`);
   const msg = `Using Groq LLM ${responseMode === "text" ? "text response" : "matching"} method...`;
@@ -4836,14 +4550,14 @@ var useGroqMethod = async (prompt, components, apiKey, logCollector, conversatio
     return { success: false, errors: [emptyMsg] };
   }
   logger.debug(`[useGroqMethod] Processing with ${components.length} components`);
-  const matchResult = await groqLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
+  const matchResult = await groqLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools, userId);
   logger.info(`[useGroqMethod] Successfully generated ${responseMode} using Groq`);
   return matchResult;
 };
 var getUserResponseFromCache = async (prompt) => {
   return false;
 };
-var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey, llmProviders, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
+var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey, llmProviders, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools, userId) => {
   logger.debug(`[get_user_response] Starting user response generation for prompt: "${prompt.substring(0, 50)}..."`);
   logger.debug(`[get_user_response] Response mode: ${responseMode}`);
   logger.debug("[get_user_response] Checking cache for existing response");
@@ -4876,9 +4590,9 @@ var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey,
     logCollector?.info(attemptMsg);
     let result;
     if (provider === "anthropic") {
-      result = await useAnthropicMethod(prompt, components, anthropicApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
+      result = await useAnthropicMethod(prompt, components, anthropicApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools, userId);
     } else if (provider === "groq") {
-      result = await useGroqMethod(prompt, components, groqApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
+      result = await useGroqMethod(prompt, components, groqApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools, userId);
     } else {
       logger.warn(`[get_user_response] Unknown provider: ${provider} - skipping`);
       errors.push(`Unknown provider: ${provider}`);
@@ -5095,6 +4809,111 @@ var UILogCollector = class {
   }
 };
 
+// src/utils/conversation-saver.ts
+async function saveConversation(params) {
+  const { userId, userPrompt, uiblock, uiBlockId, threadId, collections } = params;
+  if (!userId) {
+    logger.warn("[CONVERSATION_SAVER] Skipping save: userId not provided");
+    return {
+      success: false,
+      error: "userId is required"
+    };
+  }
+  if (!userPrompt) {
+    logger.warn("[CONVERSATION_SAVER] Skipping save: userPrompt not provided");
+    return {
+      success: false,
+      error: "userPrompt is required"
+    };
+  }
+  if (!uiblock) {
+    logger.warn("[CONVERSATION_SAVER] Skipping save: uiblock not provided");
+    return {
+      success: false,
+      error: "uiblock is required"
+    };
+  }
+  if (!threadId) {
+    logger.warn("[CONVERSATION_SAVER] Skipping save: threadId not provided");
+    return {
+      success: false,
+      error: "threadId is required"
+    };
+  }
+  if (!uiBlockId) {
+    logger.warn("[CONVERSATION_SAVER] Skipping save: uiBlockId not provided");
+    return {
+      success: false,
+      error: "uiBlockId is required"
+    };
+  }
+  if (!collections?.["user-conversations"]?.["create"]) {
+    logger.debug('[CONVERSATION_SAVER] Collection "user-conversations.create" not available, skipping save');
+    return {
+      success: false,
+      error: "user-conversations.create collection not available"
+    };
+  }
+  try {
+    logger.info(`[CONVERSATION_SAVER] Saving conversation for userId: ${userId}, uiBlockId: ${uiBlockId}, threadId: ${threadId}`);
+    const userIdNumber = Number(userId);
+    if (isNaN(userIdNumber)) {
+      logger.warn(`[CONVERSATION_SAVER] Invalid userId: ${userId} (not a valid number)`);
+      return {
+        success: false,
+        error: `Invalid userId: ${userId} (not a valid number)`
+      };
+    }
+    const saveResult = await collections["user-conversations"]["create"]({
+      userId: userIdNumber,
+      userPrompt,
+      uiblock,
+      threadId
+    });
+    if (!saveResult?.success) {
+      logger.warn(`[CONVERSATION_SAVER] Failed to save conversation to PostgreSQL: ${saveResult?.message || "Unknown error"}`);
+      return {
+        success: false,
+        error: saveResult?.message || "Unknown error from backend"
+      };
+    }
+    logger.info(`[CONVERSATION_SAVER] Successfully saved conversation to PostgreSQL, id: ${saveResult.data?.id}`);
+    if (collections?.["conversation-history"]?.["embed"]) {
+      try {
+        logger.info("[CONVERSATION_SAVER] Creating embedding for semantic search...");
+        const embedResult = await collections["conversation-history"]["embed"]({
+          uiBlockId,
+          userPrompt,
+          uiBlock: uiblock,
+          userId: userIdNumber
+        });
+        if (embedResult?.success) {
+          logger.info("[CONVERSATION_SAVER] Successfully created embedding");
+        } else {
+          logger.warn("[CONVERSATION_SAVER] Failed to create embedding:", embedResult?.error || "Unknown error");
+        }
+      } catch (embedError) {
+        const embedErrorMsg = embedError instanceof Error ? embedError.message : String(embedError);
+        logger.warn("[CONVERSATION_SAVER] Error creating embedding:", embedErrorMsg);
+      }
+    } else {
+      logger.debug("[CONVERSATION_SAVER] Embedding collection not available, skipping ChromaDB storage");
+    }
+    return {
+      success: true,
+      conversationId: saveResult.data?.id,
+      message: "Conversation saved successfully"
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error("[CONVERSATION_SAVER] Error saving conversation:", errorMessage);
+    return {
+      success: false,
+      error: errorMessage
+    };
+  }
+}
+
 // src/config/context.ts
 var CONTEXT_CONFIG = {
   /**
@@ -5106,7 +4925,7 @@ var CONTEXT_CONFIG = {
 };
 
 // src/handlers/user-prompt-request.ts
-var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools) => {
+var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools, userId) => {
   const errors = [];
   logger.debug("[USER_PROMPT_REQ] Parsing incoming message data");
   const parseResult = UserPromptRequestMessageSchema.safeParse(data);
@@ -5187,7 +5006,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     responseMode,
     streamCallback,
     collections,
-    externalTools
+    externalTools,
+    userId
   );
   logCollector.info("User prompt request completed");
   const uiBlockId = existingUiBlockId;
@@ -5238,6 +5058,34 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
   }
   thread.addUIBlock(uiBlock);
   logger.info(`Created UIBlock: ${uiBlockId} in Thread: ${threadId}`);
+  if (userId) {
+    const responseMethod = userResponse.data?.method || "";
+    const semanticSimilarity = userResponse.data?.semanticSimilarity || 0;
+    const isExactMatch = responseMethod.includes("semantic-match") && semanticSimilarity >= 0.99;
+    if (isExactMatch) {
+      logger.info(
+        `Skipping conversation save - response from exact semantic match (${(semanticSimilarity * 100).toFixed(2)}% similarity)`
+      );
+      logCollector.info(
+        `Using exact cached result (${(semanticSimilarity * 100).toFixed(2)}% match) - not saving duplicate conversation`
+      );
+    } else {
+      const uiBlockData = uiBlock.toJSON();
+      const saveResult = await saveConversation({
+        userId,
+        userPrompt: prompt,
+        uiblock: uiBlockData,
+        uiBlockId,
+        threadId,
+        collections
+      });
+      if (saveResult.success) {
+        logger.info(`Conversation saved with ID: ${saveResult.conversationId}`);
+      } else {
+        logger.warn(`Failed to save conversation: ${saveResult.error}`);
+      }
+    }
+  }
   return {
     success: userResponse.success,
     data: userResponse.data,
@@ -5248,8 +5096,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     wsId
   };
 };
-async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools) {
-  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools);
+async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools, userId) {
+  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools, userId);
   sendDataResponse4(
     response.id || data.id,
     {
@@ -7479,7 +7327,7 @@ var SuperatomSDK = class {
           });
           break;
         case "USER_PROMPT_REQ":
-          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.llmProviders, this.collections, this.tools).catch((error) => {
+          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.llmProviders, this.collections, this.tools, this.userId).catch((error) => {
             logger.error("Failed to handle user prompt request:", error);
           });
           break;