@adia-ai/a2ui-retrieval 0.6.0 → 0.6.2

package/feedback/gap-registry.ts

@@ -0,0 +1,137 @@
+/**
+ * Gap Registry
+ *
+ * Manages a persistent JSON file tracking identified pattern/training gaps.
+ * Used by the feedback pipeline to record and track resolution of weak areas.
+ *
+ * Registry file: packages/a2ui/corpus/gaps/registry.json
+ *
+ * Usage:
+ *   import { loadGaps, addGap, updateGapStatus } from './gap-registry.js';
+ *   const gaps = await loadGaps();
+ *   await addGap({ intentCategory: 'form/checkout', ... });
+ *   await updateGapStatus('form/checkout', 'resolved', 'Added checkout pattern');
+ */
+
+// `process` is not in scope under "types": []
+declare const process: { versions?: { node?: string } } | undefined;
+
+// Lazy top-level import pattern for Node-only modules
+let fs: typeof import('node:fs/promises') | null = null;
+let path: typeof import('node:path') | null = null;
+const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
+if (IS_NODE) {
+  try {
+    fs = await import(/* @vite-ignore */ 'node:fs/promises');
+    path = await import(/* @vite-ignore */ 'node:path');
+  } catch {
+    // Node builtins unavailable
+  }
+}
+
+// packages/a2ui/retrieval/feedback → up 3 → packages/a2ui → corpus/gaps/registry.json
+const REGISTRY_PATH: string | null = path
+  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..', 'a2ui/corpus', 'gaps', 'registry.json')
+  : null;
+
+export type GapStatus = 'open' | 'in-progress' | 'resolved';
+
+export type Gap = {
+  intentCategory: string;
+  detectedAt: string;
+  lastSeen: string;
+  sampleCount: number;
+  avgScore: number;
+  avgRating: number;
+  status: GapStatus;
+  resolution: string | null;
+  sampleIntents: string[];
+  resolvedAt?: string;
+};
+
+export type AddGapInput = {
+  intentCategory: string;
+  sampleCount?: number;
+  avgScore?: number;
+  avgRating?: number;
+  sampleIntents?: string[];
+};
+
+/**
+ * Load all gaps from the registry file.
+ */
+export async function loadGaps(): Promise<Gap[]> {
+  if (!fs || !REGISTRY_PATH) return [];
+  try {
+    const content = await fs.readFile(REGISTRY_PATH, 'utf8');
+    return JSON.parse(content) as Gap[];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Save the full gaps array to disk.
+ */
+export async function saveGaps(gaps: Gap[]): Promise<void> {
+  if (!fs || !REGISTRY_PATH) return;
+  const dir = path!.dirname(REGISTRY_PATH);
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(REGISTRY_PATH, JSON.stringify(gaps, null, 2) + '\n');
+}
+
+/**
+ * Add a new gap to the registry. Merges with existing if same intentCategory.
+ */
+export async function addGap(gap: AddGapInput): Promise<Gap[]> {
+  const gaps = await loadGaps();
+  const existing = gaps.find(g => g.intentCategory === gap.intentCategory && g.status !== 'resolved');
+
+  if (existing) {
+    // Merge: update stats, add new sample intents
+    existing.sampleCount = gap.sampleCount ?? existing.sampleCount;
+    existing.avgScore = gap.avgScore ?? existing.avgScore;
+    existing.avgRating = gap.avgRating ?? existing.avgRating;
+    existing.lastSeen = new Date().toISOString();
+    const intentSet = new Set([...existing.sampleIntents, ...(gap.sampleIntents ?? [])]);
+    existing.sampleIntents = [...intentSet].slice(0, 10);
+  } else {
+    gaps.push({
+      intentCategory: gap.intentCategory,
+      detectedAt: new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
+      sampleCount: gap.sampleCount ?? 0,
+      avgScore: gap.avgScore ?? 0,
+      avgRating: gap.avgRating ?? 0,
+      status: 'open',
+      resolution: null,
+      sampleIntents: (gap.sampleIntents ?? []).slice(0, 10),
+    });
+  }
+
+  await saveGaps(gaps);
+  return gaps;
+}
+
+/**
+ * Update the status of a gap by intent category.
+ */
+export async function updateGapStatus(category: string, status: GapStatus, resolution?: string): Promise<Gap> {
+  const gaps = await loadGaps();
+  const gap = gaps.find(g => g.intentCategory === category && g.status !== 'resolved');
+
+  if (!gap) {
+    throw new Error(`No open gap found for category: ${category}`);
+  }
+
+  gap.status = status;
+  if (resolution) {
+    gap.resolution = resolution;
+  }
+  if (status === 'resolved') {
+    gap.resolvedAt = new Date().toISOString();
+  }
+
+  await saveGaps(gaps);
+  return gap;
+}

package/feedback/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @adia-ai/a2ui-retrieval/feedback — feedback-loop surface.
+ *
+ * Pairs the feedback store, analyzer, dialog recorder, and gap registry
+ * — all the artifacts that compose the user-feedback ingestion loop.
+ */
+
+export { feedbackStore } from './feedback-store.js';
+export { FeedbackAnalyzer } from './feedback-analyzer.js';
+export * from './feedback.js';
+export { recordTurn, isRecording } from './dialog-recorder.js';
+export type { TurnRecord } from './dialog-recorder.js';
+export { loadGaps, addGap, updateGapStatus } from './gap-registry.js';
+export type { Gap, GapStatus, AddGapInput } from './gap-registry.js';

package/intent/clarity.ts

@@ -0,0 +1,224 @@
+/**
+ * Clarity Assessment — Evaluates whether a user intent is clear enough
+ * to generate quality UI, or needs clarifying questions first.
+ *
+ * Scores intents across 5 dimensions:
+ *   domain   — Is the domain clear? (forms, data, layout, etc.)
+ *   scope    — Is the scope defined? (how many items, what sections?)
+ *   content  — Is the content specified? (labels, values, data?)
+ *   layout   — Is the layout preference stated? (grid, stack, sidebar?)
+ *   action   — Are actions/interactions mentioned? (buttons, forms, links?)
+ *
+ * Returns a clarity score (0-1) and targeted questions for what's missing.
+ */
+
+import { classifyIntent } from '../domain-router.js';
+import { searchAll as searchCompositions } from '../../compose/strategies/zettel/composition-library.js';
+
+// ── Dimension detectors ──────────────────────────────────────────────────
+
+/** Scope indicators: quantity, enumeration, specificity */
+const SCOPE_SIGNALS = [
+  /\b\d+\b/,                        // contains a number
+  /\b(three|two|four|five|six)\b/i,  // spelled-out numbers
+  /\b(with|containing|including|showing|displaying)\b/i,  // enumerates content
+  /\b(and|plus|also)\b/i,            // multiple items
+  /\b(columns?|rows?|items?|cards?|sections?|fields?|buttons?|tabs?|steps?)\b/i,  // structural counts
+];
+
+/** Content specificity: labels, values, named data */
+const CONTENT_SIGNALS = [
+  /\b(name|email|password|title|description|price|date|status|role|avatar)\b/i,
+  /\b(revenue|users|growth|sales|orders|metrics|analytics)\b/i,
+  /\b(todo|done|in progress|pending|active|completed)\b/i,
+  /\b(bleed|margin|trim|crop|preview|artwork|brand|design system)\b/i,
+  /\b(approved|approval|production|settings|configure|preference)\b/i,
+  /["'][\w\s]+["']/,                // quoted strings (specific labels)
+  /\$[\d,.]+/,                      // dollar amounts
+  /\d+%/,                           // percentages
+];
+
+/** Layout preferences */
+const LAYOUT_SIGNALS = [
+  /\b(grid|row|column|sidebar|split|horizontal|vertical|stack|centered)\b/i,
+  /\b(full.?width|responsive|mobile|compact|wide|narrow)\b/i,
+  /\b(\d+.?col(umn)?s?)\b/i,       // "3 columns", "2-col"
+  /\b(left|right|top|bottom|center)\b/i,
+];
+
+/** Action/interaction indicators */
+const ACTION_SIGNALS = [
+  /\b(button|submit|cancel|save|delete|edit|close|open|toggle|click)\b/i,
+  /\b(form|input|select|search|filter|sort|upload|download)\b/i,
+  /\b(login|signup|register|checkout|confirm|approve|reject)\b/i,
+  /\b(navigate|link|redirect|route)\b/i,
+  /\b(drag|drop|resize|expand|collapse)\b/i,
+];
+
+export type ClarityDimensions = {
+  domain: number;
+  scope: number;
+  content: number;
+  layout: number;
+  action: number;
+};
+
+export type ClarityQuestion = {
+  text: string;
+  dimension: string;
+  priority: number;
+};
+
+export type ClarityResult = {
+  clear: boolean;
+  score: number;
+  dimensions: ClarityDimensions;
+  questions: ClarityQuestion[];
+  summary: string;
+};
+
+type ClassificationArg = {
+  domain: string;
+  confidence: number;
+  matchedSignals: string[];
+};
+
+/**
+ * Assess clarity of a user intent for UI generation.
+ */
+export function assessClarity(intent: string, classification?: ClassificationArg): ClarityResult {
+  const text = (intent ?? '').trim();
+  if (!text) {
+    return {
+      clear: false,
+      score: 0,
+      dimensions: { domain: 0, scope: 0, content: 0, layout: 0, action: 0 },
+      questions: [{ text: 'What would you like me to build?', dimension: 'domain', priority: 1 }],
+      summary: 'No intent provided',
+    };
+  }
+
+  const cls = classification || classifyIntent(text);
+  const compositionMatches = searchCompositions(text);
+  const wordCount = text.split(/\s+/).length;
+
+  // ── Score each dimension ──
+
+  // Domain: how confident is the domain classification?
+  const domainScore = cls.confidence >= 0.3 ? 1 : cls.confidence >= 0.15 ? 0.6 : cls.matchedSignals.length > 0 ? 0.3 : 0;
+
+  // Scope: is the scope specific?
+  const scopeHits = SCOPE_SIGNALS.filter(r => r.test(text)).length;
+  const scopeScore = Math.min(1, scopeHits / 2);
+
+  // Content: are concrete labels/values mentioned?
+  const contentHits = CONTENT_SIGNALS.filter(r => r.test(text)).length;
+  const contentScore = Math.min(1, contentHits / 2);
+
+  // Layout: is a layout preference stated?
+  const layoutHits = LAYOUT_SIGNALS.filter(r => r.test(text)).length;
+  const layoutScore = Math.min(1, layoutHits);
+
+  // Action: are interactions mentioned?
+  const actionHits = ACTION_SIGNALS.filter(r => r.test(text)).length;
+  const actionScore = Math.min(1, actionHits / 2);
+
+  // ── Overall score (weighted) ──
+  const score = (
+    domainScore * 0.25 +
+    scopeScore * 0.25 +
+    contentScore * 0.20 +
+    layoutScore * 0.15 +
+    actionScore * 0.15
+  );
+
+  // ── Bonus: composition match adds confidence ──
+  const patternBonus = compositionMatches.length > 0 ? 0.15 : 0;
+  // Bonus: long intents are usually more specific
+  const lengthBonus = wordCount > 10 ? 0.1 : wordCount > 6 ? 0.05 : 0;
+
+  const finalScore = Math.min(1, score + patternBonus + lengthBonus);
+
+  // ── Generate targeted questions for weak dimensions ──
+  const questions: ClarityQuestion[] = [];
+
+  if (domainScore < 0.3) {
+    questions.push({
+      text: 'What type of UI is this? (e.g., a form, dashboard, profile card, settings page)',
+      dimension: 'domain',
+      priority: 1,
+    });
+  }
+
+  if (scopeScore < 0.5) {
+    const domainQuestions: Record<string, string> = {
+      forms: 'What fields should the form include?',
+      data: 'What data should be displayed? How many items or metrics?',
+      layout: 'How many sections or cards should it have?',
+      agent: 'What actions should the assistant support?',
+      navigation: 'What pages or sections should be navigable?',
+    };
+    questions.push({
+      text: domainQuestions[cls.domain] ?? 'Can you be more specific about what it should contain?',
+      dimension: 'scope',
+      priority: 2,
+    });
+  }
+
+  if (contentScore < 0.3 && scopeScore >= 0.3) {
+    const contentQuestions: Record<string, string> = {
+      forms: 'What labels should the fields have? (e.g., "Email", "Password", "Full Name")',
+      data: 'What metrics or values should be shown? (e.g., revenue, users, growth rate)',
+      layout: 'What content goes in each section?',
+      agent: 'What kind of messages or responses should be shown?',
+      navigation: 'What should the menu items or links be labeled?',
+    };
+    questions.push({
+      text: contentQuestions[cls.domain] ?? 'What specific content should be displayed?',
+      dimension: 'content',
+      priority: 3,
+    });
+  }
+
+  if (layoutScore < 0.3 && scopeScore >= 0.5) {
+    questions.push({
+      text: 'Any layout preference? (e.g., grid of cards, single column, sidebar + content)',
+      dimension: 'layout',
+      priority: 4,
+    });
+  }
+
+  if (actionScore < 0.3 && domainScore >= 0.3) {
+    questions.push({
+      text: 'What actions should users be able to take? (e.g., submit, edit, delete, filter)',
+      dimension: 'action',
+      priority: 5,
+    });
+  }
+
+  // Sort by priority, limit to 3
+  questions.sort((a, b) => a.priority - b.priority);
+  const topQuestions = questions.slice(0, 3);
+
+  // ── Determine if clear enough to proceed ──
+  // Clear only if dimensional score meets threshold
+  const clear = finalScore >= 0.4;
+
+  const summary = clear
+    ? `Intent is ${finalScore >= 0.7 ? 'clear' : 'adequate'} (${Math.round(finalScore * 100)}%)`
+    : `Intent needs clarification (${Math.round(finalScore * 100)}% — below 40% threshold)`;
+
+  return {
+    clear,
+    score: Math.round(finalScore * 100) / 100,
+    dimensions: {
+      domain: Math.round(domainScore * 100) / 100,
+      scope: Math.round(scopeScore * 100) / 100,
+      content: Math.round(contentScore * 100) / 100,
+      layout: Math.round(layoutScore * 100) / 100,
+      action: Math.round(actionScore * 100) / 100,
+    },
+    questions: topQuestions,
+    summary,
+  };
+}

package/intent/decomposer.ts

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

@@ -0,0 +1,20 @@
+/**
+ * @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';