@adia-ai/a2ui-retrieval 0.6.4 → 0.6.7

package/feedback/feedback.ts

@@ -1,201 +0,0 @@
-/**
- * FeedbackCollector — Structured feedback for the evolution engine.
- *
- * Captures per-generation feedback across multiple dimensions:
- *   - Overall rating (1-5)
- *   - Intent alignment, visual quality, component choice (1-5 each)
- *   - Whether the user edited the output
- *   - Pattern promotion signals ("this should become a pattern")
- *
- * Exports as a structured JSON log for the training cycle.
- */
-
-export type QualityDimensions = {
-  structural: number;
-  completeness: number;
-  idiomatic: number;
-  minimal: number;
-};
-
-export type ValidationCheck = { name: string; passed: boolean };
-
-export type GenerationData = {
-  componentCount: number;
-  componentTypes: string[];
-  score: number;
-  validationChecks: ValidationCheck[];
-  qualityDimensions: QualityDimensions;
-};
-
-export type FeedbackData = {
-  rating?: number;
-  intentAlignment?: number;
-  visualQuality?: number;
-  componentChoice?: number;
-  userEdited?: boolean;
-  editSummary?: string;
-  notes?: string;
-};
-
-export type PatternData = {
-  patternUsed?: string;
-  shouldBePattern?: boolean;
-  suggestedName?: string;
-};
-
-export type FeedbackEntry = {
-  executionId: string;
-  intent: string;
-  domain: string;
-  mode: string;
-  timestamp: number;
-  generation: GenerationData;
-  feedback: FeedbackData;
-  patterns: PatternData;
-};
-
-type ComponentLike = {
-  component?: string;
-  [key: string]: unknown;
-};
-
-type ValidationResult = {
-  score?: number;
-  checks?: Array<{ name: string; passed: boolean }>;
-};
-
-export class FeedbackCollector {
-  readonly #entries = new Map<string, FeedbackEntry>();
-
-  /**
-   * Initialize a feedback entry from generation results.
-   * Called automatically after each generation completes.
-   */
-  initFromGeneration(executionId: string, { intent, domain, mode, messages, validation }: {
-    intent?: string;
-    domain?: string;
-    mode?: string;
-    messages?: Array<{ components?: ComponentLike[] }>;
-    validation?: ValidationResult;
-  }): void {
-    const components: ComponentLike[] = messages?.[0]?.components ?? [];
-    const checks = validation?.checks ?? [];
-
-    // Compute quality dimensions
-    const failedChecks = checks.filter(c => !c.passed);
-    const structural = failedChecks.some(c =>
-      ['hasRootComponent', 'noOrphanedChildren', 'flatAdjacency'].includes(c.name)
-    ) ? 0.5 : 1;
-    const completeness = Math.max(0, 1 - (
-      failedChecks.filter(c => ['textContentSet', 'allTypesRegistered'].includes(c.name)).length * 0.1
-    ));
-    const idiomatic = failedChecks.some(c =>
-      ['noBareDivs', 'noBareInputs', 'cardStructure'].includes(c.name)
-    ) ? 0.5 : 1;
-    const minimal = failedChecks.some(c =>
-      ['noHardcodedColors', 'noInlineLayout'].includes(c.name)
-    ) ? 0.5 : 1;
-
-    this.#entries.set(executionId, {
-      executionId,
-      intent: intent ?? '',
-      domain: domain ?? '',
-      mode: mode ?? 'instant',
-      timestamp: Date.now(),
-      generation: {
-        componentCount: components.length,
-        componentTypes: [...new Set(components.map(c => c.component).filter((x): x is string => Boolean(x)))],
-        score: validation?.score ?? 0,
-        validationChecks: checks.map(c => ({ name: c.name, passed: c.passed })),
-        qualityDimensions: { structural, completeness, idiomatic, minimal },
-      },
-      feedback: {},
-      patterns: {},
-    });
-  }
-
-  /**
-   * Collect user feedback for an execution.
-   */
-  collectFeedback(executionId: string, feedback: FeedbackData): void {
-    const entry = this.#entries.get(executionId);
-    if (!entry) {
-      // Create a minimal entry if init wasn't called
-      this.#entries.set(executionId, {
-        executionId,
-        intent: '', domain: '', mode: '', timestamp: Date.now(),
-        generation: { componentCount: 0, componentTypes: [], score: 0, validationChecks: [], qualityDimensions: { structural: 0, completeness: 0, idiomatic: 0, minimal: 0 } },
-        feedback: {},
-        patterns: {},
-      });
-    }
-    const e = this.#entries.get(executionId)!;
-    e.feedback = { ...e.feedback, ...feedback };
-  }
-
-  /**
-   * Collect pattern-related feedback.
-   */
-  collectPatternFeedback(executionId: string, patternFeedback: PatternData): void {
-    const entry = this.#entries.get(executionId);
-    if (!entry) return;
-    entry.patterns = { ...entry.patterns, ...patternFeedback };
-  }
-
-  /**
-   * Get a single feedback entry.
-   */
-  get(executionId: string): FeedbackEntry | null {
-    return this.#entries.get(executionId) ?? null;
-  }
-
-  /**
-   * Get all feedback entries.
-   */
-  getAll(): FeedbackEntry[] {
-    return [...this.#entries.values()];
-  }
-
-  /** Number of entries. */
-  get size(): number {
-    return this.#entries.size;
-  }
-
-  /**
-   * Export all feedback as structured JSON.
-   * In browser: triggers a file download.
-   * In Node: returns the JSON string.
-   */
-  exportFeedback(): string {
-    const data = {
-      exportedAt: new Date().toISOString(),
-      entryCount: this.#entries.size,
-      entries: this.getAll(),
-    };
-    const json = JSON.stringify(data, null, 2);
-
-    // Browser download
-    if (typeof document !== 'undefined') {
-      const date = new Date().toISOString().slice(0, 10);
-      const blob = new Blob([json], { type: 'application/json' });
-      const url = URL.createObjectURL(blob);
-      const a = document.createElement('a');
-      a.href = url;
-      a.download = `gen-ui-feedback-${date}.json`;
-      a.style.display = 'none';
-      // Prevent SPA router from intercepting the blob URL click
-      a.addEventListener('click', (e) => e.stopPropagation());
-      document.body.appendChild(a);
-      a.click();
-      document.body.removeChild(a);
-      URL.revokeObjectURL(url);
-    }
-
-    return json;
-  }
-
-  /** Clear all entries. */
-  clear(): void {
-    this.#entries.clear();
-  }
-}

package/feedback/gap-registry.ts

@@ -1,137 +0,0 @@
-/**
- * Gap Registry
- *
- * Manages a persistent JSON file tracking identified pattern/training gaps.
- * Used by the feedback pipeline to record and track resolution of weak areas.
- *
- * Registry file: packages/a2ui/corpus/gaps/registry.json
- *
- * Usage:
- *   import { loadGaps, addGap, updateGapStatus } from './gap-registry.js';
- *   const gaps = await loadGaps();
- *   await addGap({ intentCategory: 'form/checkout', ... });
- *   await updateGapStatus('form/checkout', 'resolved', 'Added checkout pattern');
- */
-
-// `process` is not in scope under "types": []
-declare const process: { versions?: { node?: string } } | undefined;
-
-// Lazy top-level import pattern for Node-only modules
-let fs: typeof import('node:fs/promises') | null = null;
-let path: typeof import('node:path') | null = null;
-const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
-if (IS_NODE) {
-  try {
-    fs = await import(/* @vite-ignore */ 'node:fs/promises');
-    path = await import(/* @vite-ignore */ 'node:path');
-  } catch {
-    // Node builtins unavailable
-  }
-}
-
-// packages/a2ui/retrieval/feedback → up 3 → packages/a2ui → corpus/gaps/registry.json
-const REGISTRY_PATH: string | null = path
-  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..', 'a2ui/corpus', 'gaps', 'registry.json')
-  : null;
-
-export type GapStatus = 'open' | 'in-progress' | 'resolved';
-
-export type Gap = {
-  intentCategory: string;
-  detectedAt: string;
-  lastSeen: string;
-  sampleCount: number;
-  avgScore: number;
-  avgRating: number;
-  status: GapStatus;
-  resolution: string | null;
-  sampleIntents: string[];
-  resolvedAt?: string;
-};
-
-export type AddGapInput = {
-  intentCategory: string;
-  sampleCount?: number;
-  avgScore?: number;
-  avgRating?: number;
-  sampleIntents?: string[];
-};
-
-/**
- * Load all gaps from the registry file.
- */
-export async function loadGaps(): Promise<Gap[]> {
-  if (!fs || !REGISTRY_PATH) return [];
-  try {
-    const content = await fs.readFile(REGISTRY_PATH, 'utf8');
-    return JSON.parse(content) as Gap[];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Save the full gaps array to disk.
- */
-export async function saveGaps(gaps: Gap[]): Promise<void> {
-  if (!fs || !REGISTRY_PATH) return;
-  const dir = path!.dirname(REGISTRY_PATH);
-  await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(REGISTRY_PATH, JSON.stringify(gaps, null, 2) + '\n');
-}
-
-/**
- * Add a new gap to the registry. Merges with existing if same intentCategory.
- */
-export async function addGap(gap: AddGapInput): Promise<Gap[]> {
-  const gaps = await loadGaps();
-  const existing = gaps.find(g => g.intentCategory === gap.intentCategory && g.status !== 'resolved');
-
-  if (existing) {
-    // Merge: update stats, add new sample intents
-    existing.sampleCount = gap.sampleCount ?? existing.sampleCount;
-    existing.avgScore = gap.avgScore ?? existing.avgScore;
-    existing.avgRating = gap.avgRating ?? existing.avgRating;
-    existing.lastSeen = new Date().toISOString();
-    const intentSet = new Set([...existing.sampleIntents, ...(gap.sampleIntents ?? [])]);
-    existing.sampleIntents = [...intentSet].slice(0, 10);
-  } else {
-    gaps.push({
-      intentCategory: gap.intentCategory,
-      detectedAt: new Date().toISOString(),
-      lastSeen: new Date().toISOString(),
-      sampleCount: gap.sampleCount ?? 0,
-      avgScore: gap.avgScore ?? 0,
-      avgRating: gap.avgRating ?? 0,
-      status: 'open',
-      resolution: null,
-      sampleIntents: (gap.sampleIntents ?? []).slice(0, 10),
-    });
-  }
-
-  await saveGaps(gaps);
-  return gaps;
-}
-
-/**
- * Update the status of a gap by intent category.
- */
-export async function updateGapStatus(category: string, status: GapStatus, resolution?: string): Promise<Gap> {
-  const gaps = await loadGaps();
-  const gap = gaps.find(g => g.intentCategory === category && g.status !== 'resolved');
-
-  if (!gap) {
-    throw new Error(`No open gap found for category: ${category}`);
-  }
-
-  gap.status = status;
-  if (resolution) {
-    gap.resolution = resolution;
-  }
-  if (status === 'resolved') {
-    gap.resolvedAt = new Date().toISOString();
-  }
-
-  await saveGaps(gaps);
-  return gap;
-}

package/feedback/index.ts

@@ -1,14 +0,0 @@
-/**
- * @adia-ai/a2ui-retrieval/feedback — feedback-loop surface.
- *
- * Pairs the feedback store, analyzer, dialog recorder, and gap registry
- * — all the artifacts that compose the user-feedback ingestion loop.
- */
-
-export { feedbackStore } from './feedback-store.js';
-export { FeedbackAnalyzer } from './feedback-analyzer.js';
-export * from './feedback.js';
-export { recordTurn, isRecording } from './dialog-recorder.js';
-export type { TurnRecord } from './dialog-recorder.js';
-export { loadGaps, addGap, updateGapStatus } from './gap-registry.js';
-export type { Gap, GapStatus, AddGapInput } from './gap-registry.js';

package/intent/clarity.ts

@@ -1,224 +0,0 @@
-/**
- * Clarity Assessment — Evaluates whether a user intent is clear enough
- * to generate quality UI, or needs clarifying questions first.
- *
- * Scores intents across 5 dimensions:
- *   domain   — Is the domain clear? (forms, data, layout, etc.)
- *   scope    — Is the scope defined? (how many items, what sections?)
- *   content  — Is the content specified? (labels, values, data?)
- *   layout   — Is the layout preference stated? (grid, stack, sidebar?)
- *   action   — Are actions/interactions mentioned? (buttons, forms, links?)
- *
- * Returns a clarity score (0-1) and targeted questions for what's missing.
- */
-
-import { classifyIntent } from '../domain-router.js';
-import { searchAll as searchCompositions } from '../../compose/strategies/zettel/composition-library.js';
-
-// ── Dimension detectors ──────────────────────────────────────────────────
-
-/** Scope indicators: quantity, enumeration, specificity */
-const SCOPE_SIGNALS = [
-  /\b\d+\b/,                        // contains a number
-  /\b(three|two|four|five|six)\b/i,  // spelled-out numbers
-  /\b(with|containing|including|showing|displaying)\b/i,  // enumerates content
-  /\b(and|plus|also)\b/i,            // multiple items
-  /\b(columns?|rows?|items?|cards?|sections?|fields?|buttons?|tabs?|steps?)\b/i,  // structural counts
-];
-
-/** Content specificity: labels, values, named data */
-const CONTENT_SIGNALS = [
-  /\b(name|email|password|title|description|price|date|status|role|avatar)\b/i,
-  /\b(revenue|users|growth|sales|orders|metrics|analytics)\b/i,
-  /\b(todo|done|in progress|pending|active|completed)\b/i,
-  /\b(bleed|margin|trim|crop|preview|artwork|brand|design system)\b/i,
-  /\b(approved|approval|production|settings|configure|preference)\b/i,
-  /["'][\w\s]+["']/,                // quoted strings (specific labels)
-  /\$[\d,.]+/,                      // dollar amounts
-  /\d+%/,                           // percentages
-];
-
-/** Layout preferences */
-const LAYOUT_SIGNALS = [
-  /\b(grid|row|column|sidebar|split|horizontal|vertical|stack|centered)\b/i,
-  /\b(full.?width|responsive|mobile|compact|wide|narrow)\b/i,
-  /\b(\d+.?col(umn)?s?)\b/i,       // "3 columns", "2-col"
-  /\b(left|right|top|bottom|center)\b/i,
-];
-
-/** Action/interaction indicators */
-const ACTION_SIGNALS = [
-  /\b(button|submit|cancel|save|delete|edit|close|open|toggle|click)\b/i,
-  /\b(form|input|select|search|filter|sort|upload|download)\b/i,
-  /\b(login|signup|register|checkout|confirm|approve|reject)\b/i,
-  /\b(navigate|link|redirect|route)\b/i,
-  /\b(drag|drop|resize|expand|collapse)\b/i,
-];
-
-export type ClarityDimensions = {
-  domain: number;
-  scope: number;
-  content: number;
-  layout: number;
-  action: number;
-};
-
-export type ClarityQuestion = {
-  text: string;
-  dimension: string;
-  priority: number;
-};
-
-export type ClarityResult = {
-  clear: boolean;
-  score: number;
-  dimensions: ClarityDimensions;
-  questions: ClarityQuestion[];
-  summary: string;
-};
-
-type ClassificationArg = {
-  domain: string;
-  confidence: number;
-  matchedSignals: string[];
-};
-
-/**
- * Assess clarity of a user intent for UI generation.
- */
-export function assessClarity(intent: string, classification?: ClassificationArg): ClarityResult {
-  const text = (intent ?? '').trim();
-  if (!text) {
-    return {
-      clear: false,
-      score: 0,
-      dimensions: { domain: 0, scope: 0, content: 0, layout: 0, action: 0 },
-      questions: [{ text: 'What would you like me to build?', dimension: 'domain', priority: 1 }],
-      summary: 'No intent provided',
-    };
-  }
-
-  const cls = classification || classifyIntent(text);
-  const compositionMatches = searchCompositions(text);
-  const wordCount = text.split(/\s+/).length;
-
-  // ── Score each dimension ──
-
-  // Domain: how confident is the domain classification?
-  const domainScore = cls.confidence >= 0.3 ? 1 : cls.confidence >= 0.15 ? 0.6 : cls.matchedSignals.length > 0 ? 0.3 : 0;
-
-  // Scope: is the scope specific?
-  const scopeHits = SCOPE_SIGNALS.filter(r => r.test(text)).length;
-  const scopeScore = Math.min(1, scopeHits / 2);
-
-  // Content: are concrete labels/values mentioned?
-  const contentHits = CONTENT_SIGNALS.filter(r => r.test(text)).length;
-  const contentScore = Math.min(1, contentHits / 2);
-
-  // Layout: is a layout preference stated?
-  const layoutHits = LAYOUT_SIGNALS.filter(r => r.test(text)).length;
-  const layoutScore = Math.min(1, layoutHits);
-
-  // Action: are interactions mentioned?
-  const actionHits = ACTION_SIGNALS.filter(r => r.test(text)).length;
-  const actionScore = Math.min(1, actionHits / 2);
-
-  // ── Overall score (weighted) ──
-  const score = (
-    domainScore * 0.25 +
-    scopeScore * 0.25 +
-    contentScore * 0.20 +
-    layoutScore * 0.15 +
-    actionScore * 0.15
-  );
-
-  // ── Bonus: composition match adds confidence ──
-  const patternBonus = compositionMatches.length > 0 ? 0.15 : 0;
-  // Bonus: long intents are usually more specific
-  const lengthBonus = wordCount > 10 ? 0.1 : wordCount > 6 ? 0.05 : 0;
-
-  const finalScore = Math.min(1, score + patternBonus + lengthBonus);
-
-  // ── Generate targeted questions for weak dimensions ──
-  const questions: ClarityQuestion[] = [];
-
-  if (domainScore < 0.3) {
-    questions.push({
-      text: 'What type of UI is this? (e.g., a form, dashboard, profile card, settings page)',
-      dimension: 'domain',
-      priority: 1,
-    });
-  }
-
-  if (scopeScore < 0.5) {
-    const domainQuestions: Record<string, string> = {
-      forms: 'What fields should the form include?',
-      data: 'What data should be displayed? How many items or metrics?',
-      layout: 'How many sections or cards should it have?',
-      agent: 'What actions should the assistant support?',
-      navigation: 'What pages or sections should be navigable?',
-    };
-    questions.push({
-      text: domainQuestions[cls.domain] ?? 'Can you be more specific about what it should contain?',
-      dimension: 'scope',
-      priority: 2,
-    });
-  }
-
-  if (contentScore < 0.3 && scopeScore >= 0.3) {
-    const contentQuestions: Record<string, string> = {
-      forms: 'What labels should the fields have? (e.g., "Email", "Password", "Full Name")',
-      data: 'What metrics or values should be shown? (e.g., revenue, users, growth rate)',
-      layout: 'What content goes in each section?',
-      agent: 'What kind of messages or responses should be shown?',
-      navigation: 'What should the menu items or links be labeled?',
-    };
-    questions.push({
-      text: contentQuestions[cls.domain] ?? 'What specific content should be displayed?',
-      dimension: 'content',
-      priority: 3,
-    });
-  }
-
-  if (layoutScore < 0.3 && scopeScore >= 0.5) {
-    questions.push({
-      text: 'Any layout preference? (e.g., grid of cards, single column, sidebar + content)',
-      dimension: 'layout',
-      priority: 4,
-    });
-  }
-
-  if (actionScore < 0.3 && domainScore >= 0.3) {
-    questions.push({
-      text: 'What actions should users be able to take? (e.g., submit, edit, delete, filter)',
-      dimension: 'action',
-      priority: 5,
-    });
-  }
-
-  // Sort by priority, limit to 3
-  questions.sort((a, b) => a.priority - b.priority);
-  const topQuestions = questions.slice(0, 3);
-
-  // ── Determine if clear enough to proceed ──
-  // Clear only if dimensional score meets threshold
-  const clear = finalScore >= 0.4;
-
-  const summary = clear
-    ? `Intent is ${finalScore >= 0.7 ? 'clear' : 'adequate'} (${Math.round(finalScore * 100)}%)`
-    : `Intent needs clarification (${Math.round(finalScore * 100)}% — below 40% threshold)`;
-
-  return {
-    clear,
-    score: Math.round(finalScore * 100) / 100,
-    dimensions: {
-      domain: Math.round(domainScore * 100) / 100,
-      scope: Math.round(scopeScore * 100) / 100,
-      content: Math.round(contentScore * 100) / 100,
-      layout: Math.round(layoutScore * 100) / 100,
-      action: Math.round(actionScore * 100) / 100,
-    },
-    questions: topQuestions,
-    summary,
-  };
-}