@retrivora-ai/rag-engine 1.5.4 → 1.5.5

package/dist/{chunk-BLLMNP77.mjs → chunk-Q4MDH6C4.mjs}

@@ -2259,23 +2259,68 @@ var Pipeline = class {
   async initialize() {
     var _a, _b;
     if (this.initialised) return;
-    const CHART_MARKER = "<!-- UI_PROTOCOL_V3 -->";
+    const CHART_MARKER = "<!-- UI_PROTOCOL_V5 -->";
     const chartInstruction = `
 
 ${CHART_MARKER}
-### UNIVERSAL UI PROTOCOL:
-You have a specialized UI system. For any structured data (charts, product lists, or tables), you MUST use a single \`\`\`ui\`\`\` block.
-1. DECIDE the best "view" for the user's query:
-   - "chart": For statistics, distributions, or comparisons. (Requires "chartType": "pie" | "bar" | "line")
-   - "carousel": For browsing specific product items.
-   - "table": For detailed raw data comparisons.
-2. OUTPUT a \`\`\`ui\`\`\` block with this schema:
+### UNIVERSAL UI PROTOCOL
+When the user asks for a visual representation, comparison, distribution, breakdown, table, list, catalog, products, carousel, stock view, or category summary, you MUST include exactly one \`\`\`ui\`\`\` block.
+
+1. VIEW SELECTION
+   - Use "chart" for distributions, percentages, counts, comparisons, trends, or "show me in a chart".
+   - Use "carousel" for browseable product recommendations or when the user asks to see products/items/cards.
+   - Use "table" for tabular/raw detail, explicit table/list requests, or when there are many attributes to compare.
+
+2. REQUIRED JSON SHAPE
    {
      "view": "chart" | "carousel" | "table",
-     "chartType": "pie" | "bar" | "line" (only for view: "chart"),
-     "data": [ ... objects ... ]
+     "title": "Short heading",
+     "description": "One sentence describing the view",
+     "chartType": "pie" | "bar" | "line",
+     "xAxisKey": "label",
+     "dataKeys": ["value"],
+     "columns": ["name", "category", "price", "stockStatus"],
+     "insights": ["Short takeaway 1", "Short takeaway 2"],
+     "data": []
    }
-3. RULES: Valid JSON only. Data must be FLAT. Never draw charts/tables with text. Choose ONLY the most useful view.`;
+
+3. DATA RULES
+   - Build the UI payload from retrieved context only. Do not invent products, categories, or stock values.
+   - Aggregate raw product rows when the user asks for a chart.
+   - For charts, every row in "data" must be flat JSON with primitive values only.
+   - Prefer { "label": "...", "value": number } for pie charts.
+   - If stock information exists, preserve it in each row with fields like "inStock", "inStockCount", "outOfStockCount", or "stockStatus".
+   - If the user asks to highlight what is in stock, include those stock-related fields in the chart data and mention the pattern in "insights".
+   - For carousel rows, include product-friendly fields such as id, name, brand, price, image, link, category, stockStatus.
+   - For tables, keep "data" row-oriented and include "columns" when possible.
+
+4. FORMAT RULES
+   - Never use ASCII art, markdown tables as the primary answer, or text-only fake charts when a UI block is requested.
+   - Put any short natural-language explanation before or after the \`\`\`ui\`\`\` block, but keep it concise.
+   - Return valid JSON inside the \`\`\`ui\`\`\` block.
+
+5. EXAMPLE
+User: "provide me the distribution of products across categories and highlight which ones are in stock in a pie chart"
+Assistant:
+\`\`\`ui
+{
+  "view": "chart",
+  "title": "Product Distribution Across Categories",
+  "description": "Pie chart showing product count by category with stock signals preserved per slice.",
+  "chartType": "pie",
+  "xAxisKey": "label",
+  "dataKeys": ["value"],
+  "insights": [
+    "Beauty has the highest product count.",
+    "Electronics has the largest number of in-stock products."
+  ],
+  "data": [
+    { "label": "Beauty", "value": 12, "inStockCount": 9, "outOfStockCount": 3 },
+    { "label": "Electronics", "value": 8, "inStockCount": 7, "outOfStockCount": 1 },
+    { "label": "Home", "value": 5, "inStockCount": 2, "outOfStockCount": 3 }
+  ]
+}
+\`\`\``;
     if (!((_a = this.config.llm.systemPrompt) == null ? void 0 : _a.includes(CHART_MARKER))) {
       this.config.llm.systemPrompt = (this.config.llm.systemPrompt || "") + chartInstruction;
     }

package/dist/handlers/index.js

@@ -3822,23 +3822,68 @@ var Pipeline = class {
   async initialize() {
     var _a, _b;
     if (this.initialised) return;
-    const CHART_MARKER = "<!-- UI_PROTOCOL_V3 -->";
+    const CHART_MARKER = "<!-- UI_PROTOCOL_V5 -->";
     const chartInstruction = `
 
 ${CHART_MARKER}
-### UNIVERSAL UI PROTOCOL:
-You have a specialized UI system. For any structured data (charts, product lists, or tables), you MUST use a single \`\`\`ui\`\`\` block.
-1. DECIDE the best "view" for the user's query:
-   - "chart": For statistics, distributions, or comparisons. (Requires "chartType": "pie" | "bar" | "line")
-   - "carousel": For browsing specific product items.
-   - "table": For detailed raw data comparisons.
-2. OUTPUT a \`\`\`ui\`\`\` block with this schema:
+### UNIVERSAL UI PROTOCOL
+When the user asks for a visual representation, comparison, distribution, breakdown, table, list, catalog, products, carousel, stock view, or category summary, you MUST include exactly one \`\`\`ui\`\`\` block.
+
+1. VIEW SELECTION
+   - Use "chart" for distributions, percentages, counts, comparisons, trends, or "show me in a chart".
+   - Use "carousel" for browseable product recommendations or when the user asks to see products/items/cards.
+   - Use "table" for tabular/raw detail, explicit table/list requests, or when there are many attributes to compare.
+
+2. REQUIRED JSON SHAPE
    {
      "view": "chart" | "carousel" | "table",
-     "chartType": "pie" | "bar" | "line" (only for view: "chart"),
-     "data": [ ... objects ... ]
+     "title": "Short heading",
+     "description": "One sentence describing the view",
+     "chartType": "pie" | "bar" | "line",
+     "xAxisKey": "label",
+     "dataKeys": ["value"],
+     "columns": ["name", "category", "price", "stockStatus"],
+     "insights": ["Short takeaway 1", "Short takeaway 2"],
+     "data": []
    }
-3. RULES: Valid JSON only. Data must be FLAT. Never draw charts/tables with text. Choose ONLY the most useful view.`;
+
+3. DATA RULES
+   - Build the UI payload from retrieved context only. Do not invent products, categories, or stock values.
+   - Aggregate raw product rows when the user asks for a chart.
+   - For charts, every row in "data" must be flat JSON with primitive values only.
+   - Prefer { "label": "...", "value": number } for pie charts.
+   - If stock information exists, preserve it in each row with fields like "inStock", "inStockCount", "outOfStockCount", or "stockStatus".
+   - If the user asks to highlight what is in stock, include those stock-related fields in the chart data and mention the pattern in "insights".
+   - For carousel rows, include product-friendly fields such as id, name, brand, price, image, link, category, stockStatus.
+   - For tables, keep "data" row-oriented and include "columns" when possible.
+
+4. FORMAT RULES
+   - Never use ASCII art, markdown tables as the primary answer, or text-only fake charts when a UI block is requested.
+   - Put any short natural-language explanation before or after the \`\`\`ui\`\`\` block, but keep it concise.
+   - Return valid JSON inside the \`\`\`ui\`\`\` block.
+
+5. EXAMPLE
+User: "provide me the distribution of products across categories and highlight which ones are in stock in a pie chart"
+Assistant:
+\`\`\`ui
+{
+  "view": "chart",
+  "title": "Product Distribution Across Categories",
+  "description": "Pie chart showing product count by category with stock signals preserved per slice.",
+  "chartType": "pie",
+  "xAxisKey": "label",
+  "dataKeys": ["value"],
+  "insights": [
+    "Beauty has the highest product count.",
+    "Electronics has the largest number of in-stock products."
+  ],
+  "data": [
+    { "label": "Beauty", "value": 12, "inStockCount": 9, "outOfStockCount": 3 },
+    { "label": "Electronics", "value": 8, "inStockCount": 7, "outOfStockCount": 1 },
+    { "label": "Home", "value": 5, "inStockCount": 2, "outOfStockCount": 3 }
+  ]
+}
+\`\`\``;
     if (!((_a = this.config.llm.systemPrompt) == null ? void 0 : _a.includes(CHART_MARKER))) {
       this.config.llm.systemPrompt = (this.config.llm.systemPrompt || "") + chartInstruction;
     }

package/dist/handlers/index.mjs

@@ -9,7 +9,7 @@ import {
   sseFrame,
   sseMetaFrame,
   sseTextFrame
-} from "../chunk-BLLMNP77.mjs";
+} from "../chunk-Q4MDH6C4.mjs";
 import "../chunk-YLTMFW4M.mjs";
 import "../chunk-X4TOT24V.mjs";
 export {

package/dist/index.js

@@ -270,8 +270,58 @@ function DynamicChart({ config, primaryColor = "#6366f1", accentColor = "#8b5cf6
   }).slice(0, 5);
   const finalXKey = String(resolvedXKey);
   const finalDataKeys = resolvedDataKeys.map(String).filter((k) => k !== "undefined");
+  const pieDataKey = finalDataKeys[0] || "value";
+  const stockAwareColor = (entry, index) => {
+    var _a, _b, _c;
+    const stockStatus = String(
+      (_c = (_b = (_a = entry.stockStatus) != null ? _a : entry.status) != null ? _b : entry.availability) != null ? _c : ""
+    ).toLowerCase();
+    const inStockCount = typeof entry.inStockCount === "number" ? entry.inStockCount : void 0;
+    const outOfStockCount = typeof entry.outOfStockCount === "number" ? entry.outOfStockCount : void 0;
+    const inStockFlag = entry.inStock;
+    if (stockStatus.includes("in stock")) return "#10b981";
+    if (stockStatus.includes("out of stock")) return "#f97316";
+    if (typeof inStockFlag === "string" && inStockFlag.toLowerCase() === "true") return "#10b981";
+    if (inStockFlag === 1) return "#10b981";
+    if (inStockFlag === 0) return "#f97316";
+    if (typeof inStockCount === "number" || typeof outOfStockCount === "number") {
+      const inCount = inStockCount != null ? inStockCount : 0;
+      const outCount = outOfStockCount != null ? outOfStockCount : 0;
+      if (inCount > outCount) return "#10b981";
+      if (outCount > inCount) return "#f97316";
+    }
+    return colors[index % colors.length];
+  };
+  const tooltipLabelMap = {
+    value: "Value",
+    count: "Count",
+    inStock: "In stock",
+    inStockCount: "In stock",
+    outOfStockCount: "Out of stock",
+    stockStatus: "Stock status",
+    category: "Category",
+    label: "Label",
+    name: "Name"
+  };
+  const renderTooltip = (row, label) => {
+    var _a, _b;
+    if (!row) return null;
+    return /* @__PURE__ */ import_react4.default.createElement("div", { className: "rounded-xl border border-slate-200 bg-white px-3 py-2 text-xs shadow-xl dark:border-white/10 dark:bg-slate-950" }, /* @__PURE__ */ import_react4.default.createElement("p", { className: "mb-2 font-semibold text-slate-800 dark:text-white/90" }, String((_b = (_a = row[finalXKey]) != null ? _a : label) != null ? _b : "Details")), Object.entries(row).map(([key, value]) => {
+      var _a2;
+      if (value === null || value === void 0 || key === finalXKey) return null;
+      if (typeof value === "object") return null;
+      return /* @__PURE__ */ import_react4.default.createElement("div", { key, className: "flex items-center justify-between gap-3 text-slate-600 dark:text-white/70" }, /* @__PURE__ */ import_react4.default.createElement("span", null, (_a2 = tooltipLabelMap[key]) != null ? _a2 : key), /* @__PURE__ */ import_react4.default.createElement("span", { className: "font-medium text-slate-900 dark:text-white/90" }, String(value)));
+    }));
+  };
+  const getTooltipRow = (payload) => {
+    if (!Array.isArray(payload) || payload.length === 0) return null;
+    const first = payload[0];
+    if (!first || typeof first !== "object" || !("payload" in first)) return null;
+    const row = first.payload;
+    if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+    return row;
+  };
   if (type === "pie") {
-    const pieDataKey = finalDataKeys[0] || "value";
     return /* @__PURE__ */ import_react4.default.createElement("div", { className: "w-full h-72 min-h-[280px] mt-4 mb-2 select-none overflow-hidden" }, /* @__PURE__ */ import_react4.default.createElement(import_recharts.ResponsiveContainer, { width: "99%", height: "100%" }, /* @__PURE__ */ import_react4.default.createElement(import_recharts.PieChart, null, /* @__PURE__ */ import_react4.default.createElement(
       import_recharts.Pie,
       {
@@ -283,21 +333,10 @@ function DynamicChart({ config, primaryColor = "#6366f1", accentColor = "#8b5cf6
         outerRadius: 80,
         label: ({ name, percent }) => `${name} ${((percent != null ? percent : 0) * 100).toFixed(0)}%`
       },
-      data.map((entry, index) => /* @__PURE__ */ import_react4.default.createElement(import_recharts.Cell, { key: `cell-${index}`, fill: colors[index % colors.length] }))
-    ), /* @__PURE__ */ import_react4.default.createElement(
-      import_recharts.Tooltip,
-      {
-        contentStyle: { borderRadius: "8px", border: "none", boxShadow: "0 4px 6px -1px rgb(0 0 0 / 0.1)" }
-      }
-    ), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Legend, null))));
+      sanitizedData.map((entry, index) => /* @__PURE__ */ import_react4.default.createElement(import_recharts.Cell, { key: `cell-${index}`, fill: stockAwareColor(entry, index) }))
+    ), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Tooltip, { content: (props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === "string" ? props.label : void 0) }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Legend, null))));
   }
-  return /* @__PURE__ */ import_react4.default.createElement("div", { className: "w-full h-72 min-h-[280px] mt-4 mb-2 select-none overflow-hidden" }, /* @__PURE__ */ import_react4.default.createElement(import_recharts.ResponsiveContainer, { width: "99%", height: "100%" }, type === "bar" ? /* @__PURE__ */ import_react4.default.createElement(import_recharts.BarChart, { data: sanitizedData, margin: { top: 10, right: 10, left: -20, bottom: 0 } }, /* @__PURE__ */ import_react4.default.createElement(import_recharts.CartesianGrid, { strokeDasharray: "3 3", vertical: false, stroke: "#e2e8f0" }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.XAxis, { dataKey: finalXKey, tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: { stroke: "#cbd5e1" } }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.YAxis, { tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: false }), /* @__PURE__ */ import_react4.default.createElement(
-    import_recharts.Tooltip,
-    {
-      contentStyle: { borderRadius: "8px", border: "none", boxShadow: "0 4px 6px -1px rgb(0 0 0 / 0.1)" },
-      cursor: { fill: "#f1f5f9" }
-    }
-  ), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Legend, { wrapperStyle: { fontSize: 12 } }), finalDataKeys.map((key, index) => /* @__PURE__ */ import_react4.default.createElement(
+  return /* @__PURE__ */ import_react4.default.createElement("div", { className: "w-full h-72 min-h-[280px] mt-4 mb-2 select-none overflow-hidden" }, /* @__PURE__ */ import_react4.default.createElement(import_recharts.ResponsiveContainer, { width: "99%", height: "100%" }, type === "bar" ? /* @__PURE__ */ import_react4.default.createElement(import_recharts.BarChart, { data: sanitizedData, margin: { top: 10, right: 10, left: -20, bottom: 0 } }, /* @__PURE__ */ import_react4.default.createElement(import_recharts.CartesianGrid, { strokeDasharray: "3 3", vertical: false, stroke: "#e2e8f0" }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.XAxis, { dataKey: finalXKey, tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: { stroke: "#cbd5e1" } }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.YAxis, { tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: false }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Tooltip, { content: (props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === "string" ? props.label : void 0), cursor: { fill: "#f1f5f9" } }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Legend, { wrapperStyle: { fontSize: 12 } }), finalDataKeys.map((key, index) => /* @__PURE__ */ import_react4.default.createElement(
     import_recharts.Bar,
     {
       key,
@@ -306,12 +345,7 @@ function DynamicChart({ config, primaryColor = "#6366f1", accentColor = "#8b5cf6
       radius: [4, 4, 0, 0],
       barSize: Math.max(20, 60 / data.length)
     }
-  ))) : /* @__PURE__ */ import_react4.default.createElement(import_recharts.LineChart, { data: sanitizedData, margin: { top: 10, right: 10, left: -20, bottom: 0 } }, /* @__PURE__ */ import_react4.default.createElement(import_recharts.CartesianGrid, { strokeDasharray: "3 3", vertical: false, stroke: "#e2e8f0" }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.XAxis, { dataKey: finalXKey, tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: { stroke: "#cbd5e1" } }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.YAxis, { tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: false }), /* @__PURE__ */ import_react4.default.createElement(
-    import_recharts.Tooltip,
-    {
-      contentStyle: { borderRadius: "8px", border: "none", boxShadow: "0 4px 6px -1px rgb(0 0 0 / 0.1)" }
-    }
-  ), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Legend, { wrapperStyle: { fontSize: 12 } }), finalDataKeys.map((key, index) => /* @__PURE__ */ import_react4.default.createElement(
+  ))) : /* @__PURE__ */ import_react4.default.createElement(import_recharts.LineChart, { data: sanitizedData, margin: { top: 10, right: 10, left: -20, bottom: 0 } }, /* @__PURE__ */ import_react4.default.createElement(import_recharts.CartesianGrid, { strokeDasharray: "3 3", vertical: false, stroke: "#e2e8f0" }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.XAxis, { dataKey: finalXKey, tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: { stroke: "#cbd5e1" } }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.YAxis, { tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: false }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Tooltip, { content: (props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === "string" ? props.label : void 0) }), /* @__PURE__ */ import_react4.default.createElement(import_recharts.Legend, { wrapperStyle: { fontSize: 12 } }), finalDataKeys.map((key, index) => /* @__PURE__ */ import_react4.default.createElement(
     import_recharts.Line,
     {
       key,
@@ -440,7 +474,8 @@ function DataTable({ config }) {
     ))
   ))))), /* @__PURE__ */ import_react5.default.createElement("div", { className: "px-4 py-2 bg-slate-50 dark:bg-white/5 border-t border-slate-100 dark:border-white/5" }, /* @__PURE__ */ import_react5.default.createElement("p", { className: "text-[11px] text-slate-400 dark:text-white/30" }, config.data.length, " row", config.data.length !== 1 ? "s" : "")));
 }
-function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming }) {
+function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming, onAddToCart }) {
+  var _a;
   const result = import_react5.default.useMemo(() => {
     if (isStreaming) return { loading: true };
     try {
@@ -472,28 +507,48 @@ function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming }) {
     return /* @__PURE__ */ import_react5.default.createElement("pre", { className: "p-4 my-2 bg-slate-900 text-slate-100 rounded-lg text-[10px] overflow-auto max-h-40" }, /* @__PURE__ */ import_react5.default.createElement("code", null, rawContent));
   }
   const { config } = result;
+  const hasInsights = Array.isArray(config.insights) && config.insights.length > 0;
+  const hasDescription = typeof config.description === "string" && config.description.trim().length > 0;
   switch (config.view) {
     case "chart":
-      return /* @__PURE__ */ import_react5.default.createElement("div", { className: "my-6 p-4 bg-white dark:bg-slate-900 rounded-2xl border border-slate-200 dark:border-white/10 shadow-sm overflow-hidden" }, config.title && /* @__PURE__ */ import_react5.default.createElement("h4", { className: "text-xs font-semibold text-slate-500 mb-4 px-2" }, config.title), /* @__PURE__ */ import_react5.default.createElement(
+      return /* @__PURE__ */ import_react5.default.createElement("div", { className: "my-6 p-4 bg-white dark:bg-slate-900 rounded-2xl border border-slate-200 dark:border-white/10 shadow-sm overflow-hidden" }, config.title && /* @__PURE__ */ import_react5.default.createElement("h4", { className: "text-xs font-semibold text-slate-500 mb-4 px-2" }, config.title), hasDescription && /* @__PURE__ */ import_react5.default.createElement("p", { className: "px-2 text-sm text-slate-500 dark:text-white/60" }, config.description), /* @__PURE__ */ import_react5.default.createElement(
         DynamicChart,
         {
           config: {
             type: config.chartType || "bar",
-            data: config.data
+            data: config.data,
+            xAxisKey: config.xAxisKey,
+            dataKeys: config.dataKeys,
+            colors: config.colors
           },
           primaryColor,
           accentColor
         }
-      ));
+      ), hasInsights && /* @__PURE__ */ import_react5.default.createElement("div", { className: "mt-4 flex flex-wrap gap-2 px-2" }, (_a = config.insights) == null ? void 0 : _a.map((insight) => /* @__PURE__ */ import_react5.default.createElement(
+        "span",
+        {
+          key: insight,
+          className: "rounded-full border border-emerald-200 bg-emerald-50 px-3 py-1 text-[11px] font-medium text-emerald-700 dark:border-emerald-500/20 dark:bg-emerald-500/10 dark:text-emerald-300"
+        },
+        insight
+      ))));
     case "carousel":
-      return /* @__PURE__ */ import_react5.default.createElement("div", { className: "my-4" }, /* @__PURE__ */ import_react5.default.createElement(ProductCarousel, { products: config.data.map((item) => {
-        var _a;
+      return /* @__PURE__ */ import_react5.default.createElement("div", { className: "my-4" }, config.title && /* @__PURE__ */ import_react5.default.createElement("h4", { className: "mb-2 text-xs font-semibold text-slate-500" }, config.title), hasDescription && /* @__PURE__ */ import_react5.default.createElement("p", { className: "mb-3 text-sm text-slate-500 dark:text-white/60" }, config.description), /* @__PURE__ */ import_react5.default.createElement(ProductCarousel, { products: config.data.map((item) => {
+        var _a2;
         return __spreadProps(__spreadValues({}, item), {
-          image: (_a = item.image) != null ? _a : typeof resolveImage === "function" ? resolveImage(item) : void 0
+          image: (_a2 = item.image) != null ? _a2 : typeof resolveImage === "function" ? resolveImage(item) : void 0
         });
-      }) }));
+      }), primaryColor, onAddToCart }));
     case "table":
-      return /* @__PURE__ */ import_react5.default.createElement("div", { className: "my-4 p-4 bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 shadow-sm overflow-auto max-h-[400px]" }, config.title && /* @__PURE__ */ import_react5.default.createElement("h4", { className: "text-xs font-semibold text-slate-500 mb-2" }, config.title), /* @__PURE__ */ import_react5.default.createElement(DataTable, { config: { type: "table", data: config.data } }));
+      return /* @__PURE__ */ import_react5.default.createElement("div", { className: "my-4 p-4 bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 shadow-sm overflow-auto max-h-[400px]" }, config.title && /* @__PURE__ */ import_react5.default.createElement("h4", { className: "text-xs font-semibold text-slate-500 mb-2" }, config.title), hasDescription && /* @__PURE__ */ import_react5.default.createElement("p", { className: "mb-3 text-sm text-slate-500 dark:text-white/60" }, config.description), /* @__PURE__ */ import_react5.default.createElement(DataTable, { config: {
+        type: "table",
+        title: config.title,
+        description: config.description,
+        columns: config.columns,
+        dataKeys: config.dataKeys,
+        xAxisKey: config.xAxisKey,
+        data: config.data
+      } }));
     default:
       return null;
   }
@@ -508,6 +563,10 @@ function MessageBubble({
 }) {
   const isUser = message.role === "user";
   const [showSources, setShowSources] = import_react5.default.useState(false);
+  const hasStructuredProductBlock = import_react5.default.useMemo(
+    () => /```(?:ui|json|chart)\s*[\s\S]*?"(?:view|type)"\s*:\s*"(?:carousel|products)"/i.test(message.content),
+    [message.content]
+  );
   const productsFromSources = import_react5.default.useMemo(() => {
     if (isUser || !sources) return [];
     return sources.filter((s) => {
@@ -678,7 +737,8 @@ ${match.trim()}
               rawContent: String(children != null ? children : "").trim(),
               primaryColor,
               accentColor,
-              isStreaming
+              isStreaming,
+              onAddToCart
             }
           );
         }
@@ -691,7 +751,8 @@ ${match.trim()}
                 rawContent: content,
                 primaryColor,
                 accentColor,
-                isStreaming
+                isStreaming,
+                onAddToCart
               }
             );
           }
@@ -702,7 +763,7 @@ ${match.trim()}
         return /* @__PURE__ */ import_react5.default.createElement("code", __spreadValues({ className }, props), typeof children === "string" || typeof children === "number" ? children : JSON.stringify(children));
       }
     }),
-    [primaryColor, accentColor, isStreaming]
+    [primaryColor, accentColor, isStreaming, onAddToCart]
   );
   return /* @__PURE__ */ import_react5.default.createElement("div", { className: `flex gap-3 ${isUser ? "flex-row-reverse" : "flex-row"} items-start` }, /* @__PURE__ */ import_react5.default.createElement(
     "div",
@@ -718,7 +779,7 @@ ${match.trim()}
       style: isUser ? { background: `linear-gradient(135deg, ${primaryColor}, ${accentColor})` } : {}
     },
     isStreaming && !message.content ? /* @__PURE__ */ import_react5.default.createElement("span", { className: "flex items-center gap-1 py-1" }, /* @__PURE__ */ import_react5.default.createElement("span", { className: "w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:0ms]" }), /* @__PURE__ */ import_react5.default.createElement("span", { className: "w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:150ms]" }), /* @__PURE__ */ import_react5.default.createElement("span", { className: "w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:300ms]" })) : /* @__PURE__ */ import_react5.default.createElement("div", { className: `prose prose-sm max-w-none ${isUser ? "prose-invert" : "dark:prose-invert"}` }, /* @__PURE__ */ import_react5.default.createElement(import_react_markdown.default, { remarkPlugins: [import_remark_gfm.default], components: markdownComponents }, processedMarkdown), isStreaming && message.content && /* @__PURE__ */ import_react5.default.createElement("span", { className: "inline-block w-1.5 h-3.5 ml-1 bg-emerald-500 animate-pulse align-middle" }))
-  ), !isUser && allProducts.length > 0 && /* @__PURE__ */ import_react5.default.createElement("div", { className: "w-full mt-1" }, /* @__PURE__ */ import_react5.default.createElement(
+  ), !isUser && !hasStructuredProductBlock && allProducts.length > 0 && /* @__PURE__ */ import_react5.default.createElement("div", { className: "w-full mt-1" }, /* @__PURE__ */ import_react5.default.createElement(
     ProductCarousel,
     {
       products: allProducts,

package/dist/index.mjs

@@ -233,8 +233,58 @@ function DynamicChart({ config, primaryColor = "#6366f1", accentColor = "#8b5cf6
   }).slice(0, 5);
   const finalXKey = String(resolvedXKey);
   const finalDataKeys = resolvedDataKeys.map(String).filter((k) => k !== "undefined");
+  const pieDataKey = finalDataKeys[0] || "value";
+  const stockAwareColor = (entry, index) => {
+    var _a, _b, _c;
+    const stockStatus = String(
+      (_c = (_b = (_a = entry.stockStatus) != null ? _a : entry.status) != null ? _b : entry.availability) != null ? _c : ""
+    ).toLowerCase();
+    const inStockCount = typeof entry.inStockCount === "number" ? entry.inStockCount : void 0;
+    const outOfStockCount = typeof entry.outOfStockCount === "number" ? entry.outOfStockCount : void 0;
+    const inStockFlag = entry.inStock;
+    if (stockStatus.includes("in stock")) return "#10b981";
+    if (stockStatus.includes("out of stock")) return "#f97316";
+    if (typeof inStockFlag === "string" && inStockFlag.toLowerCase() === "true") return "#10b981";
+    if (inStockFlag === 1) return "#10b981";
+    if (inStockFlag === 0) return "#f97316";
+    if (typeof inStockCount === "number" || typeof outOfStockCount === "number") {
+      const inCount = inStockCount != null ? inStockCount : 0;
+      const outCount = outOfStockCount != null ? outOfStockCount : 0;
+      if (inCount > outCount) return "#10b981";
+      if (outCount > inCount) return "#f97316";
+    }
+    return colors[index % colors.length];
+  };
+  const tooltipLabelMap = {
+    value: "Value",
+    count: "Count",
+    inStock: "In stock",
+    inStockCount: "In stock",
+    outOfStockCount: "Out of stock",
+    stockStatus: "Stock status",
+    category: "Category",
+    label: "Label",
+    name: "Name"
+  };
+  const renderTooltip = (row, label) => {
+    var _a, _b;
+    if (!row) return null;
+    return /* @__PURE__ */ React4.createElement("div", { className: "rounded-xl border border-slate-200 bg-white px-3 py-2 text-xs shadow-xl dark:border-white/10 dark:bg-slate-950" }, /* @__PURE__ */ React4.createElement("p", { className: "mb-2 font-semibold text-slate-800 dark:text-white/90" }, String((_b = (_a = row[finalXKey]) != null ? _a : label) != null ? _b : "Details")), Object.entries(row).map(([key, value]) => {
+      var _a2;
+      if (value === null || value === void 0 || key === finalXKey) return null;
+      if (typeof value === "object") return null;
+      return /* @__PURE__ */ React4.createElement("div", { key, className: "flex items-center justify-between gap-3 text-slate-600 dark:text-white/70" }, /* @__PURE__ */ React4.createElement("span", null, (_a2 = tooltipLabelMap[key]) != null ? _a2 : key), /* @__PURE__ */ React4.createElement("span", { className: "font-medium text-slate-900 dark:text-white/90" }, String(value)));
+    }));
+  };
+  const getTooltipRow = (payload) => {
+    if (!Array.isArray(payload) || payload.length === 0) return null;
+    const first = payload[0];
+    if (!first || typeof first !== "object" || !("payload" in first)) return null;
+    const row = first.payload;
+    if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+    return row;
+  };
   if (type === "pie") {
-    const pieDataKey = finalDataKeys[0] || "value";
     return /* @__PURE__ */ React4.createElement("div", { className: "w-full h-72 min-h-[280px] mt-4 mb-2 select-none overflow-hidden" }, /* @__PURE__ */ React4.createElement(ResponsiveContainer, { width: "99%", height: "100%" }, /* @__PURE__ */ React4.createElement(PieChart, null, /* @__PURE__ */ React4.createElement(
       Pie,
       {
@@ -246,21 +296,10 @@ function DynamicChart({ config, primaryColor = "#6366f1", accentColor = "#8b5cf6
         outerRadius: 80,
         label: ({ name, percent }) => `${name} ${((percent != null ? percent : 0) * 100).toFixed(0)}%`
       },
-      data.map((entry, index) => /* @__PURE__ */ React4.createElement(Cell, { key: `cell-${index}`, fill: colors[index % colors.length] }))
-    ), /* @__PURE__ */ React4.createElement(
-      Tooltip,
-      {
-        contentStyle: { borderRadius: "8px", border: "none", boxShadow: "0 4px 6px -1px rgb(0 0 0 / 0.1)" }
-      }
-    ), /* @__PURE__ */ React4.createElement(Legend, null))));
+      sanitizedData.map((entry, index) => /* @__PURE__ */ React4.createElement(Cell, { key: `cell-${index}`, fill: stockAwareColor(entry, index) }))
+    ), /* @__PURE__ */ React4.createElement(Tooltip, { content: (props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === "string" ? props.label : void 0) }), /* @__PURE__ */ React4.createElement(Legend, null))));
   }
-  return /* @__PURE__ */ React4.createElement("div", { className: "w-full h-72 min-h-[280px] mt-4 mb-2 select-none overflow-hidden" }, /* @__PURE__ */ React4.createElement(ResponsiveContainer, { width: "99%", height: "100%" }, type === "bar" ? /* @__PURE__ */ React4.createElement(BarChart, { data: sanitizedData, margin: { top: 10, right: 10, left: -20, bottom: 0 } }, /* @__PURE__ */ React4.createElement(CartesianGrid, { strokeDasharray: "3 3", vertical: false, stroke: "#e2e8f0" }), /* @__PURE__ */ React4.createElement(XAxis, { dataKey: finalXKey, tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: { stroke: "#cbd5e1" } }), /* @__PURE__ */ React4.createElement(YAxis, { tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: false }), /* @__PURE__ */ React4.createElement(
-    Tooltip,
-    {
-      contentStyle: { borderRadius: "8px", border: "none", boxShadow: "0 4px 6px -1px rgb(0 0 0 / 0.1)" },
-      cursor: { fill: "#f1f5f9" }
-    }
-  ), /* @__PURE__ */ React4.createElement(Legend, { wrapperStyle: { fontSize: 12 } }), finalDataKeys.map((key, index) => /* @__PURE__ */ React4.createElement(
+  return /* @__PURE__ */ React4.createElement("div", { className: "w-full h-72 min-h-[280px] mt-4 mb-2 select-none overflow-hidden" }, /* @__PURE__ */ React4.createElement(ResponsiveContainer, { width: "99%", height: "100%" }, type === "bar" ? /* @__PURE__ */ React4.createElement(BarChart, { data: sanitizedData, margin: { top: 10, right: 10, left: -20, bottom: 0 } }, /* @__PURE__ */ React4.createElement(CartesianGrid, { strokeDasharray: "3 3", vertical: false, stroke: "#e2e8f0" }), /* @__PURE__ */ React4.createElement(XAxis, { dataKey: finalXKey, tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: { stroke: "#cbd5e1" } }), /* @__PURE__ */ React4.createElement(YAxis, { tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: false }), /* @__PURE__ */ React4.createElement(Tooltip, { content: (props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === "string" ? props.label : void 0), cursor: { fill: "#f1f5f9" } }), /* @__PURE__ */ React4.createElement(Legend, { wrapperStyle: { fontSize: 12 } }), finalDataKeys.map((key, index) => /* @__PURE__ */ React4.createElement(
     Bar,
     {
       key,
@@ -269,12 +308,7 @@ function DynamicChart({ config, primaryColor = "#6366f1", accentColor = "#8b5cf6
       radius: [4, 4, 0, 0],
       barSize: Math.max(20, 60 / data.length)
     }
-  ))) : /* @__PURE__ */ React4.createElement(LineChart, { data: sanitizedData, margin: { top: 10, right: 10, left: -20, bottom: 0 } }, /* @__PURE__ */ React4.createElement(CartesianGrid, { strokeDasharray: "3 3", vertical: false, stroke: "#e2e8f0" }), /* @__PURE__ */ React4.createElement(XAxis, { dataKey: finalXKey, tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: { stroke: "#cbd5e1" } }), /* @__PURE__ */ React4.createElement(YAxis, { tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: false }), /* @__PURE__ */ React4.createElement(
-    Tooltip,
-    {
-      contentStyle: { borderRadius: "8px", border: "none", boxShadow: "0 4px 6px -1px rgb(0 0 0 / 0.1)" }
-    }
-  ), /* @__PURE__ */ React4.createElement(Legend, { wrapperStyle: { fontSize: 12 } }), finalDataKeys.map((key, index) => /* @__PURE__ */ React4.createElement(
+  ))) : /* @__PURE__ */ React4.createElement(LineChart, { data: sanitizedData, margin: { top: 10, right: 10, left: -20, bottom: 0 } }, /* @__PURE__ */ React4.createElement(CartesianGrid, { strokeDasharray: "3 3", vertical: false, stroke: "#e2e8f0" }), /* @__PURE__ */ React4.createElement(XAxis, { dataKey: finalXKey, tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: { stroke: "#cbd5e1" } }), /* @__PURE__ */ React4.createElement(YAxis, { tick: { fontSize: 12, fill: "#64748b" }, tickLine: false, axisLine: false }), /* @__PURE__ */ React4.createElement(Tooltip, { content: (props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === "string" ? props.label : void 0) }), /* @__PURE__ */ React4.createElement(Legend, { wrapperStyle: { fontSize: 12 } }), finalDataKeys.map((key, index) => /* @__PURE__ */ React4.createElement(
     Line,
     {
       key,
@@ -403,7 +437,8 @@ function DataTable({ config }) {
     ))
   ))))), /* @__PURE__ */ React5.createElement("div", { className: "px-4 py-2 bg-slate-50 dark:bg-white/5 border-t border-slate-100 dark:border-white/5" }, /* @__PURE__ */ React5.createElement("p", { className: "text-[11px] text-slate-400 dark:text-white/30" }, config.data.length, " row", config.data.length !== 1 ? "s" : "")));
 }
-function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming }) {
+function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming, onAddToCart }) {
+  var _a;
   const result = React5.useMemo(() => {
     if (isStreaming) return { loading: true };
     try {
@@ -435,28 +470,48 @@ function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming }) {
     return /* @__PURE__ */ React5.createElement("pre", { className: "p-4 my-2 bg-slate-900 text-slate-100 rounded-lg text-[10px] overflow-auto max-h-40" }, /* @__PURE__ */ React5.createElement("code", null, rawContent));
   }
   const { config } = result;
+  const hasInsights = Array.isArray(config.insights) && config.insights.length > 0;
+  const hasDescription = typeof config.description === "string" && config.description.trim().length > 0;
   switch (config.view) {
     case "chart":
-      return /* @__PURE__ */ React5.createElement("div", { className: "my-6 p-4 bg-white dark:bg-slate-900 rounded-2xl border border-slate-200 dark:border-white/10 shadow-sm overflow-hidden" }, config.title && /* @__PURE__ */ React5.createElement("h4", { className: "text-xs font-semibold text-slate-500 mb-4 px-2" }, config.title), /* @__PURE__ */ React5.createElement(
+      return /* @__PURE__ */ React5.createElement("div", { className: "my-6 p-4 bg-white dark:bg-slate-900 rounded-2xl border border-slate-200 dark:border-white/10 shadow-sm overflow-hidden" }, config.title && /* @__PURE__ */ React5.createElement("h4", { className: "text-xs font-semibold text-slate-500 mb-4 px-2" }, config.title), hasDescription && /* @__PURE__ */ React5.createElement("p", { className: "px-2 text-sm text-slate-500 dark:text-white/60" }, config.description), /* @__PURE__ */ React5.createElement(
         DynamicChart,
         {
           config: {
             type: config.chartType || "bar",
-            data: config.data
+            data: config.data,
+            xAxisKey: config.xAxisKey,
+            dataKeys: config.dataKeys,
+            colors: config.colors
           },
           primaryColor,
           accentColor
         }
-      ));
+      ), hasInsights && /* @__PURE__ */ React5.createElement("div", { className: "mt-4 flex flex-wrap gap-2 px-2" }, (_a = config.insights) == null ? void 0 : _a.map((insight) => /* @__PURE__ */ React5.createElement(
+        "span",
+        {
+          key: insight,
+          className: "rounded-full border border-emerald-200 bg-emerald-50 px-3 py-1 text-[11px] font-medium text-emerald-700 dark:border-emerald-500/20 dark:bg-emerald-500/10 dark:text-emerald-300"
+        },
+        insight
+      ))));
     case "carousel":
-      return /* @__PURE__ */ React5.createElement("div", { className: "my-4" }, /* @__PURE__ */ React5.createElement(ProductCarousel, { products: config.data.map((item) => {
-        var _a;
+      return /* @__PURE__ */ React5.createElement("div", { className: "my-4" }, config.title && /* @__PURE__ */ React5.createElement("h4", { className: "mb-2 text-xs font-semibold text-slate-500" }, config.title), hasDescription && /* @__PURE__ */ React5.createElement("p", { className: "mb-3 text-sm text-slate-500 dark:text-white/60" }, config.description), /* @__PURE__ */ React5.createElement(ProductCarousel, { products: config.data.map((item) => {
+        var _a2;
         return __spreadProps(__spreadValues({}, item), {
-          image: (_a = item.image) != null ? _a : typeof resolveImage === "function" ? resolveImage(item) : void 0
+          image: (_a2 = item.image) != null ? _a2 : typeof resolveImage === "function" ? resolveImage(item) : void 0
         });
-      }) }));
+      }), primaryColor, onAddToCart }));
     case "table":
-      return /* @__PURE__ */ React5.createElement("div", { className: "my-4 p-4 bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 shadow-sm overflow-auto max-h-[400px]" }, config.title && /* @__PURE__ */ React5.createElement("h4", { className: "text-xs font-semibold text-slate-500 mb-2" }, config.title), /* @__PURE__ */ React5.createElement(DataTable, { config: { type: "table", data: config.data } }));
+      return /* @__PURE__ */ React5.createElement("div", { className: "my-4 p-4 bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 shadow-sm overflow-auto max-h-[400px]" }, config.title && /* @__PURE__ */ React5.createElement("h4", { className: "text-xs font-semibold text-slate-500 mb-2" }, config.title), hasDescription && /* @__PURE__ */ React5.createElement("p", { className: "mb-3 text-sm text-slate-500 dark:text-white/60" }, config.description), /* @__PURE__ */ React5.createElement(DataTable, { config: {
+        type: "table",
+        title: config.title,
+        description: config.description,
+        columns: config.columns,
+        dataKeys: config.dataKeys,
+        xAxisKey: config.xAxisKey,
+        data: config.data
+      } }));
     default:
       return null;
   }
@@ -471,6 +526,10 @@ function MessageBubble({
 }) {
   const isUser = message.role === "user";
   const [showSources, setShowSources] = React5.useState(false);
+  const hasStructuredProductBlock = React5.useMemo(
+    () => /```(?:ui|json|chart)\s*[\s\S]*?"(?:view|type)"\s*:\s*"(?:carousel|products)"/i.test(message.content),
+    [message.content]
+  );
   const productsFromSources = React5.useMemo(() => {
     if (isUser || !sources) return [];
     return sources.filter((s) => {
@@ -641,7 +700,8 @@ ${match.trim()}
               rawContent: String(children != null ? children : "").trim(),
               primaryColor,
               accentColor,
-              isStreaming
+              isStreaming,
+              onAddToCart
             }
           );
         }
@@ -654,7 +714,8 @@ ${match.trim()}
                 rawContent: content,
                 primaryColor,
                 accentColor,
-                isStreaming
+                isStreaming,
+                onAddToCart
               }
             );
           }
@@ -665,7 +726,7 @@ ${match.trim()}
         return /* @__PURE__ */ React5.createElement("code", __spreadValues({ className }, props), typeof children === "string" || typeof children === "number" ? children : JSON.stringify(children));
       }
     }),
-    [primaryColor, accentColor, isStreaming]
+    [primaryColor, accentColor, isStreaming, onAddToCart]
   );
   return /* @__PURE__ */ React5.createElement("div", { className: `flex gap-3 ${isUser ? "flex-row-reverse" : "flex-row"} items-start` }, /* @__PURE__ */ React5.createElement(
     "div",
@@ -681,7 +742,7 @@ ${match.trim()}
       style: isUser ? { background: `linear-gradient(135deg, ${primaryColor}, ${accentColor})` } : {}
     },
     isStreaming && !message.content ? /* @__PURE__ */ React5.createElement("span", { className: "flex items-center gap-1 py-1" }, /* @__PURE__ */ React5.createElement("span", { className: "w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:0ms]" }), /* @__PURE__ */ React5.createElement("span", { className: "w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:150ms]" }), /* @__PURE__ */ React5.createElement("span", { className: "w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:300ms]" })) : /* @__PURE__ */ React5.createElement("div", { className: `prose prose-sm max-w-none ${isUser ? "prose-invert" : "dark:prose-invert"}` }, /* @__PURE__ */ React5.createElement(ReactMarkdown, { remarkPlugins: [remarkGfm], components: markdownComponents }, processedMarkdown), isStreaming && message.content && /* @__PURE__ */ React5.createElement("span", { className: "inline-block w-1.5 h-3.5 ml-1 bg-emerald-500 animate-pulse align-middle" }))
-  ), !isUser && allProducts.length > 0 && /* @__PURE__ */ React5.createElement("div", { className: "w-full mt-1" }, /* @__PURE__ */ React5.createElement(
+  ), !isUser && !hasStructuredProductBlock && allProducts.length > 0 && /* @__PURE__ */ React5.createElement("div", { className: "w-full mt-1" }, /* @__PURE__ */ React5.createElement(
     ProductCarousel,
     {
       products: allProducts,

package/dist/server.js

@@ -3913,23 +3913,68 @@ var Pipeline = class {
   async initialize() {
     var _a, _b;
     if (this.initialised) return;
-    const CHART_MARKER = "<!-- UI_PROTOCOL_V3 -->";
+    const CHART_MARKER = "<!-- UI_PROTOCOL_V5 -->";
     const chartInstruction = `
 
 ${CHART_MARKER}
-### UNIVERSAL UI PROTOCOL:
-You have a specialized UI system. For any structured data (charts, product lists, or tables), you MUST use a single \`\`\`ui\`\`\` block.
-1. DECIDE the best "view" for the user's query:
-   - "chart": For statistics, distributions, or comparisons. (Requires "chartType": "pie" | "bar" | "line")
-   - "carousel": For browsing specific product items.
-   - "table": For detailed raw data comparisons.
-2. OUTPUT a \`\`\`ui\`\`\` block with this schema:
+### UNIVERSAL UI PROTOCOL
+When the user asks for a visual representation, comparison, distribution, breakdown, table, list, catalog, products, carousel, stock view, or category summary, you MUST include exactly one \`\`\`ui\`\`\` block.
+
+1. VIEW SELECTION
+   - Use "chart" for distributions, percentages, counts, comparisons, trends, or "show me in a chart".
+   - Use "carousel" for browseable product recommendations or when the user asks to see products/items/cards.
+   - Use "table" for tabular/raw detail, explicit table/list requests, or when there are many attributes to compare.
+
+2. REQUIRED JSON SHAPE
    {
      "view": "chart" | "carousel" | "table",
-     "chartType": "pie" | "bar" | "line" (only for view: "chart"),
-     "data": [ ... objects ... ]
+     "title": "Short heading",
+     "description": "One sentence describing the view",
+     "chartType": "pie" | "bar" | "line",
+     "xAxisKey": "label",
+     "dataKeys": ["value"],
+     "columns": ["name", "category", "price", "stockStatus"],
+     "insights": ["Short takeaway 1", "Short takeaway 2"],
+     "data": []
    }
-3. RULES: Valid JSON only. Data must be FLAT. Never draw charts/tables with text. Choose ONLY the most useful view.`;
+
+3. DATA RULES
+   - Build the UI payload from retrieved context only. Do not invent products, categories, or stock values.
+   - Aggregate raw product rows when the user asks for a chart.
+   - For charts, every row in "data" must be flat JSON with primitive values only.
+   - Prefer { "label": "...", "value": number } for pie charts.
+   - If stock information exists, preserve it in each row with fields like "inStock", "inStockCount", "outOfStockCount", or "stockStatus".
+   - If the user asks to highlight what is in stock, include those stock-related fields in the chart data and mention the pattern in "insights".
+   - For carousel rows, include product-friendly fields such as id, name, brand, price, image, link, category, stockStatus.
+   - For tables, keep "data" row-oriented and include "columns" when possible.
+
+4. FORMAT RULES
+   - Never use ASCII art, markdown tables as the primary answer, or text-only fake charts when a UI block is requested.
+   - Put any short natural-language explanation before or after the \`\`\`ui\`\`\` block, but keep it concise.
+   - Return valid JSON inside the \`\`\`ui\`\`\` block.
+
+5. EXAMPLE
+User: "provide me the distribution of products across categories and highlight which ones are in stock in a pie chart"
+Assistant:
+\`\`\`ui
+{
+  "view": "chart",
+  "title": "Product Distribution Across Categories",
+  "description": "Pie chart showing product count by category with stock signals preserved per slice.",
+  "chartType": "pie",
+  "xAxisKey": "label",
+  "dataKeys": ["value"],
+  "insights": [
+    "Beauty has the highest product count.",
+    "Electronics has the largest number of in-stock products."
+  ],
+  "data": [
+    { "label": "Beauty", "value": 12, "inStockCount": 9, "outOfStockCount": 3 },
+    { "label": "Electronics", "value": 8, "inStockCount": 7, "outOfStockCount": 1 },
+    { "label": "Home", "value": 5, "inStockCount": 2, "outOfStockCount": 3 }
+  ]
+}
+\`\`\``;
     if (!((_a = this.config.llm.systemPrompt) == null ? void 0 : _a.includes(CHART_MARKER))) {
       this.config.llm.systemPrompt = (this.config.llm.systemPrompt || "") + chartInstruction;
     }

package/dist/server.mjs

@@ -39,7 +39,7 @@ import {
   sseFrame,
   sseMetaFrame,
   sseTextFrame
-} from "./chunk-BLLMNP77.mjs";
+} from "./chunk-Q4MDH6C4.mjs";
 import "./chunk-YLTMFW4M.mjs";
 import {
   PineconeProvider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retrivora-ai/rag-engine",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "Retrivora AI is a plug-and-play AI engine for RAG chat experiences — generic vector DB + LLM provider, embeddable or standalone.",
   "author": "Abhinav Alkuchi",
   "license": "MIT",

package/src/app/api/chat/route.ts

@@ -1,4 +1,4 @@
-import { createChatHandler } from '@/handlers';
+import { createStreamHandler } from '@/handlers';
 import { getRagConfig } from '@/config/serverConfig';
 
-export const POST = createChatHandler(getRagConfig());
+export const POST = createStreamHandler(getRagConfig());

package/src/components/DynamicChart.tsx

@@ -96,11 +96,85 @@ export function DynamicChart({ config, primaryColor = '#6366f1', accentColor = '
   // Final sanity check: ensure all keys are strings
   const finalXKey = String(resolvedXKey);
   const finalDataKeys = resolvedDataKeys.map(String).filter(k => k !== 'undefined');
+  const pieDataKey = finalDataKeys[0] || 'value';
+
+  const stockAwareColor = (entry: Record<string, string | number | null>, index: number) => {
+    const stockStatus = String(
+      entry.stockStatus ??
+      entry.status ??
+      entry.availability ??
+      '',
+    ).toLowerCase();
+    const inStockCount = typeof entry.inStockCount === 'number' ? entry.inStockCount : undefined;
+    const outOfStockCount = typeof entry.outOfStockCount === 'number' ? entry.outOfStockCount : undefined;
+    const inStockFlag = entry.inStock;
+
+    if (stockStatus.includes('in stock')) return '#10b981';
+    if (stockStatus.includes('out of stock')) return '#f97316';
+    if (typeof inStockFlag === 'string' && inStockFlag.toLowerCase() === 'true') return '#10b981';
+    if (inStockFlag === 1) return '#10b981';
+    if (inStockFlag === 0) return '#f97316';
+    if (typeof inStockCount === 'number' || typeof outOfStockCount === 'number') {
+      const inCount = inStockCount ?? 0;
+      const outCount = outOfStockCount ?? 0;
+      if (inCount > outCount) return '#10b981';
+      if (outCount > inCount) return '#f97316';
+    }
+
+    return colors[index % colors.length];
+  };
+
+  const tooltipLabelMap: Record<string, string> = {
+    value: 'Value',
+    count: 'Count',
+    inStock: 'In stock',
+    inStockCount: 'In stock',
+    outOfStockCount: 'Out of stock',
+    stockStatus: 'Stock status',
+    category: 'Category',
+    label: 'Label',
+    name: 'Name',
+  };
+
+  const renderTooltip = (
+    row: Record<string, string | number | null> | null,
+    label?: string,
+  ) => {
+    if (!row) return null;
+
+    return (
+      <div className="rounded-xl border border-slate-200 bg-white px-3 py-2 text-xs shadow-xl dark:border-white/10 dark:bg-slate-950">
+        <p className="mb-2 font-semibold text-slate-800 dark:text-white/90">
+          {String(row[finalXKey] ?? label ?? 'Details')}
+        </p>
+        {Object.entries(row).map(([key, value]) => {
+          if (value === null || value === undefined || key === finalXKey) return null;
+          if (typeof value === 'object') return null;
+
+          return (
+            <div key={key} className="flex items-center justify-between gap-3 text-slate-600 dark:text-white/70">
+              <span>{tooltipLabelMap[key] ?? key}</span>
+              <span className="font-medium text-slate-900 dark:text-white/90">{String(value)}</span>
+            </div>
+          );
+        })}
+      </div>
+    );
+  };
+
+  const getTooltipRow = (payload: unknown): Record<string, string | number | null> | null => {
+    if (!Array.isArray(payload) || payload.length === 0) return null;
+    const first = payload[0];
+    if (!first || typeof first !== 'object' || !('payload' in first)) return null;
+
+    const row = (first as { payload?: unknown }).payload;
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return null;
+
+    return row as Record<string, string | number | null>;
+  };
 
   // Handle Pie Chart separately as it has a different structure
   if (type === 'pie') {
-    const pieDataKey = finalDataKeys[0] || 'value';
-    
     return (
       <div className="w-full h-72 min-h-[280px] mt-4 mb-2 select-none overflow-hidden">
         <ResponsiveContainer width="99%" height="100%">
@@ -114,13 +188,11 @@ export function DynamicChart({ config, primaryColor = '#6366f1', accentColor = '
               outerRadius={80}
               label={({ name, percent }) => `${name} ${((percent ?? 0) * 100).toFixed(0)}%`}
             >
-              {data.map((entry, index) => (
-                <Cell key={`cell-${index}`} fill={colors[index % colors.length]} />
+              {sanitizedData.map((entry, index) => (
+                <Cell key={`cell-${index}`} fill={stockAwareColor(entry, index)} />
               ))}
             </Pie>
-            <Tooltip 
-              contentStyle={{ borderRadius: '8px', border: 'none', boxShadow: '0 4px 6px -1px rgb(0 0 0 / 0.1)' }}
-            />
+            <Tooltip content={(props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === 'string' ? props.label : undefined)} />
             <Legend />
           </PieChart>
         </ResponsiveContainer>
@@ -137,10 +209,7 @@ export function DynamicChart({ config, primaryColor = '#6366f1', accentColor = '
             <CartesianGrid strokeDasharray="3 3" vertical={false} stroke="#e2e8f0" />
             <XAxis dataKey={finalXKey} tick={{ fontSize: 12, fill: '#64748b' }} tickLine={false} axisLine={{ stroke: '#cbd5e1' }} />
             <YAxis tick={{ fontSize: 12, fill: '#64748b' }} tickLine={false} axisLine={false} />
-            <Tooltip 
-              contentStyle={{ borderRadius: '8px', border: 'none', boxShadow: '0 4px 6px -1px rgb(0 0 0 / 0.1)' }}
-              cursor={{ fill: '#f1f5f9' }}
-            />
+            <Tooltip content={(props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === 'string' ? props.label : undefined)} cursor={{ fill: '#f1f5f9' }} />
             <Legend wrapperStyle={{ fontSize: 12 }} />
             {finalDataKeys.map((key, index) => (
               <Bar 
@@ -157,9 +226,7 @@ export function DynamicChart({ config, primaryColor = '#6366f1', accentColor = '
             <CartesianGrid strokeDasharray="3 3" vertical={false} stroke="#e2e8f0" />
             <XAxis dataKey={finalXKey} tick={{ fontSize: 12, fill: '#64748b' }} tickLine={false} axisLine={{ stroke: '#cbd5e1' }} />
             <YAxis tick={{ fontSize: 12, fill: '#64748b' }} tickLine={false} axisLine={false} />
-            <Tooltip 
-              contentStyle={{ borderRadius: '8px', border: 'none', boxShadow: '0 4px 6px -1px rgb(0 0 0 / 0.1)' }}
-            />
+            <Tooltip content={(props) => renderTooltip(getTooltipRow(props.payload), typeof props.label === 'string' ? props.label : undefined)} />
             <Legend wrapperStyle={{ fontSize: 12 }} />
             {finalDataKeys.map((key, index) => (
               <Line 

package/src/components/MessageBubble.tsx

@@ -123,6 +123,7 @@ function normaliseChild(children: React.ReactNode): React.ReactNode {
 interface TableConfig {
   type: 'table';
   title?: string;
+  description?: string;
   columns?: string[];   // preferred: explicit ordered column labels
   dataKeys?: string[];  // fallback column keys (may omit xAxisKey)
   xAxisKey?: string;    // row-label key to prepend when using dataKeys
@@ -216,17 +217,24 @@ function DataTable({ config }: { config: TableConfig }) {
 interface UIConfig {
   view: 'chart' | 'carousel' | 'table';
   chartType?: 'pie' | 'bar' | 'line';
+  xAxisKey?: string;
+  dataKeys?: string[];
+  columns?: string[];
+  colors?: string[];
   data: Record<string, unknown>[];
   title?: string;
+  description?: string;
+  insights?: string[];
   type?: string;
   items?: Record<string, unknown>[];
 }
 
-function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming }: {
+function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming, onAddToCart }: {
   rawContent: string;
   primaryColor?: string;
   accentColor?: string;
   isStreaming?: boolean;
+  onAddToCart?: (product: Product) => void;
 }) {
   const result = React.useMemo<{ config: UIConfig } | { error: string } | { loading: true }>(() => {
     if (isStreaming) return { loading: true };
@@ -273,36 +281,71 @@ function UIDispatcher({ rawContent, primaryColor, accentColor, isStreaming }: {
   }
 
   const { config } = result;
+  const hasInsights = Array.isArray(config.insights) && config.insights.length > 0;
+  const hasDescription = typeof config.description === 'string' && config.description.trim().length > 0;
 
   switch (config.view) {
     case 'chart':
       return (
         <div className="my-6 p-4 bg-white dark:bg-slate-900 rounded-2xl border border-slate-200 dark:border-white/10 shadow-sm overflow-hidden">
           {config.title && <h4 className="text-xs font-semibold text-slate-500 mb-4 px-2">{config.title}</h4>}
+          {hasDescription && (
+            <p className="px-2 text-sm text-slate-500 dark:text-white/60">{config.description}</p>
+          )}
           <DynamicChart 
             config={{ 
               type: (config.chartType || 'bar') as 'bar' | 'line' | 'pie',
-              data: config.data as unknown as Record<string, string | number>[]
+              data: config.data as unknown as Record<string, string | number>[],
+              xAxisKey: config.xAxisKey,
+              dataKeys: config.dataKeys,
+              colors: config.colors,
             }}
             primaryColor={primaryColor}
             accentColor={accentColor}
           />
+          {hasInsights && (
+            <div className="mt-4 flex flex-wrap gap-2 px-2">
+              {config.insights?.map((insight) => (
+                <span
+                  key={insight}
+                  className="rounded-full border border-emerald-200 bg-emerald-50 px-3 py-1 text-[11px] font-medium text-emerald-700 dark:border-emerald-500/20 dark:bg-emerald-500/10 dark:text-emerald-300"
+                >
+                  {insight}
+                </span>
+              ))}
+            </div>
+          )}
         </div>
       );
     case 'carousel':
       return (
         <div className="my-4">
+          {config.title && <h4 className="mb-2 text-xs font-semibold text-slate-500">{config.title}</h4>}
+          {hasDescription && (
+            <p className="mb-3 text-sm text-slate-500 dark:text-white/60">{config.description}</p>
+          )}
           <ProductCarousel products={(config.data as unknown as Product[]).map(item => ({
             ...item,
             image: item.image ?? (typeof resolveImage === 'function' ? resolveImage(item as unknown as Record<string, unknown>) : undefined)
-          }))} />
+          }))} primaryColor={primaryColor} onAddToCart={onAddToCart} />
         </div>
       );
     case 'table':
       return (
         <div className="my-4 p-4 bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 shadow-sm overflow-auto max-h-[400px]">
           {config.title && <h4 className="text-xs font-semibold text-slate-500 mb-2">{config.title}</h4>}
-          <DataTable config={{ type: 'table', data: config.data } as TableConfig} />
+          {hasDescription && (
+            <p className="mb-3 text-sm text-slate-500 dark:text-white/60">{config.description}</p>
+          )}
+          <DataTable config={{
+            type: 'table',
+            title: config.title,
+            description: config.description,
+            columns: config.columns,
+            dataKeys: config.dataKeys,
+            xAxisKey: config.xAxisKey,
+            data: config.data,
+          }} />
         </div>
       );
     default:
@@ -324,6 +367,10 @@ export function MessageBubble({
 }: MessageBubbleProps) {
   const isUser = message.role === 'user';
   const [showSources, setShowSources] = React.useState(false);
+  const hasStructuredProductBlock = React.useMemo(
+    () => /```(?:ui|json|chart)\s*[\s\S]*?"(?:view|type)"\s*:\s*"(?:carousel|products)"/i.test(message.content),
+    [message.content],
+  );
 
   // ── Products from sources ──────────────────────────────────────────────────
   const productsFromSources = React.useMemo<Product[]>(() => {
@@ -500,6 +547,7 @@ export function MessageBubble({
               primaryColor={primaryColor}
               accentColor={accentColor}
               isStreaming={isStreaming}
+              onAddToCart={onAddToCart}
             />
           );
         }
@@ -513,6 +561,7 @@ export function MessageBubble({
                 primaryColor={primaryColor}
                 accentColor={accentColor}
                 isStreaming={isStreaming}
+                onAddToCart={onAddToCart}
               />
             );
           }
@@ -538,7 +587,7 @@ export function MessageBubble({
         );
       },
     }),
-    [primaryColor, accentColor, isStreaming],
+    [primaryColor, accentColor, isStreaming, onAddToCart],
   );
 
   // ── Render ─────────────────────────────────────────────────────────────────
@@ -586,7 +635,7 @@ export function MessageBubble({
         </div>
 
         {/* Product Carousel */}
-        {!isUser && allProducts.length > 0 && (
+        {!isUser && !hasStructuredProductBlock && allProducts.length > 0 && (
           <div className="w-full mt-1">
             <ProductCarousel
               products={allProducts}
@@ -619,4 +668,4 @@ export function MessageBubble({
       </div>
     </div>
   );
-}
+}

package/src/core/Pipeline.ts

@@ -101,21 +101,66 @@ export class Pipeline {
 
     // Augment system prompt with a Universal Visualization Protocol
     // We use a unique marker to ensure this is only injected once but is ALWAYS present.
-    const CHART_MARKER = '<!-- UI_PROTOCOL_V3 -->';
+    const CHART_MARKER = '<!-- UI_PROTOCOL_V5 -->';
     const chartInstruction = `\n\n${CHART_MARKER}
-### UNIVERSAL UI PROTOCOL:
-You have a specialized UI system. For any structured data (charts, product lists, or tables), you MUST use a single \`\`\`ui\`\`\` block.
-1. DECIDE the best "view" for the user's query:
-   - "chart": For statistics, distributions, or comparisons. (Requires "chartType": "pie" | "bar" | "line")
-   - "carousel": For browsing specific product items.
-   - "table": For detailed raw data comparisons.
-2. OUTPUT a \`\`\`ui\`\`\` block with this schema:
+### UNIVERSAL UI PROTOCOL
+When the user asks for a visual representation, comparison, distribution, breakdown, table, list, catalog, products, carousel, stock view, or category summary, you MUST include exactly one \`\`\`ui\`\`\` block.
+
+1. VIEW SELECTION
+   - Use "chart" for distributions, percentages, counts, comparisons, trends, or "show me in a chart".
+   - Use "carousel" for browseable product recommendations or when the user asks to see products/items/cards.
+   - Use "table" for tabular/raw detail, explicit table/list requests, or when there are many attributes to compare.
+
+2. REQUIRED JSON SHAPE
    {
      "view": "chart" | "carousel" | "table",
-     "chartType": "pie" | "bar" | "line" (only for view: "chart"),
-     "data": [ ... objects ... ]
+     "title": "Short heading",
+     "description": "One sentence describing the view",
+     "chartType": "pie" | "bar" | "line",
+     "xAxisKey": "label",
+     "dataKeys": ["value"],
+     "columns": ["name", "category", "price", "stockStatus"],
+     "insights": ["Short takeaway 1", "Short takeaway 2"],
+     "data": []
    }
-3. RULES: Valid JSON only. Data must be FLAT. Never draw charts/tables with text. Choose ONLY the most useful view.`;
+
+3. DATA RULES
+   - Build the UI payload from retrieved context only. Do not invent products, categories, or stock values.
+   - Aggregate raw product rows when the user asks for a chart.
+   - For charts, every row in "data" must be flat JSON with primitive values only.
+   - Prefer { "label": "...", "value": number } for pie charts.
+   - If stock information exists, preserve it in each row with fields like "inStock", "inStockCount", "outOfStockCount", or "stockStatus".
+   - If the user asks to highlight what is in stock, include those stock-related fields in the chart data and mention the pattern in "insights".
+   - For carousel rows, include product-friendly fields such as id, name, brand, price, image, link, category, stockStatus.
+   - For tables, keep "data" row-oriented and include "columns" when possible.
+
+4. FORMAT RULES
+   - Never use ASCII art, markdown tables as the primary answer, or text-only fake charts when a UI block is requested.
+   - Put any short natural-language explanation before or after the \`\`\`ui\`\`\` block, but keep it concise.
+   - Return valid JSON inside the \`\`\`ui\`\`\` block.
+
+5. EXAMPLE
+User: "provide me the distribution of products across categories and highlight which ones are in stock in a pie chart"
+Assistant:
+\`\`\`ui
+{
+  "view": "chart",
+  "title": "Product Distribution Across Categories",
+  "description": "Pie chart showing product count by category with stock signals preserved per slice.",
+  "chartType": "pie",
+  "xAxisKey": "label",
+  "dataKeys": ["value"],
+  "insights": [
+    "Beauty has the highest product count.",
+    "Electronics has the largest number of in-stock products."
+  ],
+  "data": [
+    { "label": "Beauty", "value": 12, "inStockCount": 9, "outOfStockCount": 3 },
+    { "label": "Electronics", "value": 8, "inStockCount": 7, "outOfStockCount": 1 },
+    { "label": "Home", "value": 5, "inStockCount": 2, "outOfStockCount": 3 }
+  ]
+}
+\`\`\``;
 
     if (!this.config.llm.systemPrompt?.includes(CHART_MARKER)) {
       this.config.llm.systemPrompt = (this.config.llm.systemPrompt || '') + chartInstruction;