@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/engine/consolidate.mjs

@@ -0,0 +1,287 @@
+/**
+ * lib/engine/consolidate.mjs — sleep-time consolidation for the observation store.
+ *
+ * Periodically clusters near-duplicate observations by cosine similarity and
+ * merges each cluster into a single consolidated insight that records the
+ * representative, hit count, member ids, and last-seen timestamp. Optionally
+ * summarises clusters via a Compressor plugin (or via any LM the operator
+ * wires in) — when no summariser is provided, the representative observation's
+ * own summary is kept verbatim.
+ *
+ * Outputs:
+ *   .cx/observations/consolidated.json    list of insight clusters
+ *   .cx/observations/archive/<id>.json    observations demoted to cold archive
+ *
+ * The pass is idempotent: re-running it on a stable corpus produces the same
+ * cluster set. It is safe to schedule as a cron / launchd job, run in the
+ * embed daemon, or invoke ad-hoc as `construct memory consolidate`.
+ *
+ * Plugin entry points:
+ *   `summariser`  - any object with `compress(text, opts)` (Compressor contract)
+ *                   that generates a one-line cluster summary from member text.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { cosineSimilarity } from '../storage/embeddings.mjs';
+
+const OBS_DIR = '.cx/observations';
+const ARCHIVE_DIR = '.cx/observations/archive';
+const CONSOLIDATED_FILE = 'consolidated.json';
+const VECTORS_FILE = 'vectors.json';
+const INDEX_FILE = 'index.json';
+
+const DEFAULTS = {
+  similarityThreshold: 0.95,
+  archiveAfterDays: 60,
+  archiveBelowConfidence: 0.5,
+  maxStored: 5000,
+  // Archive retention: keep at most this many archived files, and delete
+  // anything older than archiveRetainDays. Both bounds apply.
+  archiveRetainDays: 365,
+  archiveMaxFiles: 1000,
+};
+
+function readJsonOrEmpty(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function readObservation(rootDir, id) {
+  const filePath = path.join(rootDir, OBS_DIR, `${id}.json`);
+  if (!fs.existsSync(filePath)) return null;
+  return readJsonOrEmpty(filePath, null);
+}
+
+function archiveObservation(rootDir, id) {
+  const src = path.join(rootDir, OBS_DIR, `${id}.json`);
+  if (!fs.existsSync(src)) return false;
+  const archiveDir = path.join(rootDir, ARCHIVE_DIR);
+  fs.mkdirSync(archiveDir, { recursive: true });
+  const dest = path.join(archiveDir, `${id}.json`);
+  fs.renameSync(src, dest);
+  return true;
+}
+
+function daysAgo(dateStr) {
+  if (!dateStr) return Infinity;
+  return (Date.now() - new Date(dateStr).getTime()) / (24 * 60 * 60 * 1000);
+}
+
+/**
+ * Greedy single-pass clustering. Each observation is added to the existing
+ * cluster whose centroid has highest cosine similarity, provided that
+ * similarity exceeds `threshold`. Otherwise a new cluster is opened. The
+ * centroid is recomputed as a running mean as members join.
+ *
+ * Stable across runs because the input is sorted by id before clustering.
+ */
+function greedyCluster(records, threshold) {
+  const sorted = [...records].sort((a, b) => String(a.id).localeCompare(String(b.id)));
+  const clusters = [];
+
+  for (const record of sorted) {
+    if (!record.embedding || record.embedding.length === 0) {
+      clusters.push({
+        centroid: [],
+        members: [record],
+      });
+      continue;
+    }
+    let bestIdx = -1;
+    let bestSim = threshold;
+    for (let i = 0; i < clusters.length; i++) {
+      const cluster = clusters[i];
+      if (cluster.centroid.length !== record.embedding.length) continue;
+      const sim = cosineSimilarity(record.embedding, cluster.centroid);
+      if (sim > bestSim) {
+        bestSim = sim;
+        bestIdx = i;
+      }
+    }
+    if (bestIdx >= 0) {
+      const cluster = clusters[bestIdx];
+      const n = cluster.members.length;
+      const next = new Array(record.embedding.length);
+      for (let j = 0; j < record.embedding.length; j++) {
+        next[j] = (cluster.centroid[j] * n + record.embedding[j]) / (n + 1);
+      }
+      cluster.centroid = next;
+      cluster.members.push(record);
+    } else {
+      clusters.push({
+        centroid: [...record.embedding],
+        members: [record],
+      });
+    }
+  }
+
+  return clusters;
+}
+
+async function buildSummary(cluster, summariser) {
+  const representative = cluster.members[0];
+  const baseText = representative?.summary || representative?.content || '';
+  if (!summariser || typeof summariser.compress !== 'function') return baseText;
+  try {
+    const merged = cluster.members
+      .map((m) => m?.summary || m?.content || '')
+      .filter(Boolean)
+      .join(' ');
+    return await summariser.compress(merged, { ratio: 0.4, maxTokens: 60 });
+  } catch {
+    return baseText;
+  }
+}
+
+/**
+ * Run a consolidation pass against a project root.
+ *
+ * @param {string} rootDir
+ * @param {object} [opts]
+ * @param {number} [opts.similarityThreshold=0.95]
+ * @param {number} [opts.archiveAfterDays=60]
+ * @param {number} [opts.archiveBelowConfidence=0.5]
+ * @param {number} [opts.maxStored=5000]
+ * @param {object} [opts.summariser] - Compressor-shaped plugin
+ * @returns {Promise<{ clustersBefore: number, clusters: number, archived: string[], stored: number }>}
+ */
+export async function consolidate(rootDir, opts = {}) {
+  const settings = { ...DEFAULTS, ...opts };
+  const obsRoot = path.join(rootDir, OBS_DIR);
+  if (!fs.existsSync(obsRoot)) {
+    return { clustersBefore: 0, clusters: 0, archived: [], stored: 0 };
+  }
+
+  const vectorsPath = path.join(obsRoot, VECTORS_FILE);
+  const vectors = readJsonOrEmpty(vectorsPath, []);
+  const records = vectors.map((v) => {
+    const full = readObservation(rootDir, v.id);
+    if (!full) return null;
+    return {
+      id: v.id,
+      embedding: v.embedding || [],
+      summary: full.summary || '',
+      content: full.content || '',
+      tags: full.tags || [],
+      role: full.role || null,
+      category: full.category || null,
+      confidence: typeof full.confidence === 'number' ? full.confidence : 0.8,
+      createdAt: full.createdAt || null,
+    };
+  }).filter(Boolean);
+
+  const clustersBefore = records.length;
+
+  const archived = [];
+  const liveRecords = records.filter((r) => {
+    const old = daysAgo(r.createdAt) > settings.archiveAfterDays;
+    const lowConfidence = r.confidence < settings.archiveBelowConfidence;
+    if (old && lowConfidence) {
+      if (archiveObservation(rootDir, r.id)) archived.push(r.id);
+      return false;
+    }
+    return true;
+  });
+
+  const clusters = greedyCluster(liveRecords, settings.similarityThreshold);
+
+  const consolidated = [];
+  for (const cluster of clusters) {
+    const representative = cluster.members[0];
+    const summary = await buildSummary(cluster, settings.summariser);
+    const lastSeen = cluster.members.reduce((acc, m) => {
+      if (!m.createdAt) return acc;
+      return acc && new Date(acc) > new Date(m.createdAt) ? acc : m.createdAt;
+    }, null);
+    consolidated.push({
+      id: `consolidated:${representative.id}`,
+      representativeId: representative.id,
+      hitCount: cluster.members.length,
+      summary,
+      role: representative.role,
+      category: representative.category,
+      tags: [...new Set(cluster.members.flatMap((m) => m.tags || []))].slice(0, 10),
+      memberIds: cluster.members.map((m) => m.id),
+      avgConfidence:
+        cluster.members.reduce((acc, m) => acc + (m.confidence || 0), 0) /
+        Math.max(cluster.members.length, 1),
+      lastSeen,
+    });
+  }
+
+  consolidated.sort((a, b) => (b.hitCount - a.hitCount) || (a.id < b.id ? -1 : 1));
+
+  if (consolidated.length > settings.maxStored) {
+    const dropped = consolidated.slice(settings.maxStored);
+    for (const insight of dropped) {
+      for (const memberId of insight.memberIds) {
+        if (archiveObservation(rootDir, memberId)) archived.push(memberId);
+      }
+    }
+    consolidated.length = settings.maxStored;
+  }
+
+  fs.mkdirSync(obsRoot, { recursive: true });
+  fs.writeFileSync(
+    path.join(obsRoot, CONSOLIDATED_FILE),
+    JSON.stringify(consolidated, null, 2) + '\n'
+  );
+
+  if (archived.length > 0) {
+    const indexPath = path.join(obsRoot, INDEX_FILE);
+    const index = readJsonOrEmpty(indexPath, []);
+    const archivedSet = new Set(archived);
+    const filtered = index.filter((entry) => !archivedSet.has(entry.id));
+    if (filtered.length !== index.length) {
+      fs.writeFileSync(indexPath, JSON.stringify(filtered, null, 2) + '\n');
+    }
+  }
+
+  const archivePruned = pruneArchive(rootDir, settings);
+
+  return {
+    clustersBefore,
+    clusters: consolidated.length,
+    archived,
+    archivePruned,
+    stored: consolidated.length,
+  };
+}
+
+// Prune the cold archive directory: delete files older than archiveRetainDays,
+// then keep at most archiveMaxFiles by mtime descending. Returns number deleted.
+export function pruneArchive(rootDir, opts = {}) {
+  const settings = { ...DEFAULTS, ...opts };
+  const archiveDir = path.join(rootDir, ARCHIVE_DIR);
+  if (!fs.existsSync(archiveDir)) return 0;
+
+  const cutoffMs = Date.now() - settings.archiveRetainDays * 24 * 60 * 60 * 1000;
+  const files = fs.readdirSync(archiveDir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      const full = path.join(archiveDir, f);
+      const stat = fs.statSync(full);
+      return { name: f, path: full, mtime: stat.mtimeMs };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+
+  let deleted = 0;
+  const kept = [];
+  for (const file of files) {
+    if (file.mtime < cutoffMs) {
+      try { fs.unlinkSync(file.path); deleted += 1; } catch { /* best effort */ }
+    } else {
+      kept.push(file);
+    }
+  }
+  if (kept.length > settings.archiveMaxFiles) {
+    for (const file of kept.slice(settings.archiveMaxFiles)) {
+      try { fs.unlinkSync(file.path); deleted += 1; } catch { /* best effort */ }
+    }
+  }
+  return deleted;
+}

package/lib/engine/contracts.mjs

@@ -0,0 +1,126 @@
+/**
+ * lib/engine/contracts.mjs — Six stable plugin contracts for the Construct retrieval engine.
+ *
+ * Each layer of the recall stack is defined here as a runtime-checkable contract:
+ *   Embedder, Chunker, Indexer, Fuser, Reranker, Compressor.
+ *
+ * External git projects can satisfy any contract by exporting a factory that returns
+ * an object with the listed methods and a `meta` object. The resolver
+ * (lib/engine/registry.mjs) validates against `assertContract(layer, plugin)` before
+ * accepting a plugin; failures fall back to the default impl and are logged via
+ * lib/hooks/_lib/log.mjs.
+ *
+ * Contracts are intentionally narrow. They describe what the engine needs, nothing
+ * about how a plugin implements it. Capabilities are declared on `plugin.meta` so
+ * callers can reason about batch support, async cost, dimensions, max tokens, etc.
+ *
+ * Layer dependencies:
+ *   Embedder is required by Indexer (for query embedding) and Reranker.
+ *   Indexer is required at retrieve time.
+ *   Fuser combines Indexer outputs.
+ *   Reranker reorders Fuser output.
+ *   Compressor is applied independently to text blocks (chunks, prompts, injections).
+ *   Chunker is upstream of Embedder at index-build time only.
+ */
+
+export const LAYERS = Object.freeze([
+  'embedder',
+  'chunker',
+  'indexer',
+  'fuser',
+  'reranker',
+  'compressor',
+]);
+
+// Contract definitions. Each entry lists the required `meta` fields and method
+// signatures the plugin must expose. Method bodies may be sync OR async — the
+// engine awaits all results, so plugins are free to be either.
+
+const CONTRACTS = {
+  embedder: {
+    meta: ['id', 'modelId', 'dimensions'],
+    methods: ['embed', 'embedBatch'],
+  },
+  chunker: {
+    meta: ['id'],
+    methods: ['chunk'],
+  },
+  indexer: {
+    meta: ['id'],
+    methods: ['store', 'query', 'health'],
+  },
+  fuser: {
+    meta: ['id'],
+    methods: ['fuse'],
+  },
+  reranker: {
+    meta: ['id'],
+    methods: ['rerank'],
+  },
+  compressor: {
+    meta: ['id'],
+    methods: ['compress'],
+  },
+};
+
+/**
+ * Throws if `plugin` does not satisfy the contract for `layer`.
+ *
+ * @param {string} layer — one of LAYERS
+ * @param {object} plugin — plugin instance returned from a factory
+ */
+export function assertContract(layer, plugin) {
+  if (!LAYERS.includes(layer)) {
+    throw new Error(`Unknown plugin layer: ${layer}`);
+  }
+  if (!plugin || typeof plugin !== 'object') {
+    throw new Error(`${layer} plugin: must be a non-null object`);
+  }
+
+  const spec = CONTRACTS[layer];
+  const meta = plugin.meta;
+  if (!meta || typeof meta !== 'object') {
+    throw new Error(`${layer} plugin: missing required 'meta' object`);
+  }
+
+  for (const key of spec.meta) {
+    if (meta[key] === undefined || meta[key] === null || meta[key] === '') {
+      throw new Error(`${layer} plugin: meta.${key} is required`);
+    }
+  }
+
+  for (const fn of spec.methods) {
+    if (typeof plugin[fn] !== 'function') {
+      throw new Error(`${layer} plugin (${meta.id}): missing method '${fn}'`);
+    }
+  }
+
+  // Embedder must declare positive integer dimensions so downstream Indexer can
+  // assert schema compatibility before the first store call.
+  if (layer === 'embedder') {
+    const dim = meta.dimensions;
+    if (!Number.isInteger(dim) || dim <= 0) {
+      throw new Error(`embedder plugin (${meta.id}): meta.dimensions must be a positive integer`);
+    }
+  }
+}
+
+/**
+ * Lightweight, dependency-free contract test for use in `construct doctor` and
+ * plugin author CI. Returns `{ ok, errors }` instead of throwing so a single run
+ * can report on every plugin.
+ *
+ * @param {string} layer
+ * @param {object} plugin
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function checkContract(layer, plugin) {
+  try {
+    assertContract(layer, plugin);
+    return { ok: true, errors: [] };
+  } catch (err) {
+    return { ok: false, errors: [err.message] };
+  }
+}
+
+export const CONTRACT_DEFINITIONS = CONTRACTS;

package/lib/engine/defaults.mjs

@@ -0,0 +1,129 @@
+/**
+ * lib/engine/defaults.mjs — Built-in default plugin implementations.
+ *
+ * Each export is a factory that returns a contract-satisfying plugin instance.
+ * Defaults are deliberately the minimum needed to keep the contract live; the
+ * stronger implementations live in their own modules and are wired in below.
+ *
+ * Embedder default is `local-onnx` (Xenova/all-MiniLM-L6-v2, 384d). The default
+ * wraps `lib/storage/embeddings-engine.mjs` under the Embedder contract so
+ * callers go through `engine.layers.embedder` exclusively.
+ */
+
+// The Embedder default routes through the model-agnostic engine so the
+// configured model (local | openai | ollama | hashing) drives dimensionality
+// and behavior end-to-end through one call site.
+
+import {
+  embedText as embedTextEngine,
+  embedBatch as embedBatchEngine,
+  getEmbeddingModelInfo,
+} from '../storage/embeddings-engine.mjs';
+
+// ── Embedder default ──────────────────────────────────────────────────────
+
+export function createDefaultEmbedder() {
+  return {
+    meta: {
+      id: 'construct-default-embedder',
+      modelId: 'pending-init',
+      dimensions: 1,
+    },
+    async init() {
+      const info = await getEmbeddingModelInfo();
+      this.meta.modelId = info.model;
+      this.meta.dimensions = info.dimensions;
+      return this;
+    },
+    async embed(text) {
+      const r = await embedTextEngine(text);
+      return r.embedding;
+    },
+    async embedBatch(texts) {
+      const results = await embedBatchEngine(texts);
+      return results.map((r) => r.embedding);
+    },
+  };
+}
+
+// ── Chunker default ───────────────────────────────────────────────────────
+
+// Heading-prefix chunker: splits markdown at heading boundaries and
+// prepends each chunk with its heading chain so retrieved chunks carry
+// doc-relative context. Operators that want LM-generated per-chunk context
+// (the strongest known retrieval technique) plug it in via the Chunker slot.
+
+import { create as createHeadingsChunker } from './chunker-headings.mjs';
+
+export function createDefaultChunker() {
+  return createHeadingsChunker();
+}
+
+// ── Indexer default ───────────────────────────────────────────────────────
+
+// Storage is delegated to `lib/storage/vector-client.mjs` and
+// `lib/storage/sync.mjs`. The default indexer here is a thin contract
+// surface; richer indexer plugins (e.g. external vector DBs) can replace it.
+
+export function createDefaultIndexer() {
+  return {
+    meta: { id: 'construct-default-indexer', mode: 'pgvector-or-file' },
+    async store(/* chunks, embeddings */) {
+      return { stored: 0, mode: 'deferred', note: 'store delegated to lib/storage/sync.mjs' };
+    },
+    async query(/* queryEmbedding, opts */) {
+      return [];
+    },
+    async health() {
+      return { ok: true, mode: 'delegated', note: 'health checks live in lib/storage/vector-client.mjs' };
+    },
+  };
+}
+
+// ── Fuser default ─────────────────────────────────────────────────────────
+
+// Reciprocal Rank Fusion (RRF) — corpus-agnostic, parameter-light, removes
+// the BM25/cosine top-K asymmetry that the previous weighted-sum had.
+
+import { create as createRrfFuser } from './fuser-rrf.mjs';
+import { create as createMmrReranker } from './reranker-mmr.mjs';
+
+export function createDefaultFuser() {
+  return createRrfFuser();
+}
+
+// ── Reranker default ──────────────────────────────────────────────────────
+
+// Maximal Marginal Relevance (MMR) — balances relevance against diversity to
+// drop near-duplicates without a hard threshold. λ=0.7 favors relevance.
+
+export function createDefaultReranker() {
+  return createMmrReranker();
+}
+
+// ── Compressor default ────────────────────────────────────────────────────
+
+// TF-IDF sentence-selector compressor — zero deps, modest compression that
+// runs on every machine. Operators that want learned compression
+// (LLMLingua-style) plug it in via the Compressor slot.
+
+import { create as createHeuristicCompressor } from './compressor-heuristic.mjs';
+
+export function createDefaultCompressor() {
+  return createHeuristicCompressor();
+}
+
+// ── Aggregate loader ──────────────────────────────────────────────────────
+
+export async function loadDefaults() {
+  const embedder = createDefaultEmbedder();
+  if (typeof embedder.init === 'function') await embedder.init();
+  return {
+    embedder,
+    chunker: createDefaultChunker(),
+    indexer: createDefaultIndexer(),
+    fuser: createDefaultFuser(),
+    reranker: createDefaultReranker(),
+    compressor: createDefaultCompressor(),
+  };
+}

package/lib/engine/eval-retrieval.mjs

@@ -0,0 +1,148 @@
+/**
+ * lib/engine/eval-retrieval.mjs — Retrieval-quality evaluation harness.
+ *
+ * Runs a fixed query set against a corpus through the engine's retrieval
+ * pipeline (BM25 + cosine → RRF fuse → MMR rerank, with whatever plugins
+ * are active) and reports standard IR metrics:
+ *
+ *   - Recall@k     fraction of expected docs that appear in the top-k
+ *   - MRR          mean reciprocal rank of the first expected doc
+ *   - NDCG@k       discounted cumulative gain over the top-k
+ *
+ * The harness is corpus-agnostic — callers pass in chunks (each with id,
+ * title, body) and a list of queries with expected doc ids. The pipeline
+ * itself is the same one `lib/knowledge/rag.mjs::retrieve` uses, so any
+ * plugin swap (Fuser, Reranker, etc.) is reflected in the metrics.
+ *
+ * The CLI surface (`construct evals retrieval`) loads a fixture file
+ * shipped at `tests/fixtures/retrieval-eval/queries.json` against an
+ * inline mini-corpus, but callers can also provide their own datasets.
+ */
+
+import { readFileSync } from 'node:fs';
+import { rankByBm25, cosineSimilarity } from '../storage/embeddings.mjs';
+import { embedSync } from '../storage/embeddings-legacy.mjs';
+import { getEngine } from './index.mjs';
+
+function buildEmbeddedCorpus(chunks) {
+  return chunks.map((c) => ({
+    ...c,
+    embedding: embedSync(`${c.title || ''} ${c.body || ''}`),
+  }));
+}
+
+async function retrieveOne(query, corpus, engine, topK) {
+  const queryEmbedding = embedSync(query);
+  const bm25Ranked = rankByBm25(
+    corpus.map((c) => ({ ...c, text: `${c.title || ''} ${c.body || ''}` })),
+    query,
+    { limit: corpus.length },
+  );
+  const cosineRanked = corpus
+    .map((chunk) => ({
+      ...chunk,
+      score: cosineSimilarity(queryEmbedding, chunk.embedding || []),
+    }))
+    .filter((c) => c.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  const fused = engine.layers.fuser.fuse({ bm25: bm25Ranked, cosine: cosineRanked });
+  const reranked = await engine.layers.reranker.rerank(query, fused, {
+    queryEmbedding,
+    topK,
+  });
+  return reranked;
+}
+
+function recallAt(ranked, expectedIds, k) {
+  const top = new Set(ranked.slice(0, k).map((r) => r.id));
+  let hits = 0;
+  for (const id of expectedIds) if (top.has(id)) hits++;
+  return expectedIds.length === 0 ? 0 : hits / expectedIds.length;
+}
+
+function reciprocalRank(ranked, expectedIds) {
+  for (let i = 0; i < ranked.length; i++) {
+    if (expectedIds.includes(ranked[i].id)) return 1 / (i + 1);
+  }
+  return 0;
+}
+
+function ndcgAt(ranked, expectedIds, k) {
+  const expected = new Set(expectedIds);
+  let dcg = 0;
+  for (let i = 0; i < Math.min(k, ranked.length); i++) {
+    if (expected.has(ranked[i].id)) {
+      dcg += 1 / Math.log2(i + 2);
+    }
+  }
+  let idcg = 0;
+  for (let i = 0; i < Math.min(k, expectedIds.length); i++) {
+    idcg += 1 / Math.log2(i + 2);
+  }
+  return idcg === 0 ? 0 : dcg / idcg;
+}
+
+/**
+ * Run the evaluation. Returns aggregate metrics + a per-query breakdown.
+ *
+ * @param {object} args
+ * @param {Array<{ id, title, body }>} args.corpus
+ * @param {Array<{ query, expected: string[] }>} args.queries
+ * @param {object} [args.engine] — pre-resolved engine (for tests)
+ * @param {number} [args.topK=5]
+ * @returns {Promise<{
+ *   recallAt1, recallAt5, mrr, ndcgAt5,
+ *   queries: Array<{ query, expected, ranked: string[], recallAt1, recallAt5, mrr, ndcgAt5 }>,
+ * }>}
+ */
+export async function evaluateRetrieval({ corpus, queries, engine, topK = 5 }) {
+  const eng = engine || (await getEngine());
+  const embedded = buildEmbeddedCorpus(corpus);
+
+  const results = [];
+  for (const { query, expected } of queries) {
+    const ranked = await retrieveOne(query, embedded, eng, Math.max(topK, 5));
+    results.push({
+      query,
+      expected,
+      ranked: ranked.slice(0, topK).map((r) => r.id),
+      recallAt1: recallAt(ranked, expected, 1),
+      recallAt5: recallAt(ranked, expected, 5),
+      mrr: reciprocalRank(ranked, expected),
+      ndcgAt5: ndcgAt(ranked, expected, 5),
+    });
+  }
+
+  const mean = (key) => results.reduce((acc, r) => acc + r[key], 0) / Math.max(results.length, 1);
+
+  return {
+    queryCount: results.length,
+    corpusSize: corpus.length,
+    recallAt1: mean('recallAt1'),
+    recallAt5: mean('recallAt5'),
+    mrr: mean('mrr'),
+    ndcgAt5: mean('ndcgAt5'),
+    queries: results,
+  };
+}
+
+/**
+ * Convenience: load a JSON fixture { corpus, queries } from disk and run.
+ */
+export async function evaluateFixture(fixturePath, opts = {}) {
+  const data = JSON.parse(readFileSync(fixturePath, 'utf8'));
+  return evaluateRetrieval({ ...data, ...opts });
+}
+
+export function formatReport(report) {
+  const pct = (x) => `${(x * 100).toFixed(1)}%`;
+  const lines = [
+    `Corpus: ${report.corpusSize} chunks · Queries: ${report.queryCount}`,
+    `Recall@1:  ${pct(report.recallAt1)}`,
+    `Recall@5:  ${pct(report.recallAt5)}`,
+    `MRR:       ${report.mrr.toFixed(3)}`,
+    `NDCG@5:    ${report.ndcgAt5.toFixed(3)}`,
+  ];
+  return lines.join('\n');
+}