@adia-ai/gen-ui 0.8.37

package/validate/semantic/intent-specs.js

@@ -0,0 +1,162 @@
+/**
+ * IntentSpec Registry — Phase 3 kickoff (semantic-validator)
+ *
+ * Spec: .claude/docs/specs/semantic-validator.md § 5.1, § Phase 3
+ *
+ * An IntentSpec is a deterministic recipe for one common intent class.
+ * The classify-intent.js classifier matches user prompts against these
+ * specs; high-confidence matches (confidence ≥ 0.9) can bypass the LLM
+ * judge entirely.
+ *
+ * Status: kickoff — 10 IntentSpec entries covering the dominant intent
+ * classes from the existing keyword map in validator.js. NOT YET wired
+ * into validateSemantics() (Phase 3 integration deferred to a follow-up
+ * cut once shadow-compare runs prove ≥95% agreement with the LLM judge).
+ *
+ * Schema (subset of § 5.2 in the spec):
+ *
+ *   IntentSpec {
+ *     id:           string                // e.g. 'auth.signup'
+ *     keywords:     RegExp                // bag-of-words match
+ *     required:     string[]              // component types that MUST appear
+ *     forbidden:    string[]              // component types that MUST NOT appear
+ *     minComponents:number                // structural floor
+ *     domain:       'data-entry' | 'data-display' | 'action' | 'identity' | 'navigation' | 'media' | 'layout' | 'notification' | 'overlay'
+ *     description:  string                // for catalog / docs
+ *   }
+ *
+ * Adding a new spec:
+ *   1. Author the entry below
+ *   2. Add a row to the test file: `classify-intent.test.js`
+ *   3. Run shadow-compare for 1 week (Phase 3 exit criteria § Phase 3)
+ *   4. Promote to fast-path if rule verdict agrees with LLM verdict ≥ 95%
+ */
+
+/** @type {Array<IntentSpec>} */
+export const INTENT_SPECS = [
+  {
+    id: 'auth.signup',
+    keywords: /\b(?:sign[\s-]*up|register|create\s+account|new\s+user)\b/i,
+    required: ['Card', 'Input', 'Button'],
+    forbidden: ['Toast', 'Alert'],  // a signup page should not be primarily a toast/alert
+    minComponents: 7,
+    domain: 'data-entry',
+    description: 'New-user account creation flow — email/password Card with explicit submit Button',
+  },
+  {
+    id: 'auth.signin',
+    keywords: /\b(?:sign[\s-]*in|log[\s-]*in|login)\b/i,
+    required: ['Card', 'Input', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 6,
+    domain: 'data-entry',
+    description: 'Authentication form — credentials Card with submit Button',
+  },
+  {
+    id: 'auth.password-reset',
+    keywords: /\b(?:reset\s+password|forgot\s+password|recover\s+account)\b/i,
+    required: ['Card', 'Input', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 5,
+    domain: 'data-entry',
+    description: 'Password reset / forgot-password flow — single-email-input Card',
+  },
+  {
+    id: 'dashboard.analytics',
+    keywords: /\b(?:dashboard|analytics|metrics|admin\s+dashboard)\b/i,
+    required: ['Grid', 'Card'],
+    forbidden: ['Toast', 'Alert'],
+    minComponents: 10,
+    domain: 'data-display',
+    description: 'Metrics dashboard — Grid of Stat/Chart Cards with optional Nav',
+  },
+  {
+    id: 'data-table.list',
+    keywords: /\b(?:table|list|directory|roster|catalog|index)\b/i,
+    required: ['Table'],
+    forbidden: ['Toast'],
+    minComponents: 4,
+    domain: 'data-display',
+    description: 'Tabular data list — sortable/filterable Table',
+  },
+  {
+    id: 'form.settings',
+    keywords: /\b(?:settings|preferences|configuration|account\s+settings|profile\s+settings)\b/i,
+    required: ['Form', 'Input', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 8,
+    domain: 'data-entry',
+    description: 'Multi-field settings/preferences Form with explicit save Button',
+  },
+  {
+    id: 'form.contact',
+    keywords: /\b(?:contact\s+(?:us|form)|reach\s+out|get\s+in\s+touch|inquiry\s+form)\b/i,
+    required: ['Form', 'Input', 'TextArea', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 6,
+    domain: 'data-entry',
+    description: 'Contact form — name/email/message TextArea with submit Button',
+  },
+  {
+    id: 'chat.conversation',
+    keywords: /\b(?:chat|conversation|messaging|messenger)\b/i,
+    required: ['Input', 'Button'],
+    forbidden: ['Table', 'Grid'],
+    minComponents: 4,
+    domain: 'data-entry',
+    description: 'Conversational chat surface — Input + send Button stream',
+  },
+  {
+    id: 'commerce.cart',
+    keywords: /\b(?:cart|checkout|basket|shopping\s+cart)\b/i,
+    required: ['Card', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 6,
+    domain: 'data-display',
+    description: 'Shopping cart — line-item Cards with checkout Button',
+  },
+  {
+    id: 'errors.not-found',
+    keywords: /\b(?:404|not\s+found|page\s+not\s+found|page\s+missing)\b/i,
+    required: ['Card', 'Button'],
+    forbidden: ['Form', 'Table'],
+    minComponents: 3,
+    domain: 'action',
+    description: '404 error page — reassurance Card with back-to-home Button',
+  },
+];
+
+/**
+ * Find the IntentSpec matching the prompt (if any), with a confidence score.
+ *
+ * Confidence semantics:
+ *   - 1.0   = exact keyword regex match
+ *   - 0.0   = no match
+ *
+ * Returns { spec, confidence } or { spec: null, confidence: 0 }.
+ *
+ * @param {string} intent — natural-language intent prompt
+ * @returns {{ spec: IntentSpec | null, confidence: number }}
+ */
+export function findIntentSpec(intent) {
+  if (!intent || typeof intent !== 'string') {
+    return { spec: null, confidence: 0 };
+  }
+  for (const spec of INTENT_SPECS) {
+    if (spec.keywords.test(intent)) {
+      return { spec, confidence: 1.0 };
+    }
+  }
+  return { spec: null, confidence: 0 };
+}
+
+/**
+ * @typedef {object} IntentSpec
+ * @property {string} id — dot-namespaced identifier
+ * @property {RegExp} keywords — pattern that matches user prompts
+ * @property {string[]} required — A2UI component types that MUST appear
+ * @property {string[]} forbidden — component types that MUST NOT appear
+ * @property {number} minComponents — minimum total component count
+ * @property {string} domain — semantic category
+ * @property {string} description — human-readable summary
+ */

package/validate/semantic/judge.js

@@ -0,0 +1,180 @@
+/**
+ * LLM judge for semantic A2UI validation (Phase 1: Anthropic only).
+ *
+ * Implements the rubric from .claude/docs/specs/semantic-validator.md §4 (recommendation
+ * is pure 3a LLM-judge as first phase). Provider-agnostic shape per §5.3;
+ * only Anthropic wired here.
+ *
+ * Contract:
+ *   callJudge({ intent, componentSummary, rubricVersion }) →
+ *     { raw, parsed: SemanticVerdict, usage }
+ */
+
+const RUBRIC_VERSION = 'v1';
+
+const RUBRIC_TEXT = `You are a senior UI reviewer scoring whether an emitted UI actually
+satisfies a user's intent. You are NOT scoring visual polish or copy.
+You are scoring intent/output alignment on three axes.
+
+Score each axis 0-100. Cite evidence from the component summary.
+
+Axes:
+  1. dominantPattern: does the top-level pattern match what the intent asked
+     for? (form | data-display | navigation | marketing | feedback | settings
+     | chat | media | dashboard | detail | list | auth | other). A pricing
+     card in response to "signup form" is a dominant-pattern mismatch — score
+     very low (<15) regardless of filler components.
+  2. requiredCapabilities: does the output contain the specific controls /
+     affordances the intent requires? (e.g. "login form" requires Input(email
+     or username) + Input(password) + Button(submit); "users table" requires
+     a Table or tabular Grid with rows). List what was expected and what was
+     missing.
+  3. forbiddenNoise: are there prominent components that are off-topic for
+     this intent? (e.g. pricing tiers in a signup form, avatars in a data
+     table). 100 = nothing off-topic; drop for each noisy element.
+
+Overall verdict:
+  aligned     — all three axes ≥ 75
+  partial     — one axis < 60 OR overall score 40-74
+  misaligned  — dominantPattern < 40 OR two axes < 60
+  off-topic   — dominantPattern < 15
+
+Final score = round(0.5*dominantPattern + 0.35*requiredCapabilities + 0.15*forbiddenNoise).
+
+Return ONLY valid JSON, no prose, no markdown fences:
+{
+  "axes": {
+    "dominantPattern":      { "expected": "<string>", "observed": "<string>", "score": <0-100>, "evidence": "<short string>" },
+    "requiredCapabilities": { "expected": ["..."], "missing": ["..."], "score": <0-100> },
+    "forbiddenNoise":       { "observed": ["..."], "score": <0-100> }
+  },
+  "verdict": "aligned" | "partial" | "misaligned" | "off-topic",
+  "score": <0-100>,
+  "rationale": "<<= 240 chars>",
+  "evidence": ["<component id or short quote>", ...]
+}`;
+
+export function getRubric() {
+  return { version: RUBRIC_VERSION, text: RUBRIC_TEXT };
+}
+
+/**
+ * Summarize emitted A2UI messages into a compact human-readable string
+ * (§5.4). Handles both monolithic (messages with .components array) and
+ * zettel (flat beginComponent/endComponent stream) shapes.
+ */
+export function summarizeA2UI(messages) {
+  const msgs = Array.isArray(messages) ? messages : [];
+  const counts = new Map();
+  const samples = new Map(); // component -> [labels]
+  let rootType = null;
+  let totalComponents = 0;
+
+  const record = (type, props) => {
+    if (!type) return;
+    totalComponents += 1;
+    counts.set(type, (counts.get(type) || 0) + 1);
+    if (!rootType) rootType = type;
+    const label = props?.label || props?.text || props?.title || props?.placeholder;
+    if (label && typeof label === 'string') {
+      const arr = samples.get(type) || [];
+      if (arr.length < 3) arr.push(label.slice(0, 32));
+      samples.set(type, arr);
+    }
+  };
+
+  for (const m of msgs) {
+    if (Array.isArray(m?.components)) {
+      for (const c of m.components) record(c.component, c.props || c);
+    } else if (m?.componentType && m?.messageType !== 'endComponent') {
+      record(m.componentType, m.props || m);
+    }
+  }
+
+  const parts = [];
+  for (const [type, n] of [...counts.entries()].sort((a, b) => b[1] - a[1])) {
+    const s = samples.get(type);
+    const lbl = s && s.length ? ` (labels: ${s.map((x) => JSON.stringify(x)).join(', ')})` : '';
+    parts.push(`${type}×${n}${lbl}`);
+  }
+  return `Root: ${rootType || 'none'}\nTotal components: ${totalComponents}\nBreakdown: ${parts.join('; ') || '(empty)'}`;
+}
+
+function parseJSONLoose(raw) {
+  if (!raw) throw new Error('empty judge response');
+  let text = String(raw).trim();
+  // Strip markdown fences if present.
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+  if (fence) text = fence[1].trim();
+  // Grab the first top-level { ... } block.
+  const first = text.indexOf('{');
+  const last = text.lastIndexOf('}');
+  if (first < 0 || last < 0 || last <= first) throw new Error('no JSON object in judge response');
+  const slice = text.slice(first, last + 1);
+  return JSON.parse(slice);
+}
+
+/**
+ * Call the LLM judge. Anthropic-only in Phase 1.
+ * Returns { raw, parsed, usage, latencyMs, provider, model }.
+ */
+export async function callJudge({
+  intent,
+  componentSummary,
+  rubricVersion = RUBRIC_VERSION,
+  timeoutMs = 15000,
+  model = 'claude-haiku-4-5-20251001',
+} = {}) {
+  const key = process.env.ANTHROPIC_API_KEY;
+  if (!key) throw new Error('ANTHROPIC_API_KEY missing — cannot call semantic judge');
+
+  const rubric = RUBRIC_TEXT;
+  const userBlock = `Intent: ${intent}\n\nEmitted UI summary:\n${componentSummary}\n\nRespond with JSON only.`;
+
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  const started = Date.now();
+  let res;
+  try {
+    res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-api-key': key,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 1024,
+        temperature: 0,
+        system: rubric,
+        messages: [{ role: 'user', content: userBlock }],
+      }),
+      signal: ac.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const latencyMs = Date.now() - started;
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`Anthropic judge ${res.status}: ${body.slice(0, 200)}`);
+  }
+  const data = await res.json();
+  const raw = data.content?.[0]?.text || '';
+  const parsed = parseJSONLoose(raw);
+
+  return {
+    raw,
+    parsed,
+    usage: {
+      inputTokens: data.usage?.input_tokens ?? 0,
+      outputTokens: data.usage?.output_tokens ?? 0,
+    },
+    latencyMs,
+    provider: 'anthropic',
+    model,
+    rubricVersion,
+  };
+}