@adia-ai/a2ui-compose 0.0.1

package/engines/zettel/fragment-library.js

@@ -0,0 +1,209 @@
+/**
+ * Fragment Library — zettel-style loader for A2UI fragments.
+ *
+ * Loads all /a2ui/fragments/**\/*.json into memory, builds a backlink graph,
+ * and exposes typed retrieval helpers. Fragments ARE A2UI chunks — the library
+ * preserves their flat-adjacency template verbatim.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const FRAGMENTS_ROOT = path.resolve(__dirname, '../../../corpus/fragments');
+const COMPOSITIONS_ROOT = path.resolve(__dirname, '../../../corpus/compositions');
+
+/** @type {Map<string, object>} */
+const fragments = new Map();
+/** @type {Map<string, object>} */
+const compositions = new Map();
+
+function walk(dir, cb) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(p, cb);
+    else if (entry.name.endsWith('.json') && !entry.name.startsWith('_')) cb(p);
+  }
+}
+
+export function loadAll() {
+  fragments.clear();
+  compositions.clear();
+
+  walk(FRAGMENTS_ROOT, (p) => {
+    const doc = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (doc.kind !== 'fragment') return;
+    doc._sourceFile = p;
+    fragments.set(doc.name, doc);
+  });
+
+  walk(COMPOSITIONS_ROOT, (p) => {
+    const doc = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (doc.kind !== 'composition') return;
+    doc._sourceFile = p;
+    compositions.set(doc.name, doc);
+  });
+
+  buildBacklinks();
+  return { fragmentCount: fragments.size, compositionCount: compositions.size };
+}
+
+/** Walk every composition and every fragment, populate `used_by` backlinks. */
+function buildBacklinks() {
+  for (const f of fragments.values()) {
+    f.links = f.links || {};
+    f.links.used_by = [];
+  }
+
+  // compositions -> fragments they reference
+  for (const comp of compositions.values()) {
+    for (const node of comp.template || []) {
+      if (node.$fragment) {
+        const frag = fragments.get(node.$fragment);
+        if (frag) frag.links.used_by.push({ type: 'composition', name: comp.name });
+      }
+    }
+  }
+
+  // fragments -> other fragments they embed (future: nested fragment refs)
+  for (const f of fragments.values()) {
+    for (const node of f.template || []) {
+      if (node.$fragment) {
+        const target = fragments.get(node.$fragment);
+        if (target) target.links.used_by.push({ type: 'fragment', name: f.name });
+      }
+    }
+  }
+}
+
+export function getFragment(name) { return fragments.get(name); }
+export function getComposition(name) { return compositions.get(name); }
+export function getAllFragments() { return [...fragments.values()]; }
+export function getAllCompositions() { return [...compositions.values()]; }
+
+/**
+ * Keyword search across fragments AND compositions.
+ *
+ * Ranking design (v2 — fixes false-positive matching):
+ *   1. Tokenize query, drop generic UI stop-words ("form", "page", "view"…)
+ *      so they can't be the sole evidence for a match.
+ *   2. Whole-word match, not substring — prevents "form" matching "login-form".
+ *   3. Require ≥2 content-token hits for compositions (they're concrete
+ *      templates — promiscuous matching is expensive). Fragments can match on 1
+ *      content token since they're meant to be widely reused.
+ *   4. Tiered weights: name hit > keyword hit > semantic_role hit > description.
+ *   5. Small leverage bias for fragments (reused fragments are more likely
+ *      relevant when multiple candidates tie).
+ */
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'of', 'to', 'in', 'on', 'at', 'for', 'with',
+  'form', 'forms', 'page', 'pages', 'view', 'views', 'screen', 'screens',
+  'ui', 'component', 'components', 'widget', 'widgets', 'block', 'blocks',
+  'section', 'sections', 'layout', 'layouts',
+]);
+
+function tokenize(str) {
+  return (str || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 2);
+}
+
+function contentTokens(str) {
+  return tokenize(str).filter((t) => !STOP_WORDS.has(t));
+}
+
+export function searchAll(query, { limit = 20 } = {}) {
+  const q = (query || '').trim();
+  if (!q) return [];
+  const queryTokens = tokenize(q);
+  const queryContent = queryTokens.filter((t) => !STOP_WORDS.has(t));
+
+  const scoreDoc = (doc, isComposition) => {
+    const nameTokens = new Set(tokenize(doc.name));
+    const roleTokens = new Set(tokenize(doc.semantic_role || ''));
+    const keywordTokens = new Set((doc.keywords || []).flatMap((k) => tokenize(k)));
+    const descTokens = new Set(tokenize(doc.description || ''));
+    const tagTokens = new Set(
+      Object.values(doc.tags || {}).flat().flatMap((v) => tokenize(String(v))),
+    );
+
+    let contentHits = 0; // distinct non-stop-word tokens that matched anywhere
+    let s = 0;
+    const contentMatched = new Set();
+
+    for (const t of queryTokens) {
+      const isStop = STOP_WORDS.has(t);
+      let matched = false;
+      if (nameTokens.has(t))    { s += isStop ? 1 : 12; matched = true; }
+      if (keywordTokens.has(t)) { s += isStop ? 1 : 8;  matched = true; }
+      if (roleTokens.has(t))    { s += isStop ? 1 : 6;  matched = true; }
+      if (tagTokens.has(t))     { s += isStop ? 0 : 3;  matched = true; }
+      if (descTokens.has(t))    { s += isStop ? 0 : 2;  matched = true; }
+      if (matched && !isStop) {
+        contentMatched.add(t);
+      }
+    }
+    contentHits = contentMatched.size;
+
+    // Gate: compositions normally require ≥2 content-token hits to avoid
+    // noisy matches. Exception: a direct name-token match (the query contains
+    // the composition's primary concept word, e.g. "weather" → weather-widget)
+    // is strong enough on its own.
+    const nameHit = queryTokens.some((t) => !STOP_WORDS.has(t) && nameTokens.has(t));
+    if (isComposition && contentHits < 2 && !nameHit) return 0;
+    // Fragments require ≥1 content-token hit — never match on stop-words alone.
+    if (!isComposition && contentHits < 1) return 0;
+
+    // Coverage bonus: more distinct content tokens matched = better match
+    s += contentHits * 3;
+
+    // Small leverage bias for fragments (reused ones slightly preferred on ties)
+    if (!isComposition && doc.metrics?.leverage) {
+      s += Math.min(doc.metrics.leverage / 20, 2);
+    }
+
+    return s;
+  };
+
+  const all = [
+    ...getAllFragments().map((d) => ({ doc: d, type: 'fragment' })),
+    ...getAllCompositions().map((d) => ({ doc: d, type: 'composition' })),
+  ];
+
+  return all
+    .map((x) => ({ ...x, score: scoreDoc(x.doc, x.type === 'composition') }))
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((x) => ({
+      type: x.type,
+      name: x.doc.name,
+      score: Math.round(x.score * 100) / 100,
+      description: x.doc.description,
+      semantic_role: x.doc.semantic_role,
+      domain: x.doc.domain,
+    }));
+}
+
+/** Return the full graph for inspection / visualization. */
+export function getGraph() {
+  return {
+    fragments: getAllFragments().map((f) => ({
+      name: f.name,
+      role: f.semantic_role,
+      uses_components: f.links?.uses_components || [],
+      used_by: f.links?.used_by || [],
+      leverage: f.metrics?.leverage || 0,
+    })),
+    compositions: getAllCompositions().map((c) => ({
+      name: c.name,
+      domain: c.domain,
+      uses_fragments: (c.template || [])
+        .filter((n) => n.$fragment)
+        .map((n) => n.$fragment),
+    })),
+  };
+}

package/engines/zettel/generate.js

@@ -0,0 +1,15 @@
+/**
+ * @adia-ai/a2ui-compose — zettel engine facade.
+ *
+ * Fragment-graph composition. Three reasoning layers:
+ *   1. Retrieval (always) — keyword-rank corpus, resolve top composition
+ *   2. LLM synthesis (when llmAdapter + weak retrieval) — compose a new
+ *      composition from fragments
+ *   3. Session-aware iteration (when sessionId + prior turns) — modify
+ *      existing canvas instead of regenerating
+ *
+ * The actual implementation is generator-adapter.js; this file is the
+ * spec-compliant entry point at engines/zettel/generate.js per §11.
+ */
+
+export { generateZettel as generate } from './generator-adapter.js';

package/engines/zettel/generator-adapter.js

@@ -0,0 +1,202 @@
+/**
+ * Generator adapter for zettel MCP — conforms to the eval harness contract:
+ *
+ *   generate({ intent, mode, llmAdapter, sessionId }) -> { messages, validation, strategy, ...extra }
+ *
+ * Three reasoning layers:
+ *   1. Retrieval (always available) — keyword-rank the corpus, resolve top composition.
+ *   2. LLM synthesis (when llmAdapter provided AND retrieval weak) — compose a new
+ *      composition from fragments, have the composer resolve it into A2UI messages.
+ *   3. Session-aware iteration (when sessionId provided AND prior turns exist) —
+ *      pass prior-turn history to the LLM so follow-ups ("add a button", "hydrate
+ *      with real images") modify the existing canvas instead of regenerating.
+ *
+ * Strategy labels in the return:
+ *   - composition-match          — fresh retrieval, strong match, emitted verbatim
+ *   - composition-synthesized    — fresh LLM composition (no prior turns)
+ *   - composition-iterated       — LLM modified prior turn's template
+ *   - fragment-candidates        — retrieval weak + no LLM, returning atoms only
+ *   - synthesis-failed           — LLM tried and failed validation
+ */
+import {
+  loadAll,
+  getComposition,
+  searchAll,
+} from './fragment-library.js';
+import { resolveComposition, templateToMessages } from './composer.js';
+import { synthesizeComposition } from './synthesizer.js';
+import {
+  recordTurn,
+  getTurns,
+  buildHistorySummary,
+} from './session-store.js';
+import { validateSchema } from '../../../validator/validator.js';
+
+let booted = false;
+function ensureBooted() {
+  if (!booted) {
+    loadAll();
+    booted = true;
+  }
+}
+
+// Retrieval score threshold — above this we trust the match and emit verbatim;
+// below, fall through to LLM synthesis (creative composition from fragments).
+// Calibrated on the 100-intent held-out set:
+//   strong matches: login-form=24 (exact), signup-form=27, chart-dashboard=48, pricing-tiers=54
+//   weak/false-positive matches: drop below 22 on off-topic queries
+// Raised from 22 → 40 (2026-04-19) so that only near-perfect retrievals play
+// verbatim; merely-good matches (login-form, signup-form) fall through to LLM
+// synthesis instead of being emitted as canned output. Tradeoff: more LLM calls
+// (slower, costlier) in exchange for compositional variety. The previous 22
+// threshold maximized verbatim-cache hits at the cost of repetitive output.
+const STRONG_MATCH_THRESHOLD = 40;
+
+function toUpdateComponentsMessages(template) {
+  return [{
+    type: 'updateComponents',
+    components: template.map((n) => {
+      const {
+        id, component, children,
+        $fragment, bindings,
+        prependChildren, appendChildren,
+        ...rest
+      } = n;
+      return { id, component, children: children || [], ...rest };
+    }),
+  }];
+}
+
+export async function generateZettel({ intent, mode = 'instant', llmAdapter = null, sessionId = null } = {}) {
+  ensureBooted();
+
+  // ── Session-aware iteration (turn > 1) ──
+  // If we have prior turns AND an LLM, the user is almost certainly modifying
+  // the existing canvas — NEVER pick a fresh retrieved composition. Go straight
+  // to synthesis with history context. This is what makes follow-ups work.
+  const priorTurns = sessionId ? getTurns(sessionId) : [];
+  const hasHistory = priorTurns.length > 0;
+
+  if (hasHistory && llmAdapter) {
+    try {
+      const historySummary = buildHistorySummary(sessionId, 3);
+      const synth = await synthesizeComposition({ intent, llmAdapter, historySummary });
+      const validation = validateSchema(synth.messages, { intent });
+      const fragments = (synth.template || []).filter((n) => n.$fragment).map((n) => n.$fragment);
+      recordTurn(sessionId, {
+        intent,
+        messages: synth.messages,
+        template: synth.template,
+        composition: null,
+        strategy: 'composition-iterated',
+        fragments,
+        validation,
+      });
+      return {
+        messages: synth.messages,
+        validation,
+        strategy: 'composition-iterated',
+        retrieval: { hit: false, rank: null, candidate: null, reason: `iteration on turn ${priorTurns.length + 1}` },
+        composition: null,
+        fragments_used: fragments,
+        synthesized_template: synth.template,
+        synthesis: synth.synthesis,
+        sessionTurns: priorTurns.length + 1,
+      };
+    } catch (err) {
+      // If iteration synthesis fails, fall through to the normal path. Record
+      // the failure so the next turn can see we tried.
+      console.error('[zettel] iteration synthesis failed:', err.message);
+    }
+  }
+
+  const hits = searchAll(intent, { limit: 5 });
+  const composition = hits.find((h) => h.type === 'composition');
+  const strongMatch = composition && composition.score >= STRONG_MATCH_THRESHOLD;
+
+  // ── Strong retrieval match: emit verbatim (turn 1 only — iteration branch above handles repeats) ──
+  if (strongMatch) {
+    const comp = getComposition(composition.name);
+    const template = resolveComposition(comp);
+    const messages = toUpdateComponentsMessages(template);
+    const validation = validateSchema(messages, { intent });
+    const rank = hits.findIndex((h) => h.type === 'composition' && h.name === composition.name) + 1;
+    const fragments = (comp.template || []).filter((n) => n.$fragment).map((n) => n.$fragment);
+    recordTurn(sessionId, {
+      intent,
+      messages,
+      template: comp.template,
+      composition: composition.name,
+      strategy: 'composition-match',
+      fragments,
+      validation,
+    });
+    return {
+      messages,
+      validation,
+      strategy: 'composition-match',
+      retrieval: { hit: true, rank, candidate: composition.name },
+      composition: composition.name,
+      retrievalScore: composition.score,
+      fragments_used: fragments,
+      candidates: hits,
+      sessionTurns: priorTurns.length + 1,
+    };
+  }
+
+  // ── Weak/no retrieval: try LLM synthesis if available (fresh, no history) ──
+  if (llmAdapter && mode !== 'instant-only') {
+    try {
+      const synth = await synthesizeComposition({ intent, llmAdapter });
+      const validation = validateSchema(synth.messages, { intent });
+      const fragments = (synth.template || []).filter((n) => n.$fragment).map((n) => n.$fragment);
+      recordTurn(sessionId, {
+        intent,
+        messages: synth.messages,
+        template: synth.template,
+        composition: null,
+        strategy: 'composition-synthesized',
+        fragments,
+        validation,
+      });
+      return {
+        messages: synth.messages,
+        validation,
+        strategy: 'composition-synthesized',
+        retrieval: {
+          hit: false,
+          rank: composition ? hits.findIndex((h) => h.type === 'composition' && h.name === composition.name) + 1 : null,
+          candidate: composition?.name ?? null,
+          reason: composition ? `top score ${composition.score} below threshold ${STRONG_MATCH_THRESHOLD}` : 'no composition retrieved',
+        },
+        composition: null,
+        fragments_used: fragments,
+        synthesized_template: synth.template,
+        synthesis: synth.synthesis,
+        candidates: hits,
+        sessionTurns: priorTurns.length + 1,
+      };
+    } catch (err) {
+      return {
+        messages: [],
+        validation: { score: 0 },
+        strategy: 'synthesis-failed',
+        retrieval: { hit: false, rank: null, candidate: hits[0]?.name ?? null },
+        candidates: hits,
+        error: err.message,
+      };
+    }
+  }
+
+  // ── No LLM, no strong match: return atoms for downstream assembly ──
+  return {
+    messages: [],
+    validation: { score: 0 },
+    strategy: 'fragment-candidates',
+    retrieval: { hit: false, rank: null, candidate: hits[0]?.name ?? null },
+    candidates: hits,
+  };
+}
+
+// Re-export session management so server.js / MCP tools can reset a session
+export { clearSession, getTurns, getDrift } from './session-store.js';

package/engines/zettel/session-store.js

@@ -0,0 +1,121 @@
+/**
+ * Zettel session store — multi-turn artifact tracking for the fragment-graph engine.
+ *
+ * Wraps the shared ArtifactStore to record every zettel turn:
+ *   - the user intent
+ *   - the composition that was retrieved OR synthesized
+ *   - the resolved A2UI messages
+ *   - the fragments that were used
+ *   - strategy (composition-match | composition-synthesized)
+ *
+ * Subsequent turns can read this history and feed it to the LLM so that
+ * "hydrate with real images" refers back to the previous "grid of images"
+ * instead of being generated in isolation.
+ *
+ * Sessions are keyed by an opaque `sessionId` minted by the caller. The store
+ * is in-memory — survives for the lifetime of the proxy process, cleared on
+ * restart. Good enough for a dev server; a persistent store is a later phase.
+ */
+
+import { ArtifactStore } from '../../engine/artifacts.js';
+
+const store = new ArtifactStore();
+
+/**
+ * Record a zettel turn.
+ *
+ * @param {string} sessionId
+ * @param {object} turn
+ * @param {string} turn.intent           — user's text for this turn
+ * @param {object[]} turn.messages       — resolved A2UI messages
+ * @param {object[]} [turn.template]     — the composition template (with $fragment refs)
+ * @param {string} [turn.composition]    — retrieved composition name (null if synthesized)
+ * @param {string} turn.strategy         — composition-match | composition-synthesized | …
+ * @param {string[]} [turn.fragments]    — fragment names used
+ * @param {object} [turn.validation]     — validator result
+ */
+export function recordTurn(sessionId, { intent, messages, template, composition, strategy, fragments, validation }) {
+  if (!sessionId) return;
+  store.record(sessionId, {
+    intent,
+    messages,
+    summary: composition
+      ? `${strategy} → ${composition}`
+      : (strategy || 'zettel turn'),
+    validation: validation || null,
+  });
+  // Stash zettel-specific fields by augmenting the latest turn record.
+  // (ArtifactStore is intentionally generic; we attach extras after the fact.)
+  const latest = store.get(sessionId, -1);
+  if (latest) {
+    latest.composition = composition || null;
+    latest.strategy = strategy || null;
+    latest.fragments = fragments || [];
+    latest.template = template || null;
+  }
+}
+
+/**
+ * Get the full turn history for a session.
+ * @returns {object[]} — empty array if session unknown
+ */
+export function getTurns(sessionId) {
+  if (!sessionId) return [];
+  return store.getAll(sessionId) || [];
+}
+
+/**
+ * Get the latest turn only (nullable).
+ */
+export function getLatestTurn(sessionId) {
+  if (!sessionId) return null;
+  return store.get(sessionId, -1);
+}
+
+/** Drift metrics across turns — reuses ArtifactStore's logic. */
+export function getDrift(sessionId) {
+  if (!sessionId) return null;
+  return store.getDriftMetrics(sessionId);
+}
+
+/** Clear a session (user hit "reset canvas"). */
+export function clearSession(sessionId) {
+  if (!sessionId) return;
+  store.delete(sessionId);
+}
+
+/**
+ * Build a compact history summary suitable for inclusion in an LLM prompt.
+ * Limits to the last N turns and trims each template to a skeletal form
+ * (ids + components/$fragment only) so we don't blow the context window.
+ *
+ * @param {string} sessionId
+ * @param {number} [maxTurns=3]
+ * @returns {string|null}
+ */
+export function buildHistorySummary(sessionId, maxTurns = 3) {
+  const turns = getTurns(sessionId);
+  if (!turns.length) return null;
+
+  const recent = turns.slice(-maxTurns);
+  const lines = recent.map((t, i) => {
+    const turnNum = turns.length - recent.length + i + 1;
+    const header = `--- turn ${turnNum}: "${t.intent}" (${t.strategy || 'unknown'}${t.composition ? ` → ${t.composition}` : ''}) ---`;
+    const skeleton = t.template
+      ? JSON.stringify(t.template.map(n => {
+          if (n.$fragment) return { id: n.id, $fragment: n.$fragment, bindings: n.bindings };
+          const { id, component, children, ...rest } = n;
+          // Keep shape-critical props, drop verbose content
+          const keep = { id, component };
+          if (children) keep.children = children;
+          // Keep variant/type-level props, drop textContent/placeholder (too verbose)
+          for (const k of ['variant', 'gap', 'columns', 'align', 'justify']) {
+            if (rest[k] !== undefined) keep[k] = rest[k];
+          }
+          return keep;
+        }), null, 2)
+      : '(no template recorded)';
+    return `${header}\n${skeleton}`;
+  });
+  return lines.join('\n\n');
+}