@adia-ai/a2ui-retrieval 0.6.1 → 0.6.2

package/intent/intent-alignment.ts

@@ -0,0 +1,267 @@
+/**
+ * Intent Alignment Verification — checks whether generated output
+ * actually contains what the user asked for.
+ *
+ * Extracts expectations from the intent (field labels, component types,
+ * quantities, action verbs) and verifies them against the A2UI output.
+ *
+ * Returns a structured alignment report with per-expectation pass/fail,
+ * an overall alignment score (0-1), and specific gaps.
+ */
+
+// ── Expectation Extractors ──────────────────────────────────────────────
+
+/** Field/label expectations — "email", "password", "name", etc. */
+const FIELD_PATTERNS = [
+  /\b(email|password|username|name|phone|address|city|state|zip|country|company|title|role|bio|url|website|date|time|description|message|subject|amount|price|quantity|search|notes?)\b/gi,
+];
+
+/** Component type expectations — "button", "form", "table", etc. */
+const COMPONENT_PATTERNS = [
+  /\b(button|form|table|chart|card|avatar|badge|alert|modal|drawer|tabs?|sidebar|navbar|breadcrumb|pagination|progress|slider|toggle|checkbox|radio|dropdown|select|upload|calendar|timeline|steps?|accordion)\b/gi,
+];
+
+/** Quantity expectations — "3 cards", "two columns", etc. */
+const QUANTITY_MAP: Record<string, number> = { one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10 };
+const QUANTITY_PATTERN = /\b(\d+|one|two|three|four|five|six|seven|eight|nine|ten)\s+(cards?|columns?|items?|fields?|buttons?|sections?|rows?|tiles?|steps?|tabs?|metrics?|stats?)\b/gi;
+
+/** Action expectations — "submit", "cancel", "delete", etc. */
+const ACTION_PATTERNS = [
+  /\b(submit|cancel|save|delete|edit|close|open|search|filter|sort|login|signup|register|checkout|confirm|reset|send|upload|download|share|copy|print)\b/gi,
+];
+
+/** Specific content expectations — quoted strings, dollar amounts, percentages */
+const CONTENT_PATTERNS = [
+  /["']([^"']+)["']/g,           // quoted strings
+  /\$[\d,.]+/g,                   // dollar amounts
+  /\d+%/g,                        // percentages
+];
+
+export type QuantityExpectation = { count: number; type: string };
+
+export type Expectations = {
+  fields: string[];
+  componentTypes: string[];
+  quantities: QuantityExpectation[];
+  actions: string[];
+  content: string[];
+};
+
+export type AlignmentCheck = {
+  category: string;
+  expected: string;
+  found: boolean;
+  detail: string;
+};
+
+export type AlignmentResult = {
+  score: number;
+  checks: AlignmentCheck[];
+  gaps: string[];
+};
+
+/**
+ * Extract expectations from a natural language intent.
+ */
+export function extractExpectations(intent: string): Expectations {
+  const lower = intent.toLowerCase();
+
+  // Fields
+  const fields: string[] = [];
+  for (const pattern of FIELD_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(lower))) {
+      const f = match[1].toLowerCase();
+      if (!fields.includes(f)) fields.push(f);
+    }
+  }
+
+  // Component types
+  const componentTypes: string[] = [];
+  for (const pattern of COMPONENT_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(lower))) {
+      const t = match[1].toLowerCase();
+      if (!componentTypes.includes(t)) componentTypes.push(t);
+    }
+  }
+
+  // Quantities
+  const quantities: QuantityExpectation[] = [];
+  QUANTITY_PATTERN.lastIndex = 0;
+  let qMatch;
+  while ((qMatch = QUANTITY_PATTERN.exec(lower))) {
+    const raw = qMatch[1];
+    const num = QUANTITY_MAP[raw] ?? parseInt(raw, 10);
+    const type = qMatch[2].replace(/s$/, ''); // singularize
+    if (!isNaN(num)) quantities.push({ count: num, type });
+  }
+
+  // Actions
+  const actions: string[] = [];
+  for (const pattern of ACTION_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(lower))) {
+      const a = match[1].toLowerCase();
+      if (!actions.includes(a)) actions.push(a);
+    }
+  }
+
+  // Specific content
+  const content: string[] = [];
+  for (const pattern of CONTENT_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(intent))) {
+      content.push(match[1] ?? match[0]);
+    }
+  }
+
+  return { fields, componentTypes, quantities, actions, content };
+}
+
+// ── A2UI Type Mapping ───────────────────────────────────────────────────
+
+/** Map intent keywords to A2UI component types */
+const TYPE_MAP: Record<string, string[]> = {
+  button: ['Button'],
+  form: ['FormContainer', 'TextField', 'Column'],
+  table: ['Table'],
+  chart: ['Chart'],
+  card: ['Card'],
+  avatar: ['Avatar'],
+  badge: ['Badge'],
+  alert: ['Alert'],
+  modal: ['Modal', 'Dialog'],
+  drawer: ['Drawer'],
+  tab: ['Tabs', 'Tab'],
+  sidebar: ['Sidebar'],
+  navbar: ['Nav'],
+  breadcrumb: ['Breadcrumb'],
+  pagination: ['Pagination'],
+  progress: ['Progress'],
+  slider: ['Slider'],
+  toggle: ['Toggle'],
+  checkbox: ['CheckBox'],
+  radio: ['Radio'],
+  dropdown: ['ChoicePicker', 'Select'],
+  select: ['ChoicePicker', 'Select'],
+  upload: ['Upload'],
+  calendar: ['CalendarPicker', 'DateTimeInput'],
+  timeline: ['Timeline'],
+  step: ['Steps'],
+  accordion: ['Accordion'],
+};
+
+type ComponentRecord = {
+  component?: string;
+  textContent?: string;
+  text?: string;
+  label?: string;
+  placeholder?: string;
+  description?: string;
+  name?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * Verify generated A2UI output against extracted expectations.
+ */
+export function verifyAlignment(components: ComponentRecord[], expectations: Expectations): AlignmentResult {
+  const checks: AlignmentCheck[] = [];
+  const gaps: string[] = [];
+
+  // Collect all text content and properties from components
+  const allText = components.map(c => {
+    const texts = [c['textContent'], c['text'], c['label'], c['placeholder'], c['description'], c['name']];
+    return texts.filter(Boolean).join(' ').toLowerCase();
+  }).join(' ');
+
+  const allTypes = new Set(components.map(c => c.component));
+
+  // ── Check fields ──
+  for (const field of expectations.fields) {
+    const found = allText.includes(field) ||
+      components.some(c => (c['label'] ?? '').toLowerCase().includes(field) ||
+        (c['placeholder'] ?? '').toLowerCase().includes(field) ||
+        (c['name'] ?? '').toLowerCase().includes(field));
+    checks.push({
+      category: 'field',
+      expected: field,
+      found,
+      detail: found ? `Found "${field}" in component properties` : `Missing field: "${field}"`,
+    });
+    if (!found) gaps.push(`Missing field "${field}"`);
+  }
+
+  // ── Check component types ──
+  for (const type of expectations.componentTypes) {
+    const mappedTypes = TYPE_MAP[type] ?? [type.charAt(0).toUpperCase() + type.slice(1)];
+    const found = mappedTypes.some(t => allTypes.has(t));
+    checks.push({
+      category: 'componentType',
+      expected: type,
+      found,
+      detail: found ? `Found ${type} component` : `Missing component type: ${type}`,
+    });
+    if (!found) gaps.push(`Missing ${type} component`);
+  }
+
+  // ── Check quantities ──
+  for (const { count, type } of expectations.quantities) {
+    const mappedTypes = TYPE_MAP[type] ?? [type.charAt(0).toUpperCase() + type.slice(1)];
+    const actual = components.filter(c => mappedTypes.some(t => c.component === t)).length;
+    const found = actual >= count;
+    checks.push({
+      category: 'quantity',
+      expected: `${count} ${type}(s)`,
+      found,
+      detail: found ? `Found ${actual} ${type}(s) (expected ${count})` : `Only ${actual} ${type}(s), expected ${count}`,
+    });
+    if (!found) gaps.push(`Expected ${count} ${type}(s), found ${actual}`);
+  }
+
+  // ── Check actions ──
+  for (const action of expectations.actions) {
+    const found = allText.includes(action) ||
+      components.some(c => c.component === 'Button' && (c['text'] ?? '').toLowerCase().includes(action));
+    checks.push({
+      category: 'action',
+      expected: action,
+      found,
+      detail: found ? `Found "${action}" action` : `Missing action: "${action}"`,
+    });
+    if (!found) gaps.push(`Missing "${action}" action`);
+  }
+
+  // ── Check specific content ──
+  for (const text of expectations.content) {
+    const found = allText.includes(text.toLowerCase());
+    checks.push({
+      category: 'content',
+      expected: text,
+      found,
+      detail: found ? `Found content "${text}"` : `Missing content: "${text}"`,
+    });
+    if (!found) gaps.push(`Missing content "${text}"`);
+  }
+
+  // ── Score ──
+  const total = checks.length;
+  const passed = checks.filter(c => c.found).length;
+  const score = total > 0 ? Math.round((passed / total) * 100) / 100 : 1;
+
+  return { score, checks, gaps };
+}
+
+/**
+ * Full intent alignment check — extract + verify in one call.
+ */
+export function checkIntentAlignment(intent: string, components: ComponentRecord[]): AlignmentResult & { expectations: Expectations } {
+  const expectations = extractExpectations(intent);
+  const result = verifyAlignment(components, expectations);
+  return { ...result, expectations };
+}

package/intent/intent-categorizer.ts

@@ -0,0 +1,104 @@
+/**
+ * Intent Categorizer
+ *
+ * Maps free-text intents to a taxonomy of UI categories using keyword matching.
+ * Used by the feedback analyzer to aggregate metrics per intent type.
+ */
+
+type CategoryRule = {
+  category: string;
+  keywords: string[];
+};
+
+const CATEGORY_RULES: CategoryRule[] = [
+  // Form categories
+  { category: 'form/login',    keywords: ['login', 'sign in', 'signin', 'log in', 'authentication'] },
+  { category: 'form/signup',   keywords: ['signup', 'sign up', 'register', 'registration', 'create account', 'onboarding'] },
+  { category: 'form/contact',  keywords: ['contact', 'contact us', 'reach out', 'get in touch', 'enquiry', 'inquiry'] },
+  { category: 'form/settings', keywords: ['settings', 'preferences', 'config', 'configuration', 'account settings', 'profile edit'] },
+  { category: 'form/checkout', keywords: ['checkout', 'check out', 'payment', 'billing', 'purchase'] },
+
+  // Data categories
+  { category: 'data/table',     keywords: ['table', 'data table', 'spreadsheet', 'grid view', 'list view', 'datagrid'] },
+  { category: 'data/dashboard', keywords: ['dashboard', 'kpi', 'metrics', 'analytics', 'overview', 'summary panel', 'stats'] },
+  { category: 'data/chart',     keywords: ['chart', 'graph', 'visualization', 'pie chart', 'bar chart', 'line chart', 'histogram'] },
+
+  // Layout categories
+  { category: 'layout/landing', keywords: ['landing', 'landing page', 'homepage', 'hero', 'splash'] },
+  { category: 'layout/profile', keywords: ['profile', 'user profile', 'avatar', 'bio', 'about me'] },
+  { category: 'layout/pricing', keywords: ['pricing', 'pricing table', 'plans', 'subscription', 'tier'] },
+
+  // Navigation categories
+  { category: 'nav/sidebar', keywords: ['sidebar', 'side nav', 'navigation menu', 'drawer', 'side panel'] },
+  { category: 'nav/tabs',    keywords: ['tabs', 'tab bar', 'tabbed', 'tab navigation', 'tab panel'] },
+
+  // Agent categories
+  { category: 'agent/chat',         keywords: ['chat', 'chatbot', 'messenger', 'conversation', 'messaging', 'chat interface'] },
+  { category: 'agent/notification', keywords: ['notification', 'alert', 'toast', 'snackbar', 'banner', 'announcement'] },
+
+  // Content categories
+  { category: 'content/blog', keywords: ['blog', 'article', 'post', 'news', 'editorial', 'content feed'] },
+  { category: 'content/faq',  keywords: ['faq', 'frequently asked', 'questions', 'help center', 'knowledge base', 'accordion'] },
+
+  // Commerce categories
+  { category: 'commerce/product', keywords: ['product', 'product card', 'product page', 'product detail', 'item detail', 'catalog'] },
+  { category: 'commerce/cart',    keywords: ['cart', 'shopping cart', 'basket', 'bag'] },
+  { category: 'commerce/order',   keywords: ['order', 'order history', 'order summary', 'receipt', 'invoice', 'order tracking'] },
+
+  // Workflow categories
+  { category: 'workflow/wizard',  keywords: ['wizard', 'stepper', 'multi-step', 'step form', 'onboard flow', 'setup wizard'] },
+  { category: 'workflow/kanban',  keywords: ['kanban', 'board', 'task board', 'trello', 'project board', 'drag and drop'] },
+
+  // Status categories
+  { category: 'status/error',   keywords: ['error', 'error page', '404', '500', 'not found', 'something went wrong'] },
+  { category: 'status/empty',   keywords: ['empty state', 'no results', 'no data', 'zero state', 'blank slate'] },
+  { category: 'status/loading', keywords: ['loading', 'skeleton', 'spinner', 'progress', 'placeholder'] },
+];
+
+export type IntentCategory = {
+  category: string;
+  confidence: number;
+};
+
+/**
+ * Categorize a free-text intent into a UI taxonomy category.
+ */
+export function categorizeIntent(intent: string): IntentCategory {
+  if (!intent || typeof intent !== 'string') {
+    return { category: 'other', confidence: 0 };
+  }
+
+  const lower = intent.toLowerCase().trim();
+  let bestCategory = 'other';
+  let bestScore = 0;
+
+  for (const rule of CATEGORY_RULES) {
+    let matchCount = 0;
+    let longestMatch = 0;
+
+    for (const kw of rule.keywords) {
+      if (lower.includes(kw)) {
+        matchCount++;
+        longestMatch = Math.max(longestMatch, kw.length);
+      }
+    }
+
+    if (matchCount === 0) continue;
+
+    // Score: multi-word keyword matches get higher confidence,
+    // more matches within a category = higher confidence
+    const kwLenBonus = longestMatch / lower.length; // longer keyword relative to intent = more specific
+    const multiMatchBonus = Math.min(matchCount * 0.15, 0.3);
+    const score = 0.5 + kwLenBonus * 0.3 + multiMatchBonus;
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestCategory = rule.category;
+    }
+  }
+
+  return {
+    category: bestCategory,
+    confidence: Math.min(Math.round(bestScore * 100) / 100, 1),
+  };
+}

package/intent/intent-gate.ts

@@ -0,0 +1,151 @@
+/**
+ * Intent Gate — Detect whether a user message is conversational (question,
+ * greeting, meta-question) vs. a UI generation request.
+ *
+ * Used by the chat setup to route non-generation messages to a text reply
+ * instead of the full 6-stage pipeline.
+ */
+
+/** Question starters that signal conversational intent */
+const QUESTION_STARTERS = /^\s*(what|how|why|can you|could you|tell me|explain|describe|help|who|where|when|is there|are there|do you|does|did|will|should|would|which|list|show me how)\b/i;
+
+/** Greetings and social signals */
+const GREETINGS = /^\s*(hi|hey|hello|thanks|thank you|bye|goodbye|ok|okay|sure|great|nice|cool|awesome|good|perfect)\b/i;
+
+/** Explicit meta-questions about the system itself */
+const META_PATTERNS = [
+  /what\s+(components?|types?|elements?)\s+(are|do|can)/i,
+  /available\s+(components?|types?|elements?)/i,
+  /how\s+(does|do)\s+(this|it|the system|gen ui|a2ui)/i,
+  /what\s+can\s+(you|this|it)\s+(do|generate|create|build)/i,
+  /help\s+me\s+understand/i,
+  /list\s+(of\s+)?(components?|types?|elements?)/i,
+  /what\s+(is|are)\s+(a2ui|agentui|agent ui|gen ui)/i,
+  /show\s+me\s+(the\s+)?(components?|options?|catalog)/i,
+  /explain\s+(the|how|what|a)/i,
+  /how\s+(to|do\s+I)\s+(use|create|build|make)/i,
+  /what\s+would\s+.+\s+look\s+like/i,
+  /show\s+me\s+how/i,
+];
+
+/** Content that is clearly not a UI intent (injection, noise, gibberish) */
+const NOISE_PATTERNS = [
+  /^<[^>]+>/,              // Starts with HTML tag
+  /^\s*[^\w\s]{3,}/,      // Starts with 3+ non-word chars
+];
+
+/** Vague, motivational, or abstract phrases with no UI-describing language.
+ *  These are common conversational inputs that the LLM hallucinates UIs from. */
+const VAGUE_PATTERNS = [
+  /^(do|just|go|let'?s|get|keep|stay|stop|try|move|make it|finish|start|begin|end|run)\b.{0,30}$/i,  // short imperative without UI nouns
+  /\b(you gotta|gotta do|no excuses|believe|motivat|inspir|goal|dream|life|love|hate|feel|think about)\b/i,
+  /\b(what is preventing|what stops|why can't|why won't)\b/i,  // philosophical/motivational questions
+  /\b(do it|get it done|let'?s go|make it happen|just do it|never give up)\b/i,  // motivational slogans
+];
+
+/** Tool-use and action-oriented intents that should be handled conversationally,
+ *  not as UI generation requests. These are commands directed at the system. */
+const TOOL_USE_PATTERNS = [
+  /\b(create|file|write|open|submit|log)\s+(a\s+)?(ticket|bug|issue|report|feature request)/i,
+  /\b(report|flag)\s+(a\s+)?(bug|issue|problem|error|regression)/i,
+  /\b(why|how come)\s+(does|did|is|was|are)\b/i,   // "why does X do Y" — asking for rationale
+  /\bthis\s+(is|looks?)\s+(broken|wrong|buggy|off|weird|strange)/i,
+  /\b(fix|repair|debug|investigate)\s+(this|the|that)/i,
+  /\bsomething\s+(is|seems|looks?)\s+(wrong|broken|off)/i,
+  /\bmark\s+(this|it)\s+as\b/i,
+  /\b(save|bookmark|pin)\s+(this|the)\s+(pattern|output|result)/i,
+];
+
+export type IntentGateResult = {
+  conversational: boolean;
+  reason: string;
+};
+
+type ClassifyResult = {
+  confidence: number;
+  matchedSignals?: string[];
+};
+
+/**
+ * Determine if a user message is conversational (should get a text reply)
+ * or a UI generation request (should go through the pipeline).
+ */
+export function isConversational(text: string, classifyResult: ClassifyResult | null | undefined): IntentGateResult {
+  const trimmed = (text ?? '').trim();
+  let cls: ClassifyResult = classifyResult && typeof classifyResult === 'object'
+    ? classifyResult
+    : { confidence: 0, matchedSignals: [] };
+
+  // Very short messages without generation keywords are likely conversational
+  if (trimmed.length < 5 && cls.confidence === 0) {
+    return { conversational: true, reason: 'short-input' };
+  }
+
+  // Noise/injection detection — not a real intent
+  for (const pattern of NOISE_PATTERNS) {
+    if (pattern.test(trimmed) && cls.confidence === 0) {
+      return { conversational: true, reason: 'noise-input' };
+    }
+  }
+
+  // Explicit meta-questions about the system → always conversational
+  for (const pattern of META_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return { conversational: true, reason: 'meta-question' };
+    }
+  }
+
+  // Tool-use commands (create ticket, report bug, etc.) → conversational
+  for (const pattern of TOOL_USE_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return { conversational: true, reason: 'tool-use' };
+    }
+  }
+
+  // Vague / motivational / abstract input with no or weak domain signals
+  if (cls.confidence < 0.2) {
+    for (const pattern of VAGUE_PATTERNS) {
+      if (pattern.test(trimmed)) {
+        return { conversational: true, reason: 'vague-or-abstract' };
+      }
+    }
+  }
+
+  // Greetings with no generation signals
+  if (GREETINGS.test(trimmed) && cls.confidence === 0) {
+    return { conversational: true, reason: 'greeting' };
+  }
+
+  // High confidence in a domain → generation request
+  if (cls.confidence >= 0.3) {
+    return { conversational: false, reason: 'high-domain-confidence' };
+  }
+
+  // Has matched at least 2 domain signals → generation
+  if ((cls.matchedSignals?.length ?? 0) >= 2) {
+    return { conversational: false, reason: 'multiple-domain-signals' };
+  }
+
+  // Question pattern with single low-confidence signal → conversational
+  if (QUESTION_STARTERS.test(trimmed) && (cls.matchedSignals?.length ?? 0) <= 1) {
+    return { conversational: true, reason: 'question-single-signal' };
+  }
+
+  // Greetings even with some confidence → still conversational
+  if (GREETINGS.test(trimmed) && cls.confidence < 0.2) {
+    return { conversational: true, reason: 'greeting-low-confidence' };
+  }
+
+  // Default: if there's any domain signal at all, treat as generation
+  if (cls.confidence > 0) {
+    return { conversational: false, reason: 'has-domain-signal' };
+  }
+
+  // No signals — check for question marks or question patterns
+  if (trimmed.endsWith('?')) {
+    return { conversational: true, reason: 'ends-with-question-mark' };
+  }
+
+  // No domain signals at all — route to conversational for clarification
+  return { conversational: true, reason: 'no-ui-signals' };
+}