@adia-ai/a2ui-retrieval 0.6.1 → 0.6.4

package/CHANGELOG.md

@@ -6,6 +6,32 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 _No pending changes._
 
+## [0.6.4] - 2026-05-18
+
+### v0.6.4 — Lockstep ride-along
+
+TS Phase 5: a2ui.schema.json schema-driven codegen (§359). No source changes in this package.
+
+
+
+## [0.6.3] - 2026-05-18
+
+### v0.6.3 — Lockstep ride-along
+
+TS Phase 5: runtime real declarations (§358) + compose branded IDs.
+No source changes in this package. Internal dep ranges stay at `^0.6.0`.
+
+
+
+## [0.6.2] - 2026-05-18
+
+### v0.6.2 §356 — TypeScript-first Phase 4: `@adia-ai/a2ui-retrieval` sources → `.ts`
+
+19 `.ts` source files. Closes TS-MIG-001 `skipLibCheck` override in
+`@adia-ai/a2ui-compose`. `tsconfig.build.json` added. **No BREAKING changes.**
+
+
+
 ## [0.6.1] - 2026-05-18
 
 ### v0.6.1 — Lockstep ride-along

package/embedding/chunk-embedding-retriever.ts

@@ -0,0 +1,156 @@
+/**
+ * Chunk embedding retriever — loads the build-time chunk embedding index
+ * and scores a query against every chunk via cosine similarity.
+ *
+ * Sibling to `embedding-retriever.js` (pattern embeddings); same provider
+ * conventions, same graceful-degradation contract.
+ *
+ * Index: packages/a2ui/corpus/chunk-embeddings.json (built by
+ * scripts/build/embeddings-chunks.mjs). When missing or empty, the
+ * retriever is effectively a no-op — callers see an empty score map and
+ * should fall back to keyword-only ranking.
+ *
+ * Used by chunk-library.searchChunks() to blend semantic + keyword scores.
+ */
+
+import { detectProvider, cosine, voyage, openai } from './embedding-provider.js';
+import type { EmbedFn } from './embedding-provider.js';
+
+// `process` is not in scope under "types": []
+declare const process: { versions?: { node?: string } } | undefined;
+
+const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
+
+type ChunkEntry = {
+  name: string;
+  vector: number[];
+};
+
+type ChunkIndex = {
+  chunks?: ChunkEntry[];
+  provider?: string;
+  model?: string;
+  dims?: number;
+};
+
+let _index: ChunkIndex | null = null;
+let _indexByName: Map<string, Float32Array> | null = null; // Map<chunk-name, Float32Array>
+let _loadPromise: Promise<ChunkIndex | null> | null = null;
+let _embedFn: EmbedFn | null = null;
+let _available: boolean | null = null;
+
+async function _loadIndex(): Promise<ChunkIndex | null> {
+  if (_index !== null) return _index;
+  if (_loadPromise) return _loadPromise;
+  _loadPromise = (async () => {
+    try {
+      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');
+        let p: string | null = null;
+        try {
+          const { createRequire } = await import(/* @vite-ignore */ 'node:module');
+          const require = createRequire(import.meta.url);
+          p = require.resolve('@adia-ai/a2ui-corpus/chunk-embeddings');
+        } catch {
+          const here = path.dirname(url.fileURLToPath(import.meta.url));
+          p = path.resolve(here, '../../corpus/chunk-embeddings.json');
+        }
+        const raw = await fs.readFile(p, 'utf8');
+        _index = JSON.parse(raw) as ChunkIndex;
+      } else {
+        const url = new URL('../../corpus/chunk-embeddings.json', import.meta.url);
+        const res = await fetch(url).catch(() => null);
+        _index = res?.ok ? await res.json().catch(() => null) as ChunkIndex : null;
+      }
+    } catch {
+      _index = null;
+    }
+    if (_index?.chunks?.length) {
+      _indexByName = new Map();
+      for (const c of _index.chunks) {
+        if (c?.name && Array.isArray(c.vector)) {
+          _indexByName.set(c.name, Float32Array.from(c.vector));
+        }
+      }
+    }
+    return _index;
+  })();
+  return _loadPromise;
+}
+
+function _resolveEmbed(providerName: string | undefined, model: string | undefined): EmbedFn | null {
+  // The index's recorded (provider, model) is the source of truth — query
+  // embeddings MUST be generated by the same model the corpus was indexed with.
+  let fn: EmbedFn | null = null;
+  if (providerName === 'voyage') fn = voyage({ model });
+  else if (providerName === 'openai') fn = openai({ model });
+  else {
+    // No provider recorded in index header (legacy index?). Fall back to auto-detect.
+    const auto = detectProvider();
+    return auto?.embed ?? null;
+  }
+  if (!fn && typeof console !== 'undefined') {
+    console.warn(
+      `[chunk-embedding-retriever] index was built with provider=${providerName} model=${model}, ` +
+      `but the corresponding API key is not set. Embeddings will be unavailable; falling back to ` +
+      `keyword-only retrieval. Set the matching API key, or rebuild the index with the available ` +
+      `provider via \`npm run build:embeddings:chunks\`.`
+    );
+  }
+  return fn;
+}
+
+export async function available(): Promise<boolean> {
+  if (_available !== null) return _available;
+  const idx = await _loadIndex();
+  if (!idx || !idx.chunks?.length) {
+    _available = false;
+    return false;
+  }
+  _embedFn = _resolveEmbed(idx.provider, idx.model);
+  _available = !!_embedFn;
+  return _available;
+}
+
+/**
+ * Embed a query and return a Map<chunk-name → cosine-score>.
+ * Returns an empty Map when unavailable (no index or no API key).
+ */
+export async function scoreAll(query: string): Promise<Map<string, number>> {
+  if (!query || typeof query !== 'string') return new Map();
+  if (!(await available())) return new Map();
+
+  let qVec: Float32Array;
+  try {
+    const [v] = await _embedFn!([query]);
+    qVec = v!;
+  } catch (e) {
+    if (typeof console !== 'undefined') console.warn('[chunk-embedding-retriever]', (e as Error).message);
+    return new Map();
+  }
+
+  const out = new Map<string, number>();
+  if (!_indexByName) return out;
+  for (const [name, vec] of _indexByName) {
+    out.set(name, cosine(qVec, vec));
+  }
+  return out;
+}
+
+export async function size(): Promise<number> {
+  const idx = await _loadIndex();
+  return idx?.chunks?.length ?? 0;
+}
+
+export type ChunkProviderInfo = {
+  provider: string | undefined;
+  model: string | undefined;
+  dims: number | undefined;
+};
+
+export async function providerInfo(): Promise<ChunkProviderInfo | null> {
+  const idx = await _loadIndex();
+  return idx ? { provider: idx.provider, model: idx.model, dims: idx.dims } : null;
+}

package/embedding/embedding-provider.ts

@@ -0,0 +1,111 @@
+/**
+ * Pluggable embedding provider. Two implementations:
+ *
+ *   voyage() — Voyage AI, voyage-3-lite by default (1024 dims).
+ *              Env: VOYAGE_API_KEY. Anthropic-recommended; generous free tier.
+ *
+ *   openai() — OpenAI text-embedding-3-small (1536 dims).
+ *              Env: OPENAI_API_KEY. Cheap ($0.02/1M tokens).
+ *
+ * detectProvider() picks Voyage if available, else OpenAI, else null.
+ * A null provider means "embeddings unavailable" — callers should fall back
+ * to keyword retrieval cleanly.
+ *
+ * Both implementations batch inputs to minimize round-trips. Every provider
+ * returns a Promise<Float32Array[]> of the same length as the input.
+ */
+
+const VOYAGE_URL = 'https://api.voyageai.com/v1/embeddings';
+const OPENAI_URL = 'https://api.openai.com/v1/embeddings';
+
+// `process` is not in scope under "types": []
+declare const process: { env?: Record<string, string | undefined> } | undefined;
+
+function getEnv(key: string): string {
+  if (typeof process !== 'undefined' && process.env?.[key]) return process.env[key] as string;
+  try {
+    const env = (import.meta as { env?: Record<string, string | undefined> }).env;
+    if (env?.[`VITE_${key}`]) return env[`VITE_${key}`] as string;
+    if (env?.[key]) return env[key] as string;
+  } catch {}
+  return '';
+}
+
+export type EmbedFn = (texts: string[]) => Promise<Float32Array[]>;
+
+export type ProviderInfo = {
+  name: string;
+  model: string;
+  embed: EmbedFn;
+};
+
+/**
+ * Voyage AI embedding provider.
+ * Returns an embed function, or null if no key.
+ */
+export function voyage({ apiKey, model = 'voyage-3-lite' }: { apiKey?: string; model?: string } = {}): EmbedFn | null {
+  const key = apiKey ?? getEnv('VOYAGE_API_KEY');
+  if (!key) return null;
+
+  return async function embed(texts: string[]): Promise<Float32Array[]> {
+    if (!Array.isArray(texts) || texts.length === 0) return [];
+    const res = await fetch(VOYAGE_URL, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'authorization': `Bearer ${key}`,
+      },
+      body: JSON.stringify({ input: texts, model, input_type: 'document' }),
+    });
+    if (!res.ok) throw new Error(`Voyage ${res.status}: ${(await res.text()).slice(0, 200)}`);
+    const data = await res.json() as { data: Array<{ embedding: number[] }> };
+    return data.data.map(d => new Float32Array(d.embedding));
+  };
+}
+
+/**
+ * OpenAI text-embedding-3-small provider.
+ * Returns an embed function, or null if no key.
+ */
+export function openai({ apiKey, model = 'text-embedding-3-small' }: { apiKey?: string; model?: string } = {}): EmbedFn | null {
+  const key = apiKey ?? getEnv('OPENAI_API_KEY');
+  if (!key) return null;
+
+  return async function embed(texts: string[]): Promise<Float32Array[]> {
+    if (!Array.isArray(texts) || texts.length === 0) return [];
+    const res = await fetch(OPENAI_URL, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'authorization': `Bearer ${key}`,
+      },
+      body: JSON.stringify({ input: texts, model }),
+    });
+    if (!res.ok) throw new Error(`OpenAI ${res.status}: ${(await res.text()).slice(0, 200)}`);
+    const data = await res.json() as { data: Array<{ embedding: number[] }> };
+    return data.data.map(d => new Float32Array(d.embedding));
+  };
+}
+
+/**
+ * Auto-detect the best available provider. Voyage first (cheaper, dense vectors
+ * at 1024 dims), then OpenAI, then null.
+ */
+export function detectProvider(): ProviderInfo | null {
+  const v = voyage(); if (v) return { name: 'voyage',  model: 'voyage-3-lite',             embed: v };
+  const o = openai(); if (o) return { name: 'openai',  model: 'text-embedding-3-small',    embed: o };
+  return null;
+}
+
+/** Cosine similarity between two Float32Arrays of the same length. */
+export function cosine(a: Float32Array, b: Float32Array): number {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += (a[i] ?? 0) * (b[i] ?? 0);
+    na  += (a[i] ?? 0) * (a[i] ?? 0);
+    nb  += (b[i] ?? 0) * (b[i] ?? 0);
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}

package/embedding/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @adia-ai/a2ui-retrieval/embedding — embedding-provider + chunk retriever surface.
+ *
+ * Since §65 (v0.4.7), the legacy pattern-embedding retriever was retired
+ * along with its only consumer (concept-mapper.js, dead post-§64). The
+ * canonical retrieval surface post-§40 is chunk-embedding-retriever.
+ */
+
+export * from './embedding-provider.js';
+export * from './chunk-embedding-retriever.js';

package/feedback/dialog-recorder.ts

@@ -0,0 +1,172 @@
+/**
+ * Dialog Recorder — write every generation turn to disk for debugging,
+ * regression analysis, and training-data bootstrapping.
+ *
+ * Output: logs/dialogs/<sessionId>/<NNN>-<turnId>.json
+ *   - <sessionId>: storeId / executionId of the multi-turn session, or
+ *                  'standalone-<isodate>' for one-shot generations.
+ *   - <NNN>:        zero-padded turn index within the session (000, 001, …)
+ *   - <turnId>:     short slug from the intent + a random suffix for uniqueness
+ *
+ * Gated by ADIA_LOG_DIALOGS=1 — opt-in, zero overhead when disabled. Browser
+ * environment is also a no-op (no fs); only Node-side generation paths log.
+ */
+
+// `process` is not in scope under "types": []
+declare const process: { versions?: { node?: string }; env?: Record<string, string | undefined> } | undefined;
+
+const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
+const ENABLED = IS_NODE && (process?.env?.['ADIA_LOG_DIALOGS'] === '1' || process?.env?.['ADIA_LOG_DIALOGS'] === 'true');
+
+// Lazy-loaded Node modules (only when ENABLED)
+let _fs: typeof import('node:fs/promises') | null = null;
+let _path: typeof import('node:path') | null = null;
+let _url: typeof import('node:url') | null = null;
+let _logsRoot: string | null = null;
+
+async function _ensureModules(): Promise<void> {
+  if (_fs) return;
+  _fs = await import(/* @vite-ignore */ 'node:fs/promises');
+  _path = await import(/* @vite-ignore */ 'node:path');
+  _url = await import(/* @vite-ignore */ 'node:url');
+  // logs/ lives at the repo root: packages/a2ui/retrieval/feedback → up 4 → repo root
+  const __dirname = _path.dirname(_url.fileURLToPath(import.meta.url));
+  _logsRoot = _path.resolve(__dirname, '..', '..', '..', '..', 'logs', 'dialogs');
+}
+
+// In-memory turn counter per session
+const _turnCounter = new Map<string, number>();
+const _sessionMetaWritten = new Set<string>();
+
+export type TurnRecord = {
+  sessionId?: string;
+  intent?: string;
+  mode?: string;
+  engine?: string;
+  model?: string;
+  analysis?: {
+    steelman?: string;
+    concepts?: string[];
+    impliedComponents?: string[];
+    styleHints?: string[];
+  };
+  currentCanvas?: unknown;
+  patterns?: Array<{ name?: string; score?: number; confidence?: number; keywords?: string[] | null }>;
+  systemPrompt?: string;
+  rawLLMResponse?: string;
+  messages?: unknown[];
+  validation?: unknown;
+  drift?: unknown;
+  suggestions?: string[];
+  timing?: unknown;
+  tokens?: unknown;
+  engineDebug?: unknown;
+  isIteration?: boolean;
+};
+
+/**
+ * Record one generation turn. Safe to call unconditionally — when the env var
+ * is unset, this is a no-op that returns immediately.
+ *
+ * @returns The path written, or null when logging is disabled.
+ */
+export async function recordTurn(record: TurnRecord): Promise<string | null> {
+  if (!ENABLED) return null;
+
+  try {
+    await _ensureModules();
+
+    const sessionId = record.sessionId ?? `standalone-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    const turnIdx = (_turnCounter.get(sessionId) ?? 0);
+    _turnCounter.set(sessionId, turnIdx + 1);
+
+    const slug = String(record.intent ?? 'turn')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 32) || 'turn';
+    const rand = Math.random().toString(36).slice(2, 6);
+    const fileName = `${String(turnIdx).padStart(3, '0')}-${slug}-${rand}.json`;
+
+    const sessionDir = _path!.join(_logsRoot!, sessionId);
+    await _fs!.mkdir(sessionDir, { recursive: true });
+
+    if (!_sessionMetaWritten.has(sessionId) && turnIdx === 0) {
+      _sessionMetaWritten.add(sessionId);
+      const sessionMeta = {
+        sessionId,
+        startedAt: new Date().toISOString(),
+        originIntent: record.intent ?? null,
+        engine: record.engine ?? null,
+        mode: record.mode ?? null,
+        model: record.model ?? null,
+        originAnalysis: record.analysis ? {
+          steelman: record.analysis.steelman ?? null,
+          concepts: record.analysis.concepts ?? [],
+          impliedComponents: record.analysis.impliedComponents ?? [],
+          styleHints: record.analysis.styleHints ?? [],
+        } : null,
+      };
+      await _fs!.writeFile(
+        _path!.join(sessionDir, '_session.json'),
+        JSON.stringify(sessionMeta, null, 2) + '\n',
+      );
+    }
+
+    const payload = {
+      // ── Identity ────────────────────────────────────────────────
+      sessionId,
+      turnIndex: turnIdx,
+      timestamp: new Date().toISOString(),
+      isIteration: !!record.isIteration,
+
+      // ── Request ─────────────────────────────────────────────────
+      intent: record.intent,
+      mode: record.mode ?? null,
+      engine: record.engine ?? null,
+      model: record.model ?? null,
+      currentCanvas: record.currentCanvas ?? null,
+
+      // ── Pipeline-side reasoning ─────────────────────────────────
+      analysis: record.analysis ?? null,
+      patterns: (record.patterns ?? []).slice(0, 10).map(p => ({
+        name: p.name,
+        score: p.score ?? p.confidence ?? null,
+        keywords: p.keywords ?? null,
+      })),
+
+      // ── LLM I/O ─────────────────────────────────────────────────
+      systemPrompt: record.systemPrompt ?? null,
+      rawLLMResponse: record.rawLLMResponse ?? null,
+
+      // ── Result ──────────────────────────────────────────────────
+      messages: record.messages ?? [],
+      validation: record.validation ?? null,
+      drift: record.drift ?? null,
+      suggestions: record.suggestions ?? [],
+
+      // ── Telemetry ───────────────────────────────────────────────
+      timing: record.timing ?? null,
+      tokens: record.tokens ?? null,
+      engineDebug: record.engineDebug ?? null,
+    };
+
+    const filePath = _path!.join(sessionDir, fileName);
+    await _fs!.writeFile(filePath, JSON.stringify(payload, null, 2) + '\n');
+    return filePath;
+  } catch (err) {
+    // Logging must NEVER break a generation. Swallow + warn once per turn.
+    console.warn('[dialog-recorder] failed to record turn:', (err as Error).message);
+    return null;
+  }
+}
+
+/** True when logging is on. Useful for guarding expensive capture work. */
+export function isRecording(): boolean {
+  // ENABLED is already gated by IS_NODE at module init. The A2UI_COMPOSE_TRACE
+  // bypass must guard `process` again — without it, browser callers throw
+  // `ReferenceError: process is not defined` after a successful LLM round-trip.
+  if (ENABLED) return true;
+  const IS_NODE_RT = typeof process !== 'undefined' && process.versions?.node;
+  return IS_NODE_RT ? !!(process?.env?.['A2UI_COMPOSE_TRACE']) : false;
+}