@adia-ai/a2ui-retrieval 0.6.4 → 0.6.6

package/intent/clarity.js

@@ -1,196 +1,125 @@
-/**
- * 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 */
+import { classifyIntent } from "../domain-router.js";
+import { searchAll as searchCompositions } from "../../compose/strategies/zettel/composition-library.js";
 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
+  /\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
+  /["'][\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,
+  /\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,
+  /\b(drag|drop|resize|expand|collapse)\b/i
 ];
-
-/**
- * Assess clarity of a user intent for UI generation.
- *
- * @param {string} intent — Raw user input
- * @param {{ domain: string, confidence: number, matchedSignals: string[] }} [classification] — Pre-computed classification
- * @returns {{
- *   clear: boolean,
- *   score: number,
- *   dimensions: { domain: number, scope: number, content: number, layout: number, action: number },
- *   questions: { text: string, dimension: string, priority: number }[],
- *   summary: string,
- * }}
- */
-export function assessClarity(intent, classification) {
-  const text = (intent ?? '').trim();
+function assessClarity(intent, classification) {
+  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',
+      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 lower = text.toLowerCase();
   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 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 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 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 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 score = domainScore * 0.25 + scopeScore * 0.25 + contentScore * 0.2 + layoutScore * 0.15 + actionScore * 0.15;
   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 = [];
-
   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,
+      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 = {
-      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?',
+      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,
+      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 = {
       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?',
+      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,
+      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,
+      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,
+      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)`;
-
+  const summary = clear ? `Intent is ${finalScore >= 0.7 ? "clear" : "adequate"} (${Math.round(finalScore * 100)}%)` : `Intent needs clarification (${Math.round(finalScore * 100)}% \u2014 below 40% threshold)`;
   return {
     clear,
     score: Math.round(finalScore * 100) / 100,
@@ -199,9 +128,12 @@ export function assessClarity(intent, classification) {
       scope: Math.round(scopeScore * 100) / 100,
       content: Math.round(contentScore * 100) / 100,
       layout: Math.round(layoutScore * 100) / 100,
-      action: Math.round(actionScore * 100) / 100,
+      action: Math.round(actionScore * 100) / 100
     },
     questions: topQuestions,
-    summary,
+    summary
   };
 }
+export {
+  assessClarity
+};

package/intent/decomposer.js

@@ -1,216 +1,124 @@
-/**
- * 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 */
+import { classifyIntent } from "../domain-router.js";
 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,
+  /\beach\s+(with|having|containing)\b/i
 ];
-
-/** Layout containers that imply multi-section structure */
 const LAYOUT_KEYWORDS = {
-  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' },
+  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" }
 };
-
-/**
- * Analyze an intent for decomposition potential.
- *
- * @param {string} intent
- * @returns {{ shouldDecompose: boolean, subtasks: { intent: string, label: string }[], layout: { component: string, child: string } | null, original: string }}
- */
-export function decomposeIntent(intent) {
-  const trimmed = (intent || '').trim();
+function decomposeIntent(intent) {
+  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);
+      const sections2 = extractSections(trimmed);
+      if (sections2.length >= 2) {
+        const layout = detectLayout(trimmed, sections2.length);
         return {
           shouldDecompose: true,
-          subtasks: sections,
+          subtasks: sections2,
           layout,
-          original: trimmed,
+          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,
+      original: trimmed
     };
   }
-
-  // ── Short or simple intent → don't decompose ──
   return { shouldDecompose: false, subtasks: [], layout: null, original: trimmed };
 }
-
-/**
- * Extract individual section descriptions from an intent.
- *
- * @param {string} intent
- * @returns {{ intent: string, label: string }[]}
- */
 function extractSections(intent) {
-  // 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);
-
+  const payload = withMatch ? withMatch[1] ?? intent : intent;
+  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 baseContext = withMatch ? intent.slice(0, withMatch.index).trim() : "";
   const domain = classifyIntent(intent).domain;
-
-  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}`;
-
+  void domain;
+  return parts.map((part) => {
+    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.
- *
- * @param {string} intent
- * @param {number} sectionCount
- * @returns {{ component: string, child: string }}
- */
 function detectLayout(intent, sectionCount) {
   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' };
+  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' };
+  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' };
+  if (sectionCount <= 4) return { component: "Tabs", child: "Tab" };
+  return { component: "Grid", child: "Card" };
 }
-
-/**
- * Compose independently generated subtask results into a layout.
- *
- * @param {{ component: string, child: string }} layout
- * @param {{ label: string, messages: object[] }[]} subtaskResults
- * @returns {object[]} — A2UI messages for the composed layout
- */
-export function composeSubtasks(layout, subtaskResults) {
+function composeSubtasks(layout, subtaskResults) {
   const rootChildren = [];
   const allComponents = [];
   let idCounter = 0;
-
   for (const { label, messages } of subtaskResults) {
     const prefix = `s${++idCounter}`;
-    const subtaskComponents = messages?.[0]?.components || [];
-
-    // Re-prefix all component IDs to avoid collisions
-    const idMap = new Map();
-    const remapped = subtaskComponents.map(c => {
-      const newId = c.id === 'root' ? prefix : `${prefix}-${c.id}`;
+    const subtaskComponents = messages?.[0]?.components ?? [];
+    const idMap = /* @__PURE__ */ new Map();
+    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);
+        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
+    if (layout.child === "Tab") {
       const tabId = `${prefix}-tab`;
-      allComponents.push({ id: tabId, component: 'Tab', text: label, children: [prefix] });
+      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 = {
-    id: 'root',
+    id: "root",
     component: layout.component,
-    children: rootChildren,
+    children: rootChildren
   };
-
-  if (layout.component === 'Grid') {
-    root.columns = String(Math.min(subtaskResults.length, 4));
-    root.gap = 'md';
+  if (layout.component === "Grid") {
+    root["columns"] = String(Math.min(subtaskResults.length, 4));
+    root["gap"] = "md";
   }
-
   return [{
-    type: 'updateComponents',
-    surfaceId: 'default',
-    components: [root, ...allComponents],
+    type: "updateComponents",
+    surfaceId: "default",
+    components: [root, ...allComponents]
   }];
 }
-
 function capitalizeFirst(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
+export {
+  composeSubtasks,
+  decomposeIntent
+};

package/intent/decomposer.ts

@@ -97,7 +97,7 @@ export function decomposeIntent(intent: string): DecomposeResult {
 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;
+  const payload = withMatch ? (withMatch[1] ?? intent) : intent;
 
   // Split on connectors
   const parts = payload.split(SECTION_SPLITTERS)

package/intent/index.js

@@ -1,14 +1,18 @@
-/**
- * @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 { categorizeIntent } from './intent-categorizer.js';
-export { isConversational } from './intent-gate.js';
-export { analyzePrompt } from './prompt-analyzer.js';
-export { decomposeIntent, composeSubtasks } from './decomposer.js';
-export { assessClarity } from './clarity.js';
+import { extractExpectations, verifyAlignment, checkIntentAlignment } from "./intent-alignment.js";
+import { categorizeIntent } from "./intent-categorizer.js";
+import { isConversational } from "./intent-gate.js";
+import { analyzePrompt, formatAnalysisForPrompt } from "./prompt-analyzer.js";
+import { decomposeIntent, composeSubtasks } from "./decomposer.js";
+import { assessClarity } from "./clarity.js";
+export {
+  analyzePrompt,
+  assessClarity,
+  categorizeIntent,
+  checkIntentAlignment,
+  composeSubtasks,
+  decomposeIntent,
+  extractExpectations,
+  formatAnalysisForPrompt,
+  isConversational,
+  verifyAlignment
+};