@adia-ai/a2ui-retrieval 0.6.4 → 0.6.7

package/intent/decomposer.ts

@@ -1,229 +0,0 @@
-/**
- * Intent Decomposer — breaks complex intents into independent subtasks.
- *
- * When an intent describes multiple sections, areas, or features,
- * the decomposer splits it into atomic generation units that can be
- * generated independently and composed into a layout.
- *
- * Example:
- *   "settings page with profile, notifications, security, and billing"
- *   → 4 subtasks + a composition plan (Tabs layout)
- *
- * The decomposition is the single most important capability per the
- * Software Factory Manifesto: "Get decomposition right and generation
- * is almost trivial."
- */
-
-import { classifyIntent } from '../domain-router.js';
-
-// ── Section Detection ────────────────────────────────────────────────────
-
-/** Connectors that separate sections in an intent */
-const SECTION_SPLITTERS = /\band\b|\bwith\b|\bplus\b|\balso\b|,\s*(?:and\s+)?/gi;
-
-/** Words that signal enumerated sections */
-const SECTION_SIGNALS = [
-  /\b(\d+)\s+(sections?|areas?|parts?|panels?|columns?|cards?|tabs?|pages?|views?)\b/i,
-  /\bsections?:\s/i,
-  /\bincluding\b/i,
-  /\beach\s+(with|having|containing)\b/i,
-];
-
-/** Layout containers that imply multi-section structure */
-const LAYOUT_KEYWORDS: Record<string, { component: string; child: string }> = {
-  tabs: { component: 'Tabs', child: 'Tab' },
-  sections: { component: 'Column', child: 'Card' },
-  columns: { component: 'Grid', child: 'Column' },
-  cards: { component: 'Grid', child: 'Card' },
-  panels: { component: 'Accordion', child: 'Panel' },
-  pages: { component: 'Tabs', child: 'Tab' },
-  areas: { component: 'Grid', child: 'Card' },
-  steps: { component: 'Steps', child: 'Step' },
-};
-
-export type Subtask = { intent: string; label: string };
-export type LayoutInfo = { component: string; child: string };
-
-export type DecomposeResult = {
-  shouldDecompose: boolean;
-  subtasks: Subtask[];
-  layout: LayoutInfo | null;
-  original: string;
-};
-
-/**
- * Analyze an intent for decomposition potential.
- */
-export function decomposeIntent(intent: string): DecomposeResult {
-  const trimmed = (intent || '').trim();
-  if (!trimmed) return { shouldDecompose: false, subtasks: [], layout: null, original: trimmed };
-
-  // ── Detect explicit section count ──
-  for (const pattern of SECTION_SIGNALS) {
-    if (pattern.test(trimmed)) {
-      const sections = extractSections(trimmed);
-      if (sections.length >= 2) {
-        const layout = detectLayout(trimmed, sections.length);
-        return {
-          shouldDecompose: true,
-          subtasks: sections,
-          layout,
-          original: trimmed,
-        };
-      }
-    }
-  }
-
-  // ── Detect enumerated items ──
-  const sections = extractSections(trimmed);
-  if (sections.length >= 2) {
-    // 2+ distinct sections → decompose
-    const layout = detectLayout(trimmed, sections.length);
-    return {
-      shouldDecompose: true,
-      subtasks: sections,
-      layout,
-      original: trimmed,
-    };
-  }
-
-  // ── Short or simple intent → don't decompose ──
-  return { shouldDecompose: false, subtasks: [], layout: null, original: trimmed };
-}
-
-/**
- * Extract individual section descriptions from an intent.
- */
-function extractSections(intent: string): Subtask[] {
-  // Find the "with X, Y, Z, and W" pattern
-  const withMatch = intent.match(/\bwith\s+(.+)$/i);
-  const payload = withMatch ? withMatch[1] : intent;
-
-  // Split on connectors
-  const parts = payload.split(SECTION_SPLITTERS)
-    .map(s => s.trim())
-    .filter(s => s.length > 2);
-
-  if (parts.length < 2) return [];
-
-  // Extract the base context (everything before "with")
-  const baseContext = withMatch ? intent.slice(0, withMatch.index).trim() : '';
-  const domain = classifyIntent(intent).domain;
-  void domain; // used for context only in the original
-
-  return parts.map(part => {
-    // Build a self-contained subtask intent
-    const label = part.replace(/\b(section|area|panel|tab|page)\b/gi, '').trim();
-    const subtaskIntent = baseContext
-      ? `${label} section for a ${baseContext}`
-      : `${label}`;
-
-    return { intent: subtaskIntent, label: capitalizeFirst(label) };
-  });
-}
-
-/**
- * Detect the best layout container for the decomposed sections.
- */
-function detectLayout(intent: string, sectionCount: number): LayoutInfo {
-  const lower = intent.toLowerCase();
-
-  // Explicit layout keywords in the intent
-  for (const [keyword, layout] of Object.entries(LAYOUT_KEYWORDS)) {
-    if (lower.includes(keyword)) return layout;
-  }
-
-  // Heuristic: settings/profile pages → Tabs
-  if (lower.includes('settings') || lower.includes('preferences') || lower.includes('account')) {
-    return { component: 'Tabs', child: 'Tab' };
-  }
-
-  // Heuristic: dashboard with metrics → Grid of Cards
-  if (lower.includes('dashboard') || lower.includes('overview') || lower.includes('stat')) {
-    return { component: 'Grid', child: 'Card' };
-  }
-
-  // Default: small count → Tabs, large count → Grid
-  if (sectionCount <= 4) return { component: 'Tabs', child: 'Tab' };
-  return { component: 'Grid', child: 'Card' };
-}
-
-type SubtaskResult = {
-  label: string;
-  messages: Array<{ components?: ComponentItem[] }>;
-};
-
-type ComponentItem = {
-  id: string;
-  component?: string;
-  children?: string[];
-  text?: string;
-  columns?: string;
-  gap?: string;
-  [key: string]: unknown;
-};
-
-/**
- * Compose independently generated subtask results into a layout.
- * Returns A2UI messages for the composed layout.
- */
-export function composeSubtasks(layout: LayoutInfo, subtaskResults: SubtaskResult[]): object[] {
-  const rootChildren: string[] = [];
-  const allComponents: ComponentItem[] = [];
-  let idCounter = 0;
-
-  for (const { label, messages } of subtaskResults) {
-    const prefix = `s${++idCounter}`;
-    const subtaskComponents: ComponentItem[] = messages?.[0]?.components ?? [];
-
-    // Re-prefix all component IDs to avoid collisions
-    const idMap = new Map<string, string>();
-    const remapped = subtaskComponents.map(c => {
-      const newId = c.id === 'root' ? prefix : `${prefix}-${c.id}`;
-      idMap.set(c.id, newId);
-      return { ...c, id: newId };
-    });
-
-    // Fix child references
-    for (const c of remapped) {
-      if (c.children) {
-        c.children = c.children.map(id => idMap.get(id) ?? id);
-      }
-    }
-
-    // Create the layout wrapper for this subtask
-    if (layout.child === 'Tab') {
-      // Tabs: wrap in a Tab with a label
-      const tabId = `${prefix}-tab`;
-      allComponents.push({ id: tabId, component: 'Tab', text: label, children: [prefix] });
-      rootChildren.push(tabId);
-    } else {
-      // Grid/Column: subtask root becomes a direct child
-      rootChildren.push(prefix);
-    }
-
-    allComponents.push(...remapped);
-  }
-
-  // Build the root layout
-  const root: ComponentItem = {
-    id: 'root',
-    component: layout.component,
-    children: rootChildren,
-  };
-
-  if (layout.component === 'Grid') {
-    root['columns'] = String(Math.min(subtaskResults.length, 4));
-    root['gap'] = 'md';
-  }
-
-  return [{
-    type: 'updateComponents',
-    surfaceId: 'default',
-    components: [root, ...allComponents],
-  }];
-}
-
-function capitalizeFirst(str: string): string {
-  return str.charAt(0).toUpperCase() + str.slice(1);
-}

package/intent/index.ts

@@ -1,20 +0,0 @@
-/**
- * @adia-ai/a2ui-retrieval/intent — intent classification + decomposition surface.
- *
- * Re-exports the intent-shaped retrieval primitives. Importers can reach
- * individual files directly (e.g. `@adia-ai/a2ui-retrieval/intent/clarity`)
- * or pull the bundle via this barrel.
- */
-
-export { extractExpectations, verifyAlignment, checkIntentAlignment } from './intent-alignment.js';
-export type { Expectations, AlignmentCheck, AlignmentResult, QuantityExpectation } from './intent-alignment.js';
-export { categorizeIntent } from './intent-categorizer.js';
-export type { IntentCategory } from './intent-categorizer.js';
-export { isConversational } from './intent-gate.js';
-export type { IntentGateResult } from './intent-gate.js';
-export { analyzePrompt, formatAnalysisForPrompt } from './prompt-analyzer.js';
-export type { PromptAnalysis } from './prompt-analyzer.js';
-export { decomposeIntent, composeSubtasks } from './decomposer.js';
-export type { DecomposeResult, Subtask, LayoutInfo } from './decomposer.js';
-export { assessClarity } from './clarity.js';
-export type { ClarityResult, ClarityDimensions, ClarityQuestion } from './clarity.js';

package/intent/intent-alignment.ts

@@ -1,267 +0,0 @@
-/**
- * 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

@@ -1,104 +0,0 @@
-/**
- * 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),
-  };
-}