@ashlr/hub 2.2.0

package/dist/core/genome/playbook.js

@@ -0,0 +1,320 @@
+/**
+ * playbook.ts — Genome playbook synthesis (M16).
+ *
+ * Recalls similar past genome entries for a goal and synthesizes a concise
+ * "how we've approached this before — what worked / what failed / cost"
+ * string using the LOCAL provider. Falls back to a concatenated-recall
+ * synthesis on any failure, over-budget condition, or absent provider.
+ *
+ * Guardrails:
+ *  - LOCAL-ONLY: no cloud calls; synthesis uses local provider best-effort.
+ *  - Never throws; always returns a Playbook.
+ *  - Bounded: synthesis prompt and output are capped; playbookText hard-truncates.
+ *  - PRIVACY: works only from already-sanitised recall entries (genome never
+ *    stores secrets/raw payloads per M7/M16 privacy discipline).
+ */
+import { recall } from './recall.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default number of past entries to recall for the playbook. */
+const DEFAULT_RECALL_LIMIT = 5;
+/** Hard cap on the synthesis prompt text fed to the local model (chars). */
+const SYNTHESIS_PROMPT_MAX_CHARS = 4000;
+/** Hard cap on each recalled entry's text included in the prompt (chars). */
+const ENTRY_TEXT_MAX_CHARS = 600;
+/** Timeout (ms) for the local model synthesis call. */
+const SYNTHESIS_TIMEOUT_MS = 20_000;
+/** Elision marker appended when playbookText truncates. */
+const ELISION = '… [truncated]';
+// ---------------------------------------------------------------------------
+// Fallback synthesis — pure, no I/O
+// ---------------------------------------------------------------------------
+/**
+ * Build a concatenated-recall synthesis string from recalled entries.
+ * Used when no local provider is available or the model call fails.
+ * Pure; never throws.
+ */
+function fallbackSynthesis(goal, entries) {
+    if (entries.length === 0) {
+        return `No past entries found for goal: "${goal}". Proceeding without historical context.`;
+    }
+    const lines = [`Past approaches for: "${goal}"`, ''];
+    for (const hit of entries) {
+        const { entry } = hit;
+        const tags = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+        const ts = entry.ts ? ` (${entry.ts.slice(0, 10)})` : '';
+        const text = entry.text.slice(0, ENTRY_TEXT_MAX_CHARS);
+        lines.push(`• ${entry.title}${tags}${ts}`);
+        if (text)
+            lines.push(`  ${text.replace(/\n/g, '\n  ')}`);
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+// ---------------------------------------------------------------------------
+// Prompt builder — pure, no I/O
+// ---------------------------------------------------------------------------
+/**
+ * Build the synthesis prompt from recalled entries, capped at
+ * SYNTHESIS_PROMPT_MAX_CHARS. Pure; never throws.
+ */
+function buildSynthesisPrompt(goal, entries) {
+    const header = [
+        `Goal: "${goal}"`,
+        '',
+        'Past approaches (from genome memory):',
+        '',
+    ].join('\n');
+    let body = '';
+    for (const hit of entries) {
+        const { entry } = hit;
+        const tags = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+        const ts = entry.ts ? ` (${entry.ts.slice(0, 10)})` : '';
+        const text = entry.text.slice(0, ENTRY_TEXT_MAX_CHARS);
+        const chunk = `### ${entry.title}${tags}${ts}\n${text}\n\n`;
+        // Stop adding entries if we'd overflow the prompt cap
+        if ((header + body + chunk).length > SYNTHESIS_PROMPT_MAX_CHARS)
+            break;
+        body += chunk;
+    }
+    const instruction = [
+        'Given these past approaches to similar goals, provide a concise playbook that covers:',
+        '- What worked well',
+        '- What failed or caused problems',
+        '- Recommended approach and any cost/time considerations',
+        '',
+        'Be concise (3-5 bullet points or a short paragraph). Do not repeat the entries verbatim.',
+    ].join('\n');
+    return `${header}${body}\n${instruction}`;
+}
+// ---------------------------------------------------------------------------
+// Local model synthesis — best-effort, never throws
+// ---------------------------------------------------------------------------
+/**
+ * Attempt a local model synthesis call via Ollama (POST /api/chat with
+ * stream:false). Returns null on any failure or timeout.
+ * LOCAL-ONLY. Never throws.
+ */
+async function tryLocalSynthesis(prompt, cfg) {
+    try {
+        const ollamaBase = (cfg.models?.ollama ?? 'http://localhost:11434').replace(/\/+$/, '');
+        const chatUrl = `${ollamaBase}/api/chat`;
+        // Probe for available models first — quick check, bounded timeout.
+        const probeController = new AbortController();
+        const probeTimer = setTimeout(() => probeController.abort(), 3000);
+        let modelName = null;
+        try {
+            const tagsRes = await fetch(`${ollamaBase}/api/tags`, {
+                signal: probeController.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (tagsRes.ok) {
+                const body = (await tagsRes.json());
+                if (typeof body === 'object' &&
+                    body !== null &&
+                    Array.isArray(body['models'])) {
+                    const models = body.models;
+                    // Skip embedding-only models; prefer smallest chat model.
+                    const isEmbed = (n) => /embed|bge|e5|nomic/i.test(n);
+                    const chatModels = models.map((m) => m.name).filter((n) => !isEmbed(n));
+                    if (chatModels.length > 0) {
+                        // Pick smallest by parameter size heuristic
+                        const sizeOf = (m) => {
+                            const b = m.match(/(\d+(?:\.\d+)?)\s*b\b/i);
+                            if (b)
+                                return parseFloat(b[1]);
+                            if (/mini|small|tiny|nano|phi/i.test(m))
+                                return 3;
+                            return 999;
+                        };
+                        chatModels.sort((a, b) => sizeOf(a) - sizeOf(b));
+                        modelName = chatModels[0];
+                    }
+                }
+            }
+        }
+        catch {
+            // Probe failed — no Ollama available
+        }
+        finally {
+            clearTimeout(probeTimer);
+        }
+        if (!modelName)
+            return null;
+        // Make the synthesis call with a bounded timeout.
+        const chatController = new AbortController();
+        const chatTimer = setTimeout(() => chatController.abort(), SYNTHESIS_TIMEOUT_MS);
+        try {
+            const res = await fetch(chatUrl, {
+                method: 'POST',
+                signal: chatController.signal,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    model: modelName,
+                    messages: [{ role: 'user', content: prompt }],
+                    stream: false,
+                }),
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            if (typeof data !== 'object' || data === null)
+                return null;
+            const d = data;
+            const message = (d['message'] ?? {});
+            const content = typeof message['content'] === 'string' ? message['content'] : null;
+            return content && content.trim().length > 0 ? content.trim() : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(chatTimer);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Also try LM Studio as a fallback local provider
+// ---------------------------------------------------------------------------
+/**
+ * Attempt synthesis via LM Studio (OpenAI-compat /v1/chat/completions).
+ * Returns null on any failure. LOCAL-ONLY. Never throws.
+ */
+async function tryLmStudioSynthesis(prompt, cfg) {
+    try {
+        const lmBase = (cfg.models?.lmstudio ?? 'http://localhost:1234').replace(/\/+$/, '');
+        const modelsUrl = `${lmBase}/v1/models`;
+        const chatUrl = `${lmBase}/v1/chat/completions`;
+        // Probe for available models.
+        const probeController = new AbortController();
+        const probeTimer = setTimeout(() => probeController.abort(), 3000);
+        let modelName = null;
+        try {
+            const modelsRes = await fetch(modelsUrl, {
+                signal: probeController.signal,
+                headers: { Accept: 'application/json' },
+            });
+            if (modelsRes.ok) {
+                const body = (await modelsRes.json());
+                if (typeof body === 'object' &&
+                    body !== null &&
+                    Array.isArray(body['data'])) {
+                    const data = body.data;
+                    if (data.length > 0 && typeof data[0].id === 'string') {
+                        modelName = data[0].id;
+                    }
+                }
+            }
+        }
+        catch {
+            // LM Studio not available
+        }
+        finally {
+            clearTimeout(probeTimer);
+        }
+        if (!modelName)
+            return null;
+        const chatController = new AbortController();
+        const chatTimer = setTimeout(() => chatController.abort(), SYNTHESIS_TIMEOUT_MS);
+        try {
+            const res = await fetch(chatUrl, {
+                method: 'POST',
+                signal: chatController.signal,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    model: modelName,
+                    messages: [{ role: 'user', content: prompt }],
+                    stream: false,
+                }),
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            if (typeof data !== 'object' || data === null)
+                return null;
+            const d = data;
+            const choices = Array.isArray(d['choices']) ? d['choices'] : [];
+            const firstChoice = (choices[0] ?? {});
+            const message = (firstChoice['message'] ?? {});
+            const content = typeof message['content'] === 'string' ? message['content'] : null;
+            return content && content.trim().length > 0 ? content.trim() : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(chatTimer);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build a playbook for `goal` by recalling similar past entries and
+ * synthesizing a concise guidance string via the LOCAL provider.
+ *
+ * Falls back to a concatenated-recall synthesis on any failure, over-budget
+ * condition, or when no local provider is reachable.
+ *
+ * Never throws. Returns `{ goal, entries, synthesis }`.
+ */
+export async function buildPlaybook(goal, cfg, opts) {
+    // Step 1: recall similar past entries
+    let entries = [];
+    try {
+        const limit = opts?.limit ?? cfg.genome?.maxRecall ?? DEFAULT_RECALL_LIMIT;
+        entries = await recall(goal, cfg, { limit });
+    }
+    catch {
+        // recall never throws per its own contract; guard defensively anyway
+        entries = [];
+    }
+    // If no entries recalled, return immediately with a minimal playbook
+    if (entries.length === 0) {
+        return {
+            goal,
+            entries,
+            synthesis: `No past entries found for goal: "${goal}". Proceeding without historical context.`,
+        };
+    }
+    // Step 2: build the synthesis prompt
+    const prompt = buildSynthesisPrompt(goal, entries);
+    // Step 3: attempt local synthesis (Ollama first, then LM Studio)
+    let synthesis = null;
+    synthesis = await tryLocalSynthesis(prompt, cfg);
+    if (!synthesis) {
+        synthesis = await tryLmStudioSynthesis(prompt, cfg);
+    }
+    // Step 4: fall back to concatenated-recall synthesis if model unavailable/failed
+    if (!synthesis) {
+        synthesis = fallbackSynthesis(goal, entries);
+    }
+    return { goal, entries, synthesis };
+}
+/**
+ * Render a playbook to an injection-ready string capped at `maxChars`.
+ * Appends an elision marker when truncated. Pure; never throws.
+ */
+export function playbookText(p, maxChars) {
+    if (maxChars <= 0)
+        return '';
+    const header = `=== Playbook: ${p.goal} ===\n`;
+    const body = p.synthesis;
+    const full = header + body;
+    if (full.length <= maxChars)
+        return full;
+    // Hard truncate with elision marker
+    const cutoff = maxChars - ELISION.length;
+    if (cutoff <= 0)
+        return ELISION.slice(0, maxChars);
+    return full.slice(0, cutoff) + ELISION;
+}
+//# sourceMappingURL=playbook.js.map

package/dist/core/genome/playbook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook.js","sourceRoot":"","sources":["../../../src/core/genome/playbook.ts"],"names":[],"mappings":"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"}

package/dist/core/genome/recall.d.ts

@@ -0,0 +1,45 @@
+/**
+ * recall.ts — Genome recall: keyword/TF-IDF scoring + optional Ollama embedding rerank.
+ *
+ * Rules:
+ *  - keywordScore is pure, synchronous, deterministic; returns 0..∞ (0 = no overlap).
+ *  - recall never throws; embedding rerank is best-effort, falls back to keyword silently.
+ *  - Local-first: embeddings only via local Ollama /api/embeddings. Never cloud.
+ *  - Offline-capable: keyword path always works without network.
+ *  - Bounded: caps candidates sent to embedding reranker at EMBED_CANDIDATE_CAP.
+ */
+import type { AshlrConfig, GenomeEntry, RecallHit } from '../types.js';
+/**
+ * Compute a keyword overlap score between a query and a genome entry.
+ *
+ * Approach: TF-style term overlap.
+ *  - Tokenise the query into a unique term set.
+ *  - For each query term, sum its frequency in the entry's weighted text bag:
+ *      title tokens  × weight 3
+ *      tag tokens    × weight 2
+ *      body tokens   × weight 1
+ *  - Normalise by (queryTermCount × maxPossibleHitsPerTerm) to keep roughly 0..1
+ *    (may exceed 1 for very short queries with many hits — intentional).
+ *
+ * Returns 0 when there is no overlap at all.
+ */
+export declare function keywordScore(query: string, entry: GenomeEntry): number;
+/**
+ * Recall the top-k genome entries most relevant to `query`.
+ *
+ * 1. Load all genome entries via store.loadGenome (bounded, never throws).
+ * 2. Score all entries by keyword/TF-IDF overlap.
+ * 3. If opts.embeddings is true (or not explicitly false) AND an embedding
+ *    model is available at the configured Ollama endpoint:
+ *      a. Take up to EMBED_CANDIDATE_CAP top keyword candidates.
+ *      b. Fetch embeddings for query + each candidate in parallel.
+ *      c. Re-sort by cosine similarity; tag hits as method:'embedding'.
+ *      d. On ANY failure, silently fall back to keyword results.
+ * 4. Return top `limit` hits, sorted descending by score, with method tag.
+ *
+ * Never throws. Never calls cloud. Offline-capable (keyword path).
+ */
+export declare function recall(query: string, cfg: AshlrConfig, opts?: {
+    limit?: number;
+    embeddings?: boolean;
+}): Promise<RecallHit[]>;

package/dist/core/genome/recall.js

@@ -0,0 +1,293 @@
+/**
+ * recall.ts — Genome recall: keyword/TF-IDF scoring + optional Ollama embedding rerank.
+ *
+ * Rules:
+ *  - keywordScore is pure, synchronous, deterministic; returns 0..∞ (0 = no overlap).
+ *  - recall never throws; embedding rerank is best-effort, falls back to keyword silently.
+ *  - Local-first: embeddings only via local Ollama /api/embeddings. Never cloud.
+ *  - Offline-capable: keyword path always works without network.
+ *  - Bounded: caps candidates sent to embedding reranker at EMBED_CANDIDATE_CAP.
+ */
+import { loadGenome } from './store.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Max candidates forwarded to embedding reranker to keep latency bounded. */
+const EMBED_CANDIDATE_CAP = 20;
+/** Timeout (ms) for a single Ollama /api/embeddings request. */
+const EMBED_TIMEOUT_MS = 8000;
+/** Minimum keyword score for an entry to be included at all (0 = include everything). */
+const MIN_SCORE = 0;
+// ---------------------------------------------------------------------------
+// Tokenisation helpers
+// ---------------------------------------------------------------------------
+/**
+ * Tokenise text: lowercase, split on non-alphanumeric boundaries, drop empties.
+ * Returns a deduplicated term array for IDF-style calcs + a full term-count map.
+ */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 0);
+}
+// ---------------------------------------------------------------------------
+// keywordScore — pure, synchronous, deterministic
+// ---------------------------------------------------------------------------
+/**
+ * Compute a keyword overlap score between a query and a genome entry.
+ *
+ * Approach: TF-style term overlap.
+ *  - Tokenise the query into a unique term set.
+ *  - For each query term, sum its frequency in the entry's weighted text bag:
+ *      title tokens  × weight 3
+ *      tag tokens    × weight 2
+ *      body tokens   × weight 1
+ *  - Normalise by (queryTermCount × maxPossibleHitsPerTerm) to keep roughly 0..1
+ *    (may exceed 1 for very short queries with many hits — intentional).
+ *
+ * Returns 0 when there is no overlap at all.
+ */
+export function keywordScore(query, entry) {
+    const queryTerms = new Set(tokenize(query));
+    if (queryTerms.size === 0)
+        return 0;
+    // Build a weighted token bag for the entry
+    const titleTokens = tokenize(entry.title);
+    const textTokens = tokenize(entry.text);
+    const tagTokens = entry.tags.flatMap((tag) => tokenize(tag));
+    // Weighted frequency map: title ×3, tags ×2, body ×1
+    const weightedFreq = new Map();
+    for (const t of titleTokens) {
+        weightedFreq.set(t, (weightedFreq.get(t) ?? 0) + 3);
+    }
+    for (const t of tagTokens) {
+        weightedFreq.set(t, (weightedFreq.get(t) ?? 0) + 2);
+    }
+    for (const t of textTokens) {
+        weightedFreq.set(t, (weightedFreq.get(t) ?? 0) + 1);
+    }
+    if (weightedFreq.size === 0)
+        return 0;
+    // Sum weighted hits for query terms
+    let hits = 0;
+    for (const term of queryTerms) {
+        hits += weightedFreq.get(term) ?? 0;
+    }
+    if (hits === 0)
+        return 0;
+    // Normalise: divide by queryTermCount to get average weighted hits per query term.
+    // This produces a score ≥ 0 where higher = more relevant.
+    return hits / queryTerms.size;
+}
+// ---------------------------------------------------------------------------
+// Embedding helpers — best-effort, local Ollama only
+// ---------------------------------------------------------------------------
+/**
+ * Detect whether any embedding-capable model is available at the Ollama base URL.
+ * Heuristic: look for well-known embedding model name substrings in the /api/tags list.
+ * Returns { available: true, model } or { available: false }.
+ * Never throws.
+ */
+async function detectEmbeddingModel(ollamaBase) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    try {
+        const res = await fetch(`${ollamaBase.replace(/\/+$/, '')}/api/tags`, {
+            signal: controller.signal,
+            headers: { Accept: 'application/json' },
+        });
+        if (!res.ok)
+            return { available: false };
+        const body = (await res.json());
+        if (typeof body !== 'object' ||
+            body === null ||
+            !Array.isArray(body['models'])) {
+            return { available: false };
+        }
+        const models = body.models;
+        // Prefer bge, nomic-embed, mxbai-embed, all-minilm — common local embedding models
+        const EMBED_HINTS = ['bge', 'nomic-embed', 'mxbai-embed', 'all-minilm', 'embed'];
+        for (const hint of EMBED_HINTS) {
+            const found = models.find((m) => m.name.toLowerCase().includes(hint));
+            if (found)
+                return { available: true, model: found.name };
+        }
+        return { available: false };
+    }
+    catch {
+        return { available: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch an embedding vector for `text` from local Ollama.
+ * Uses POST /api/embeddings with { model, prompt }.
+ * Returns null on any error (never throws).
+ */
+async function fetchEmbedding(ollamaBase, model, text) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EMBED_TIMEOUT_MS);
+    try {
+        const res = await fetch(`${ollamaBase.replace(/\/+$/, '')}/api/embeddings`, {
+            method: 'POST',
+            signal: controller.signal,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ model, prompt: text }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (typeof body !== 'object' ||
+            body === null ||
+            !Array.isArray(body['embedding'])) {
+            return null;
+        }
+        const embedding = body.embedding;
+        // Validate: all elements must be numbers
+        if (!embedding.every((v) => typeof v === 'number'))
+            return null;
+        return embedding;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Compute cosine similarity between two vectors.
+ * Returns 0 on zero-length or mismatched vectors.
+ */
+function cosine(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom === 0)
+        return 0;
+    return dot / denom;
+}
+/**
+ * Build a single text blob from an entry for embedding (title + tags + text).
+ * Truncated to keep embedding calls bounded.
+ */
+function entryToEmbedText(entry) {
+    const parts = [
+        entry.title,
+        entry.tags.join(' '),
+        entry.text,
+    ].filter(Boolean);
+    return parts.join(' ').slice(0, 2000);
+}
+// ---------------------------------------------------------------------------
+// Main recall function
+// ---------------------------------------------------------------------------
+/**
+ * Recall the top-k genome entries most relevant to `query`.
+ *
+ * 1. Load all genome entries via store.loadGenome (bounded, never throws).
+ * 2. Score all entries by keyword/TF-IDF overlap.
+ * 3. If opts.embeddings is true (or not explicitly false) AND an embedding
+ *    model is available at the configured Ollama endpoint:
+ *      a. Take up to EMBED_CANDIDATE_CAP top keyword candidates.
+ *      b. Fetch embeddings for query + each candidate in parallel.
+ *      c. Re-sort by cosine similarity; tag hits as method:'embedding'.
+ *      d. On ANY failure, silently fall back to keyword results.
+ * 4. Return top `limit` hits, sorted descending by score, with method tag.
+ *
+ * Never throws. Never calls cloud. Offline-capable (keyword path).
+ */
+export async function recall(query, cfg, opts) {
+    const limit = opts?.limit ?? cfg.genome?.maxRecall ?? 5;
+    // Load all entries defensively (store never throws)
+    let entries;
+    try {
+        entries = loadGenome(cfg);
+    }
+    catch {
+        entries = [];
+    }
+    if (entries.length === 0 || query.trim().length === 0)
+        return [];
+    // --- Step 1: keyword scoring ---
+    const keywordHits = entries
+        .map((entry) => ({
+        entry,
+        score: keywordScore(query, entry),
+        method: 'keyword',
+    }))
+        .filter((h) => h.score > MIN_SCORE)
+        .sort((a, b) => b.score - a.score);
+    // Embeddings are strictly opt-in per the contract: only rerank when the
+    // caller explicitly passes embeddings:true. The default (and any non-true
+    // value) returns the keyword path immediately — keeping recall offline-first,
+    // deterministic, and never surfacing zero-keyword-overlap entries that an
+    // embedding rerank would otherwise pull in.
+    if (opts?.embeddings !== true) {
+        return keywordHits.slice(0, limit);
+    }
+    // --- Step 2: optional embedding rerank ---
+    // Take top candidates (by keyword score) for embedding reranking
+    // Include all entries with positive keyword score, then pad with remaining
+    // entries up to EMBED_CANDIDATE_CAP so we don't miss zero-keyword relevant entries.
+    const positiveHits = keywordHits.slice(0, EMBED_CANDIDATE_CAP);
+    const positiveIds = new Set(positiveHits.map((h) => h.entry.id));
+    // Fill remaining slots with entries that had no keyword overlap (sorted by ts desc)
+    const remaining = entries
+        .filter((e) => !positiveIds.has(e.id))
+        .slice(0, Math.max(0, EMBED_CANDIDATE_CAP - positiveHits.length))
+        .map((entry) => ({ entry, score: 0, method: 'keyword' }));
+    const candidates = [...positiveHits, ...remaining];
+    try {
+        const ollamaBase = cfg.models.ollama ?? 'http://localhost:11434';
+        const modelProbe = await detectEmbeddingModel(ollamaBase);
+        if (!modelProbe.available) {
+            // No embedding model — return keyword results
+            return keywordHits.slice(0, limit);
+        }
+        const { model } = modelProbe;
+        // Fetch query embedding + all candidate embeddings in parallel
+        const queryEmbedPromise = fetchEmbedding(ollamaBase, model, query.slice(0, 2000));
+        const candidateEmbedPromises = candidates.map((h) => fetchEmbedding(ollamaBase, model, entryToEmbedText(h.entry)));
+        const [queryVec, ...candidateVecs] = await Promise.all([
+            queryEmbedPromise,
+            ...candidateEmbedPromises,
+        ]);
+        // If query embedding failed, fall back to keyword
+        if (queryVec === null) {
+            return keywordHits.slice(0, limit);
+        }
+        // Build reranked hits; fall back per-entry to keyword score if embedding failed
+        const reranked = candidates.map((hit, i) => {
+            const vec = candidateVecs[i];
+            if (vec === null) {
+                // Embedding unavailable for this entry — keep keyword score
+                return hit;
+            }
+            return {
+                entry: hit.entry,
+                score: cosine(queryVec, vec),
+                method: 'embedding',
+            };
+        });
+        // Sort descending by embedding score
+        reranked.sort((a, b) => b.score - a.score);
+        return reranked.slice(0, limit);
+    }
+    catch {
+        // Any unexpected failure: return keyword results
+        return keywordHits.slice(0, limit);
+    }
+}
+//# sourceMappingURL=recall.js.map