@adia-ai/a2ui-retrieval 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 _No pending changes._
 
+## [0.4.7] - 2026-05-12
+
+### Removed — `embedding/embedding-retriever.js` + `concept-mapper.js` retired (§72, the §65 carry-over)
+
+The pattern-embeddings retrieval surface — `embedding-retriever.js` and its sole consumer `concept-mapper.js` (dead since v0.4.6 §64 retired `pattern-library.js`) — has been deleted from `packages/a2ui/retrieval/`. Companion artifacts in `@adia-ai/a2ui-corpus` (`pattern-embeddings.json` data file + `./pattern-embeddings` subpath export) and repo-side (`scripts/build/embeddings.mjs` + `build:embeddings` / `build:embeddings:all` npm scripts) retired in the same arc.
+
+`embedding/index.js` no longer re-exports from `embedding-retriever.js`. The remaining surface: `embedding-provider.js` (provider abstraction over Voyage / OpenAI) + `chunk-embedding-retriever.js` (the canonical embedding-based retriever, scoped to chunks).
+
+### Changed — `intent/prompt-analyzer.js` `getVocab()` reads canonical catalog (§72)
+
+Migrated from `@adia-ai/a2ui-corpus/patterns/_components.json` (retired) to `@adia-ai/a2ui-corpus/catalog-a2ui_0_9.json` (the canonical v0.9 catalog). Vocabulary now built from `components[name].x-adiaui.synonyms.tags`. Same `displayList` + `allowedSet` output shape; no behavior change for downstream callers.
+
 ## [0.4.6] - 2026-05-12
 
 ### Changed — `pattern-library.js` retired, consumers migrate to `composition-library` (§64 multi-step, 2026-05-12)

package/embedding/index.js

@@ -1,7 +1,10 @@
 /**
- * @adia-ai/a2ui-retrieval/embedding — embedding-provider + retrievers surface.
+ * @adia-ai/a2ui-retrieval/embedding — embedding-provider + chunk retriever surface.
+ *
+ * Since §65 (v0.4.7), the legacy pattern-embedding retriever was retired
+ * along with its only consumer (concept-mapper.js, dead post-§64). The
+ * canonical retrieval surface post-§40 is chunk-embedding-retriever.
  */
 
 export * from './embedding-provider.js';
-export * from './embedding-retriever.js';
 export * from './chunk-embedding-retriever.js';

package/intent/prompt-analyzer.js

@@ -38,28 +38,36 @@
 let _vocab = null;
 async function getVocab() {
   if (_vocab) return _vocab;
-  let catalog = {};
+  let catalogJson = {};
   try {
     const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
     if (IS_NODE) {
       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');
-      // packages/a2ui/retrieval/intent → up 2 → packages/a2ui → corpus/patterns/_components.json
+      // Since §65 (v0.4.7), reads from canonical v0.9 catalog at
+      // corpus/catalog-a2ui_0_9.json (assembled from yamls). Previously read
+      // the hand-maintained corpus/patterns/_components.json retired in §65.
+      // packages/a2ui/retrieval/intent → up 2 → packages/a2ui → corpus/catalog-a2ui_0_9.json
       const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
-      const raw = await fs.readFile(path.join(__dirname, '../../corpus/patterns/_components.json'), 'utf8');
-      catalog = JSON.parse(raw);
+      const raw = await fs.readFile(path.join(__dirname, '../../corpus/catalog-a2ui_0_9.json'), 'utf8');
+      catalogJson = JSON.parse(raw);
     } else {
-      const resp = await fetch(new URL('../../corpus/patterns/_components.json', import.meta.url));
-      if (resp.ok) catalog = await resp.json();
+      const resp = await fetch(new URL('../../corpus/catalog-a2ui_0_9.json', import.meta.url));
+      if (resp.ok) catalogJson = await resp.json();
     }
   } catch { /* empty vocab — analyzer will still work, just unconstrained */ }
 
+  // Adapt v0.9 catalog shape: `components: {Name: {x-adiaui: {synonyms: {tags: [...]}}}}`
+  // → legacy `{Name: {aliases}}` shape this vocab builder expects.
+  const comps = catalogJson?.components || {};
   const displayList = [];
   const allowedSet = new Set();
-  for (const [name, data] of Object.entries(catalog)) {
+  for (const [name, def] of Object.entries(comps)) {
     allowedSet.add(name);
-    const aliases = Array.isArray(data?.aliases) ? data.aliases : [];
+    const ext = def?.['x-adiaui'] || {};
+    const syns = (ext.synonyms && typeof ext.synonyms === 'object') ? ext.synonyms : null;
+    const aliases = Array.isArray(syns?.tags) ? syns.tags : [];
     for (const a of aliases) allowedSet.add(a);
     displayList.push(aliases.length ? `${name} (also: ${aliases.join(', ')})` : name);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-retrieval",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "AdiaUI A2UI retrieval layer — catalog lookup, intent classification, domain routing, pattern + anti-pattern matching, clarity + context assembly. Consumed by the compose engine and any A2UI-protocol tooling that needs to reason about user intent against the catalog.",
   "type": "module",
   "main": "./index.js",

package/concept-mapper.js

@@ -1,127 +0,0 @@
-/**
- * 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/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/embedding/embedding-retriever.js

@@ -1,152 +0,0 @@
-/**
- * Embedding retriever — loads the build-time pattern embedding index and
- * scores a query against every pattern via cosine similarity.
- *
- * Index: packages/a2ui/corpus/pattern-embeddings.json (built by
- * scripts/build-embeddings.mjs). When missing or empty, the retriever is
- * effectively a no-op — callers see a scoreFor(name) of 0 and should fall
- * back to keyword-only ranking.
- *
- * Query embedding uses the same provider as the index (baked in at build),
- * so the query path also requires the provider's API key at runtime. If
- * the key is absent, the retriever exposes a `available()` probe returning
- * false and callers degrade gracefully.
- */
-
-import { detectProvider, cosine, voyage, openai } from './embedding-provider.js';
-
-const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
-
-let _index = null;
-let _indexByName = null;   // Map<string, Float32Array>
-let _loadPromise = null;
-let _embedFn = null;
-let _available = null;      // lazy, once the first probe runs
-
-async function _loadIndex() {
-  if (_index) return _index;
-  if (_loadPromise) return _loadPromise;
-  _loadPromise = (async () => {
-    try {
-      if (IS_NODE) {
-        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');
-        // Try the package-import path first (works under node_modules
-        // install layout — `@adia-ai/a2ui-corpus` exports
-        // `./pattern-embeddings`). Fall back to the relative source-tree
-        // path so a source-checkout monorepo without symlinked deps
-        // still resolves.
-        let p = null;
-        try {
-          const { createRequire } = await import(/* @vite-ignore */ 'node:module');
-          const require = createRequire(import.meta.url);
-          p = require.resolve('@adia-ai/a2ui-corpus/pattern-embeddings');
-        } catch {
-          const here = path.dirname(url.fileURLToPath(import.meta.url));
-          p = path.resolve(here, '../../corpus/pattern-embeddings.json');
-        }
-        const raw = await fs.readFile(p, 'utf8');
-        _index = JSON.parse(raw);
-      } else {
-        const url = new URL('../../corpus/pattern-embeddings.json', import.meta.url);
-        const res = await fetch(url).catch(() => null);
-        _index = res?.ok ? await res.json().catch(() => null) : null;
-      }
-    } catch {
-      _index = null;
-    }
-    if (_index?.patterns?.length) {
-      _indexByName = new Map();
-      for (const p of _index.patterns) {
-        if (p?.name && Array.isArray(p.vector)) {
-          _indexByName.set(p.name, Float32Array.from(p.vector));
-        }
-      }
-    }
-    return _index;
-  })();
-  return _loadPromise;
-}
-
-/** Resolve the embed function matching the index's provider. */
-function _resolveEmbed(providerName, model) {
-  // The index's recorded (provider, model) is the source of truth — query
-  // embeddings MUST be generated by the same model the corpus was indexed
-  // with. Cross-provider mixing produces meaningless cosine scores; even
-  // same-provider/different-model emits different-dim vectors which cosine()
-  // short-circuits to 0 — silent retrieval failure. Fail loud (warn + null)
-  // when the recorded provider's key is unset, instead of auto-picking a
-  // different provider that would silently corrupt similarity rankings.
-  // (See chunk-embedding-retriever.js for the parallel implementation.)
-  let fn = null;
-  if (providerName === 'voyage') fn = voyage({ model });
-  else if (providerName === 'openai') fn = openai({ model });
-  else {
-    // No provider recorded in index header (legacy index) — fall through.
-    const auto = detectProvider();
-    return auto?.embed || null;
-  }
-  if (!fn && typeof console !== 'undefined') {
-    console.warn(
-      `[embedding-retriever] index was built with provider=${providerName} model=${model}, ` +
-      `but the corresponding API key is not set. Embeddings will be unavailable; falling back ` +
-      `to keyword-only retrieval. Set the matching API key, or rebuild the index with the ` +
-      `available provider via \`npm run build:embeddings\`.`
-    );
-  }
-  return fn;
-}
-
-/**
- * True when both the index AND the matching provider's API key are available.
- * Callers use this to decide whether to include embedding scores in the blend.
- */
-export async function available() {
-  if (_available !== null) return _available;
-  const idx = await _loadIndex();
-  if (!idx || !idx.patterns?.length) { _available = false; return false; }
-  _embedFn = _resolveEmbed(idx.provider, idx.model);
-  _available = !!_embedFn;
-  return _available;
-}
-
-/**
- * Embed a query string and return a { patternName → cosineScore } map.
- * Returns an empty Map when unavailable (no index or no API key).
- *
- * @param {string} query — the user's intent (steelman or raw)
- * @returns {Promise<Map<string, number>>}
- */
-export async function scoreAll(query) {
-  if (!query || typeof query !== 'string') return new Map();
-  if (!(await available())) return new Map();
-
-  let qVec;
-  try {
-    const [v] = await _embedFn([query]);
-    qVec = v;
-  } catch (e) {
-    // Don't let a runtime embedding failure nuke retrieval — fall back cleanly.
-    if (typeof console !== 'undefined') console.warn('[embedding-retriever]', e.message);
-    return new Map();
-  }
-
-  const out = new Map();
-  for (const [name, vec] of _indexByName) {
-    out.set(name, cosine(qVec, vec));
-  }
-  return out;
-}
-
-/** Number of patterns in the index. Useful for logging/diagnostics. */
-export async function size() {
-  const idx = await _loadIndex();
-  return idx?.patterns?.length || 0;
-}
-
-/** Diagnostics: the provider/model the index was built with. */
-export async function providerInfo() {
-  const idx = await _loadIndex();
-  return idx ? { provider: idx.provider, model: idx.model, dims: idx.dims } : null;
-}