@adia-ai/a2ui-retrieval 0.0.1

package/pattern-library.js

@@ -0,0 +1,659 @@
+/**
+ * Pattern Library — Loads named reference patterns from JSON files on disk.
+ *
+ * Replaces the former monolithic Map with a lazy-loading corpus that reads
+ * from packages/a2ui/compose/patterns/{domain}/*.json at runtime.
+ *
+ * Works in both Node.js (readdir/readFile) and the browser (Vite import.meta.glob).
+ */
+
+// ── Environment detection ────────────────────────────────────────────────
+const IS_NODE =
+  typeof process !== 'undefined' &&
+  typeof process.versions?.node === 'string';
+
+// ── State ────────────────────────────────────────────────────────────────
+const patterns = new Map();
+let _loaded = false;
+let _loadPromise = null;
+let _synonyms = new Map(); // populated from _taxonomy.json
+const _componentData = new Map(); // populated from .a2ui.json files
+
+// ── Browser glob (Vite) ──────────────────────────────────────────────────
+// Vite resolves this at build time; at runtime in Node the variable is unused.
+let _globModules = null;
+let _globA2UIModules = null;
+if (!IS_NODE) {
+  try {
+    _globModules = import.meta.glob('../corpus/patterns/**/*.json', {
+      query: '?raw',
+      import: 'default',
+    });
+  } catch {
+    // Not in a Vite context — will fall back to empty corpus
+  }
+  try {
+    _globA2UIModules = import.meta.glob('../../web-components/components/**/*.a2ui.json', {
+      query: '?raw',
+      import: 'default',
+    });
+  } catch {
+    // Not in a Vite context — no component data
+  }
+}
+
+// ── Corpus loader ────────────────────────────────────────────────────────
+
+/**
+ * Load all pattern JSON files into the in-memory Map.
+ * Called lazily on first access. Safe to call multiple times (idempotent).
+ */
+export async function loadCorpus() {
+  if (_loaded) return;
+  if (_loadPromise) return _loadPromise;
+  _loadPromise = _doLoad();
+  await _loadPromise;
+  _loaded = true;
+}
+
+async function _doLoad() {
+  if (IS_NODE) {
+    await _loadNode();
+  } else {
+    await _loadBrowser();
+  }
+}
+
+/** Skip files whose basename starts with _ (index, domain, schema, taxonomy, components). */
+function _shouldSkip(basename) {
+  return basename.startsWith('_');
+}
+
+// ── .a2ui.json processing ────────────────────────────────────────────────
+
+/**
+ * Process a parsed .a2ui.json object: register examples as patterns,
+ * merge synonyms, and store the component data.
+ */
+function _processA2UIData(data) {
+  // v0.9 shape (YAML-generated, produced by scripts/build-components.mjs):
+  //   top-level:  `title` = PascalCase component name, JSON Schema fields
+  //   x-adiaui:   retrieval signals (keywords, synonyms, examples, related, category)
+  const ext      = data?.['x-adiaui'] || {};
+  const compName = data?.title;
+  if (!compName) return;
+
+  const category = ext.category || 'layout';
+  const keywords = ext.keywords || [];
+  const synonyms = ext.synonyms || null;
+  const related  = ext.related  || [];
+  const examples = Array.isArray(ext.examples) ? ext.examples : [];
+
+  _componentData.set(compName, data);
+
+  if (synonyms && typeof synonyms === 'object') {
+    for (const [term, syns] of Object.entries(synonyms)) {
+      const existing = _synonyms.get(term) || [];
+      const merged = [...new Set([...existing, ...syns])];
+      _synonyms.set(term, merged);
+    }
+  }
+
+  for (const example of examples) {
+    if (!example.name) continue;
+    // Example payload may be a structured template array OR a JSON string
+    // under `a2ui`. Normalize to an array.
+    let template = null;
+    if (Array.isArray(example.template)) {
+      template = example.template;
+    } else if (typeof example.a2ui === 'string') {
+      try {
+        const parsed = JSON.parse(example.a2ui);
+        template = Array.isArray(parsed) ? parsed : [parsed];
+      } catch { /* skip malformed */ }
+    }
+    if (!Array.isArray(template) || template.length === 0) continue;
+    registerPattern({
+      name: example.name,
+      description: example.description || `${compName} example`,
+      domain: category,
+      template,
+      tags: keywords,
+      keywords,
+      related,
+      source: `a2ui:${compName}`,
+    }, { replace: false });
+  }
+}
+
+// ── Node.js loader ───────────────────────────────────────────────────────
+async function _loadNode() {
+  // Dynamic import so Vite never tries to bundle these
+  const fs = await import(/* @vite-ignore */ 'node:fs/promises');
+  const path = await import(/* @vite-ignore */ 'node:path');
+  const url = await import(/* @vite-ignore */ 'node:url');
+
+  const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+  const patternsDir = path.resolve(__dirname, '../corpus/patterns');
+
+  // Load _taxonomy.json for synonyms
+  try {
+    const taxRaw = await fs.readFile(path.join(patternsDir, '_taxonomy.json'), 'utf8');
+    _parseTaxonomy(JSON.parse(taxRaw));
+  } catch {
+    // _taxonomy.json not present — synonyms stay empty
+  }
+
+  // Walk domain directories
+  let entries;
+  try {
+    entries = await fs.readdir(patternsDir, { withFileTypes: true });
+  } catch {
+    return; // patterns dir doesn't exist yet
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const domainDir = path.join(patternsDir, entry.name);
+    const files = await fs.readdir(domainDir);
+
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      if (_shouldSkip(file)) continue;
+
+      try {
+        const raw = await fs.readFile(path.join(domainDir, file), 'utf8');
+        const pattern = JSON.parse(raw);
+        if (pattern.name) {
+          // Normalize tags: ensure .tags is always a flat string array for search compatibility
+          if (pattern.tags && !Array.isArray(pattern.tags)) {
+            pattern.tagsMeta = pattern.tags;
+            pattern.tags = pattern.keywords || [];
+          }
+          // Derive components from template (source of truth)
+          pattern.components = [...new Set(pattern.template.map(n => n.component).filter(Boolean))];
+          patterns.set(pattern.name, pattern);
+        }
+      } catch {
+        // Malformed JSON — skip silently
+      }
+    }
+  }
+
+  // ── Scan web-components/components/ for .a2ui.json files ──────────────
+  // .a2ui.json sidecars live with their components (packages/web-components/components/).
+  // These are hand-authored component contracts — part of the component library,
+  // not the training corpus — so they stay in web-components.
+  const componentsDir = path.resolve(__dirname, '..', '..', 'web-components', 'components');
+  try {
+    const compEntries = await fs.readdir(componentsDir, { withFileTypes: true });
+    for (const compEntry of compEntries) {
+      if (!compEntry.isDirectory()) continue;
+      const a2uiPath = path.join(componentsDir, compEntry.name, `${compEntry.name}.a2ui.json`);
+      try {
+        const raw = await fs.readFile(a2uiPath, 'utf8');
+        const data = JSON.parse(raw);
+        _processA2UIData(data);
+      } catch {
+        // No .a2ui.json for this component — skip
+      }
+    }
+  } catch {
+    // components dir doesn't exist — skip
+  }
+}
+
+
+// ── Browser (Vite) loader ────────────────────────────────────────────────
+async function _loadBrowser() {
+  if (!_globModules) return;
+
+  for (const [filePath, loader] of Object.entries(_globModules)) {
+    // filePath looks like ../patterns/data/dashboard.json
+    const basename = filePath.split('/').pop();
+    if (_shouldSkip(basename)) {
+      // But still load _taxonomy.json for synonyms
+      if (basename === '_taxonomy.json') {
+        try {
+          const raw = await loader();
+          _parseTaxonomy(JSON.parse(raw));
+        } catch { /* ignore */ }
+      }
+      continue;
+    }
+
+    try {
+      const raw = await loader();
+      const pattern = JSON.parse(raw);
+      if (pattern.name) {
+          if (pattern.tags && !Array.isArray(pattern.tags)) {
+            pattern.tagsMeta = pattern.tags;
+            pattern.tags = pattern.keywords || [];
+          }
+          // Derive components from template (source of truth)
+          pattern.components = [...new Set(pattern.template.map(n => n.component).filter(Boolean))];
+          patterns.set(pattern.name, pattern);
+        }
+    } catch {
+      // skip malformed
+    }
+  }
+
+  // ── Load .a2ui.json files from components/ (Vite glob) ─────────────────
+  if (_globA2UIModules) {
+    for (const [filePath, loader] of Object.entries(_globA2UIModules)) {
+      try {
+        const raw = await loader();
+        const data = JSON.parse(raw);
+        _processA2UIData(data);
+      } catch {
+        // skip malformed .a2ui.json
+      }
+    }
+  }
+}
+
+// ── Taxonomy / synonym parsing ───────────────────────────────────────────
+
+function _parseTaxonomy(tax) {
+  if (!tax?.synonyms) return;
+  // Expected format: { synonyms: { "term": ["syn1", "syn2", ...], ... } }
+  _synonyms = new Map(Object.entries(tax.synonyms));
+}
+
+// ── Lazy init guard ──────────────────────────────────────────────────────
+async function _ensureLoaded() {
+  if (!_loaded) await loadCorpus();
+}
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+// ── Eager load on module import ──────────────────────────────────────
+// Top-level await ensures patterns are available before any export is called.
+// This keeps getAllPatterns/searchPatterns/registerPattern synchronous for callers.
+await loadCorpus();
+
+// ── Public API (synchronous after top-level load) ─────────────────────
+
+/**
+ * Get a pattern by name.
+ * @param {string} name
+ * @returns {object|null}
+ */
+export function getPattern(name) {
+  return patterns.get(name) || null;
+}
+
+/**
+ * Get .a2ui.json data for a named component.
+ * @param {string} name — Component name (e.g., "Swiper")
+ * @returns {object|null}
+ */
+export function getComponentData(name) {
+  return _componentData.get(name) || null;
+}
+
+/**
+ * Get all loaded .a2ui.json component data.
+ * @returns {Object.<string, object>} — Map of component name → .a2ui.json data
+ */
+export function getAllComponentData() {
+  return Object.fromEntries(_componentData);
+}
+
+/**
+ * Get all registered patterns.
+ * @returns {object[]}
+ */
+export function getAllPatterns() {
+  return [...patterns.values()];
+}
+
+/**
+ * Register a new pattern at runtime.
+ * @param {object} pattern — Must have { name, template }
+ * @param {object} [opts] — { replace: boolean }
+ * @returns {boolean}
+ */
+export function registerPattern(pattern, opts = {}) {
+  if (!pattern?.name || !pattern?.template || !Array.isArray(pattern.template)) return false;
+  if (patterns.has(pattern.name) && !opts.replace) return false;
+  const template = pattern.template;
+  patterns.set(pattern.name, {
+    name: pattern.name,
+    description: pattern.description || '',
+    domain: pattern.domain || 'layout',
+    components: [...new Set(template.map(c => c.component).filter(Boolean))],
+    tags: Array.isArray(pattern.tags) ? pattern.tags : pattern.keywords || [],
+    tagsMeta: (!Array.isArray(pattern.tags) && pattern.tags) ? pattern.tags : null,
+    keywords: pattern.keywords || [],
+    source: pattern.source || null,
+    template,
+    styling: pattern.styling || null,
+    wiring: pattern.wiring || null,
+    related: pattern.related || [],
+    primitive: pattern.primitive || false,
+  });
+  return true;
+}
+
+// ── Search ───────────────────────────────────────────────────────────────
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+  'of', 'with', 'by', 'from', 'as', 'is', 'was', 'are', 'be', 'it',
+  'that', 'this', 'my', 'its', 'has', 'have', 'do', 'does', 'did',
+  'i', 'me', 'we', 'you', 'he', 'she', 'them', 'so', 'if', 'not',
+  'no', 'can', 'will', 'just', 'should', 'would', 'could', 'about',
+  'like', 'make', 'show', 'want', 'need', 'give', 'use', 'some',
+]);
+
+/**
+ * Search patterns by query string. Matches against name, description,
+ * domain, components, and taxonomy synonyms.
+ *
+ * @param {string} query — Search query
+ * @param {object} [opts]
+ * @param {string} [opts.domain] — Boost patterns matching this domain
+ * @returns {Promise<object[]>} — Matching patterns sorted by relevance
+ */
+export function searchPatterns(query, { domain } = {}) {
+
+  const words = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(w => w.length > 1 && !STOP_WORDS.has(w));
+
+  if (!words.length) return [...patterns.values()];
+
+  const results = [];
+
+  for (const pattern of patterns.values()) {
+    let score = 0;
+    const name = pattern.name.toLowerCase();
+    const desc = (pattern.description || '').toLowerCase();
+    const tags = [
+      ...(pattern.keywords || []),
+      ...((pattern.tags?.purpose) || []),
+      ...((pattern.tags?.interaction) || []),
+    ].map(t => t.toLowerCase());
+    const comps = (pattern.components || []).map(c => c.toLowerCase());
+    let nameHits = 0;
+
+    for (const word of words) {
+      // Name match — strongest signal (+3)
+      if (name.includes(word)) { score += 3; nameHits++; }
+      // Description match (+2)
+      if (desc.includes(word)) score += 2;
+      // Domain match (+2)
+      if (pattern.domain && pattern.domain.toLowerCase().includes(word)) score += 2;
+      // Component match (+1)
+      if (comps.some(c => c.toLowerCase().includes(word))) score += 1;
+      // Tag/keyword exact match
+      if (tags.some(t => t === word)) score += 2;
+    }
+
+    // Synonym expansion from loaded taxonomy
+    score += synonymScore(words, pattern);
+
+    // Specificity bonus: reward patterns where query covers a large fraction of the name
+    if (nameHits > 0) {
+      const nameWords = name.split(/[-_\s]+/).filter(w => w.length > 1);
+      const coverage = nameHits / Math.max(nameWords.length, 1);
+      score += Math.round(coverage * 5);
+    }
+
+    // Domain boost: same-domain patterns get a bonus (+4)
+    if (domain && pattern.domain === domain) {
+      score += 4;
+    }
+
+    // Primitive penalty: demote single-component patterns for complex queries
+    if (pattern.primitive && words.length > 2) {
+      score -= 5;
+    }
+
+    // Require minimum score — lower threshold for short queries
+    const minScore = words.length === 1 ? 2 : 3;
+    if (score >= minScore) {
+      results.push({ ...pattern, _score: score });
+    }
+  }
+
+  results.sort((a, b) => b._score - a._score);
+  return results.map(({ _score, ...rest }) => rest);
+}
+
+// ── Synonym scoring ──────────────────────────────────────────────────────
+
+function synonymScore(words, pattern) {
+  if (_synonyms.size === 0) return 0;
+
+  let score = 0;
+  const name = pattern.name.toLowerCase();
+  const desc = (pattern.description || '').toLowerCase();
+  const comps = (pattern.components || []).map(c => c.toLowerCase());
+  const tags = [
+    ...(pattern.keywords || []),
+    ...((Array.isArray(pattern.tags) ? pattern.tags : pattern.tags?.purpose) || []),
+    ...((pattern.tags?.interaction) || []),
+  ].map(t => t.toLowerCase());
+
+  for (const word of words) {
+    const syns = _synonyms.get(word);
+    if (!syns) continue;
+    for (const syn of syns) {
+      // Synonym name match — nearly as strong as direct name match (+2.5)
+      if (name.includes(syn)) score += 2.5;
+      // Synonym description match (+1.5)
+      if (desc.includes(syn)) score += 1.5;
+      // Synonym component match (+1)
+      if (comps.some(c => c.includes(syn))) score += 1;
+      // Synonym tag/keyword match (+1.5)
+      if (tags.some(t => t === syn || t.includes(syn))) score += 1.5;
+    }
+  }
+  return score;
+}
+
+// ── Embedding blend ──────────────────────────────────────────────────────
+// Produce a fused ranking from keyword hits + semantic-similarity scores.
+//   - Keyword hits keep their order and gain a semantic bump.
+//   - New semantic hits (high cosine but no lexical overlap) are PROMOTED
+//     into the result set above a threshold. This is where "product card
+//     → product-pricing-card" wins over "ticket form" regardless of the
+//     keyword word "card" collision.
+//
+// Weights: keyword hits are normalized to [0, 1] then scaled 3×; semantic
+// scores sit in [0, 1] after the cosine clamp. Final score = keywordScaled +
+// 2 × semantic. Patterns below 0.30 semantic and with no lexical match are
+// dropped. Threshold picked to be recall-generous (we're ranking for LLM
+// grounding, not committing to a single answer).
+function _blendEmbedding(keywordHits, semanticMap, allPatterns) {
+  const SEM_PROMOTE_THRESHOLD = 0.30;
+  const SEM_WEIGHT = 2.0;
+
+  // Normalize keyword scores. Since searchPatterns strips _score before
+  // returning, we work with zero-based rank implying a linear boost.
+  const keywordByName = new Map();
+  for (let i = 0; i < keywordHits.length; i++) {
+    const p = keywordHits[i];
+    // Rank-based keyword signal: 1.0 at top, tapering to ~0.1 at 20th.
+    const rank = 1.0 - (i / Math.max(keywordHits.length, 20));
+    keywordByName.set(p.name, { pattern: p, keyword: Math.max(0.1, rank) });
+  }
+
+  // Collect semantic-only promotions (not in keyword hits but above threshold).
+  const promotions = [];
+  for (const [name, sem] of semanticMap) {
+    if (keywordByName.has(name)) continue;
+    if (sem < SEM_PROMOTE_THRESHOLD) continue;
+    const p = allPatterns.find(x => x.name === name);
+    if (p) promotions.push({ pattern: p, keyword: 0, semantic: sem });
+  }
+
+  // Blend scores: keyword + SEM_WEIGHT × semantic.
+  const blended = [];
+  for (const { pattern, keyword } of keywordByName.values()) {
+    const sem = Math.max(0, semanticMap.get(pattern.name) || 0);
+    blended.push({ pattern, score: keyword + SEM_WEIGHT * sem });
+  }
+  for (const { pattern, semantic } of promotions) {
+    blended.push({ pattern, score: SEM_WEIGHT * semantic });
+  }
+
+  blended.sort((a, b) => b.score - a.score);
+  return blended.map(b => b.pattern);
+}
+
+// ── Semantic search (LLM-powered) ────────────────────────────────────────
+
+const PATTERN_SEARCH_SYSTEM_PROMPT = `You are a AdiaUI pattern matching engine. Given a user query and a library of UI patterns, you identify which patterns are conceptually relevant — even if they don't share keywords.
+
+Output ONLY valid JSON. No explanation, no markdown.`;
+
+/**
+ * Semantic search using an LLM to find conceptually related patterns and
+ * optionally remix multiple patterns into a new composition.
+ *
+ * Falls back to keyword search if no LLM adapter is provided.
+ *
+ * @param {string} query — Natural language query
+ * @param {object} [options]
+ * @param {object} [options.llmAdapter] — LLM adapter with .complete()
+ * @param {boolean} [options.remix] — If true, ask LLM to compose a new pattern
+ * @returns {Promise<{ matches: object[], remix?: object }>}
+ */
+export async function semanticSearchPatterns(query, options = {}) {
+  const { llmAdapter, remix = false } = options;
+
+  // Keyword channel — always available, sub-ms, authoritative for lexical hits.
+  let keywordMatches = await searchPatterns(query);
+
+  // Embedding channel — blend when the build-time index + provider key are
+  // both present. Fixes the "product card → ticket form" class of failures
+  // where keyword collisions pick the wrong pattern. Graceful degradation:
+  // empty map → no effect, pipeline behaves exactly as pre-embedding.
+  try {
+    const { scoreAll, available } = await import('./embedding-retriever.js');
+    if (await available()) {
+      const semanticMap = await scoreAll(query);
+      if (semanticMap.size > 0) {
+        keywordMatches = _blendEmbedding(keywordMatches, semanticMap, getAllPatterns());
+      }
+    }
+  } catch { /* keep keyword-only path on any failure */ }
+
+  if (!llmAdapter) {
+    return { matches: keywordMatches };
+  }
+
+  // Build a compact pattern index for the LLM
+  const allPatterns = await getAllPatterns();
+  const index = allPatterns.map(p => ({
+    name: p.name,
+    description: p.description,
+    domain: p.domain,
+    components: p.components,
+  }));
+
+  const prompt = remix
+    ? buildRemixPrompt(query, index, keywordMatches)
+    : buildSearchPrompt(query, index, keywordMatches);
+
+  try {
+    const response = await llmAdapter.complete({
+      messages: [{ role: 'user', content: prompt }],
+      systemPrompt: PATTERN_SEARCH_SYSTEM_PROMPT,
+    });
+
+    const parsed = parseSearchResponse(response.content);
+
+    // Resolve matched pattern names to full pattern objects
+    const semanticMatches = (parsed.matches || [])
+      .map(name => patterns.get(name))
+      .filter(Boolean);
+
+    // Merge: keyword matches first (known good), then semantic additions
+    const seen = new Set(keywordMatches.map(p => p.name));
+    const merged = [...keywordMatches];
+    for (const p of semanticMatches) {
+      if (!seen.has(p.name)) {
+        seen.add(p.name);
+        merged.push(p);
+      }
+    }
+
+    const result = { matches: merged };
+
+    // If remix was requested and LLM produced one, include it
+    if (remix && parsed.remix) {
+      result.remix = parsed.remix;
+    }
+
+    return result;
+  } catch {
+    // LLM failed — return keyword results
+    return { matches: keywordMatches };
+  }
+}
+
+// ── LLM prompt builders ──────────────────────────────────────────────────
+
+function buildSearchPrompt(query, index, keywordMatches) {
+  const keywordNames = keywordMatches.map(p => p.name);
+  return `Query: "${query}"
+
+Available patterns:
+${JSON.stringify(index, null, 2)}
+
+Keyword matches already found: ${JSON.stringify(keywordNames)}
+
+Which additional patterns are conceptually relevant to this query? Consider:
+- Structural similarity (similar layout/composition)
+- Functional similarity (serves a similar purpose)
+- Component overlap (uses similar building blocks)
+
+Output: { "matches": ["pattern-name", ...], "reasoning": "brief explanation" }
+Only include patterns NOT already in keyword matches.`;
+}
+
+function buildRemixPrompt(query, index, keywordMatches) {
+  const topPatterns = keywordMatches.slice(0, 3).map(p => ({
+    name: p.name,
+    description: p.description,
+    template: p.template,
+  }));
+
+  return `Query: "${query}"
+
+Available patterns with templates:
+${JSON.stringify(topPatterns, null, 2)}
+
+All available patterns:
+${JSON.stringify(index, null, 2)}
+
+Create a new AdiaUI component tree that fulfills the query by remixing elements from the available patterns. The result should:
+1. Use the flat adjacency format: { id, component, children?, ...props }
+2. Root component must have id "root"
+3. Follow Card content model: Card > Header + Section > Column + Footer
+4. Use only registered AdiaUI types
+
+Output: { "matches": ["pattern-names-used"], "remix": { "name": "suggested-name", "description": "what this is", "components": [...flat adjacency list...] } }`;
+}
+
+function parseSearchResponse(content) {
+  if (!content) return { matches: [] };
+  let json = content.trim();
+  const fenceMatch = json.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+  if (fenceMatch) json = fenceMatch[1].trim();
+  try {
+    const parsed = JSON.parse(json);
+    return {
+      matches: Array.isArray(parsed.matches) ? parsed.matches : [],
+      remix: parsed.remix || null,
+    };
+  } catch {
+    return { matches: [] };
+  }
+}