@wirecat/cli-core 0.434.0 → 0.435.0

package/dist/embeddings/embed.js

@@ -8,6 +8,20 @@ export const isTextModelInstalled = (model, directory) => filesPresent(placedTex
 /** Past 8 threads one session gains nothing; Bun takes 1 unless told (`2026-10-02-embeddings.md`). */
 export const defaultThreads = () => Math.min(8, availableParallelism());
 export const WARM_IDLE_MS = 10 * 60_000;
+/** One search's models, so the parts of a search that need the same model load it once; closed when it ends. */
+export const runEmbedders = () => {
+    const held = new Map();
+    return {
+        get: (key, open) => {
+            const one = held.get(key) ?? open();
+            held.set(key, one);
+            return one;
+        },
+        close: async () => {
+            await Promise.allSettled([...held.values()].map(async (one) => (await one).close()));
+        },
+    };
+};
 export const warmEmbedders = ({ idleMs = WARM_IDLE_MS } = {}) => {
     const held = new Map();
     const timers = new Map();
@@ -33,28 +47,38 @@ export const warmEmbedders = ({ idleMs = WARM_IDLE_MS } = {}) => {
         timer.unref?.();
         timers.set(key, timer);
     };
+    const hold = (key, open, serial) => {
+        let opening = held.get(key);
+        if (!opening) {
+            const started = open().then((one) => serial(one, queue({
+                starts: () => running.set(key, (running.get(key) ?? 0) + 1),
+                ends: () => {
+                    running.set(key, (running.get(key) ?? 1) - 1);
+                    rearm(key);
+                },
+            })));
+            held.set(key, started);
+            // A model not downloaded yet must not stay refused once it is.
+            started.catch(() => {
+                if (held.get(key) === started)
+                    drop(key);
+            });
+            opening = started;
+        }
+        rearm(key);
+        return opening;
+    };
     return {
-        get: (key, open) => {
-            let opening = held.get(key);
-            if (!opening) {
-                const started = open().then((one) => serial(one, {
-                    starts: () => running.set(key, (running.get(key) ?? 0) + 1),
-                    ends: () => {
-                        running.set(key, (running.get(key) ?? 1) - 1);
-                        rearm(key);
-                    },
-                }));
-                held.set(key, started);
-                // A model not downloaded yet must not stay refused once it is.
-                started.catch(() => {
-                    if (held.get(key) === started)
-                        drop(key);
-                });
-                opening = started;
-            }
-            rearm(key);
-            return opening;
-        },
+        get: (key, open) => hold(key, open, (embedder, run) => ({
+            model: embedder.model,
+            embed: (texts, kind) => run.next(() => embedder.embed(texts, kind)),
+            close: run.closing(() => embedder.close()),
+        })),
+        reranker: (key, open) => hold(key, open, (reranker, run) => ({
+            model: reranker.model,
+            score: (question, passages) => run.next(() => reranker.score(question, passages)),
+            close: run.closing(() => reranker.close()),
+        })),
         close: async () => {
             const all = [...held.keys()].map(drop);
             await Promise.allSettled(all.map(async (one) => (await one)?.close()));
@@ -62,19 +86,19 @@ export const warmEmbedders = ({ idleMs = WARM_IDLE_MS } = {}) => {
     };
 };
 /** Two MCP calls may arrive at once; a session is not documented to take overlapping runs. */
-const serial = (embedder, { starts, ends }) => {
+const queue = ({ starts, ends }) => {
     let last = Promise.resolve();
     return {
-        model: embedder.model,
-        embed: (texts, kind) => {
+        next: (work) => {
             starts();
-            const next = last.then(() => embedder.embed(texts, kind));
+            const next = last.then(work);
             last = next.then(ends, ends);
             return next;
         },
-        close: async () => {
+        /** Closing waits for the run in progress. */
+        closing: (close) => async () => {
             await last;
-            await embedder.close();
+            await close();
         },
     };
 };
@@ -96,7 +120,8 @@ export const meanOf = (data, tokens, dims) => {
     }
     return mean;
 };
-export const openEmbedder = async (model, directory, { threads = defaultThreads() } = {}) => {
+/** A model's tokenizer and ONNX session, from its folder. */
+export const loadModel = async (model, directory, threads) => {
     const [{ Tokenizer }, ort] = await Promise.all([import("@huggingface/tokenizers"), import("@wirecat/cli-core-onnx")]);
     const path = (name) => join(directory, model.id, name);
     const tokenizer = new Tokenizer(JSON.parse(readFileSync(path("tokenizer.json"), "utf8")), JSON.parse(readFileSync(path("tokenizer_config.json"), "utf8")));
@@ -104,6 +129,10 @@ export const openEmbedder = async (model, directory, { threads = defaultThreads(
     const session = await ort.InferenceSession.create(readFileSync(path(model.onnx)), model.externalData
         ? { externalData: [{ path: basename(model.externalData), data: readFileSync(path(model.externalData)) }] }
         : {});
+    return { ort, tokenizer, session };
+};
+export const openEmbedder = async (model, directory, { threads = defaultThreads() } = {}) => {
+    const { ort, tokenizer, session } = await loadModel(model, directory, threads);
     const typeIds = session.inputNames.includes("token_type_ids");
     const one = async (text) => {
         const ids = truncated(tokenizer.encode(text).ids, model.maxTokens);

package/dist/embeddings/models.d.ts

@@ -32,6 +32,24 @@ export interface TextModel {
 export declare const TEXT_MODELS: TextModel[];
 export declare const DEFAULT_TEXT_MODEL = "e5-small";
 export declare const textModel: (id: string) => TextModel;
+/**
+ * Cross-encoders that read a question and one hit together and score how well the hit answers it: discovery's
+ * last step. Pinned and checked as the text models are, and kept beside them. Picked in the evidence-pipeline
+ * benchmark (cli-testing performance/search/evidence-pipeline, "Reranker variants").
+ */
+export interface RerankModel {
+    id: string;
+    title: string;
+    languages: string;
+    licence: string;
+    /** Question and hit together; a longer pair loses the end of the hit. */
+    maxTokens: number;
+    files: ModelFile[];
+    onnx: string;
+}
+export declare const RERANK_MODELS: RerankModel[];
+export declare const DEFAULT_RERANK_MODEL = "mmarco";
+export declare const rerankModel: (id: string) => RerankModel;
 /** The cosine a meaning hit must beat, measured in bench/search-quality; an unmeasured model keeps every hit. */
 /** A vector's model: the provider, the model and its size — vectors of two of them never mix. */
 export declare const vectorModelKey: (model: TextModel) => string;

package/dist/embeddings/models.js

@@ -85,6 +85,75 @@ export const textModel = (id) => {
     }
     return found;
 };
+const mmarco = huggingFace("cross-encoder/mmarco-mMiniLMv2-L12-H384-v1", "1427fd652930e4ba29e8149678df786c240d8825");
+const bge = huggingFace("onnx-community/bge-reranker-v2-m3-ONNX", "6f5ff65298512715a1e669753bc754d2bc8f367b");
+export const RERANK_MODELS = [
+    {
+        id: "mmarco",
+        title: "mMARCO mMiniLMv2-L12 cross-encoder, 8-bit",
+        languages: "about 100 languages, Russian and English among them",
+        licence: "Apache-2.0",
+        maxTokens: 512,
+        // The x86 name is the quantizer's target; Core runs every model as WebAssembly, on any processor.
+        onnx: "onnx/model_quint8_avx2.onnx",
+        files: [
+            {
+                name: "onnx/model_quint8_avx2.onnx",
+                url: mmarco("onnx/model_quint8_avx2.onnx"),
+                sha256: "6c2513767fb63d008a4377bef7a7a3555433d9436342bb53e35a3a72ffc52d4b",
+                bytes: 118_620_016,
+            },
+            {
+                name: "tokenizer.json",
+                url: mmarco("tokenizer.json"),
+                sha256: "62c24cdc13d4c9952d63718d6c9fa4c287974249e16b7ade6d5a85e7bbb75626",
+                bytes: 17_082_660,
+            },
+            {
+                name: "tokenizer_config.json",
+                url: mmarco("tokenizer_config.json"),
+                sha256: "e7fbfbfa6347b4e414c1cee50d142e2c2f9a895dad68b068ae83a8b564c3837e",
+                bytes: 435,
+            },
+        ],
+    },
+    {
+        id: "bge-reranker-v2-m3",
+        title: "BGE reranker v2 m3, 8-bit",
+        languages: "over 100 languages — better than mmarco in the benchmark, about seven times slower",
+        licence: "Apache-2.0 (BAAI's; the ONNX export declares none)",
+        maxTokens: 512,
+        onnx: "onnx/model_quantized.onnx",
+        files: [
+            {
+                name: "onnx/model_quantized.onnx",
+                url: bge("onnx/model_quantized.onnx"),
+                sha256: "912fc1215c2dbff6499700534bd8d31253af01573861abbfc43afd1fab6cce5d",
+                bytes: 570_727_094,
+            },
+            {
+                name: "tokenizer.json",
+                url: bge("tokenizer.json"),
+                sha256: "8bf8afbfd11306bd872018c53bfdf2e160a56f8edbcf49933324404791c148d3",
+                bytes: 17_082_900,
+            },
+            {
+                name: "tokenizer_config.json",
+                url: bge("tokenizer_config.json"),
+                sha256: "b87c8703482b0300d3da30e201519aa641f6a450f5eb5bf1e624afbf70c74d80",
+                bytes: 1_203,
+            },
+        ],
+    },
+];
+export const DEFAULT_RERANK_MODEL = "mmarco";
+export const rerankModel = (id) => {
+    const found = RERANK_MODELS.find((model) => model.id === id);
+    if (!found) {
+        throw new CliError("validation_error", `no reranker ${id} — one of: ${RERANK_MODELS.map((model) => model.id).join(", ")}`);
+    }
+    return found;
+};
 /** The cosine a meaning hit must beat, measured in bench/search-quality; an unmeasured model keeps every hit. */
 /** A vector's model: the provider, the model and its size — vectors of two of them never mix. */
 export const vectorModelKey = (model) => `local:${model.id}:${model.dims}`;

package/dist/embeddings/process.d.ts

@@ -1,5 +1,6 @@
 import type { Embedder } from "./embed.js";
-import type { TextModel } from "./models.js";
+import type { RerankModel, TextModel } from "./models.js";
+import type { Reranker } from "./rerank.js";
 /**
  * One session in a process of its own, run by the same runtime. When it exits, all of its memory goes back:
  * closing the session gives back ~0.1 of ~1 GB, and on Bun ending a worker thread gives back none for good
@@ -8,3 +9,7 @@ import type { TextModel } from "./models.js";
 export declare const openProcess: (model: TextModel, directory: string, { threads }: {
     threads: number;
 }) => Promise<Embedder>;
+/** The reranker the same way, for the MCP server. */
+export declare const openRerankerProcess: (model: RerankModel, directory: string, { threads }: {
+    threads: number;
+}) => Promise<Reranker>;

package/dist/embeddings/process.js

@@ -7,7 +7,24 @@ import { fileURLToPath } from "node:url";
  * (measured 2026-10-02, docs/storage/search-indexes.md).
  */
 export const openProcess = async (model, directory, { threads }) => {
-    const child = spawn(process.execPath, [fileURLToPath(new URL("./child.js", import.meta.url)), JSON.stringify({ model, directory, threads })], { stdio: ["pipe", "pipe", "pipe"] });
+    const child = await modelProcess({ model, directory, threads });
+    return {
+        model,
+        embed: async (texts, kind) => ((await child.ask({ texts, kind })).vectors ?? []).map((vector) => Float32Array.from(vector)),
+        close: child.close,
+    };
+};
+/** The reranker the same way, for the MCP server. */
+export const openRerankerProcess = async (model, directory, { threads }) => {
+    const child = await modelProcess({ model, directory, threads, rerank: true });
+    return {
+        model,
+        score: async (question, passages) => (await child.ask({ question, texts: passages })).scores ?? [],
+        close: child.close,
+    };
+};
+const modelProcess = async (setup) => {
+    const child = spawn(process.execPath, [fileURLToPath(new URL("./child.js", import.meta.url)), JSON.stringify(setup)], { stdio: ["pipe", "pipe", "pipe"] });
     const pending = new Map();
     let said = "";
     child.stderr.setEncoding("utf8").on("data", (text) => {
@@ -41,21 +58,20 @@ export const openProcess = async (model, directory, { threads }) => {
             return ready();
         const job = pending.get(answer.id);
         pending.delete(answer.id);
-        if (answer.error !== undefined || !answer.vectors)
-            job?.reject(new Error(answer.error ?? "no vectors"));
+        if (answer.error !== undefined || !(answer.vectors ?? answer.scores))
+            job?.reject(new Error(answer.error ?? "no answer"));
         else
-            job?.resolve(answer.vectors.map((vector) => Float32Array.from(vector)));
+            job?.resolve(answer);
     });
     await started;
     let next = 0;
     return {
-        model,
-        embed: (texts, kind) => new Promise((resolve, reject) => {
+        ask: (request) => new Promise((resolve, reject) => {
             if (gone)
                 return reject(gone);
             const id = next++;
             pending.set(id, { resolve, reject });
-            child.stdin.write(`${JSON.stringify({ id, texts, kind })}\n`);
+            child.stdin.write(`${JSON.stringify({ id, ...request })}\n`);
         }),
         close: async () => {
             if (child.exitCode === null && child.signalCode === null)

package/dist/embeddings/rerank.d.ts

@@ -0,0 +1,10 @@
+import type { RerankModel } from "./models.js";
+export interface Reranker {
+    readonly model: RerankModel;
+    /** How well each passage answers the question, in order: the model's raw logit, higher is better. */
+    score(question: string, passages: string[]): Promise<number[]>;
+    close(): Promise<void>;
+}
+export declare const openReranker: (model: RerankModel, directory: string, { threads }?: {
+    threads?: number;
+}) => Promise<Reranker>;

package/dist/embeddings/rerank.js

@@ -0,0 +1,31 @@
+import { defaultThreads, loadModel, truncated } from "./embed.js";
+export const openReranker = async (model, directory, { threads = defaultThreads() } = {}) => {
+    const { ort, tokenizer, session } = await loadModel(model, directory, threads);
+    const typeIds = session.inputNames.includes("token_type_ids");
+    const output = session.outputNames[0];
+    const one = async (question, passage) => {
+        const encoded = tokenizer.encode(question, { text_pair: passage, return_token_type_ids: true });
+        const ids = truncated(encoded.ids, model.maxTokens);
+        const shape = [1, ids.length];
+        const feeds = {
+            input_ids: new ort.Tensor("int64", BigInt64Array.from(ids, BigInt), shape),
+            attention_mask: new ort.Tensor("int64", new BigInt64Array(ids.length).fill(1n), shape),
+        };
+        if (typeIds)
+            feeds.token_type_ids = new ort.Tensor("int64", BigInt64Array.from(truncated(encoded.token_type_ids, model.maxTokens), BigInt), shape);
+        const logit = (await session.run(feeds))[output]?.data[0];
+        if (typeof logit !== "number" || !Number.isFinite(logit))
+            throw new Error(`${model.id} gave no score`);
+        return logit;
+    };
+    return {
+        model,
+        score: async (question, passages) => {
+            const scores = [];
+            for (const passage of passages)
+                scores.push(await one(question, passage));
+            return scores;
+        },
+        close: () => session.release(),
+    };
+};

package/dist/entities/conversation-results.d.ts

@@ -42,6 +42,7 @@ export declare const conversationDetails: v.UnionSchema<[v.StrictObjectSchema<{
             readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
             readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+            readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
             readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -229,6 +230,7 @@ export declare const conversationDetails: v.UnionSchema<[v.StrictObjectSchema<{
         readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
         readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
         readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+        readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
         readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;

package/dist/entities/evidence.d.ts

@@ -33,6 +33,7 @@ export declare const contribution: v.StrictObjectSchema<{
             readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
             readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+            readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
             readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -220,6 +221,7 @@ export declare const contribution: v.StrictObjectSchema<{
                 readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
                 readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+                readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             }, undefined>, undefined>;
             readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
                 readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -445,6 +447,7 @@ export declare const contribution: v.StrictObjectSchema<{
             readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
             readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+            readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
             readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -632,6 +635,7 @@ export declare const contribution: v.StrictObjectSchema<{
                 readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
                 readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+                readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             }, undefined>, undefined>;
             readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
                 readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -893,6 +897,7 @@ export declare const evidence: v.UnionSchema<[v.StrictObjectSchema<{
             readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
             readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+            readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
             readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -1080,6 +1085,7 @@ export declare const evidence: v.UnionSchema<[v.StrictObjectSchema<{
                 readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
                 readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+                readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             }, undefined>, undefined>;
             readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
                 readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -1305,6 +1311,7 @@ export declare const evidence: v.UnionSchema<[v.StrictObjectSchema<{
             readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
             readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+            readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
             readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
@@ -1492,6 +1499,7 @@ export declare const evidence: v.UnionSchema<[v.StrictObjectSchema<{
                 readonly missing_terms: v.ArraySchema<v.StringSchema<undefined>, undefined>;
                 readonly parent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly found_by: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>, undefined>;
+                readonly reranker_score: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
             }, undefined>, undefined>;
             readonly context: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
                 readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;