md-semantic-search 1.0.2 → 1.0.3

package/dist/providers.js

@@ -0,0 +1,104 @@
+/**
+ * Pluggable embedding providers (issue #124): Ollama and OpenAI-compatible
+ * endpoints beside the built-in local transformers.js path.
+ *
+ * Design: a provider produces (a) an async embedFn with the SAME signature as
+ * core.embed(texts, role, model, cacheDir, offline) and (b) a synthetic
+ * ModelAdapter descriptor. The descriptor flows through the EXISTING machinery
+ * (adapter fingerprint, dim validation, index metadata) so switching providers
+ * invalidates vectors exactly like switching local models — no special cases.
+ *
+ * Local transformers.js stays the zero-config default and the only fully
+ * offline path; providers are opt-in via explicit flags.
+ */
+import { loadApiKeyFile } from './serve.js';
+function baseOf(cfg) {
+    const raw = cfg.baseUrl ||
+        (cfg.embedder === 'ollama' ? process.env.OLLAMA_HOST || 'http://127.0.0.1:11434' : 'https://api.openai.com/v1');
+    return raw.replace(/\/$/, '');
+}
+function bearerKey(cfg) {
+    if (cfg.embedder !== 'openai')
+        return undefined;
+    if (cfg.keyFile)
+        return loadApiKeyFile(cfg.keyFile);
+    return process.env.OPENAI_API_KEY || undefined;
+}
+async function postJson(fetchImpl, url, headers, body) {
+    const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`embedder ${url} -> HTTP ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`);
+    }
+    return res.json();
+}
+/** Build an external embedder; dim is probed once on first use and cached. */
+export function resolveExternalEmbedder(cfg) {
+    const fetchImpl = cfg.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function')
+        throw new Error('embedder: no fetch implementation available');
+    let cachedDim = 0;
+    const embedOneBatch = async (texts) => {
+        if (cfg.embedder === 'ollama') {
+            const data = await postJson(fetchImpl, `${baseOf(cfg)}/api/embed`, {}, { model: cfg.model, input: texts });
+            const embs = data?.embeddings;
+            if (!Array.isArray(embs) || embs.length !== texts.length) {
+                throw new Error('ollama /api/embed returned unexpected shape');
+            }
+            return embs;
+        }
+        // OpenAI-compatible
+        const headers = {};
+        const key = bearerKey(cfg);
+        if (key)
+            headers.authorization = `Bearer ${key}`;
+        const data = await postJson(fetchImpl, `${baseOf(cfg)}/embeddings`, headers, {
+            model: cfg.model,
+            input: texts,
+        });
+        const rows = data?.data;
+        if (!Array.isArray(rows) || rows.length !== texts.length) {
+            throw new Error('openai /embeddings returned unexpected shape');
+        }
+        return rows
+            .slice()
+            .sort((a, b) => a.index - b.index)
+            .map((r) => r.embedding);
+    };
+    const embedFn = async (texts, _role) => {
+        if (texts.length === 0)
+            return [];
+        const out = await embedOneBatch(texts);
+        if (cachedDim === 0 && out[0]?.length)
+            cachedDim = out[0].length;
+        return out;
+    };
+    // Dim probing: one tiny request at resolve time keeps index metadata honest
+    // without hardcoding per-model tables.
+    const descriptorPromise = (async () => {
+        const probe = await embedOneBatch(['dim probe']);
+        cachedDim = probe[0]?.length ?? 0;
+        if (!cachedDim)
+            throw new Error(`embedder ${cfg.embedder}:${cfg.model} returned an empty embedding`);
+        return {
+            id: `${cfg.embedder}/${cfg.model}`,
+            nativeDim: cachedDim,
+            dim: cachedDim,
+            queryPrefix: '',
+            passagePrefix: '',
+            pooling: 'mean',
+            normalize: false, // never assume; cosine still works on unnormalized vectors
+            family: cfg.embedder,
+        };
+    })();
+    return {
+        id: cfg.embedder,
+        model: cfg.model,
+        embedFn,
+        descriptor: () => descriptorPromise,
+    };
+}

package/dist/query-cache-disk.d.ts

@@ -0,0 +1,14 @@
+export declare const QUERY_CACHE_FILE = "query-cache.json";
+export declare const QUERY_CACHE_MAX_ENTRIES = 512;
+export declare function buildDiskKey(modelId: string, revision: string, dim: number | undefined, query: string): string;
+/**
+ * Look up a query vector on disk. Returns null on any miss/corruption —
+ * callers fall through to embedding without ceremony.
+ */
+export declare function diskQueryGet(cacheDir: string | undefined, key: string, expectedDim: number | undefined): Float32Array | null;
+/** Store a computed query vector (fire-and-forget, debounced flush). */
+export declare function diskQueryPut(cacheDir: string | undefined, key: string, vec: number[] | Float32Array): void;
+/** Test helper: force-write now. */
+export declare function flushQueryCacheNow(cacheDir: string): void;
+/** Test helper: forget in-process state so the next get/put reloads from disk. */
+export declare function resetQueryCacheForTest(cacheDir?: string): void;

package/dist/query-cache-disk.js

@@ -0,0 +1,175 @@
+/**
+ * Disk-backed persistent query-embedding cache (issue #114).
+ *
+ * The in-memory QueryEmbeddingCache only helps long-lived processes; every
+ * fresh `mdss search` paid full embedding latency. This module adds an L2
+ * layer under it: an LRU (512 entries) persisted to `<cacheDir>/query-cache.json`
+ * keyed by model@revision|dim|sha256(query) — the same identity the memory
+ * cache uses, hashed for compactness.
+ *
+ * Integrity mirrors vectors.bin: atomic tmp+rename write plus a `.sha256`
+ * sidecar. A missing/corrupt pair is silently ignored and rebuilt — a broken
+ * cache must never fail a search.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+export const QUERY_CACHE_FILE = 'query-cache.json';
+export const QUERY_CACHE_MAX_ENTRIES = 512;
+export function buildDiskKey(modelId, revision, dim, query) {
+    const norm = query.trim().toLowerCase();
+    return `${modelId}@${revision || 'main'}|${dim ?? 0}|${crypto.createHash('sha256').update(norm).digest('hex')}`;
+}
+/** Per-directory in-process state: loaded entries + dirty flag. */
+const states = new Map();
+function stateFor(cacheDir) {
+    let st = states.get(cacheDir);
+    if (!st) {
+        st = { entries: loadFromDisk(cacheDir), dirty: false };
+        states.set(cacheDir, st);
+    }
+    return st;
+}
+function filePaths(cacheDir) {
+    const file = path.join(cacheDir, QUERY_CACHE_FILE);
+    return { file, sha: `${file}.sha256`, tmp: `${file}.tmp-${process.pid}` };
+}
+function loadFromDisk(cacheDir) {
+    const out = new Map();
+    const { file, sha } = filePaths(cacheDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(file);
+    }
+    catch {
+        return out;
+    }
+    try {
+        if (fs.existsSync(sha)) {
+            const expected = fs.readFileSync(sha, 'utf8').trim().split(/\s+/)[0];
+            const actual = crypto.createHash('sha256').update(raw).digest('hex');
+            if (!expected || expected !== actual)
+                return out; // corrupt → silent rebuild
+        }
+        const parsed = JSON.parse(raw.toString('utf8'));
+        if (parsed.version !== 1 || typeof parsed.entries !== 'object')
+            return out;
+        for (const [key, e] of Object.entries(parsed.entries)) {
+            if (typeof key === 'string' &&
+                typeof e?.vec === 'string' &&
+                Number.isInteger(e?.dim) &&
+                e.dim > 0 &&
+                Number.isFinite(e?.ts)) {
+                out.set(key, { vec: e.vec, dim: e.dim, ts: e.ts });
+            }
+        }
+    }
+    catch {
+        return new Map(); // any corruption → treat as empty; next flush overwrites
+    }
+    return out;
+}
+function flushSync(cacheDir) {
+    const st = states.get(cacheDir);
+    if (!st || !st.dirty)
+        return;
+    // LRU trim before writing
+    const sorted = [...st.entries.entries()].sort((a, b) => b[1].ts - a[1].ts);
+    st.entries = new Map(sorted.slice(0, QUERY_CACHE_MAX_ENTRIES));
+    const payload = {
+        version: 1,
+        entries: Object.fromEntries(st.entries),
+    };
+    const body = Buffer.from(JSON.stringify(payload));
+    const digest = crypto.createHash('sha256').update(body).digest('hex');
+    const { file, sha, tmp } = filePaths(cacheDir);
+    try {
+        fs.mkdirSync(cacheDir, { recursive: true });
+        fs.writeFileSync(tmp, body);
+        fs.renameSync(tmp, file);
+        fs.writeFileSync(`${sha}.tmp`, `${digest}  ${QUERY_CACHE_FILE}\n`);
+        fs.renameSync(`${sha}.tmp`, sha);
+        st.dirty = false;
+    }
+    catch {
+        /* unwritable cacheDir is non-fatal by design */
+    }
+}
+function scheduleFlush(cacheDir) {
+    const st = stateFor(cacheDir);
+    if (st.timer)
+        return;
+    st.timer = setTimeout(() => {
+        st.timer = undefined;
+        flushSync(cacheDir);
+    }, 400);
+    st.timer.unref?.();
+}
+// best-effort flush on process exit so one-shot CLI runs persist their queries
+let exitHookInstalled = false;
+function ensureExitHook() {
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on('exit', () => {
+        for (const dir of states.keys())
+            flushSync(dir);
+    });
+}
+/**
+ * Look up a query vector on disk. Returns null on any miss/corruption —
+ * callers fall through to embedding without ceremony.
+ */
+export function diskQueryGet(cacheDir, key, expectedDim) {
+    if (!cacheDir)
+        return null;
+    const st = stateFor(cacheDir);
+    const e = st.entries.get(key);
+    if (!e)
+        return null;
+    try {
+        const buf = Buffer.from(e.vec, 'base64');
+        if (buf.byteLength !== e.dim * 4)
+            return null;
+        const arr = new Float32Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+        if (expectedDim !== undefined && arr.length !== expectedDim)
+            return null;
+        for (const x of arr)
+            if (!Number.isFinite(x))
+                return null;
+        e.ts = Date.now(); // LRU touch
+        st.dirty = true;
+        scheduleFlush(cacheDir);
+        return arr;
+    }
+    catch {
+        st.entries.delete(key);
+        return null;
+    }
+}
+/** Store a computed query vector (fire-and-forget, debounced flush). */
+export function diskQueryPut(cacheDir, key, vec) {
+    if (!cacheDir)
+        return;
+    const f32 = vec instanceof Float32Array ? vec : Float32Array.from(vec);
+    const st = stateFor(cacheDir);
+    st.entries.set(key, {
+        vec: Buffer.from(f32.buffer, f32.byteOffset, f32.byteLength).toString('base64'),
+        dim: f32.length,
+        ts: Date.now(),
+    });
+    st.dirty = true;
+    ensureExitHook();
+    scheduleFlush(cacheDir);
+}
+/** Test helper: force-write now. */
+export function flushQueryCacheNow(cacheDir) {
+    flushSync(cacheDir);
+}
+/** Test helper: forget in-process state so the next get/put reloads from disk. */
+export function resetQueryCacheForTest(cacheDir) {
+    if (cacheDir)
+        states.delete(cacheDir);
+    else
+        states.clear();
+}

package/dist/repair.d.ts

@@ -0,0 +1,36 @@
+export interface RepairAction {
+    action: 'remove-stale-lock' | 'remove-broken-vectors-bin' | 'remove-corrupt-ivf' | 'rebuild-index' | 'rewrite-hashes';
+    detail: string;
+}
+export interface RepairPlan {
+    actions: RepairAction[];
+    skipped: RepairAction[];
+}
+export interface ApplyResult {
+    performed: RepairAction[];
+    failed: Array<RepairAction & {
+        error: string;
+    }>;
+}
+interface ProbeOptions {
+    db?: string | null;
+    log?: (msg: string) => void;
+}
+/** Recompute the {relativePath: md5} map exactly as the indexer stores it. */
+export declare function recomputeHashes(db: string): Record<string, string>;
+/**
+ * Probe the index directory and decide what CAN be safely repaired.
+ * Never mutates anything — safe to call for --dry-run.
+ */
+export declare function planRepairs(indexDir: string, opts?: ProbeOptions): RepairPlan;
+/** Execute planned actions in order. dryRun=true performs nothing. */
+export declare function applyRepairs(indexDir: string, plan: RepairPlan, opts?: {
+    dryRun?: boolean;
+    db?: string | null;
+    cacheDir?: string;
+    modelName?: string;
+    embedFn?: any;
+    offline?: boolean;
+    log?: (msg: string) => void;
+}): Promise<ApplyResult>;
+export {};

package/dist/repair.js

@@ -0,0 +1,208 @@
+/**
+ * Safe auto-repairs for `mdss check --fix` (issue #117).
+ *
+ * Plan/apply split: planRepairs() probes the index directory WITHOUT mutating
+ * anything (so --dry-run can print the exact plan), applyRepairs() executes
+ * actions in order and reports per-action outcomes. Source Markdown is NEVER
+ * touched; the only reads from --db are for recomputing `.hashes.json` or a
+ * full index rebuild.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { LOCK_FILENAME, pidAlive, walkMarkdown } from './core.js';
+import { DEFAULT_MODEL } from './models.js';
+const LOCK_STALE_MS = 10 * 60 * 1000;
+function readJsonIfParsable(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return { ok: 'missing' };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** Recompute the {relativePath: md5} map exactly as the indexer stores it. */
+export function recomputeHashes(db) {
+    const hashes = {};
+    for (const f of walkMarkdown(db)) {
+        const rel = path.relative(db, f).split(path.sep).join('/');
+        const md5 = crypto.createHash('md5').update(fs.readFileSync(f)).digest('hex');
+        hashes[rel] = md5;
+    }
+    return hashes;
+}
+/**
+ * Probe the index directory and decide what CAN be safely repaired.
+ * Never mutates anything — safe to call for --dry-run.
+ */
+export function planRepairs(indexDir, opts = {}) {
+    const plan = { actions: [], skipped: [] };
+    const db = opts.db ?? null;
+    // --- 1. stale / abandoned lock ---
+    const lockPath = path.join(indexDir, LOCK_FILENAME);
+    if (fs.existsSync(lockPath)) {
+        let info = null;
+        try {
+            info = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+        }
+        catch {
+            info = null;
+        }
+        const pid = Number.isInteger(info?.pid) ? info.pid : null;
+        let statAgeMs = Infinity;
+        try {
+            statAgeMs = Date.now() - fs.statSync(lockPath).mtimeMs;
+        }
+        catch {
+            /* vanished between exists and stat */
+        }
+        if (!info) {
+            plan.actions.push({ action: 'remove-stale-lock', detail: `${LOCK_FILENAME} is unreadable/abandoned` });
+        }
+        else if (pid !== null && !pidAlive(pid)) {
+            plan.actions.push({ action: 'remove-stale-lock', detail: `${LOCK_FILENAME} held by dead pid ${pid}` });
+        }
+        else if (statAgeMs > LOCK_STALE_MS) {
+            plan.actions.push({
+                action: 'remove-stale-lock',
+                detail: `${LOCK_FILENAME} is older than ${Math.round(LOCK_STALE_MS / 60000)} min`,
+            });
+        }
+        else {
+            plan.skipped.push({
+                action: 'remove-stale-lock',
+                detail: `live writer holds the lock${pid ? ` (pid ${pid})` : ''}`,
+            });
+        }
+    }
+    // --- 2. vectors.bin integrity (SHA-256 sidecar) ---
+    const binPath = path.join(indexDir, 'vectors.bin');
+    const shaPath = `${binPath}.sha256`;
+    if (fs.existsSync(binPath)) {
+        let broken = null;
+        try {
+            const actual = crypto.createHash('sha256').update(fs.readFileSync(binPath)).digest('hex');
+            if (!fs.existsSync(shaPath)) {
+                broken = 'missing vectors.bin.sha256 sidecar';
+            }
+            else {
+                const expected = fs.readFileSync(shaPath, 'utf8').trim().split(/\s+/)[0];
+                if (!expected || expected !== actual)
+                    broken = 'SHA-256 mismatch';
+            }
+        }
+        catch (e) {
+            broken = e.message;
+        }
+        if (broken) {
+            plan.actions.push({
+                action: 'remove-broken-vectors-bin',
+                detail: `vectors.bin ignored (${broken}) — search falls back to vectors.json`,
+            });
+        }
+    }
+    // --- 3. corrupt ivf.json (optional ANN sidecar; loader silently ignores it) ---
+    const ivfPath = path.join(indexDir, 'ivf.json');
+    const ivfRaw = readJsonIfParsable(ivfPath);
+    if (ivfRaw.ok === false) {
+        plan.actions.push({
+            action: 'remove-corrupt-ivf',
+            detail: 'ivf.json is not valid JSON — removing it re-enables brute-force ANN fallback',
+        });
+    }
+    // --- 4. corrupt vectors.json ---
+    const liveWriter = plan.skipped.some((s) => s.action === 'remove-stale-lock' && /live writer/.test(s.detail));
+    const vectorsRaw = readJsonIfParsable(path.join(indexDir, 'vectors.json'));
+    if (vectorsRaw.ok === false) {
+        if (db && !liveWriter) {
+            plan.actions.push({ action: 'rebuild-index', detail: `vectors.json is not valid JSON — rebuild from ${db}` });
+        }
+        else if (liveWriter) {
+            plan.skipped.push({
+                action: 'rebuild-index',
+                detail: 'vectors.json is not valid JSON, but a live writer holds the lock — retry after it finishes',
+            });
+        }
+        else {
+            plan.skipped.push({
+                action: 'rebuild-index',
+                detail: 'vectors.json is not valid JSON — pass --db so --fix can rebuild it',
+            });
+        }
+    }
+    // --- 5. damaged .hashes.json ---
+    const hashesRaw = readJsonIfParsable(path.join(indexDir, '.hashes.json'));
+    if (hashesRaw.ok === false) {
+        if (db) {
+            plan.actions.push({ action: 'rewrite-hashes', detail: '.hashes.json is not valid JSON — recompute from source md5' });
+        }
+        else {
+            plan.skipped.push({
+                action: 'rewrite-hashes',
+                detail: '.hashes.json is not valid JSON — pass --db so --fix can recompute it',
+            });
+        }
+    }
+    return plan;
+}
+/** Execute planned actions in order. dryRun=true performs nothing. */
+export function applyRepairs(indexDir, plan, opts = {}) {
+    const performed = [];
+    const failed = [];
+    const log = opts.log ?? (() => { });
+    const run = async () => {
+        for (const action of plan.actions) {
+            if (opts.dryRun) {
+                performed.push(action);
+                continue;
+            }
+            try {
+                switch (action.action) {
+                    case 'remove-stale-lock':
+                        fs.unlinkSync(path.join(indexDir, LOCK_FILENAME));
+                        break;
+                    case 'remove-broken-vectors-bin':
+                        fs.rmSync(path.join(indexDir, 'vectors.bin'), { force: true });
+                        fs.rmSync(`${path.join(indexDir, 'vectors.bin')}.sha256`, { force: true });
+                        break;
+                    case 'remove-corrupt-ivf':
+                        fs.rmSync(path.join(indexDir, 'ivf.json'), { force: true });
+                        break;
+                    case 'rewrite-hashes': {
+                        const hashes = recomputeHashes(opts.db);
+                        fs.writeFileSync(path.join(indexDir, '.hashes.json'), JSON.stringify(hashes, null, 2));
+                        break;
+                    }
+                    case 'rebuild-index': {
+                        const { buildIndex } = await import('./indexer.js');
+                        const rebuildOpts = {
+                            db: opts.db,
+                            indexDir,
+                            cacheDir: opts.cacheDir,
+                            modelName: opts.modelName || DEFAULT_MODEL,
+                            log,
+                            _lockHeld: true, // we may have JUST removed a stale lock; never double-lock inside fix
+                        };
+                        if (opts.embedFn)
+                            rebuildOpts.embedFn = opts.embedFn; // test DI — keeps repairs model-free
+                        await buildIndex(rebuildOpts);
+                        break;
+                    }
+                }
+                performed.push(action);
+            }
+            catch (e) {
+                failed.push({ ...action, error: e.message });
+            }
+        }
+        return { performed, failed };
+    };
+    return run();
+}

package/dist/rerank.js

@@ -1,7 +1,7 @@
 /**
  * Cross-encoder re-ranking (issue #15).
  */
-import { resolveSessionOptions, retryWithBackoff } from './core.js';
+import { resolveSessionOptions, retryWithBackoff, emitDownloadEvent } from './core.js';
 const _rerankers = new Map();
 export const RERANK_MODEL = 'Xenova/bge-reranker-base';
 export async function getReranker(cacheDir, offline = false, retryOpts = {}) {
@@ -15,9 +15,10 @@ export async function getReranker(cacheDir, offline = false, retryOpts = {}) {
         if (cacheDir)
             env.cacheDir = cacheDir;
         env.allowRemoteModels = !offline;
-        const tokenizer = await AutoTokenizer.from_pretrained(RERANK_MODEL);
+        const tokenizer = await AutoTokenizer.from_pretrained(RERANK_MODEL, { progress_callback: emitDownloadEvent });
         const loadOpts = {
             dtype: 'q8',
+            progress_callback: emitDownloadEvent,
             ...(sessionOptions ? { session_options: sessionOptions } : {}),
         };
         const model = await AutoModelForSequenceClassification.from_pretrained(RERANK_MODEL, loadOpts);

package/dist/search.d.ts

@@ -81,6 +81,28 @@ export declare function getRuntimeGraph(runtime: RuntimeIndexState): {
     graph: RelationshipGraph;
     pageRank: Map<string, number>;
 };
+/**
+ * Issue #127 pure helpers — exported for deterministic unit tests.
+ */
+/** Frontmatter `created` → `updated` → file mtime; null when nothing parses. */
+export declare function resolvePassageAgeMs(meta: {
+    created?: unknown;
+    updated?: unknown;
+} | undefined, absFile?: string): number | null;
+/** Multiplicative recency boost: 0.5^(ageDays / halfLifeDays); 1 when off/unknown/future. */
+export declare function recencyBoost(ageMs: number | null, halfLifeDays: number, now?: number): number;
+/**
+ * HyDE passage generation via an OpenAI-compatible chat endpoint (issue #125).
+ * Returns null on ANY failure — HyDE must degrade to PRF/baseline silently.
+ * Injectable fetch for tests.
+ */
+export declare function hydePassage(endpoint: string, query: string, model?: string, fetchImpl?: typeof fetch): Promise<string | null>;
+/**
+ * Salient-term extraction for PRF (issue #125): tokens that appear in the
+ * top-m feedback passages, are not query terms or stopwords, and are ranked
+ * by (tf-in-feedback × distinct-passage coverage). Pure + deterministic.
+ */
+export declare function extractExpansionTerms(topTexts: string[], queryTerms: string[], maxTerms: number): string[];
 export declare function loadIndex(indexDir: string): {
     index: IndexFile;
     model: ModelDescriptor;
@@ -113,6 +135,18 @@ export interface SearchOptions {
     maxPerFile?: number;
     maxPerDoc?: number;
     useQueryCache?: boolean;
+    /** issue #114: persist query embeddings to <cacheDir>/query-cache.json (default on). */
+    queryDiskCache?: boolean;
+    /** issue #127: time-decay half-life in days; boost = 0.5^(ageDays/halfLife). Omitted = off. */
+    recency?: number;
+    /** issue #125: query expansion mode. 'prf' is fully offline; 'hyde' needs llmEndpoint (else baseline). */
+    expand?: 'prf' | 'hyde';
+    /** issue #125: feedback passages for 'prf' (default 3). */
+    expandPassages?: number;
+    /** issue #125: LLM endpoint used by 'hyde' (OpenAI-compatible chat completions). */
+    llmEndpoint?: string;
+    /** issue #125: model name for the HyDE chat call. */
+    llmModel?: string;
     ann?: boolean;
     nprobe?: number;
     graphBoost?: number;