@adia-ai/a2ui-retrieval 0.0.1

package/synthetic-data.js

@@ -0,0 +1,446 @@
+/**
+ * SyntheticDataGenerator — Fills coverage gaps in training data by
+ * generating A2UI JSON examples for uncovered patterns.
+ *
+ * Uses the LLM adapter to generate schemas, validates them via the
+ * generative validator, scores quality via anti-pattern checks,
+ * and stores results as training pairs (prompt -> schema).
+ *
+ * Spec: A003 section 6 — Synthetic Data Generation
+ */
+
+import { getCatalog } from './catalog.js';
+import { getAntiPatterns } from './anti-patterns.js';
+import { getAllPatterns } from './pattern-library.js';
+import { serializeEntry } from './component-entry.js';
+
+// ── Coverage targets (spec section 6.2) ──
+
+const COVERAGE_TARGETS = [
+  { id: 'sidebar-main', description: 'Sidebar navigation with main content area', complexity: 'medium' },
+  { id: 'modal-form', description: 'Modal dialog containing a form with validation', complexity: 'medium' },
+  { id: 'drawer-nav', description: 'Drawer panel with navigation links', complexity: 'medium' },
+  { id: 'toast-sequence', description: 'Sequence of toast notifications (success, error, info)', complexity: 'low' },
+  { id: 'tabs-content', description: 'Tabbed interface with different content per tab', complexity: 'medium' },
+  { id: 'accordion-faq', description: 'Accordion with FAQ-style question/answer pairs', complexity: 'low' },
+  { id: 'wizard-steps', description: 'Multi-step wizard with progress indicator and form fields', complexity: 'high' },
+  { id: 'data-grid', description: 'Data table with sort, filter, and pagination', complexity: 'high' },
+  { id: 'card-grid', description: 'Grid of cards with different content types', complexity: 'medium' },
+  { id: 'auth-form', description: 'Login form with email, password, and social buttons', complexity: 'medium' },
+  { id: 'profile-card', description: 'User profile card with avatar, name, stats, and actions', complexity: 'medium' },
+  { id: 'empty-state', description: 'Empty state with illustration, heading, and CTA button', complexity: 'low' },
+];
+
+// ── Default generation options ──
+
+const DEFAULT_OPTIONS = {
+  temperature: 0.7,
+  maxRetries: 2,
+  batchSize: 4,
+};
+
+/**
+ * SyntheticDataGenerator — generates A2UI training examples for coverage gaps.
+ */
+export class SyntheticDataGenerator {
+  #llmAdapter;
+  #catalog;
+  #patternLibrary;
+  #validator;
+  #antiPatterns;
+
+  /**
+   * @param {object} deps
+   * @param {object} deps.llmAdapter — LLM adapter with complete() method
+   * @param {object} [deps.catalog] — Component catalog (defaults to built-in)
+   * @param {object} [deps.patternLibrary] — Pattern library (defaults to built-in)
+   * @param {object} [deps.validator] — Schema validator with validateSchema()
+   * @param {object} [deps.antiPatterns] — Anti-patterns checker
+   */
+  constructor({ llmAdapter, catalog, patternLibrary, validator, antiPatterns }) {
+    this.#llmAdapter = llmAdapter;
+    this.#catalog = catalog || null;
+    this.#patternLibrary = patternLibrary || null;
+    this.#validator = validator || null;
+    this.#antiPatterns = antiPatterns || null;
+  }
+
+  /**
+   * Analyze coverage gaps — which target patterns are missing from existing examples.
+   *
+   * @param {object[]} existingExamples — Array of { name, template } pattern objects
+   * @returns {{ covered: string[], missing: string[], coverage: number }}
+   */
+  analyzeCoverage(existingExamples) {
+    const existingNames = new Set(
+      (existingExamples || getAllPatterns()).map(p => p.name)
+    );
+
+    const covered = [];
+    const missing = [];
+
+    for (const target of COVERAGE_TARGETS) {
+      if (existingNames.has(target.id)) {
+        covered.push(target.id);
+      } else {
+        missing.push(target.id);
+      }
+    }
+
+    const total = COVERAGE_TARGETS.length;
+    const coverage = total === 0 ? 1 : covered.length / total;
+
+    return { covered, missing, coverage };
+  }
+
+  /**
+   * Generate synthetic examples for missing patterns.
+   *
+   * For each gap: builds a prompt, calls the LLM, validates, scores, and stores.
+   *
+   * @param {string[]} gaps — Pattern IDs to generate (from analyzeCoverage().missing)
+   * @param {object} [options]
+   * @param {string} [options.model] — Model override for the LLM adapter
+   * @param {number} [options.temperature] — Sampling temperature (default 0.7)
+   * @param {number} [options.maxRetries] — Max retries per pattern (default 2)
+   * @param {number} [options.batchSize] — Concurrent generation batch size (default 4)
+   * @returns {Promise<{ generated: object[], failed: string[], stats: object }>}
+   */
+  async generateExamples(gaps, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const generated = [];
+    const failed = [];
+    let totalTokens = 0;
+    let totalAttempts = 0;
+
+    // Process in batches
+    for (let i = 0; i < gaps.length; i += opts.batchSize) {
+      const batch = gaps.slice(i, i + opts.batchSize);
+
+      const results = await Promise.allSettled(
+        batch.map(gapId => this.#generateWithRetry(gapId, opts))
+      );
+
+      for (let j = 0; j < results.length; j++) {
+        const result = results[j];
+        const gapId = batch[j];
+
+        if (result.status === 'fulfilled' && result.value) {
+          generated.push(result.value);
+          totalTokens += result.value.tokenUsage || 0;
+          totalAttempts += result.value.attempts || 1;
+        } else {
+          failed.push(gapId);
+          totalAttempts += opts.maxRetries + 1;
+        }
+      }
+    }
+
+    return {
+      generated,
+      failed,
+      stats: {
+        total: gaps.length,
+        succeeded: generated.length,
+        failed: failed.length,
+        totalTokens,
+        totalAttempts,
+        averageQuality: generated.length > 0
+          ? generated.reduce((sum, g) => sum + g.quality.overall, 0) / generated.length
+          : 0,
+      },
+    };
+  }
+
+  /**
+   * Generate a single training pair for a pattern description.
+   *
+   * @param {string} patternDescription — Natural language description of the pattern
+   * @returns {Promise<{ prompt: string, schema: object[], quality: object }>}
+   */
+  async generateOne(patternDescription) {
+    const systemPrompt = await this.#buildSystemPrompt();
+    const userPrompt = this.#buildUserPrompt(patternDescription);
+
+    const response = await this.#llmAdapter.complete({
+      messages: [{ role: 'user', content: userPrompt }],
+      systemPrompt,
+    });
+
+    const schema = this.#parseResponse(response.content);
+    const quality = this.scoreExample(schema);
+
+    return {
+      prompt: patternDescription,
+      schema,
+      quality,
+      tokenUsage: (response.usage?.inputTokens || 0) + (response.usage?.outputTokens || 0),
+    };
+  }
+
+  /**
+   * Score a generated example against quality criteria.
+   *
+   * Uses the anti-patterns checker from the intelligence system to detect
+   * structural issues, missing props, anti-patterns, and unnecessary wrappers.
+   *
+   * @param {object[]} schema — A2UI messages array
+   * @returns {{ structural: number, completeness: number, idiomatic: number, minimal: number, overall: number }}
+   */
+  scoreExample(schema) {
+    // Collect all components across messages
+    const allComponents = [];
+    for (const msg of schema) {
+      if (msg.type === 'updateComponents' && Array.isArray(msg.components)) {
+        allComponents.push(...msg.components);
+      }
+    }
+
+    // Run validation if available
+    let validationIssues = [];
+    if (this.#validator) {
+      const validation = this.#validator(schema);
+      validationIssues = (validation.checks || []).filter(c => !c.passed);
+    }
+
+    // Run anti-pattern checks (HTML-based)
+    // Serialize components to a minimal HTML representation for pattern matching
+    const html = this.#componentsToHtml(allComponents);
+    const antiPatternChecks = this.#antiPatterns
+      ? this.#antiPatterns(html)
+      : [];
+
+    // Structural: no orphaned children, valid message format, root exists
+    const structuralIssues = validationIssues.filter(c =>
+      ['hasRootComponent', 'noOrphanedChildren', 'validMessageFormat', 'flatAdjacency'].includes(c.name)
+    );
+    const structural = structuralIssues.length === 0 ? 1 : 0.5;
+
+    // Completeness: text content set, all types registered
+    const completenessIssues = validationIssues.filter(c =>
+      ['textContentSet', 'allTypesRegistered'].includes(c.name)
+    );
+    const completeness = Math.max(0, 1 - (completenessIssues.length * 0.1));
+
+    // Idiomatic: no anti-patterns (bare divs, inline styles, wrong nesting)
+    const idiomaticViolations = antiPatternChecks.filter(ap =>
+      ['noBareDivs', 'noBareInputs', 'cardStructure', 'noInventedComponents'].includes(ap.name)
+    );
+    const idiomatic = idiomaticViolations.length === 0 ? 1 : 0.5;
+
+    // Minimal: no unnecessary wrappers or inline layout/colors
+    const minimalViolations = antiPatternChecks.filter(ap =>
+      ['noHardcodedColors', 'noInlineLayout'].includes(ap.name)
+    );
+    const minimal = minimalViolations.length === 0 ? 1 : 0.5;
+
+    // Overall weighted average
+    const overall = (structural * 0.3) + (completeness * 0.25) + (idiomatic * 0.25) + (minimal * 0.2);
+
+    return { structural, completeness, idiomatic, minimal, overall };
+  }
+
+  // ── Private helpers ──
+
+  /**
+   * Generate with retry logic.
+   * @param {string} gapId — Target pattern ID
+   * @param {object} opts — Generation options
+   * @returns {Promise<object|null>}
+   */
+  async #generateWithRetry(gapId, opts) {
+    const target = COVERAGE_TARGETS.find(t => t.id === gapId);
+    if (!target) return null;
+
+    let lastError;
+    for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+      try {
+        const result = await this.generateOne(target.description);
+
+        // Require minimum quality threshold
+        if (result.quality.overall >= 0.5) {
+          return {
+            id: gapId,
+            ...result,
+            attempts: attempt + 1,
+          };
+        }
+
+        lastError = new Error(`Quality too low: ${result.quality.overall}`);
+      } catch (err) {
+        lastError = err;
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Build the system prompt with catalog, anti-patterns, and format rules.
+   * @returns {string}
+   */
+  async #buildSystemPrompt() {
+    const parts = [];
+
+    // Role
+    parts.push('You are an A2UI training data generator for the AdiaUI design system. Output ONLY a JSON array of A2UI messages.');
+
+    // Output format
+    parts.push('Output format: [{ "type": "updateComponents", "surfaceId": "default", "components": [...] }]');
+    parts.push('Components use flat adjacency: each has { id, component, children?: [string ids], ...props }.');
+    parts.push('The root component must have id "root".');
+
+    // Anti-patterns (rules)
+    const antiPatterns = getAntiPatterns();
+    if (antiPatterns.length > 0) {
+      const rules = antiPatterns.map(ap => `- ${ap.description}`).join('\n');
+      parts.push(`Rules:\n${rules}`);
+    }
+
+    // Available components (summary level)
+    const catalog = this.#catalog || await getCatalog();
+    const entries = catalog.entries || new Map();
+    if (entries.size > 0) {
+      const lines = [];
+      for (const entry of entries.values()) {
+        const serialized = serializeEntry(entry, 'index');
+        lines.push(`- ${serialized.type} (${serialized.tag}): ${serialized.description || ''}`);
+      }
+      parts.push(`Available components:\n${lines.join('\n')}`);
+    }
+
+    // Quality criteria
+    parts.push([
+      'Quality criteria:',
+      '- Structural: valid root, all children resolve, flat adjacency list',
+      '- Completeness: all Text components have textContent, all types are registered',
+      '- Idiomatic: use Card > Header + Section + Footer, no bare divs, no invented components',
+      '- Minimal: no inline styles, no hardcoded colors, use semantic props and variants',
+    ].join('\n'));
+
+    return parts.join('\n\n');
+  }
+
+  /**
+   * Build the user prompt for a specific pattern.
+   * @param {string} patternDescription
+   * @returns {string}
+   */
+  #buildUserPrompt(patternDescription) {
+    return [
+      `Generate an A2UI component tree for this UI pattern:`,
+      ``,
+      `Pattern: ${patternDescription}`,
+      ``,
+      `Requirements:`,
+      `- Use realistic content (names, values, labels)`,
+      `- Follow Card > Header + Section + Footer anatomy where appropriate`,
+      `- Use layout components (Row, Column, Grid) for composition`,
+      `- Include all necessary props (text, variant, label, placeholder, etc.)`,
+      `- Output valid JSON — no markdown, no explanation`,
+    ].join('\n');
+  }
+
+  /**
+   * Parse an LLM response into A2UI messages.
+   * Handles raw JSON, markdown code fences, bare component arrays.
+   *
+   * @param {string} content — Raw LLM response
+   * @returns {object[]}
+   */
+  #parseResponse(content) {
+    if (!content || typeof content !== 'string') {
+      return [];
+    }
+
+    let json = content.trim();
+
+    // Strip markdown code fences
+    const fenceMatch = json.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+    if (fenceMatch) {
+      json = fenceMatch[1].trim();
+    }
+
+    try {
+      const parsed = JSON.parse(json);
+
+      // Array of messages
+      if (Array.isArray(parsed)) {
+        if (parsed.length > 0 && parsed[0].type === 'updateComponents') {
+          return parsed;
+        }
+        // Bare components array — wrap
+        if (parsed.length > 0 && parsed[0].id && parsed[0].component) {
+          return [{ type: 'updateComponents', surfaceId: 'default', components: parsed }];
+        }
+        return parsed;
+      }
+
+      // Single message object
+      if (parsed && typeof parsed === 'object' && parsed.type === 'updateComponents') {
+        return [parsed];
+      }
+
+      // Single component — wrap
+      if (parsed && typeof parsed === 'object' && parsed.id && parsed.component) {
+        return [{ type: 'updateComponents', surfaceId: 'default', components: [parsed] }];
+      }
+
+      return [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Convert a flat component list to a minimal HTML-like string for anti-pattern checking.
+   * The anti-patterns module uses regex/function checks on HTML strings.
+   *
+   * @param {object[]} components
+   * @returns {string}
+   */
+  #componentsToHtml(components) {
+    const byId = new Map(components.map(c => [c.id, c]));
+    const lines = [];
+
+    for (const comp of components) {
+      const type = comp.component;
+      if (!type) continue;
+
+      // Map A2UI types to their AdiaUI tag names for anti-pattern checking
+      const tag = type.toLowerCase().replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+      const tagName = tag.endsWith('-n') ? tag : `${tag}-n`;
+
+      // Build a minimal HTML representation
+      const attrs = [];
+      if (comp.style) {
+        attrs.push(`style="${typeof comp.style === 'object' ? Object.entries(comp.style).map(([k, v]) => `${k}:${v}`).join(';') : comp.style}"`);
+      }
+      const attrStr = attrs.length > 0 ? ' ' + attrs.join(' ') : '';
+
+      // Represent nesting for structural checks
+      if (Array.isArray(comp.children)) {
+        const childTypes = comp.children
+          .map(id => byId.get(id))
+          .filter(Boolean)
+          .map(c => {
+            const ct = c.component?.toLowerCase().replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase() || '';
+            return ct.endsWith('-n') ? ct : ct;
+          });
+        lines.push(`<${tagName}${attrStr}>${childTypes.map(ct => `<${ct}>`).join('')}</${tagName}>`);
+      } else {
+        lines.push(`<${tagName}${attrStr}></${tagName}>`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Get the list of coverage targets.
+ * @returns {Array<{ id: string, description: string, complexity: string }>}
+ */
+export function getCoverageTargets() {
+  return [...COVERAGE_TARGETS];
+}

package/web-research.js

@@ -0,0 +1,186 @@
+/**
+ * Web Research — Enriches generation context with web search results.
+ *
+ * Detects reference mentions in intents ("like Stripe", "Notion-style"),
+ * generates targeted search queries, fetches results, and extracts
+ * UI-relevant patterns to feed into the generation prompt.
+ *
+ * Works with any search function that matches:
+ *   search(query) → Promise<{ results: { title, snippet, url }[] }>
+ *
+ * Falls back to LLM knowledge when no search function is provided.
+ */
+
+// ── Reference detection ──────────────────────────────────────────────────
+
+/** Patterns that indicate the user is referencing a specific product/design */
+const REFERENCE_PATTERNS = [
+  /\blike\s+(\w[\w\s]*?)(?:\s*['']s|\s+style|\s+design|\s*$)/i,
+  /\b(\w[\w\s]*?)[\s-]style\b/i,
+  /\b(\w[\w\s]*?)[\s-]inspired\b/i,
+  /\bsimilar\s+to\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+  /\bbased\s+on\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+  /\bcopy\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+  /\bclone\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+  /\b(\w+)\s+(?:pricing|dashboard|landing|login|settings|profile)\s+page\b/i,
+];
+
+/** Well-known product/brand names for UI reference */
+const KNOWN_REFERENCES = new Set([
+  'stripe', 'notion', 'linear', 'figma', 'slack', 'discord', 'spotify',
+  'github', 'vercel', 'netlify', 'supabase', 'firebase', 'tailwind',
+  'shadcn', 'radix', 'chakra', 'material', 'ant', 'bootstrap',
+  'shopify', 'airbnb', 'uber', 'twitter', 'instagram', 'dribbble',
+  'apple', 'google', 'microsoft', 'amazon', 'netflix',
+]);
+
+/**
+ * Detect product/brand references in an intent.
+ *
+ * @param {string} intent
+ * @returns {{ references: string[], queries: string[] }}
+ */
+export function detectReferences(intent) {
+  const references = [];
+  const lower = intent.toLowerCase();
+
+  // Pattern matching
+  for (const pattern of REFERENCE_PATTERNS) {
+    const match = intent.match(pattern);
+    if (match) {
+      let ref = (match[1] || '').trim();
+      // Strip leading articles
+      ref = ref.replace(/^(the|a|an)\s+/i, '');
+      if (ref && ref.length > 1 && ref.length < 30) {
+        references.push(ref);
+      }
+    }
+  }
+
+  // Direct brand name detection (only as whole words)
+  for (const brand of KNOWN_REFERENCES) {
+    const re = new RegExp(`\\b${brand}\\b`, 'i');
+    if (re.test(lower) && !references.some(r => r.toLowerCase() === brand)) {
+      references.push(brand);
+    }
+  }
+
+  // Filter out non-brand captures (e.g., "inspired" from "X-inspired")
+  const NON_BRANDS = new Set(['inspired', 'style', 'based', 'like', 'similar', 'the']);
+  for (let i = references.length - 1; i >= 0; i--) {
+    if (NON_BRANDS.has(references[i].toLowerCase())) references.splice(i, 1);
+  }
+
+  // Generate search queries from references + intent context
+  const queries = [];
+  const uniqueRefs = [...new Set(references.map(r => r.toLowerCase()))];
+
+  for (const ref of uniqueRefs.slice(0, 2)) {
+    // Extract the UI type from the intent
+    const uiType = extractUIType(intent);
+    if (uiType) {
+      queries.push(`${ref} ${uiType} UI design components`);
+    } else {
+      queries.push(`${ref} UI design pattern layout`);
+    }
+  }
+
+  // If no references but intent mentions specific UI patterns
+  if (queries.length === 0) {
+    const uiType = extractUIType(intent);
+    if (uiType && intent.split(/\s+/).length < 6) {
+      // Short intent about a UI type — search for best practices
+      queries.push(`best ${uiType} UI design patterns 2024`);
+    }
+  }
+
+  return { references: uniqueRefs, queries };
+}
+
+/**
+ * Extract the UI type/pattern from an intent (pricing, dashboard, login, etc.)
+ */
+function extractUIType(intent) {
+  const lower = intent.toLowerCase();
+  const types = [
+    'pricing', 'dashboard', 'landing page', 'login', 'signup', 'settings',
+    'profile', 'onboarding', 'checkout', 'notification', 'kanban', 'calendar',
+    'chat', 'sidebar', 'navbar', 'hero', 'footer', 'table', 'form',
+    'modal', 'card', 'timeline', 'analytics', 'admin',
+  ];
+  return types.find(t => lower.includes(t)) || null;
+}
+
+/**
+ * Research UI patterns for an intent using web search.
+ *
+ * @param {string} intent — User's generation intent
+ * @param {object} [options]
+ * @param {(query: string) => Promise<{ results: { title: string, snippet: string, url: string }[] }>} [options.search] — Search function
+ * @param {object} [options.llmAdapter] — LLM adapter for summarization
+ * @returns {Promise<{ references: string[], insights: string[], searchResults: object[], context: string }>}
+ */
+export async function researchIntent(intent, options = {}) {
+  const { search, llmAdapter } = options;
+  const { references, queries } = detectReferences(intent);
+
+  // No references and no search → return empty
+  if (references.length === 0 && queries.length === 0) {
+    return { references: [], insights: [], searchResults: [], context: '' };
+  }
+
+  // ── Fetch search results ──
+  const searchResults = [];
+  if (search && queries.length > 0) {
+    for (const query of queries.slice(0, 2)) {
+      try {
+        const result = await search(query);
+        if (result?.results?.length) {
+          searchResults.push(...result.results.slice(0, 3));
+        }
+      } catch {
+        // Search failed — continue without it
+      }
+    }
+  }
+
+  // ── Build context from results ──
+  const insights = [];
+
+  if (searchResults.length > 0) {
+    // Extract UI-relevant snippets
+    for (const result of searchResults) {
+      if (result.snippet) {
+        insights.push(`${result.title}: ${result.snippet}`);
+      }
+    }
+  }
+
+  // ── LLM-powered reference description (when search has no results) ──
+  if (insights.length === 0 && llmAdapter && references.length > 0) {
+    try {
+      const refList = references.join(', ');
+      const uiType = extractUIType(intent) || 'UI';
+      const response = await llmAdapter.complete({
+        messages: [{ role: 'user', content: `Briefly describe the ${uiType} design of ${refList}. Focus on: layout structure, key components, visual hierarchy, and interaction patterns. 3-4 sentences max.` }],
+        systemPrompt: 'You are a UI design expert. Give concise, factual descriptions of well-known product UIs. Focus on structure and components, not opinions.',
+      });
+      if (response.content) {
+        insights.push(response.content);
+      }
+    } catch {
+      // LLM failed — continue without it
+    }
+  }
+
+  // ── Compile context string for the generation prompt ──
+  let context = '';
+  if (references.length > 0) {
+    context += `Reference designs: ${references.join(', ')}\n`;
+  }
+  if (insights.length > 0) {
+    context += `Design insights:\n${insights.map(i => `- ${i}`).join('\n')}`;
+  }
+
+  return { references, insights, searchResults, context };
+}