@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/relevance/manager.d.ts

@@ -0,0 +1,79 @@
+import { type GezelConfig, type RelevanceModelOverride, type RelevanceModelStatusResponse, type RelevanceScoreRequest, type RetrievalTraceSurface } from '@bendyline/gezel';
+import type { ActiveRelevance, RelevanceStageProvider } from '../search/relevance-stage.js';
+import type { ResolvedRelevanceModel } from './relevance-core.js';
+import { type RelevanceScorer } from './relevance-model.js';
+import { type ResolvedRelevanceSetting } from './settings.js';
+/**
+ * The relevance model's lifecycle: which one is selected, whether it is on
+ * disk, downloading it on opt-in (only when the security policy allows app
+ * network), warming it, and the status the Settings card and evals read.
+ */
+export declare class RelevanceModelManager implements RelevanceStageProvider {
+    private readonly opts;
+    private job;
+    readonly scorer: RelevanceScorer;
+    constructor(opts: {
+        home: string;
+        readConfig: () => Promise<GezelConfig | null>;
+        scorer?: RelevanceScorer;
+        fetchImpl?: typeof fetch;
+    });
+    setting(): Promise<ResolvedRelevanceSetting>;
+    /**
+     * The model a surface should score with right now, or null when the
+     * setting is off or the model is not installed. Never downloads.
+     */
+    activeModel(): Promise<{
+        setting: ResolvedRelevanceSetting;
+        model: ResolvedRelevanceModel;
+    } | null>;
+    /**
+     * What a retrieval surface scores with: the setting when that surface is on,
+     * or a preview's override (which ignores the surface list and the switch).
+     * Null when off or the model is not on disk — search never downloads.
+     */
+    forSurface(surface: RetrievalTraceSurface, override?: RelevanceModelOverride): Promise<ActiveRelevance | null>;
+    status(): Promise<RelevanceModelStatusResponse>;
+    /** Download a model in the background (network permitting), then warm it. */
+    install(modelId: string): Promise<{
+        started: boolean;
+        installed?: boolean;
+        reason?: string;
+    }>;
+    /** Bring the disk in line with the setting: install the selected model when it is on. */
+    reconcile(): Promise<void>;
+    /**
+     * Deferred boot step: log what is resolved, then warm an installed, enabled
+     * model — or download it when it is enabled but missing. New installs turn
+     * the check on in first-run, which writes config without passing through
+     * the Settings route that would otherwise start the download; so does a
+     * download that failed or was interrupted last session. `install` keeps the
+     * security policy's app-network gate.
+     */
+    bootWarm(): Promise<void>;
+    remove(modelId: string): Promise<boolean>;
+    /** Raw scores for calibration: the bench's `/score` path. */
+    score(request: RelevanceScoreRequest): Promise<{
+        readonly error: `unknown relevance model ${string}`;
+        modelId?: undefined;
+        status?: undefined;
+        ms?: undefined;
+        scores?: undefined;
+        relevances?: undefined;
+    } | {
+        readonly error: `${string} is not installed`;
+        modelId?: undefined;
+        status?: undefined;
+        ms?: undefined;
+        scores?: undefined;
+        relevances?: undefined;
+    } | {
+        modelId: string;
+        status: import("./relevance-model.js").RelevanceRunStatus;
+        ms: number;
+        scores: (number | null)[];
+        relevances: (number | null)[];
+        readonly error?: undefined;
+    }>;
+    private networkAllowed;
+}

package/dist/relevance/manager.js

@@ -0,0 +1,211 @@
+import { createLogger, relevanceFromModelScore, resolveSecurityPolicy, } from '@bendyline/gezel';
+import { installRelevanceModel, installedRelevanceModel, removeRelevanceModel } from './install.js';
+import { DEFAULT_RELEVANCE_MODEL_ID, RELEVANCE_MODELS, findRelevanceModel } from './registry.js';
+import { relevanceScorer } from './relevance-model.js';
+import { resolveRelevanceSetting, toResolvedModel, } from './settings.js';
+const log = createLogger('relevance');
+/**
+ * The relevance model's lifecycle: which one is selected, whether it is on
+ * disk, downloading it on opt-in (only when the security policy allows app
+ * network), warming it, and the status the Settings card and evals read.
+ */
+export class RelevanceModelManager {
+    opts;
+    job = null;
+    scorer;
+    constructor(opts) {
+        this.opts = opts;
+        this.scorer = opts.scorer ?? relevanceScorer();
+    }
+    async setting() {
+        return resolveRelevanceSetting(await this.opts.readConfig().catch(() => null));
+    }
+    /**
+     * The model a surface should score with right now, or null when the
+     * setting is off or the model is not installed. Never downloads.
+     */
+    async activeModel() {
+        const setting = await this.setting();
+        if (!setting.enabled || !setting.spec)
+            return null;
+        if (!(await installedRelevanceModel(this.opts.home, setting.spec)))
+            return null;
+        return { setting, model: toResolvedModel(this.opts.home, setting.spec) };
+    }
+    /**
+     * What a retrieval surface scores with: the setting when that surface is on,
+     * or a preview's override (which ignores the surface list and the switch).
+     * Null when off or the model is not on disk — search never downloads.
+     */
+    async forSurface(surface, override) {
+        const setting = await this.setting();
+        if (override && !override.enabled)
+            return null;
+        if (!override && (!setting.enabled || !setting.surfaces.has(surface)))
+            return null;
+        const spec = override
+            ? findRelevanceModel(override.modelId ?? setting.spec?.id ?? DEFAULT_RELEVANCE_MODEL_ID)
+            : setting.spec;
+        if (!spec || !(await installedRelevanceModel(this.opts.home, spec)))
+            return null;
+        const thresholds = override?.thresholds !== undefined
+            ? override.thresholds
+            : spec.id === setting.spec?.id
+                ? setting.thresholds
+                : spec.thresholds;
+        return {
+            model: toResolvedModel(this.opts.home, spec),
+            thresholds,
+            budgetMs: override?.budgetMs ?? setting.budgets[surface],
+            order: setting.order,
+            knowledgeKeep: override?.knowledgeKeep ?? setting.knowledgeKeep,
+        };
+    }
+    async status() {
+        const setting = await this.setting();
+        const installed = new Set();
+        for (const spec of RELEVANCE_MODELS) {
+            if (await installedRelevanceModel(this.opts.home, spec))
+                installed.add(spec.id);
+        }
+        const modelId = setting.spec?.id ?? '';
+        const job = this.job?.modelId === modelId ? this.job : null;
+        let status;
+        if (!setting.enabled)
+            status = 'off';
+        else if (job && !job.error)
+            status = 'downloading';
+        else if (!installed.has(modelId)) {
+            status = (await this.networkAllowed()) ? 'not-installed' : 'blocked-network';
+        }
+        else
+            status = this.scorer.status(modelId);
+        return {
+            enabled: setting.enabled,
+            modelId,
+            status,
+            source: setting.source,
+            ...(job && !job.error
+                ? { progress: { bytesDone: job.bytesDone, bytesTotal: job.bytesTotal } }
+                : {}),
+            ...(job?.error ? { error: job.error } : {}),
+            models: RELEVANCE_MODELS.map((spec) => ({
+                id: spec.id,
+                displayName: spec.displayName,
+                description: spec.description,
+                languages: spec.languages,
+                approxBytes: spec.approxBytes,
+                ...(spec.experimental ? { experimental: true } : {}),
+                installed: installed.has(spec.id),
+                calibrated: spec.thresholds !== null,
+            })),
+        };
+    }
+    /** Download a model in the background (network permitting), then warm it. */
+    async install(modelId) {
+        const spec = findRelevanceModel(modelId);
+        if (!spec)
+            return { started: false, reason: `unknown relevance model ${modelId}` };
+        if (await installedRelevanceModel(this.opts.home, spec)) {
+            return { started: false, installed: true };
+        }
+        if (this.job && !this.job.error)
+            return { started: this.job.modelId === modelId };
+        if (!(await this.networkAllowed())) {
+            return { started: false, reason: 'app network access is off in Security settings' };
+        }
+        this.job = { modelId, bytesDone: 0, bytesTotal: spec.approxBytes };
+        void (async () => {
+            const opts = this.opts.fetchImpl ? { fetchImpl: this.opts.fetchImpl } : {};
+            for await (const event of installRelevanceModel(this.opts.home, spec, opts)) {
+                if (event.type === 'progress' && this.job) {
+                    this.job.bytesDone = event.bytesDone;
+                    this.job.bytesTotal = event.bytesTotal;
+                }
+                else if (event.type === 'error' && this.job) {
+                    this.job.error = event.error;
+                    log.warn(`[relevance] install of ${modelId} failed: ${event.error}`);
+                    return;
+                }
+            }
+            this.job = null;
+            log.info(`[relevance] installed ${modelId}`);
+            await this.scorer.warm(toResolvedModel(this.opts.home, spec));
+        })().catch((err) => {
+            if (this.job)
+                this.job.error = err instanceof Error ? err.message : String(err);
+        });
+        return { started: true };
+    }
+    /** Bring the disk in line with the setting: install the selected model when it is on. */
+    async reconcile() {
+        const setting = await this.setting();
+        if (!setting.enabled || !setting.spec)
+            return;
+        if (await installedRelevanceModel(this.opts.home, setting.spec)) {
+            void this.scorer.warm(toResolvedModel(this.opts.home, setting.spec));
+            return;
+        }
+        await this.install(setting.spec.id);
+    }
+    /**
+     * Deferred boot step: log what is resolved, then warm an installed, enabled
+     * model — or download it when it is enabled but missing. New installs turn
+     * the check on in first-run, which writes config without passing through
+     * the Settings route that would otherwise start the download; so does a
+     * download that failed or was interrupted last session. `install` keeps the
+     * security policy's app-network gate.
+     */
+    async bootWarm() {
+        const setting = await this.setting();
+        const installed = setting.spec
+            ? await installedRelevanceModel(this.opts.home, setting.spec)
+            : false;
+        log.info(`[relevance] resolved enabled=${setting.enabled} model=${setting.spec?.id ?? 'none'} source=${setting.source} surfaces=${[...setting.surfaces].join(',')} installed=${installed}`);
+        if (!setting.enabled || !setting.spec)
+            return;
+        if (installed) {
+            await this.scorer.warm(toResolvedModel(this.opts.home, setting.spec));
+            return;
+        }
+        const started = await this.install(setting.spec.id);
+        if (!started.started && !started.installed && started.reason) {
+            log.info(`[relevance] not downloading ${setting.spec.id}: ${started.reason}`);
+        }
+    }
+    async remove(modelId) {
+        if (!findRelevanceModel(modelId))
+            return false;
+        await removeRelevanceModel(this.opts.home, modelId);
+        return true;
+    }
+    /** Raw scores for calibration: the bench's `/score` path. */
+    async score(request) {
+        const setting = await this.setting();
+        const spec = findRelevanceModel(request.modelId ?? setting.spec?.id ?? '');
+        if (!spec)
+            return { error: `unknown relevance model ${request.modelId ?? ''}` };
+        if (!(await installedRelevanceModel(this.opts.home, spec))) {
+            return { error: `${spec.id} is not installed` };
+        }
+        const result = await this.scorer.score({
+            model: toResolvedModel(this.opts.home, spec),
+            query: request.query,
+            passages: request.passages,
+            budgetMs: 60_000,
+            waitForLoad: request.waitForLoad ?? true,
+        });
+        const thresholds = setting.spec?.id === spec.id ? setting.thresholds : spec.thresholds;
+        return {
+            modelId: spec.id,
+            status: result.status,
+            ms: result.ms,
+            scores: result.scores ?? [],
+            relevances: (result.scores ?? []).map((score) => score === null ? null : relevanceFromModelScore(score, thresholds)),
+        };
+    }
+    async networkAllowed() {
+        const config = await this.opts.readConfig().catch(() => null);
+        return config ? resolveSecurityPolicy(config).allowAppNetwork : true;
+    }
+}

package/dist/relevance/registry.d.ts

@@ -0,0 +1,11 @@
+import { type RelevanceModelSpec } from '@bendyline/gezel';
+/**
+ * The relevance models gezel can run. Every entry is pinned byte-for-byte
+ * (produced by `evals/src/bin/relevance-pin.ts`, reviewed by a person) and
+ * starts uncalibrated: `thresholds` come only from the retrieval bench
+ * (evals/src/retrieval-bench/LEVERS.md), and an uncalibrated model can
+ * reorder results but never drop one. A new pin gets a new id.
+ */
+export declare const RELEVANCE_MODELS: readonly RelevanceModelSpec[];
+export declare const DEFAULT_RELEVANCE_MODEL_ID = "ms-marco-minilm-l6@1";
+export declare function findRelevanceModel(id: string): RelevanceModelSpec | null;

package/dist/relevance/registry.js

@@ -0,0 +1,158 @@
+import { RelevanceModelSpecSchema } from '@bendyline/gezel';
+/**
+ * The relevance models gezel can run. Every entry is pinned byte-for-byte
+ * (produced by `evals/src/bin/relevance-pin.ts`, reviewed by a person) and
+ * starts uncalibrated: `thresholds` come only from the retrieval bench
+ * (evals/src/retrieval-bench/LEVERS.md), and an uncalibrated model can
+ * reorder results but never drop one. A new pin gets a new id.
+ */
+export const RELEVANCE_MODELS = [
+    {
+        id: 'ms-marco-minilm-l6@1',
+        displayName: 'English — faster',
+        description: 'A small English model (about 24 MB) that checks each passage against the request.',
+        source: {
+            repo: 'Xenova/ms-marco-MiniLM-L-6-v2',
+            revision: 'a09144355adeed5f58c8ed011d209bf8ee5a1fec',
+            upstream: 'cross-encoder/ms-marco-MiniLM-L6-v2',
+        },
+        license: {
+            spdx: 'Apache-2.0',
+            url: 'https://huggingface.co/cross-encoder/ms-marco-MiniLM-L6-v2',
+        },
+        languages: ['en'],
+        architecture: 'bert',
+        files: [
+            {
+                path: 'config.json',
+                sha256: 'd827779a72d27ae68cf878a6fc2e954542663fe21ca515d9f4783fc96be2d37e',
+                bytes: 824,
+            },
+            {
+                path: 'tokenizer.json',
+                sha256: 'd241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66',
+                bytes: 711_396,
+            },
+            {
+                path: 'tokenizer_config.json',
+                sha256: '0b29c7bfc889e53b36d9dd3e686dd4300f6525110eaa98c76a5dafceb2029f53',
+                bytes: 1_242,
+            },
+            {
+                path: 'onnx/model_quantized.onnx',
+                sha256: 'e9d8ebf845c413e981c175bfe49a3bfa9b3dcce2a3ba54875ee5df5a58639fbe',
+                bytes: 23_143_499,
+            },
+        ],
+        graph: 'onnx/model_quantized.onnx',
+        approxBytes: 23_856_961,
+        maxTokens: 512,
+        queryMaxTokens: 96,
+        scoreActivation: 'sigmoid',
+        // Live-confirmed on the retrieval bench (labels 259a61bbaafc9c49). The
+        // sigmoid saturates, so the useful cuts sit orders of magnitude below 0.1.
+        // Drop is below every live cut that cost search recall: `search` only
+        // reorders. See RELEVANCE-CALIBRATION-2026-09-26.md for the arms.
+        thresholds: { drop: 0.00001, keep: 0.00003, strong: 0.95 },
+        calibration: {
+            measuredAt: '2026-09-26',
+            evalRun: 'evals/src/retrieval-bench/RELEVANCE-CALIBRATION-2026-09-26.md',
+        },
+    },
+    {
+        id: 'mmarco-mminilm-l12@1',
+        displayName: 'Many languages',
+        description: 'A multilingual model (about 136 MB) for documents in Dutch, German, French, and other languages.',
+        source: {
+            repo: 'cross-encoder/mmarco-mMiniLMv2-L12-H384-v1',
+            revision: '1427fd652930e4ba29e8149678df786c240d8825',
+        },
+        license: {
+            spdx: 'Apache-2.0',
+            url: 'https://huggingface.co/cross-encoder/mmarco-mMiniLMv2-L12-H384-v1',
+        },
+        languages: ['multilingual'],
+        architecture: 'xlm-roberta',
+        files: [
+            {
+                path: 'config.json',
+                sha256: 'cc2cfe51aa3fd759d21d21acf5dfd6994aa67a3c9210636d22e143699d336c77',
+                bytes: 891,
+            },
+            {
+                path: 'tokenizer.json',
+                sha256: '62c24cdc13d4c9952d63718d6c9fa4c287974249e16b7ade6d5a85e7bbb75626',
+                bytes: 17_082_660,
+            },
+            {
+                path: 'tokenizer_config.json',
+                sha256: 'e7fbfbfa6347b4e414c1cee50d142e2c2f9a895dad68b068ae83a8b564c3837e',
+                bytes: 435,
+            },
+            {
+                // Dynamic int8 quantization; the "arm64" in the name is the export
+                // target, the operators are portable. Verified on arm64; x64 needs
+                // a run before this entry is offered on Windows/Linux x64.
+                path: 'onnx/model_qint8_arm64.onnx',
+                sha256: '1825907d6c1a9001ff78124780bbde20a614a8c3df3b63409cf3c72c6fe5c8b4',
+                bytes: 118_620_017,
+            },
+        ],
+        graph: 'onnx/model_qint8_arm64.onnx',
+        approxBytes: 135_704_003,
+        maxTokens: 512,
+        queryMaxTokens: 96,
+        scoreActivation: 'sigmoid',
+        thresholds: null,
+        calibration: null,
+    },
+    {
+        id: 'mxbai-rerank-xsmall@1',
+        displayName: 'English — mixedbread xsmall',
+        description: 'An English model (about 96 MB), kept for comparison in the retrieval evals.',
+        source: {
+            repo: 'mixedbread-ai/mxbai-rerank-xsmall-v1',
+            revision: 'b5c6e9da73abc3711f593f705371cdbe9e0fe422',
+        },
+        license: {
+            spdx: 'Apache-2.0',
+            url: 'https://huggingface.co/mixedbread-ai/mxbai-rerank-xsmall-v1',
+        },
+        languages: ['en'],
+        architecture: 'deberta-v2',
+        files: [
+            {
+                path: 'config.json',
+                sha256: '470a53befc79da411cc04e466770d9f219f3c14adb276bfa0a58df28774ceade',
+                bytes: 968,
+            },
+            {
+                path: 'tokenizer.json',
+                sha256: '305674b4d785287feecfb5f73f24aa75e9b57c87c579cfe24fbd207987d4b4c4',
+                bytes: 8_649_139,
+            },
+            {
+                path: 'tokenizer_config.json',
+                sha256: 'aafc9f36a056307bf0cbfcbd42fe00d9df89083d23db6114466c8bfaedb09ce5',
+                bytes: 1_447,
+            },
+            {
+                path: 'onnx/model_quantized.onnx',
+                sha256: '15ef19a6de90be7d52b627f2c784107bd806e64826450f41fb75fa4f0179ab30',
+                bytes: 87_245_802,
+            },
+        ],
+        graph: 'onnx/model_quantized.onnx',
+        approxBytes: 95_897_356,
+        maxTokens: 512,
+        queryMaxTokens: 96,
+        scoreActivation: 'sigmoid',
+        thresholds: null,
+        calibration: null,
+        experimental: true,
+    },
+].map((entry) => RelevanceModelSpecSchema.parse(entry));
+export const DEFAULT_RELEVANCE_MODEL_ID = 'ms-marco-minilm-l6@1';
+export function findRelevanceModel(id) {
+    return RELEVANCE_MODELS.find((model) => model.id === id) ?? null;
+}

package/dist/relevance/relevance-core.d.ts

@@ -0,0 +1,67 @@
+export interface ResolvedRelevanceModel {
+    id: string;
+    /** Absolute folder holding the repo layout (config.json, tokenizer.json, onnx/…). */
+    dir: string;
+    graph: string;
+    graphSha256: string;
+    maxTokens: number;
+    queryMaxTokens: number;
+    scoreActivation: 'sigmoid' | 'softmax-positive';
+    intraOpNumThreads?: number;
+}
+interface Tensor {
+    data: Float32Array | BigInt64Array | number[];
+    dims: number[];
+}
+interface Tokenizer {
+    (text: string[], opts: {
+        text_pair: string[];
+        padding: boolean;
+        truncation: boolean;
+        max_length: number;
+    }): Record<string, Tensor>;
+    encode(text: string, opts?: {
+        add_special_tokens?: boolean;
+        text_pair?: string;
+    }): number[];
+    decode(ids: number[], opts?: {
+        skip_special_tokens?: boolean;
+    }): string;
+}
+interface SequenceClassifier {
+    (inputs: Record<string, Tensor>): Promise<{
+        logits: Tensor;
+    }>;
+    sessions?: Record<string, {
+        inputNames?: string[];
+    }>;
+    dispose?: () => Promise<unknown>;
+}
+/** Test seam: the two transformers.js classes this module uses. */
+export interface RelevanceTransformers {
+    AutoTokenizer: {
+        from_pretrained(path: string, opts: Record<string, unknown>): Promise<Tokenizer>;
+    };
+    AutoModelForSequenceClassification: {
+        from_pretrained(path: string, opts: Record<string, unknown>): Promise<SequenceClassifier>;
+    };
+}
+interface LoadedRelevanceModel {
+    tokenizer: Tokenizer;
+    model: SequenceClassifier;
+    /** Special tokens a (query, passage) pair costs. */
+    pairOverhead: number;
+    loadMs: number;
+}
+export interface RelevanceScoreOutcome {
+    /** Activated 0–1 score per passage; null past the deadline. */
+    scores: Array<number | null>;
+    partial: boolean;
+    truncatedPassages: number;
+    inferMs: number;
+}
+export declare function loadRelevanceModel(model: ResolvedRelevanceModel, transformers?: RelevanceTransformers): Promise<LoadedRelevanceModel>;
+export declare function disposeRelevanceModels(): void;
+export declare function scoreRelevancePairs(model: ResolvedRelevanceModel, query: string, passages: readonly string[], deadlineAt?: number, transformers?: RelevanceTransformers): Promise<RelevanceScoreOutcome>;
+export declare function activate(logits: readonly number[], activation: 'sigmoid' | 'softmax-positive'): number;
+export {};