@adia-ai/a2ui-retrieval 0.0.1

package/component-entry.js

@@ -0,0 +1,80 @@
+/**
+ * ComponentEntry — Detail level serialization for catalog entries.
+ *
+ * Three progressive-disclosure levels:
+ *   Index    (~10 tokens):  { type, tag, category }
+ *   Summary  (~50 tokens):  index + { description, properties: [names] }
+ *   Reference (~200 tokens): summary + { properties: [full], slots, events, children, tokens }
+ */
+
+/** @typedef {'index' | 'summary' | 'reference'} DetailLevel */
+
+/**
+ * Serialize a component entry to the requested detail level.
+ *
+ * @param {object} entry — Full component entry from the catalog
+ * @param {DetailLevel} level — Detail level
+ * @returns {object} — Serialized entry at the requested level
+ */
+export function serializeEntry(entry, level = 'index') {
+  if (level === 'index') return serializeIndex(entry);
+  if (level === 'summary') return serializeSummary(entry);
+  return serializeReference(entry);
+}
+
+function serializeIndex(entry) {
+  return {
+    type: entry.type,
+    tag: entry.tag,
+    category: entry.category,
+  };
+}
+
+function serializeSummary(entry) {
+  const index = serializeIndex(entry);
+  const result = {
+    ...index,
+    description: entry.description || '',
+  };
+  if (entry.schema?.properties) {
+    result.properties = Object.keys(entry.schema.properties);
+  }
+  return result;
+}
+
+function serializeReference(entry) {
+  const summary = serializeSummary(entry);
+  const schema = entry.schema;
+  if (!schema) return summary;
+
+  const result = { ...summary };
+
+  // Full property definitions
+  if (schema.properties) {
+    result.properties = Object.entries(schema.properties).map(([name, def]) => ({
+      name,
+      type: def.type,
+      ...(def.enum ? { enum: def.enum } : {}),
+      ...(def.default !== undefined ? { default: def.default } : {}),
+      ...(def.description ? { description: def.description } : {}),
+    }));
+  }
+
+  if (schema.slots && Object.keys(schema.slots).length > 0) {
+    result.slots = schema.slots;
+  }
+
+  if (schema.events && Object.keys(schema.events).length > 0) {
+    result.events = schema.events;
+  }
+
+  if (schema.children) {
+    result.children = schema.children;
+  }
+
+  if (schema.tokens) {
+    result.tokens = schema.tokens;
+  }
+
+  return result;
+}

package/concept-mapper.js

@@ -0,0 +1,127 @@
+/**
+ * Concept Mapper — re-rank corpus patterns using analyzer signals.
+ *
+ * The existing `searchBlocks(query)` does pure keyword matching against
+ * pattern.keywords + pattern.description. That's necessary but not sufficient
+ * — a prompt about a "user dashboard" might lexically prefer a pattern named
+ * "user-profile" over "admin-dashboard" even though the latter is a better
+ * conceptual match.
+ *
+ * This module takes the structured analysis produced by prompt-analyzer.js
+ * and combines THREE signals into a final pattern score:
+ *
+ *   lexical:   the original keyword score from searchBlocks (steelman → keywords)
+ *   conceptual: overlap between analysis.concepts and pattern.tags.purpose
+ *   structural: overlap between analysis.impliedComponents and the set of
+ *               component types referenced in the pattern's template
+ *
+ * Patterns missing tags fall back to lexical-only scoring (graceful
+ * degradation; the older patterns in the corpus haven't all been retagged).
+ */
+
+import { searchBlocks } from '../engine/reference.js';
+import { scoreAll as embeddingScoreAll, available as embeddingAvailable } from './embedding-retriever.js';
+
+/** Weights for the combined score. Tuned to keep lexical authoritative
+ *  but let strong conceptual+structural+semantic signals override marginal
+ *  lexical differences. Embedding semantic similarity scores are in [-1, 1]
+ *  so their weight is high (30) — cosine of 0.8 → 24 points, comparable to
+ *  3 concept-tag hits. Tuned to fix the "product card → ticket form"
+ *  keyword-collision class of failure. */
+const WEIGHTS = {
+  lexical:    1.0,   // baseline
+  conceptual: 8,     // each matching concept-tag adds 8 points
+  structural: 1.5,   // each matching component-signature element adds 1.5 points
+  semantic:   30,    // cosine(query_embedding, pattern_embedding) × 30
+};
+
+/**
+ * Re-rank pattern matches using the analyzer's structured signals.
+ *
+ * @param {object} opts
+ * @param {object} opts.analysis — Output of analyzePrompt() from prompt-analyzer.js
+ * @param {string} [opts.domain] — Domain hint (passed through to searchBlocks)
+ * @param {number} [opts.limit=10] — Cap on returned results
+ * @returns {Array<{ pattern: object, score: number, breakdown: object }>}
+ *          Patterns ranked by combined score, descending.
+ */
+export async function rankByConceptAndSignature({ analysis, domain, limit = 10 }) {
+  if (!analysis) return [];
+
+  // Use the steelmanned brief for lexical search — it's denser than the raw
+  // intent and surfaces keywords the user implied but didn't say.
+  const query = analysis.steelman || analysis.raw;
+  const lexicalHits = searchBlocks(query, { domain });
+  if (!Array.isArray(lexicalHits) || lexicalHits.length === 0) return [];
+
+  const conceptSet = new Set((analysis.concepts || []).map(c => c.toLowerCase()));
+  const componentSet = new Set(analysis.impliedComponents || []);
+
+  // Semantic channel — only run when the index + provider are both available.
+  // Returns a Map<patternName, cosineSim>. Silent no-op otherwise.
+  const semanticMap = (await embeddingAvailable())
+    ? await embeddingScoreAll(query)
+    : new Map();
+
+  const ranked = lexicalHits.map(hit => {
+    // Different shapes of hit objects in the corpus — be permissive.
+    const pattern = hit.pattern || hit;
+    const lexicalScore = hit.score ?? hit.confidence ?? 1;
+
+    const conceptScore = scoreConceptOverlap(pattern, conceptSet);
+    const structuralScore = scoreSignatureOverlap(pattern, componentSet);
+    // Clamp negative cosines to 0 — no retrieval value in "most anti-similar".
+    const semanticScore = Math.max(0, semanticMap.get(pattern.name) || 0);
+
+    const combined =
+      WEIGHTS.lexical * lexicalScore +
+      WEIGHTS.conceptual * conceptScore +
+      WEIGHTS.structural * structuralScore +
+      WEIGHTS.semantic * semanticScore;
+
+    return {
+      pattern,
+      score: combined,
+      breakdown: {
+        lexical:    +(WEIGHTS.lexical * lexicalScore).toFixed(2),
+        conceptual: +(WEIGHTS.conceptual * conceptScore).toFixed(2),
+        structural: +(WEIGHTS.structural * structuralScore).toFixed(2),
+        semantic:   +(WEIGHTS.semantic * semanticScore).toFixed(2),
+      },
+    };
+  });
+
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked.slice(0, limit);
+}
+
+/** Count how many of the analysis concepts appear in the pattern's tag system. */
+function scoreConceptOverlap(pattern, conceptSet) {
+  if (!pattern || conceptSet.size === 0) return 0;
+  const tags = pattern.tags || {};
+  const flat = []
+    .concat(tags.purpose || [])
+    .concat(tags.layout || [])
+    .concat(tags.interaction || [])
+    .concat(pattern.keywords || [])
+    .map(t => String(t).toLowerCase());
+  let hits = 0;
+  for (const c of conceptSet) if (flat.includes(c)) hits++;
+  return hits;
+}
+
+/** Count how many of the implied components appear in the pattern's template. */
+function scoreSignatureOverlap(pattern, componentSet) {
+  if (!pattern || componentSet.size === 0) return 0;
+  const template = pattern.template;
+  if (!Array.isArray(template)) return 0;
+  // Build the pattern's component signature once per call; small templates
+  // mean the cost is negligible. Cache later if hot.
+  const sig = new Set();
+  for (const node of template) {
+    if (node && typeof node.component === 'string') sig.add(node.component);
+  }
+  let hits = 0;
+  for (const c of componentSet) if (sig.has(c)) hits++;
+  return hits;
+}

package/context-assembler.js

@@ -0,0 +1,168 @@
+/**
+ * Context Assembler — Progressive-disclosure context packaging with token budgets.
+ *
+ * Assembles context at 5 budget tiers, combining component entries,
+ * domain-relevant patterns, and anti-patterns within token limits.
+ *
+ * Token estimation: ~1 token per 4 characters of JSON output.
+ */
+
+import { getCatalog, getComponentsByCategory } from './catalog.js';
+import { serializeEntry } from './component-entry.js';
+import { classifyIntent, getDomain } from './domain-router.js';
+import { getAntiPatterns } from './anti-patterns.js';
+import { searchPatterns, getAllPatterns } from './pattern-library.js';
+
+/** Token budget per tier */
+const TIER_BUDGETS = {
+  0: 500,
+  1: 2000,
+  2: 5000,
+  3: 10000,
+  4: 20000,
+};
+
+/**
+ * Estimate token count from a JavaScript value (serialized as JSON).
+ * @param {*} value
+ * @returns {number}
+ */
+function estimateTokens(value) {
+  const json = JSON.stringify(value);
+  return Math.ceil(json.length / 4);
+}
+
+/**
+ * Assemble context for a given intent at a specific budget tier.
+ *
+ * @param {object} options
+ * @param {string} [options.intent] — Natural language intent (used for domain classification)
+ * @param {number} [options.tier=1] — Budget tier (0-4)
+ * @param {string} [options.domain] — Override domain (skips classification)
+ * @returns {{ components: object[], patterns: object[], antiPatterns: object[], domain: object, estimatedTokens: number }}
+ */
+export async function assembleContext({ intent = '', tier = 1, domain: overrideDomain } = {}) {
+  const budget = TIER_BUDGETS[tier] ?? TIER_BUDGETS[1];
+
+  // Classify domain
+  const classification = intent ? classifyIntent(intent) : null;
+  const domainName = overrideDomain || classification?.domain || 'layout';
+  const domainConfig = getDomain(domainName);
+
+  let usedTokens = 0;
+  const result = {
+    components: [],
+    patterns: [],
+    antiPatterns: [],
+    domain: {
+      name: domainName,
+      confidence: classification?.confidence ?? 1,
+      matchedSignals: classification?.matchedSignals ?? [],
+    },
+    estimatedTokens: 0,
+  };
+
+  // Account for domain metadata
+  usedTokens += estimateTokens(result.domain);
+
+  const catalog = await getCatalog();
+
+  // ── Tier 0: Component index only ──
+  if (tier === 0) {
+    for (const entry of catalog.entries.values()) {
+      const serialized = serializeEntry(entry, 'index');
+      const cost = estimateTokens(serialized);
+      if (usedTokens + cost > budget) break;
+      result.components.push(serialized);
+      usedTokens += cost;
+    }
+    result.estimatedTokens = usedTokens;
+    return result;
+  }
+
+  // ── Tier 1+: Domain-relevant summaries first ──
+  const domainComponents = domainConfig?.components || [];
+  const addedTypes = new Set();
+
+  // Add domain-relevant components as summaries
+  for (const typeName of domainComponents) {
+    const entry = findEntry(catalog, typeName);
+    if (!entry) continue;
+
+    const level = tier >= 2 ? 'reference' : 'summary';
+    const serialized = serializeEntry(entry, level);
+    const cost = estimateTokens(serialized);
+    if (usedTokens + cost > budget) break;
+
+    result.components.push(serialized);
+    addedTypes.add(entry.type);
+    usedTokens += cost;
+  }
+
+  // ── Tier 2+: Fill remaining budget with other components ──
+  if (tier >= 2) {
+    for (const entry of catalog.entries.values()) {
+      if (addedTypes.has(entry.type)) continue;
+
+      const level = tier >= 3 ? 'reference' : 'summary';
+      const serialized = serializeEntry(entry, level);
+      const cost = estimateTokens(serialized);
+      if (usedTokens + cost > budget) break;
+
+      result.components.push(serialized);
+      addedTypes.add(entry.type);
+      usedTokens += cost;
+    }
+  }
+
+  // ── Tier 1+: Add anti-patterns ──
+  if (tier >= 1) {
+    const ap = getAntiPatterns();
+    const apCost = estimateTokens(ap);
+    if (usedTokens + apCost <= budget) {
+      result.antiPatterns = ap;
+      usedTokens += apCost;
+    }
+  }
+
+  // ── Tier 3+: Add matching patterns ──
+  if (tier >= 3) {
+    const matchedPatterns = intent
+      ? searchPatterns(intent)
+      : getAllPatterns().filter(p => p.domain === domainName);
+
+    for (const pattern of matchedPatterns) {
+      const cost = estimateTokens(pattern);
+      if (usedTokens + cost > budget) break;
+      result.patterns.push(pattern);
+      usedTokens += cost;
+    }
+  }
+
+  // ── Tier 4: Full exploration — add remaining patterns ──
+  if (tier >= 4) {
+    const addedPatterns = new Set(result.patterns.map(p => p.name));
+    for (const pattern of getAllPatterns()) {
+      if (addedPatterns.has(pattern.name)) continue;
+      const cost = estimateTokens(pattern);
+      if (usedTokens + cost > budget) break;
+      result.patterns.push(pattern);
+      usedTokens += cost;
+    }
+  }
+
+  result.estimatedTokens = usedTokens;
+  return result;
+}
+
+/**
+ * Find an entry in the catalog by type name.
+ */
+function findEntry(catalog, typeName) {
+  if (catalog.entries.has(typeName)) return catalog.entries.get(typeName);
+  // Search by tag fallback
+  for (const entry of catalog.entries.values()) {
+    if (entry.type === typeName) return entry;
+  }
+  return null;
+}

package/decomposer.js

@@ -0,0 +1,216 @@
+/**
+ * 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 = {
+  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();
+  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.
+ *
+ * @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);
+
+  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;
+
+  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.
+ *
+ * @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' };
+  }
+
+  // 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' };
+}
+
+/**
+ * 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) {
+  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}`;
+      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 = {
+    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) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}