md-semantic-search 1.1.0 → 2.0.0

package/dist/providers.js

@@ -12,6 +12,7 @@
  * offline path; providers are opt-in via explicit flags.
  */
 import { loadApiKeyFile } from './serve.js';
+import { fetchTimeoutMs } from './core.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');
@@ -29,6 +30,9 @@ async function postJson(fetchImpl, url, headers, body) {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...headers },
         body: JSON.stringify(body),
+        // issue #184: a hung embedder endpoint must fail into the retry path,
+        // not hold an index run / serve slot for undici's ~300s default
+        signal: AbortSignal.timeout(fetchTimeoutMs()),
     });
     if (!res.ok) {
         const text = await res.text().catch(() => '');
@@ -95,6 +99,10 @@ export function resolveExternalEmbedder(cfg) {
             family: cfg.embedder,
         };
     })();
+    // The probe starts eagerly; callers that only ever use embedFn never await
+    // it, so its rejection (e.g. the issue #184 fetch timeout) must not become
+    // an unhandled one. descriptor() re-surfaces the same rejection to awaiters.
+    descriptorPromise.catch(() => { });
     return {
         id: cfg.embedder,
         model: cfg.model,
@@ -102,3 +110,300 @@ export function resolveExternalEmbedder(cfg) {
         descriptor: () => descriptorPromise,
     };
 }
+/**
+ * Incremental SSE frame parser (issue #199): feed it raw network chunks, it
+ * emits one `data:` payload per complete event. Handles CRLF, LF-only streams,
+ * multi-line `data:` fields (joined with \n per the WHATWG spec), comment
+ * keep-alive lines (`: ping`), and chunks that split a line or a CRLF pair
+ * across the boundary. Non-`data` fields (event/id/retry) are irrelevant to
+ * the chat delta stream and dropped.
+ */
+export function createSseParser(onData) {
+    let buf = '';
+    let dataLines = [];
+    const dispatch = () => {
+        if (dataLines.length > 0) {
+            const payload = dataLines.join('\n');
+            dataLines = [];
+            onData(payload);
+        }
+    };
+    const consumeLine = (rawLine) => {
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+        if (line === '') {
+            dispatch();
+            return;
+        }
+        if (line.startsWith(':'))
+            return; // comment / keep-alive
+        if (line.startsWith('data:'))
+            dataLines.push(line.slice(5).replace(/^ /, ''));
+    };
+    return {
+        push(chunk) {
+            buf += chunk;
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                consumeLine(line);
+            }
+        },
+        end() {
+            if (buf !== '') {
+                consumeLine(buf);
+                buf = '';
+            }
+            dispatch();
+        },
+    };
+}
+/** `data:` payload of an OpenAI streaming chunk → delta text ('' when none). */
+export function openAiDeltaText(payload) {
+    if (payload === '[DONE]')
+        return '';
+    try {
+        const json = JSON.parse(payload);
+        const text = json?.choices?.[0]?.delta?.content;
+        return typeof text === 'string' ? text : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** One Ollama NDJSON streaming line → delta text ('' when none). */
+export function ollamaDeltaText(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return '';
+    try {
+        const json = JSON.parse(trimmed);
+        const text = json?.response;
+        return typeof text === 'string' ? text : '';
+    }
+    catch {
+        return '';
+    }
+}
+function chatBaseOf(cfg) {
+    const raw = cfg.baseUrl ||
+        (cfg.provider === 'ollama' ? process.env.OLLAMA_HOST || 'http://127.0.0.1:11434' : 'https://api.openai.com/v1');
+    return raw.replace(/\/+$/, '');
+}
+function chatBearerKey(cfg) {
+    if (cfg.provider !== 'openai')
+        return undefined;
+    if (cfg.keyFile)
+        return loadApiKeyFile(cfg.keyFile);
+    return process.env.OPENAI_API_KEY || undefined;
+}
+const IDLE_ABORT_REASON = () => new DOMException('The operation was aborted due to timeout', 'TimeoutError');
+/**
+ * Streams one completion with an IDLE timeout (issue #199 × #184): the
+ * abort timer arms before connect and resets on every received chunk, so a
+ * hung endpoint fails fast while a long streaming generation is never killed
+ * mid-answer the way a whole-request `AbortSignal.timeout` would. An external
+ * `signal` (serve: client disconnected mid-stream) aborts immediately.
+ */
+function makeIdleGuard(external) {
+    const controller = new AbortController();
+    const idleMs = fetchTimeoutMs();
+    let timer = setTimeout(() => controller.abort(IDLE_ABORT_REASON()), idleMs);
+    timer?.unref?.();
+    const onExternalAbort = () => controller.abort(external.reason);
+    if (external) {
+        if (external.aborted)
+            onExternalAbort();
+        else
+            external.addEventListener('abort', onExternalAbort, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        /** Reset the idle window (after connect, after every chunk). */
+        arm() {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => controller.abort(IDLE_ABORT_REASON()), idleMs);
+            timer?.unref?.();
+        },
+        done() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            external?.removeEventListener('abort', onExternalAbort);
+        },
+    };
+}
+/** Line-splitting over arbitrary network chunks (Ollama NDJSON). */
+function createLineParser(onLine) {
+    let buf = '';
+    return {
+        push(chunk) {
+            buf += chunk;
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl).replace(/\r$/, '');
+                buf = buf.slice(nl + 1);
+                onLine(line);
+            }
+        },
+        end() {
+            if (buf !== '') {
+                onLine(buf.replace(/\r$/, ''));
+                buf = '';
+            }
+        },
+    };
+}
+function isLegacyFallbackEligible(err) {
+    // Only a clearly OpenAI-incompatible shape (no such route) justifies trying
+    // the Ollama-native endpoint; auth/4xx/5xx errors must surface as-is.
+    return /HTTP 40[45]\b/.test(String(err?.message || ''));
+}
+/**
+ * Build a chat completion provider over HTTP streaming (issue #199).
+ * `openai` → POST {base}/chat/completions with `stream:true`, SSE deltas.
+ * `ollama` → POST {base}/api/generate with `stream:true`, NDJSON deltas —
+ * the pre-#199 endpoint, upgraded from `stream:false` to streaming. The
+ * openai path additionally falls back to /api/generate once when the endpoint
+ * answers 404/405 (not OpenAI-shaped), so an Ollama root URL keeps working
+ * with default flags.
+ */
+export function resolveChatProvider(cfg) {
+    const fetchImpl = cfg.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function')
+        throw new Error('chat: no fetch implementation available');
+    const base = chatBaseOf(cfg);
+    const streamOllamaGenerate = async (system, user, onDelta, signal) => {
+        const guard = makeIdleGuard(signal);
+        let res;
+        try {
+            res = await fetchImpl(`${base}/api/generate`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                signal: guard.signal,
+                body: JSON.stringify({
+                    model: cfg.model || 'llama3',
+                    // legacy wire format: one prompt string, byte-identical to the
+                    // pre-#199 single-string synthesis prompt
+                    prompt: system + user,
+                    stream: true,
+                }),
+            });
+        }
+        catch (e) {
+            guard.done();
+            throw e;
+        }
+        if (!res.ok) {
+            guard.done();
+            const text = await res.text().catch(() => '');
+            throw new Error(`chat ${base}/api/generate -> HTTP ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`);
+        }
+        let full = '';
+        const parser = createLineParser((line) => {
+            const delta = ollamaDeltaText(line);
+            if (delta) {
+                full += delta;
+                onDelta?.(delta);
+            }
+        });
+        const decoder = new TextDecoder();
+        try {
+            for await (const chunk of res.body) {
+                parser.push(typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true }));
+                guard.arm();
+            }
+            parser.push(decoder.decode());
+            parser.end();
+        }
+        finally {
+            guard.done();
+        }
+        return full;
+    };
+    const streamOpenAiChat = async (system, user, onDelta, signal) => {
+        const headers = { 'content-type': 'application/json' };
+        const key = chatBearerKey(cfg);
+        if (key)
+            headers.authorization = `Bearer ${key}`;
+        const guard = makeIdleGuard(signal);
+        let res;
+        try {
+            res = await fetchImpl(`${base}/chat/completions`, {
+                method: 'POST',
+                headers,
+                signal: guard.signal,
+                body: JSON.stringify({
+                    ...(cfg.model ? { model: cfg.model } : {}),
+                    messages: [
+                        { role: 'system', content: system },
+                        { role: 'user', content: user },
+                    ],
+                    stream: true,
+                }),
+            });
+        }
+        catch (e) {
+            guard.done();
+            throw e;
+        }
+        if (!res.ok) {
+            guard.done();
+            const text = await res.text().catch(() => '');
+            throw new Error(`chat ${base}/chat/completions -> HTTP ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`);
+        }
+        let full = '';
+        let wireDone = false;
+        const parser = createSseParser((payload) => {
+            if (payload === '[DONE]') {
+                wireDone = true;
+                return;
+            }
+            const delta = openAiDeltaText(payload);
+            if (delta) {
+                full += delta;
+                onDelta?.(delta);
+            }
+        });
+        const decoder = new TextDecoder();
+        try {
+            for await (const chunk of res.body) {
+                parser.push(typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true }));
+                guard.arm();
+                // leaving the for-await on [DONE] cancels the stream through the
+                // iterator's return() — a manual cancel() here would just reject
+                // with "ReadableStream is locked"
+                if (wireDone)
+                    break;
+            }
+            if (!wireDone) {
+                parser.push(decoder.decode());
+                parser.end();
+            }
+        }
+        finally {
+            guard.done();
+        }
+        return full;
+    };
+    return {
+        id: cfg.provider,
+        model: cfg.model || '',
+        async complete(req) {
+            if (cfg.provider === 'ollama') {
+                return streamOllamaGenerate(req.system, req.user, req.onDelta, req.signal);
+            }
+            try {
+                return await streamOpenAiChat(req.system, req.user, req.onDelta, req.signal);
+            }
+            catch (e) {
+                if (isLegacyFallbackEligible(e)) {
+                    return streamOllamaGenerate(req.system, req.user, req.onDelta, req.signal);
+                }
+                throw e;
+            }
+        },
+    };
+}

package/dist/quantization.d.ts

@@ -22,3 +22,15 @@ export declare function dequantizeFromInt8(vec: Int8Array): Float32Array;
  * cosine(q, c) = (q · c_fp32) / ||c_fp32|| = (sum(q_i * c_i) / 127) / (||c|| / 127) = sum(q_i * c_i) / ||c||.
  */
 export declare function asymmetricCosineInt8(queryFp32: Float32Array, chunkInt8: Int8Array): number;
+/**
+ * Precomputed int8 chunk norm = sqrt(sum(c_i^2)) (issue #190): constant per
+ * chunk, so caching it at load time removes half of the asymmetric sweep.
+ * Accumulates in the same order as `asymmetricCosineInt8` so the cached-norm
+ * fast path returns bitwise-equal scores.
+ */
+export declare function int8Norm(chunkInt8: Int8Array): number;
+/**
+ * Dot-only sweep fast path (issue #190): identical to `asymmetricCosineInt8`
+ * when `chunkNorm` came from `int8Norm` on the same vector.
+ */
+export declare function asymmetricCosineInt8CachedNorm(queryFp32: Float32Array, chunkInt8: Int8Array, chunkNorm: number): number;

package/dist/quantization.js

@@ -83,3 +83,57 @@ export function asymmetricCosineInt8(queryFp32, chunkInt8) {
         return 0.0;
     return dot / Math.sqrt(normSq);
 }
+/**
+ * Precomputed int8 chunk norm = sqrt(sum(c_i^2)) (issue #190): constant per
+ * chunk, so caching it at load time removes half of the asymmetric sweep.
+ * Accumulates in the same order as `asymmetricCosineInt8` so the cached-norm
+ * fast path returns bitwise-equal scores.
+ */
+export function int8Norm(chunkInt8) {
+    const dim = chunkInt8.length;
+    let normSq = 0.0;
+    let i = 0;
+    const limit = dim - (dim % 8);
+    for (; i < limit; i += 8) {
+        normSq +=
+            chunkInt8[i] * chunkInt8[i] +
+                chunkInt8[i + 1] * chunkInt8[i + 1] +
+                chunkInt8[i + 2] * chunkInt8[i + 2] +
+                chunkInt8[i + 3] * chunkInt8[i + 3] +
+                chunkInt8[i + 4] * chunkInt8[i + 4] +
+                chunkInt8[i + 5] * chunkInt8[i + 5] +
+                chunkInt8[i + 6] * chunkInt8[i + 6] +
+                chunkInt8[i + 7] * chunkInt8[i + 7];
+    }
+    for (; i < dim; i++) {
+        normSq += chunkInt8[i] * chunkInt8[i];
+    }
+    return Math.sqrt(normSq);
+}
+/**
+ * Dot-only sweep fast path (issue #190): identical to `asymmetricCosineInt8`
+ * when `chunkNorm` came from `int8Norm` on the same vector.
+ */
+export function asymmetricCosineInt8CachedNorm(queryFp32, chunkInt8, chunkNorm) {
+    if (!(chunkNorm > 0))
+        return 0.0;
+    const dim = queryFp32.length;
+    let dot = 0.0;
+    let i = 0;
+    const limit = dim - (dim % 8);
+    for (; i < limit; i += 8) {
+        dot +=
+            queryFp32[i] * chunkInt8[i] +
+                queryFp32[i + 1] * chunkInt8[i + 1] +
+                queryFp32[i + 2] * chunkInt8[i + 2] +
+                queryFp32[i + 3] * chunkInt8[i + 3] +
+                queryFp32[i + 4] * chunkInt8[i + 4] +
+                queryFp32[i + 5] * chunkInt8[i + 5] +
+                queryFp32[i + 6] * chunkInt8[i + 6] +
+                queryFp32[i + 7] * chunkInt8[i + 7];
+    }
+    for (; i < dim; i++) {
+        dot += queryFp32[i] * chunkInt8[i];
+    }
+    return dot / chunkNorm;
+}

package/dist/rag.d.ts

@@ -1,4 +1,5 @@
 import { LoadedIndex, SearchResultHit } from './search.js';
+import { ChatProviderId, ResolvedChat } from './providers.js';
 export interface Citation {
     file: string;
     heading?: string;
@@ -7,7 +8,25 @@ export interface Citation {
 export interface SynthesisResult {
     answer: string;
     citations: Citation[];
+    /**
+     * issue #199 follow-up: citations the answer actually mentions (bracket
+     * formats `[file#heading]` / `[file › heading]` / `[file]`), in order of
+     * first mention. Deterministic post-processing of the LLM text — a subset
+     * of `citations`, which stays the full retrieval manifest for compatibility.
+     */
+    citationsUsed?: Citation[];
     passages: SearchResultHit[];
+    /** Which synthesis stage produced the answer (issue #197 observability). */
+    mode?: 'llm' | 'endpoint' | 'extractive';
+}
+/**
+ * System/user split for transports that keep the two apart on the wire —
+ * MCP `sampling/createMessage` (issue #197) carries a `systemPrompt` field
+ * and a message list, unlike the single-string local LLM bridge.
+ */
+export interface LlmStructuredRequest {
+    system: string;
+    user: string;
 }
 export interface ChatSourceManifestItem {
     file: string;
@@ -25,6 +44,8 @@ export interface ChatTurn {
     answer: string;
     citations: Citation[];
     manifest: ChatSourceManifestItem[];
+    /** Which synthesis stage produced the answer (issue #199; optional in persisted sessions). */
+    mode?: SynthesisResult['mode'];
 }
 export interface ChatSession {
     id: string;
@@ -41,9 +62,17 @@ export interface AskOptions {
     cacheDir?: string;
     db?: string;
     k?: number;
+    offline?: boolean;
     llmEndpoint?: string;
     llmModel?: string;
+    /** issue #199: chat wire format for llmEndpoint — 'openai' (default) or 'ollama'. */
+    llmProvider?: ChatProviderId;
     llmFn?: (prompt: string) => Promise<string>;
+    llmRequestFn?: (req: LlmStructuredRequest) => Promise<string>;
+    /** issue #199: incremental render hook — fires per token chunk while the LLM streams. */
+    onDelta?: (delta: string) => void;
+    /** issue #199: injection seam for tests/serve; built from llmEndpoint when absent. */
+    llmChat?: ResolvedChat;
     systemPrompt?: string;
     embedFn?: any;
 }
@@ -55,9 +84,17 @@ export interface ChatTurnOptions {
     cacheDir?: string;
     db?: string;
     k?: number;
+    offline?: boolean;
     llmEndpoint?: string;
     llmModel?: string;
+    /** issue #199: chat wire format for llmEndpoint — 'openai' (default) or 'ollama'. */
+    llmProvider?: ChatProviderId;
     llmFn?: (prompt: string) => Promise<string>;
+    llmRequestFn?: (req: LlmStructuredRequest) => Promise<string>;
+    /** issue #199: incremental render hook — fires per token chunk while the LLM streams. */
+    onDelta?: (delta: string) => void;
+    /** issue #199: injection seam for tests/serve; built from llmEndpoint when absent. */
+    llmChat?: ResolvedChat;
     systemPrompt?: string;
     embedFn?: any;
     log?: (msg: string) => void;
@@ -67,6 +104,10 @@ export declare const DEFAULT_RAG_SYSTEM_PROMPT: string;
  * Returns the directory where chat sessions are persisted.
  */
 export declare function getSessionsDir(indexDir: string): string;
+/**
+ * Validates a session id before it is used as a filesystem path component.
+ */
+export declare function assertSafeSessionId(id: string): string;
 /**
  * Atomically saves a ChatSession to disk (<indexDir>/sessions/<id>.json).
  */
@@ -88,13 +129,28 @@ export declare function listChatSessions(indexDir: string): Array<{
  * Built-in extractive answer synthesizer for fully offline, zero-dependency QA.
  */
 export declare function extractAnswerFallback(query: string, passages: SearchResultHit[]): string;
+/**
+ * issue #199 follow-up: which of the retrieved citations the answer text
+ * actually cites. Bracket-only scan (the exact formats the system prompt and
+ * the extractive fallback emit), exact file/heading match against the
+ * retrieval manifest, order of first mention. No mention → [].
+ */
+export declare function extractUsedCitations(answer: string, citations: Citation[]): Citation[];
 /**
  * Synthesizes an answer from retrieved passages using an LLM or fallback.
  */
 export declare function synthesizeAnswer(query: string, passages: SearchResultHit[], options?: {
     llmFn?: (prompt: string) => Promise<string>;
+    llmRequestFn?: (req: LlmStructuredRequest) => Promise<string>;
     llmEndpoint?: string;
     llmModel?: string;
+    /** issue #199: chat wire format for llmEndpoint — 'openai' (default) or 'ollama'. */
+    llmProvider?: ChatProviderId;
+    llmChat?: ResolvedChat;
+    /** issue #199: incremental render hook — fires per token chunk while the LLM streams. */
+    onDelta?: (delta: string) => void;
+    /** Cooperative cancel (serve /ask: client disconnected mid-stream). */
+    signal?: AbortSignal;
     systemPrompt?: string;
     conversationHistory?: string;
 }): Promise<SynthesisResult>;
@@ -111,4 +167,8 @@ export declare function chatTurn(opts: ChatTurnOptions): Promise<{
     answer: string;
     citations: Citation[];
     manifest: ChatSourceManifestItem[];
+    /** Which synthesis stage produced the answer ('llm'/'endpoint'/'extractive'). */
+    mode: SynthesisResult['mode'];
+    /** Citations the answer text actually mentions (issue #199 follow-up). */
+    citationsUsed: Citation[];
 }>;