@adia-ai/a2ui-retrieval 0.6.6 → 0.6.8

package/intent/prompt-analyzer.ts

@@ -1,231 +0,0 @@
-/**
- * Prompt Analyzer — baseline ingestion stage for the gen-ui pipeline.
- *
- * Every user intent enters through here, regardless of engine (monolithic,
- * zettel) or mode (instant, pro, thinking). The analyzer extracts structured
- * signals from the raw prompt — what concepts the user is gesturing at, which
- * AdiaUI components are implied, what implicit requirements a good designer
- * would add — and produces a "steelmanned" enriched brief that downstream
- * stages reason against.
- *
- * Output schema:
- *   {
- *     raw:               string  // user's original intent, verbatim
- *     concepts:          string[] // 2-5 short concept tags ("commerce", "auth", "data-display")
- *     entities:          string[] // explicit nouns from the prompt ("image", "title", "price")
- *     impliedComponents: string[] // 4-12 AdiaUI component names ("Card", "Image", "Button")
- *     styleHints:        string[] // visual/style hints ("3D", "minimal", "dense"), [] if none
- *     steelman:          string   // 1-2 sentence enriched brief
- *     analyzed:          boolean  // true if LLM call succeeded; false if fell back to passthrough
- *   }
- *
- * Failure mode: if the LLM call throws or returns unparseable JSON, we
- * gracefully degrade to a passthrough analysis (steelman = raw intent, no
- * extracted signals). Generation continues; quality may suffer but nothing
- * breaks.
- */
-
-// Node's `process` global is not in scope under `"types": []` — declare
-// minimally for the typeof guard below (erased at runtime by erasableSyntaxOnly).
-declare const process: { versions?: { node?: string } } | undefined;
-
-// Component vocabulary derived from the catalog. Two artifacts:
-//   - displayList: human-readable list shown to the LLM, with aliases inlined
-//   - allowedSet:  canonical AND alias names accepted in impliedComponents
-let _vocab: { displayList: string[]; allowedSet: Set<string> } | null = null;
-
-async function getVocab(): Promise<{ displayList: string[]; allowedSet: Set<string> }> {
-  if (_vocab) return _vocab;
-  let catalogJson: Record<string, unknown> = {};
-  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');
-      const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
-      const raw = await fs.readFile(path.join(__dirname, '../../corpus/catalog-a2ui_0_9.json'), 'utf8');
-      catalogJson = JSON.parse(raw) as Record<string, unknown>;
-    } else {
-      const resp = await fetch(new URL('../../corpus/catalog-a2ui_0_9.json', import.meta.url));
-      if (resp.ok) catalogJson = await resp.json() as Record<string, unknown>;
-    }
-  } catch { /* empty vocab — analyzer will still work, just unconstrained */ }
-
-  // Adapt v0.9 catalog shape
-  const comps = (catalogJson?.['components'] ?? {}) as Record<string, unknown>;
-  const displayList: string[] = [];
-  const allowedSet = new Set<string>();
-  for (const [name, def] of Object.entries(comps)) {
-    allowedSet.add(name);
-    const ext = (def as Record<string, unknown>)?.['x-adiaui'] ?? {};
-    const syns = (ext && typeof ext === 'object') ? (ext as Record<string, unknown>)['synonyms'] : null;
-    const tags = (syns && typeof syns === 'object') ? (syns as Record<string, unknown>)['tags'] : null;
-    const aliases: string[] = Array.isArray(tags) ? (tags as unknown[]).filter((t): t is string => typeof t === 'string') : [];
-    for (const a of aliases) allowedSet.add(a);
-    displayList.push(aliases.length ? `${name} (also: ${aliases.join(', ')})` : name);
-  }
-  _vocab = { displayList, allowedSet };
-  return _vocab;
-}
-
-export type PromptAnalysis = {
-  raw: string;
-  concepts: string[];
-  entities: string[];
-  impliedComponents: string[];
-  styleHints: string[];
-  steelman: string;
-  analyzed: boolean;
-};
-
-type LLMAdapter = {
-  complete(opts: { messages: Array<{ role: string; content: string }>; systemPrompt: string }): Promise<{ content?: string; stopReason?: string }>;
-};
-
-type DomainHint = {
-  domain?: string;
-  confidence?: number;
-};
-
-/**
- * Analyze a user prompt — extract concepts, entities, implied components,
- * style hints, and produce a steelmanned brief.
- */
-export async function analyzePrompt({ intent, llmAdapter, domain }: {
-  intent: string;
-  llmAdapter?: LLMAdapter;
-  domain?: DomainHint;
-}): Promise<PromptAnalysis> {
-  const passthrough: PromptAnalysis = {
-    raw: intent,
-    concepts: [],
-    entities: [],
-    impliedComponents: [],
-    styleHints: [],
-    steelman: intent,
-    analyzed: false,
-  };
-
-  if (!intent || !llmAdapter) return passthrough;
-
-  const { displayList, allowedSet } = await getVocab();
-  const componentList = displayList.length
-    ? displayList.join(', ')
-    : 'Card, Section, Header, Footer, Column, Row, Grid, Button, Input, Text, Image, Badge, Icon, Avatar, Alert, Modal, Tabs, Accordion';
-
-  const domainHint = domain?.['domain'] && (domain?.['confidence'] ?? 0) > 0
-    ? `\nDomain classifier suggests: ${domain['domain']} (confidence ${domain['confidence']})`
-    : '';
-
-  const systemPrompt = `You are a UI brief enricher for the AdiaUI design system. Given a terse or under-specified user prompt, you extract structured signals and produce an enriched brief that a downstream UI generator can use to produce a polished, complete UI.
-
-Your output is JSON with this exact shape — no markdown, no explanation:
-{
-  "concepts": [string],          // 2-5 short concept tags (e.g. "commerce", "authentication", "data-display", "navigation")
-  "entities": [string],          // explicit nouns from the prompt (lowercase, singular)
-  "implied_components": [string],// 4-12 AdiaUI components a good designer would include
-  "style_hints": [string],       // visual/style adjectives ("minimal", "dense", "3D", "playful"), [] if none stated
-  "steelman": string             // 1-2 sentence enriched brief
-}
-
-AdiaUI components you may name in implied_components (use these names exactly): ${componentList}
-
-Rules:
-- Extract entities verbatim from the prompt — do not invent.
-- implied_components should include both the obvious (Card, Button) AND the ones a thoughtful designer would add (Badge for sale tag on a product, Avatar for a user row, EmptyState for empty data).
-- The steelman expands the prompt into what the user MEANT, not what they SAID. Add the implicit requirements: typical sub-elements, sensible defaults, a header, a footer, common variants. Do NOT add scope the user wouldn't want (e.g. don't turn "login form" into "login form with social auth" unless that's a near-universal expectation).
-- Keep steelman under 250 characters.
-- If the prompt is already well-specified (>15 words, multiple entities), the steelman is mostly a faithful restatement.
-
-Examples:
-Input: "product card"
-Output: {"concepts":["commerce","product-display"],"entities":["product"],"implied_components":["Card","Image","Text","Badge","Button"],"style_hints":[],"steelman":"E-commerce product card with image, title, price, optional sale badge, and primary 'Add to cart' button. Card layout, single product."}
-
-Input: "settings page with toggles for notifications, dark mode, and privacy"
-Output: {"concepts":["settings","preferences"],"entities":["notifications","dark mode","privacy","toggles"],"implied_components":["Card","Header","Section","Toggle","Text","Divider"],"style_hints":[],"steelman":"Settings page with three toggle rows for notifications, dark mode, and privacy. Each row has a label, description, and toggle. Grouped under a header card."}
-
-Input: "make it 3D"
-Output: {"concepts":["style-modifier"],"entities":[],"implied_components":[],"style_hints":["3D","depth","shadow"],"steelman":"Modify the existing canvas to feel three-dimensional — add elevation, layered shadows, and depth-suggesting transforms. Apply to existing components without changing structure."}`;
-
-  const userMsg = `Prompt: "${intent}"${domainHint}`;
-
-  let response: { content?: string; stopReason?: string } | undefined;
-  try {
-    response = await llmAdapter.complete({
-      messages: [{ role: 'user', content: userMsg }],
-      systemPrompt,
-    });
-  } catch {
-    return passthrough;
-  }
-
-  const text = response?.content;
-  if (!text) return passthrough;
-
-  // Truncation: if the analyzer LLM hit max_tokens we'd rather use the raw
-  // prompt than a half-parsed analysis that misleads downstream stages.
-  if (response.stopReason && response.stopReason !== 'end' && response.stopReason !== 'end_turn' && response.stopReason !== 'stop') {
-    return passthrough;
-  }
-
-  // Try direct parse, then code-fence extraction, then outermost JSON.
-  let parsed: unknown = null;
-  try { parsed = JSON.parse(text.trim()); } catch { /* fall through */ }
-  if (!parsed) {
-    const fence = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
-    if (fence) try { parsed = JSON.parse((fence[1] ?? '').trim()); } catch { /* fall through */ }
-  }
-  if (!parsed) {
-    const start = text.indexOf('{');
-    const end = text.lastIndexOf('}');
-    if (start >= 0 && end > start) {
-      try { parsed = JSON.parse(text.slice(start, end + 1)); } catch { /* fall through */ }
-    }
-  }
-  if (!parsed || typeof parsed !== 'object') return passthrough;
-
-  const p = parsed as Record<string, unknown>;
-
-  // Constrain impliedComponents to the allowed vocab
-  const impliedComponents = Array.isArray(p['implied_components'])
-    ? (p['implied_components'] as unknown[]).filter((c): c is string => typeof c === 'string' && (allowedSet.size === 0 || allowedSet.has(c)))
-    : [];
-
-  return {
-    raw: intent,
-    concepts:          asStringArray(p['concepts']).slice(0, 8),
-    entities:          asStringArray(p['entities']).slice(0, 16),
-    impliedComponents: impliedComponents.slice(0, 16),
-    styleHints:        asStringArray(p['style_hints']).slice(0, 8),
-    steelman:          (typeof p['steelman'] === 'string' && p['steelman'].trim()) || intent,
-    analyzed:          true,
-  };
-}
-
-function asStringArray(v: unknown): string[] {
-  if (!Array.isArray(v)) return [];
-  return (v as unknown[]).filter((x): x is string => typeof x === 'string' && x.trim().length > 0).map(x => (x as string).trim());
-}
-
-/**
- * Format an analysis object for inclusion in a downstream system prompt.
- * Keeps the shape compact so it doesn't blow the context budget.
- */
-export function formatAnalysisForPrompt(analysis: PromptAnalysis | null | undefined): string {
-  if (!analysis || !analysis.analyzed) return '';
-  const parts: string[] = [];
-  if (analysis.steelman && analysis.steelman !== analysis.raw) {
-    parts.push(`ENRICHED BRIEF: ${analysis.steelman}`);
-  }
-  if (analysis.impliedComponents?.length) {
-    parts.push(`EXPECTED COMPONENTS: ${analysis.impliedComponents.join(', ')}`);
-  }
-  if (analysis.concepts?.length) {
-    parts.push(`CONCEPTS: ${analysis.concepts.join(', ')}`);
-  }
-  if (analysis.styleHints?.length) {
-    parts.push(`STYLE HINTS: ${analysis.styleHints.join(', ')}`);
-  }
-  return parts.join('\n');
-}