@retrivora-ai/rag-engine 1.7.1 → 1.7.2

package/src/core/Pipeline.ts

@@ -101,16 +101,15 @@ 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_V7 -->';
+    const CHART_MARKER = '<!-- UI_PROTOCOL_V6 -->';
     const chartInstruction = `\n\n${CHART_MARKER}
-### UNIVERSAL UI PROTOCOL (MANDATORY)
-CRITICAL: When providing visual data (carousels, charts, tables), you MUST wrap the JSON payload in a \`\`\`ui\`\`\` code block. 
-NEVER output naked JSON. If you provide a visualization, do not also provide a markdown table of the same data unless explicitly asked.
+### 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 "carousel" for browsing products, items, or catalogs. (e.g., "show me beauty products").
-   - Use "chart" ONLY for numerical aggregations (counts, sums, percentages).
-   - Use "table" for technical specs or row-heavy comparisons.
+   - Use "carousel" for browsing specific products, items, or a catalog. This is the DEFAULT for "show me", "what are", or "find me" requests for a specific category (e.g. "beauty").
+   - Use "chart" ONLY for numerical aggregations: distributions, percentages, counts, comparisons over time, or trends (e.g. "how many beauty products?").
+   - Use "table" for detailed technical specifications, row-heavy comparisons, or when the user explicitly asks for a list/table format.
 
 2. REQUIRED JSON SHAPE
    {
@@ -118,31 +117,52 @@ NEVER output naked JSON. If you provide a visualization, do not also provide a m
      "title": "Short heading",
      "description": "One sentence describing the view",
      "chartType": "pie" | "bar" | "line", // Required if view is "chart"
-     "data": [] // Array of objects
+     "xAxisKey": "label",
+     "dataKeys": ["value"],
+     "columns": ["dynamicFieldKey1", "dynamicFieldKey2"],
+     "insights": ["Short takeaway 1", "Short takeaway 2"],
+     "data": []
    }
 
 3. DATA RULES
-   - Build the UI payload from retrieved context and metadata.
-   - For CAROUSEL: "data" items MUST have { id, name, brand, price, image, link }.
-   - IMPORTANT: Extract "image" and "price" from Source metadata. Image URLs are often in fields like "images", "thumbnail", or "img".
+   - Build the UI payload from retrieved context only. Do not invent products or values.
+   - For CAROUSEL: "data" must be a list of product objects (id, name, brand, price, image, link).
+   - For CHART: "data" must be aggregated counts or sums. Never put raw product lists in a chart view.
+   - If the user asks for "products in beauty", do NOT return a pie chart of categories; return a carousel of the beauty products themselves.
 
 4. FORMAT RULES
-   - Wrap the JSON in \`\`\`ui ... \`\`\` blocks.
-   - Place natural language text OUTSIDE the block.
+   - Return valid JSON inside the \`\`\`ui\`\`\` block.
+   - Put natural language explanation before or after the block, not inside.
 
-5. EXAMPLE
-User: "find me beauty products"
-Assistant: "I found several beauty products in our catalog:"
+5. EXAMPLES
+User: "show me beauty products"
+Assistant:
 \`\`\`ui
 {
   "view": "carousel",
   "title": "Beauty Products",
-  "description": "Latest skincare and makeup items.",
+  "description": "Browse our latest skincare and makeup collection.",
   "data": [
-    { "id": "1", "name": "Mascara", "brand": "Essence", "price": "$9.99", "image": "https://placehold.co/600x400?text=Product", "link": "https://example.com/product" }
+    { "id": "1", "name": "Mascara", "brand": "Essence", "price": "$9.99", "image": "...", "link": "..." },
+    { "id": "2", "name": "Lipstick", "brand": "Chic", "price": "$12.99", "image": "...", "link": "..." }
   ]
 }
 \`\`\`
+
+User: "breakdown of products by category"
+Assistant:
+\`\`\`ui
+{
+  "view": "chart",
+  "title": "Category Breakdown",
+  "chartType": "pie",
+  "xAxisKey": "label",
+  "dataKeys": ["value"],
+  "data": [
+    { "label": "Beauty", "value": 15 },
+    { "label": "Fragrances", "value": 8 }
+  ]
+}
 \`\`\``;
 
     if (!this.config.llm.systemPrompt?.includes(CHART_MARKER)) {
@@ -387,7 +407,7 @@ Assistant: "I found several beauty products in our catalog:"
 
       // 4. Context Augmentation
       let context = sources.length
-        ? sources.map((m, i) => `[Source ${i + 1}]\nContent: ${m.content}\nMetadata: ${JSON.stringify(m.metadata)}`).join('\n\n---\n\n')
+        ? sources.map((m, i) => `[Source ${i + 1}]\n${m.content}`).join('\n\n---\n\n')
         : 'No relevant context found.';
 
       if (graphData && graphData.nodes.length > 0) {

package/src/handlers/index.ts

@@ -1,8 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { VectorPlugin } from '../core/VectorPlugin';
 import { RagConfig } from '../config/RagConfig';
-import { ChatMessage } from '../types';
+import { ChatMessage, ChatResponse } from '../types';
 import { DocumentParser } from '../utils/DocumentParser';
+import { UITransformer } from '../utils/UITransformer';
 
 // ─── SSE helpers ──────────────────────────────────────────────────────────────
 
@@ -19,11 +20,16 @@ function sseTextFrame(text: string): string {
   return `data: ${JSON.stringify({ type: 'text', text })}\n\n`;
 }
 
-/** Encode the retrieval metadata as an SSE frame. */
+/** Encode the retrieval metadata with UI transformation as an SSE frame. */
 function sseMetaFrame(meta: unknown): string {
   return `data: ${JSON.stringify({ type: 'metadata', ...((meta as object) ?? {}) })}\n\n`;
 }
 
+/** Encode the UI transformation result as an SSE frame. */
+function sseUIFrame(uiTransformation: unknown): string {
+  return `data: ${JSON.stringify({ type: 'ui_transformation', ...((uiTransformation as object) ?? {}) })}\n\n`;
+}
+
 /** Encode a stream error as an SSE frame. */
 function sseErrorFrame(message: string): string {
   return `data: ${JSON.stringify({ type: 'error', error: message })}\n\n`;
@@ -145,6 +151,18 @@ export function createStreamHandler(configOrPlugin?: Partial<RagConfig> | Vector
             } else {
               // Retrieval metadata object — always the final frame
               enqueue(sseMetaFrame(chunk));
+
+              // Transform retrieved sources to UI representation
+              const sources = (chunk as ChatResponse)?.sources || [];
+              if (sources && sources.length > 0) {
+                try {
+                  const uiTransformation = UITransformer.transform(message, sources);
+                  enqueue(sseUIFrame(uiTransformation));
+                } catch (transformError) {
+                  console.warn('[createStreamHandler] UI transformation warning:', transformError);
+                  // Don't fail the stream if transformation fails, just skip it
+                }
+              }
             }
           }
         } catch (streamError) {
@@ -292,4 +310,4 @@ export function createSuggestionsHandler(configOrPlugin?: Partial<RagConfig> | V
 }
 
 // Re-export SSE helper so host apps can use it in custom handlers
-export { sseFrame, sseTextFrame, sseMetaFrame, sseErrorFrame };
+export { sseFrame, sseTextFrame, sseMetaFrame, sseErrorFrame, sseUIFrame };

package/src/hooks/useUITransform.ts

@@ -0,0 +1,54 @@
+import { useState, useCallback } from 'react';
+import { UITransformer, UITransformationResponse } from '@/utils/UITransformer';
+import { VectorMatch } from '@/types';
+
+/**
+ * useUITransform hook — Transforms vector database results into UI components
+ *
+ * @example
+ * const { transform, result, loading } = useUITransform();
+ *
+ * const handleSearch = async (query: string) => {
+ *   const results = await fetchSearchResults(query);
+ *   transform(query, results);
+ * };
+ *
+ * return (
+ *   <>
+ *     {result && <DynamicChart data={result} />}
+ *   </>
+ * );
+ */
+export function useUITransform() {
+  const [result, setResult] = useState<UITransformationResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const transform = useCallback(
+    (query: string, data: VectorMatch[]) => {
+      try {
+        setLoading(true);
+        setError(null);
+
+        const transformed = UITransformer.transform(query, data);
+        setResult(transformed);
+
+        return transformed;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Transformation error';
+        setError(message);
+        return null;
+      } finally {
+        setLoading(false);
+      }
+    },
+    []
+  );
+
+  const reset = useCallback(() => {
+    setResult(null);
+    setError(null);
+  }, []);
+
+  return { transform, result, loading, error, reset };
+}