md-semantic-search 0.4.0 → 0.5.0

package/dist/search.d.ts

@@ -0,0 +1,135 @@
+import { ModelDescriptor } from './core.js';
+import { LexicalIndex } from './lexical.js';
+import { DocumentMetadata } from './frontmatter.js';
+import { IVFIndex } from './ivf.js';
+export { tokenize } from './lexical.js';
+export declare const _stats: {
+    corpusTokenizedChars: number;
+};
+export declare function keywordScores(chunks: IndexChunk[], query: string): number[];
+export declare function rrf(rankings: Array<Array<{
+    idx: number;
+    score: number;
+}>>, k?: number): Map<number, number>;
+export interface IndexChunk {
+    file: string;
+    title: string;
+    heading: string;
+    headingPath?: string[];
+    text: string;
+    vec: number[] | Float32Array;
+    chunkHash?: string;
+    startLine?: number;
+    endLine?: number;
+    meta?: DocumentMetadata;
+}
+export interface IndexFile {
+    format?: string;
+    schemaVersion?: number;
+    model?: string;
+    modelAlias?: string;
+    dim?: number;
+    built?: string;
+    chunkCount?: number;
+    db?: string;
+    lexical?: LexicalIndex;
+    chunks: IndexChunk[];
+}
+export declare class QueryEmbeddingCache {
+    maxSize: number;
+    cache: Map<string, Float32Array>;
+    inFlight: Map<string, Promise<Float32Array>>;
+    constructor(maxSize?: number);
+    get(key: string): Float32Array | undefined;
+    set(key: string, vector: number[] | Float32Array): void;
+    getOrCompute(key: string, fn: () => Promise<number[] | Float32Array>): Promise<Float32Array>;
+    clear(): void;
+    get size(): number;
+}
+export type LexicalState = {
+    kind: 'persisted-bm25';
+    lexical: LexicalIndex;
+} | {
+    kind: 'legacy-overlap';
+};
+export interface RuntimeChunk {
+    file: string;
+    title: string;
+    heading: string;
+    headingPath?: string[];
+    text: string;
+    startLine?: number;
+    endLine?: number;
+    meta?: DocumentMetadata;
+    vec: Float32Array;
+}
+export interface RuntimeIndexState {
+    schema: number;
+    db: string | undefined;
+    chunks: RuntimeChunk[];
+    lexicalState: LexicalState;
+    expectedDim: number | undefined;
+    model: ModelDescriptor;
+    queryCache: QueryEmbeddingCache;
+    ivf?: IVFIndex;
+}
+export declare function loadIndex(indexDir: string): {
+    index: IndexFile;
+    model: ModelDescriptor;
+};
+export declare const MAX_QUERY_LENGTH = 2048;
+export interface SearchOptions {
+    loaded: {
+        index: IndexFile;
+        model: ModelDescriptor;
+    };
+    cacheDir: string;
+    query: string;
+    k?: number;
+    semanticOnly?: boolean;
+    offline?: boolean;
+    path?: string | string[];
+    since?: string | Date;
+    rerank?: boolean;
+    rerankPool?: number;
+    rerankFn?: any;
+    embedFn?: any;
+    tag?: string | string[];
+    project?: string;
+    type?: string;
+    status?: string;
+    canonicalOnly?: boolean;
+    custom?: Record<string, unknown>;
+    explain?: boolean;
+    maxPerFile?: number;
+    maxPerDoc?: number;
+    useQueryCache?: boolean;
+    ann?: boolean;
+    nprobe?: number;
+}
+export interface SearchResultHit {
+    file: string;
+    title: string;
+    heading: string;
+    cosine: number;
+    score: number;
+    matches: string[];
+    snippet: string;
+    meta?: DocumentMetadata;
+    explain?: {
+        cosine: number;
+        rrfScore: number;
+        bm25Weights: {
+            title: number;
+            aliases: number;
+            headingPath: number;
+            body: number;
+        };
+    };
+    rerankScore?: number;
+}
+export declare function searchIndex(opts: SearchOptions): Promise<SearchResultHit[]>;
+export type OneShotSearchOptions = Omit<SearchOptions, 'loaded'> & {
+    indexDir: string;
+};
+export declare function search(opts: OneShotSearchOptions): Promise<SearchResultHit[]>;

package/dist/search.js

@@ -0,0 +1,492 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { embed, cosine, decodeVec, globToRegExp, walkMarkdown } from './core.js';
+import { validateIndexEnvelope, validateNumericVector } from './index-format.js';
+import { rerankScores } from './rerank.js';
+import { bm25Scores, matchingTerms, tokenize, fuzzyTitleAliasScores } from './lexical.js';
+import { collapseResults } from './collapse.js';
+import { trainIVF, searchIVFCandidates, deserializeIVF, ANN_THRESHOLD, DEFAULT_NPROBE } from './ivf.js';
+export { tokenize } from './lexical.js';
+const chunkTokens = new WeakMap();
+export const _stats = { corpusTokenizedChars: 0 };
+function tokenSet(c) {
+    let s = chunkTokens.get(c);
+    if (!s) {
+        const text = `${c.title} ${c.heading} ${c.text}`;
+        _stats.corpusTokenizedChars += text.length;
+        s = new Set(tokenize(text));
+        chunkTokens.set(c, s);
+    }
+    return s;
+}
+export function keywordScores(chunks, query) {
+    const qTerms = new Set(tokenize(query));
+    if (qTerms.size === 0)
+        return chunks.map(() => 0);
+    return chunks.map((c) => {
+        const hay = tokenSet(c);
+        let s = 0;
+        for (const t of qTerms)
+            if (hay.has(t))
+                s++;
+        return s;
+    });
+}
+export function rrf(rankings, k = 60) {
+    const fused = new Map();
+    for (const ranking of rankings) {
+        const sorted = [...ranking].sort((a, b) => b.score - a.score);
+        let scoreRank = 0;
+        sorted.forEach((item, rank) => {
+            if (item.score <= 0)
+                return;
+            if (rank > 0 && item.score < sorted[rank - 1].score)
+                scoreRank = rank;
+            fused.set(item.idx, (fused.get(item.idx) || 0) + 1 / (k + scoreRank + 1));
+        });
+    }
+    return fused;
+}
+export class QueryEmbeddingCache {
+    maxSize;
+    cache;
+    inFlight;
+    constructor(maxSize = 100) {
+        this.maxSize = maxSize;
+        this.cache = new Map();
+        this.inFlight = new Map();
+    }
+    get(key) {
+        if (!this.cache.has(key))
+            return undefined;
+        const value = this.cache.get(key);
+        this.cache.delete(key);
+        this.cache.set(key, value);
+        return value;
+    }
+    set(key, vector) {
+        if (!Array.isArray(vector) && !(vector instanceof Float32Array))
+            return;
+        if (vector.length === 0)
+            return;
+        const arr = vector instanceof Float32Array ? vector : Float32Array.from(vector);
+        for (let i = 0; i < arr.length; i++) {
+            if (!Number.isFinite(arr[i]))
+                return;
+        }
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        else if (this.cache.size >= this.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined)
+                this.cache.delete(oldestKey);
+        }
+        this.cache.set(key, arr);
+    }
+    async getOrCompute(key, fn) {
+        const cached = this.get(key);
+        if (cached)
+            return cached;
+        if (this.inFlight.has(key)) {
+            return this.inFlight.get(key);
+        }
+        const promise = (async () => {
+            try {
+                const raw = await fn();
+                this.set(key, raw);
+                const stored = this.get(key);
+                if (stored)
+                    return stored;
+                return raw instanceof Float32Array ? raw : Float32Array.from(raw);
+            }
+            finally {
+                this.inFlight.delete(key);
+            }
+        })();
+        this.inFlight.set(key, promise);
+        return promise;
+    }
+    clear() {
+        this.cache.clear();
+        this.inFlight.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+const runtimeIndexStates = new WeakMap();
+function snapshotRuntimeIndex(index, validation) {
+    const dim = validation.dim || (index.chunks[0]?.vec?.length ?? 0);
+    const count = index.chunks.length;
+    const vectorsBuffer = dim > 0 ? new Float32Array(count * dim) : null;
+    const chunks = index.chunks.map((chunk, i) => {
+        let vec;
+        if (vectorsBuffer && dim > 0) {
+            const offset = i * dim;
+            if (chunk.vec instanceof Float32Array) {
+                vectorsBuffer.set(chunk.vec, offset);
+            }
+            else {
+                const arr = chunk.vec;
+                for (let j = 0; j < dim; j++)
+                    vectorsBuffer[offset + j] = arr[j];
+            }
+            vec = vectorsBuffer.subarray(offset, offset + dim);
+        }
+        else {
+            vec = Float32Array.from(chunk.vec);
+        }
+        return {
+            file: chunk.file,
+            title: chunk.title,
+            heading: chunk.heading,
+            headingPath: chunk.headingPath,
+            text: chunk.text,
+            startLine: chunk.startLine,
+            endLine: chunk.endLine,
+            meta: chunk.meta,
+            vec,
+        };
+    });
+    let lexicalState = { kind: 'legacy-overlap' };
+    if (validation.schema >= 3 && index.lexical) {
+        const postings = Object.create(null);
+        for (const [term, posting] of Object.entries(index.lexical.postings)) {
+            postings[term] = posting.map(([docId, frequency]) => [docId, frequency]);
+        }
+        lexicalState = {
+            kind: 'persisted-bm25',
+            lexical: {
+                format: index.lexical.format,
+                documentLengths: [...index.lexical.documentLengths],
+                postings,
+            },
+        };
+    }
+    return {
+        schema: validation.schema,
+        db: index.db,
+        chunks,
+        lexicalState,
+        expectedDim: validation.dim,
+        model: { ...validation.model },
+        queryCache: new QueryEmbeddingCache(100),
+        ivf: validation.ivf,
+    };
+}
+function validateRuntimeIndex(index) {
+    const cached = runtimeIndexStates.get(index);
+    if (cached)
+        return cached;
+    const validated = validateIndexEnvelope(index, 'index', { encoding: 'loaded' });
+    let expectedDim = validated.dim;
+    if (validated.schema < 3) {
+        for (let position = 0; position < index.chunks.length; position++) {
+            const chunk = index.chunks[position];
+            if (chunk === null || typeof chunk !== 'object' || Array.isArray(chunk)) {
+                throw new Error(`chunk ${position} must be an object — run \`mdss index\` to rebuild`);
+            }
+            const where = chunk.file + (chunk.heading ? ` › ${chunk.heading}` : '');
+            const length = validateNumericVector(chunk.vec, expectedDim, `chunk ${where}`);
+            expectedDim ??= length;
+        }
+    }
+    const state = snapshotRuntimeIndex(index, {
+        schema: validated.schema,
+        dim: expectedDim,
+        model: validated.model,
+    });
+    runtimeIndexStates.set(index, state);
+    return state;
+}
+function warnIfStale(index) {
+    if (!index.db || !index.built)
+        return;
+    const builtMs = Date.parse(index.built);
+    if (!Number.isFinite(builtMs))
+        return;
+    let newest = 0;
+    try {
+        for (const f of walkMarkdown(index.db)) {
+            const st = fs.statSync(f);
+            if (st.mtimeMs > newest)
+                newest = st.mtimeMs;
+        }
+    }
+    catch {
+        return;
+    }
+    if (newest <= builtMs + 5000)
+        return;
+    const mins = Math.max(1, Math.round((newest - builtMs) / 60000));
+    process.stderr.write(`warning: index is ${mins} min older than the newest change in ${index.db}; run \`mdss index\` to refresh.\n`);
+}
+export function loadIndex(indexDir) {
+    const vectorsPath = path.join(indexDir, 'vectors.json');
+    if (!fs.existsSync(vectorsPath)) {
+        throw new Error(`No index at ${vectorsPath}. Run \`mdss index\` first.`);
+    }
+    const rawBytes = fs.readFileSync(vectorsPath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBytes);
+    }
+    catch (e) {
+        throw new Error(`${vectorsPath} is not valid JSON (${e.message}); run \`mdss index\` to rebuild.`, { cause: e });
+    }
+    const validated = validateIndexEnvelope(parsed, vectorsPath, { encoding: 'stored' });
+    const index = validated.index;
+    const shaPath = path.join(indexDir, 'vectors.json.sha256');
+    if (fs.existsSync(shaPath)) {
+        try {
+            const shaContent = fs.readFileSync(shaPath, 'utf8').trim();
+            const expectedHash = shaContent.split(/\s+/)[0];
+            const actualHash = crypto.createHash('sha256').update(rawBytes).digest('hex');
+            if (expectedHash && actualHash !== expectedHash) {
+                throw new Error(`vectors.json integrity check failed (SHA-256 mismatch) — run \`mdss index\` to rebuild.`);
+            }
+        }
+        catch (e) {
+            if (e.message.includes('integrity check failed'))
+                throw e;
+        }
+    }
+    const { model, dim: validatedDim } = validated;
+    let expectedDim = validatedDim;
+    if (!index.model && !index.modelAlias) {
+        process.stderr.write('warning: index has no "model" field (built by an old version); assuming the default model. Re-run `mdss index` to refresh.\n');
+    }
+    for (let position = 0; position < index.chunks.length; position++) {
+        const c = index.chunks[position];
+        if (c === null || typeof c !== 'object' || Array.isArray(c)) {
+            throw new Error(`chunk ${position} must be an object — run \`mdss index\` to rebuild`);
+        }
+        if (typeof c.vec === 'string') {
+            if (index.format !== 'binary-v1') {
+                throw new Error(`chunk ${c.file}: unexpected base64 vector in a legacy decimal index — run \`mdss index\` to rebuild`);
+            }
+            try {
+                c.vec = decodeVec(c.vec, expectedDim);
+                expectedDim ??= c.vec.length;
+            }
+            catch (e) {
+                const where = c.file + (c.heading ? ` › ${c.heading}` : '');
+                throw new Error(`chunk ${where}: ${e.message}`, { cause: e });
+            }
+        }
+        else {
+            const where = c.file + (c.heading ? ` › ${c.heading}` : '');
+            const length = validateNumericVector(c.vec, expectedDim, `chunk ${where}`);
+            expectedDim ??= length;
+        }
+    }
+    warnIfStale(index);
+    const ivfPath = path.join(indexDir, 'ivf.json');
+    let ivf;
+    if (fs.existsSync(ivfPath)) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(ivfPath, 'utf8'));
+            ivf = deserializeIVF(raw);
+        }
+        catch { }
+    }
+    runtimeIndexStates.set(index, snapshotRuntimeIndex(index, { schema: validated.schema, dim: expectedDim, model, ivf }));
+    return { index, model };
+}
+export const MAX_QUERY_LENGTH = 2048;
+export async function searchIndex(opts) {
+    const { loaded, cacheDir, query, k = 6, semanticOnly = false, offline = false, path: pathFilter, since, rerank = false, rerankPool, tag, project, type, status, canonicalOnly, custom, } = opts;
+    if (typeof query === 'string' && query.length > MAX_QUERY_LENGTH) {
+        throw new Error(`query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`);
+    }
+    const embedFn = opts.embedFn ?? embed;
+    const rerankFn = opts.rerankFn ?? rerankScores;
+    const { index } = loaded;
+    const runtime = validateRuntimeIndex(index);
+    const { chunks, db, lexicalState, expectedDim } = runtime;
+    const pathRes = pathFilter ? (Array.isArray(pathFilter) ? pathFilter : [pathFilter]).map(globToRegExp) : [];
+    let sinceMs;
+    if (since !== undefined) {
+        sinceMs = since instanceof Date ? since.getTime() : Date.parse(String(since));
+        if (Number.isNaN(sinceMs))
+            throw new Error(`Invalid --since date: "${since}" (use YYYY-MM-DD or ISO 8601)`);
+    }
+    let candidates = chunks.map((chunk, idx) => ({ chunk, idx }));
+    const hasMetaFilter = tag !== undefined ||
+        project !== undefined ||
+        type !== undefined ||
+        status !== undefined ||
+        canonicalOnly !== undefined ||
+        custom !== undefined;
+    if (pathRes.length > 0 || sinceMs !== undefined || hasMetaFilter) {
+        if (sinceMs !== undefined && !db) {
+            throw new Error('--since requires an index that knows its --db (index.db missing). Re-run `mdss index`.');
+        }
+        const mtimeCache = new Map();
+        candidates = candidates.filter(({ chunk }) => {
+            if (pathRes.length > 0 && !pathRes.some((re) => re.test(chunk.file)))
+                return false;
+            if (sinceMs !== undefined) {
+                let m = mtimeCache.get(chunk.file);
+                if (m === undefined) {
+                    try {
+                        m = fs.statSync(path.join(db, chunk.file)).mtimeMs;
+                    }
+                    catch {
+                        m = -Infinity;
+                    }
+                    mtimeCache.set(chunk.file, m);
+                }
+                if (m < sinceMs)
+                    return false;
+            }
+            if (tag !== undefined) {
+                const reqTags = (Array.isArray(tag) ? tag : [tag]).map((t) => String(t).toLowerCase().replace(/^#/, ''));
+                const chunkTags = chunk.meta?.tags || [];
+                if (!reqTags.every((rt) => chunkTags.includes(rt)))
+                    return false;
+            }
+            if (project !== undefined && chunk.meta?.project !== project)
+                return false;
+            if (type !== undefined && chunk.meta?.type !== type)
+                return false;
+            if (status !== undefined && chunk.meta?.status !== status)
+                return false;
+            if (canonicalOnly && chunk.meta?.canonical === false)
+                return false;
+            if (custom && typeof custom === 'object') {
+                for (const [key, value] of Object.entries(custom)) {
+                    if (chunk.meta?.custom?.[key] !== value)
+                        return false;
+                }
+            }
+            return true;
+        });
+    }
+    let qVec;
+    if (opts.useQueryCache !== false && runtime.queryCache) {
+        const cacheKey = `${runtime.model.id}:${runtime.model.revision || 'main'}:${expectedDim || 0}:${query.trim().toLowerCase()}`;
+        qVec = await runtime.queryCache.getOrCompute(cacheKey, async () => {
+            const [v] = await embedFn([query], 'query', runtime.model, cacheDir, offline);
+            if ((Array.isArray(v) || v instanceof Float32Array) && expectedDim !== undefined && v.length !== expectedDim) {
+                throw new Error(`query vector has ${v.length} dims, expected ${expectedDim} — run \`mdss index\` to rebuild`);
+            }
+            validateNumericVector(v, undefined, 'query vector');
+            return v;
+        });
+    }
+    else {
+        const [v] = await embedFn([query], 'query', runtime.model, cacheDir, offline);
+        if ((Array.isArray(v) || v instanceof Float32Array) && expectedDim !== undefined && v.length !== expectedDim) {
+            throw new Error(`query vector has ${v.length} dims, expected ${expectedDim} — run \`mdss index\` to rebuild`);
+        }
+        validateNumericVector(v, undefined, 'query vector');
+        qVec = v;
+    }
+    const queryTerms = [...new Set(tokenize(query))];
+    let semantic;
+    const useAnn = opts.ann ?? (runtime.ivf !== undefined && candidates.length >= ANN_THRESHOLD);
+    if (useAnn && candidates.length >= ANN_THRESHOLD) {
+        if (!runtime.ivf) {
+            const rawVecs = chunks.map((c) => c.vec);
+            runtime.ivf = trainIVF(rawVecs);
+        }
+        const qVecF32 = qVec instanceof Float32Array ? qVec : Float32Array.from(qVec);
+        const probedSet = new Set(searchIVFCandidates(qVecF32, runtime.ivf, opts.nprobe ?? DEFAULT_NPROBE));
+        semantic = candidates.map(({ chunk, idx }) => {
+            if (!probedSet.has(idx)) {
+                return { idx, score: -1 };
+            }
+            return { idx, score: cosine(qVec, chunk.vec) };
+        });
+    }
+    else {
+        semantic = candidates.map(({ chunk, idx }) => {
+            return { idx, score: cosine(qVec, chunk.vec) };
+        });
+    }
+    const cosByIdx = new Map(semantic.map((s) => [s.idx, s.score]));
+    const pool = rerank ? rerankPool || Math.max(20, k * 3) : k;
+    let ranked;
+    if (semanticOnly) {
+        ranked = [...semantic]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, pool)
+            .map((s) => ({ idx: s.idx, fscore: s.score, cos: s.score }));
+    }
+    else {
+        const kw = lexicalState.kind === 'persisted-bm25'
+            ? [...bm25Scores(lexicalState.lexical, queryTerms, new Set(candidates.map((c) => c.idx))).entries()].map(([idx, score]) => ({ idx, score }))
+            : keywordScores(candidates.map((c) => c.chunk), query).map((score, position) => ({
+                idx: candidates[position].idx,
+                score,
+            }));
+        const fuzzy = [...fuzzyTitleAliasScores(candidates.map((c) => c.chunk), query).entries()].map(([position, score]) => ({
+            idx: candidates[position].idx,
+            score,
+        }));
+        const fused = rrf([semantic, kw, fuzzy]);
+        ranked = [...fused.entries()]
+            .map(([idx, fscore]) => ({ idx, fscore, cos: cosByIdx.get(idx) }))
+            .sort((a, b) => b.fscore - a.fscore)
+            .slice(0, pool);
+    }
+    if (rerank && ranked.length > 0) {
+        const texts = ranked.map((r) => chunks[r.idx].text);
+        const scores = await rerankFn(query, texts, cacheDir, offline);
+        ranked = ranked
+            .map((r, i) => ({ ...r, rerank: scores[i] ?? -Infinity }))
+            .sort((a, b) => b.rerank - a.rerank)
+            .slice(0, k);
+    }
+    const hasMetaFields = (m) => Boolean(m &&
+        (m.tags?.length > 0 ||
+            m.aliases?.length > 0 ||
+            m.project ||
+            m.type ||
+            m.status ||
+            m.canonical !== undefined ||
+            m.canonicalRef ||
+            m.created ||
+            m.updated ||
+            Object.keys(m.custom || {}).length > 0));
+    const explain = opts.explain === true;
+    const hits = ranked.map((r) => {
+        const c = chunks[r.idx];
+        const matches = lexicalState.kind === 'persisted-bm25'
+            ? matchingTerms(lexicalState.lexical, queryTerms, r.idx)
+            : queryTerms.filter((term) => tokenSet(c).has(term));
+        return {
+            file: c.file,
+            title: c.title,
+            heading: c.heading,
+            cosine: +r.cos.toFixed(3),
+            score: +r.fscore.toFixed(4),
+            matches,
+            snippet: c.text.replace(/\s+/g, ' ').slice(0, 220),
+            ...(hasMetaFields(c.meta) ? { meta: c.meta } : {}),
+            ...(explain
+                ? {
+                    explain: {
+                        cosine: +r.cos.toFixed(4),
+                        rrfScore: +r.fscore.toFixed(4),
+                        bm25Weights: { title: 3.0, aliases: 3.0, headingPath: 1.8, body: 1.0 },
+                    },
+                }
+                : {}),
+            ...(rerank ? { rerankScore: +(r.rerank ?? 0).toFixed(4) } : {}),
+        };
+    });
+    const maxPerDoc = opts.maxPerFile || opts.maxPerDoc;
+    if (maxPerDoc && maxPerDoc > 0) {
+        return collapseResults(hits, (h) => h.meta?.canonicalRef || h.file, maxPerDoc).slice(0, k);
+    }
+    return hits;
+}
+export async function search(opts) {
+    const { indexDir, ...rest } = opts;
+    const loaded = loadIndex(indexDir);
+    return searchIndex({ ...rest, loaded });
+}

package/dist/serve.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Long-running daemon mode (issue #12): keeps the parsed index AND the
+ * embedding extractor in memory across queries, so repeated searches skip
+ * the ~280 MB model load and the full vectors.json parse on every call.
+ */
+import http from 'node:http';
+import { ModelDescriptor } from './core.js';
+declare const DEFAULT_PORT = 8747;
+declare const DEFAULT_HOST = "127.0.0.1";
+declare const WATCH_INTERVAL_MS = 3000;
+declare const MAX_BODY_BYTES: number;
+export interface ServeState {
+    loaded: {
+        index: any;
+        model: ModelDescriptor;
+    };
+    indexDir: string;
+    cacheDir: string;
+    offline: boolean;
+    embedFn?: any;
+    rerankFn?: any;
+    watching: boolean;
+    reindexCount?: number;
+    apiKey?: string;
+    healthPublic?: boolean;
+}
+export interface CreateServeOptions {
+    indexDir: string;
+    cacheDir: string;
+    db?: string;
+    modelName?: string;
+    ignore?: string[];
+    offline?: boolean;
+    watch?: boolean;
+    watchInterval?: number;
+    watchDelay?: number;
+    apiKey?: string;
+    healthPublic?: boolean;
+    embedFn?: any;
+    rerankFn?: any;
+    log?: (msg: string) => void;
+}
+export declare function createServe(opts: CreateServeOptions): Promise<{
+    server: http.Server;
+    state: ServeState;
+    close: () => Promise<void>;
+}>;
+export declare function isAuthorizedToken(token?: string | null, expectedKey?: string | null): boolean;
+export { DEFAULT_PORT, DEFAULT_HOST, MAX_BODY_BYTES, WATCH_INTERVAL_MS };