@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/relevance/relevance-core.js

@@ -0,0 +1,189 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { join } from 'node:path';
+import { createLogger } from '@bendyline/gezel';
+import { transformersGraphOptions } from '@bendyline/gezel-knowledge';
+import { PipelineLoadError } from '../memory/embed-core.js';
+/**
+ * Cross-encoder inference: load a pinned relevance model from its local
+ * folder and score (query, passage) pairs. Runs inside the relevance worker
+ * (or in-process under VITEST). Never touches the network — the model is
+ * loaded with `local_files_only` from the folder `install.ts` verified.
+ *
+ * The text-classification PIPELINE is not usable here: it ignores
+ * `text_pair` and softmaxes a single-logit head to 1.0, so every passage
+ * would score the same. The tokenizer and model are called directly.
+ */
+const log = createLogger('relevance');
+const BATCH = 8;
+const MAX_LOADED = 2;
+const loaded = new Map();
+async function importTransformers() {
+    return (await import('@huggingface/transformers'));
+}
+export async function loadRelevanceModel(model, transformers) {
+    const existing = loaded.get(model.id);
+    if (existing) {
+        loaded.delete(model.id);
+        loaded.set(model.id, existing);
+        return existing;
+    }
+    const promise = createRelevanceModel(model, transformers).catch((err) => {
+        loaded.delete(model.id);
+        throw err;
+    });
+    loaded.set(model.id, promise);
+    while (loaded.size > MAX_LOADED) {
+        const [oldest, oldPromise] = loaded.entries().next().value;
+        loaded.delete(oldest);
+        void oldPromise.then((old) => old.model.dispose?.()).catch(() => { });
+    }
+    return promise;
+}
+export function disposeRelevanceModels() {
+    for (const promise of loaded.values()) {
+        void promise.then((old) => old.model.dispose?.()).catch(() => { });
+    }
+    loaded.clear();
+}
+async function createRelevanceModel(model, transformers) {
+    const started = performance.now();
+    const graph = transformersGraphOptions(model.graph);
+    if (!graph)
+        throw new PipelineLoadError(`${model.id}: unusable graph ${model.graph}`, false, false);
+    const actual = await sha256File(join(model.dir, model.graph)).catch(() => null);
+    if (actual !== model.graphSha256) {
+        throw new PipelineLoadError(`${model.id}: graph does not match its pin (expected ${model.graphSha256.slice(0, 12)}…, got ${actual?.slice(0, 12) ?? 'missing'}…)`, false, false);
+    }
+    let lib;
+    try {
+        lib = transformers ?? (await importTransformers());
+    }
+    catch (err) {
+        throw new PipelineLoadError(err instanceof Error ? err.message : String(err), true, false);
+    }
+    const local = { local_files_only: true };
+    const tokenizer = await lib.AutoTokenizer.from_pretrained(model.dir, local);
+    const classifier = await lib.AutoModelForSequenceClassification.from_pretrained(model.dir, {
+        ...local,
+        ...graph,
+        session_options: { intraOpNumThreads: model.intraOpNumThreads ?? 2 },
+    });
+    const pairOverhead = tokenizer.encode('', { text_pair: '' }).length;
+    const ready = {
+        tokenizer,
+        model: classifier,
+        pairOverhead,
+        loadMs: Math.round(performance.now() - started),
+    };
+    selfCheck(model, ready, await runBatch(model, ready, SELF_CHECK_QUERY, SELF_CHECK_PASSAGES));
+    log.info(`[relevance] loaded ${model.id} in ${ready.loadMs}ms`);
+    return ready;
+}
+const SELF_CHECK_QUERY = 'how long should coffee steep in a French press?';
+const SELF_CHECK_PASSAGES = [
+    'Let coarse ground coffee steep in hot water for about four minutes before pressing the plunger.',
+    'The treaty ended an eleven-year border war between two duchies and settled a river toll.',
+];
+/**
+ * A mis-wired pair encoding returns plausible, wrong scores — a BERT
+ * cross-encoder that never sees segment ids still produces numbers. So the
+ * model proves itself once at load: it must separate an obvious answer from
+ * an obvious non-answer, and a graph that takes `token_type_ids` must get
+ * them. Failure disables the model instead of letting it steer retrieval.
+ */
+function selfCheck(model, ready, scores) {
+    const inputs = ready.model.sessions?.model?.inputNames ?? [];
+    if (inputs.includes('token_type_ids')) {
+        const encoded = ready.tokenizer([SELF_CHECK_QUERY], {
+            text_pair: [SELF_CHECK_PASSAGES[0]],
+            padding: true,
+            truncation: true,
+            max_length: model.maxTokens,
+        });
+        const types = encoded.token_type_ids?.data;
+        const hasPassageSegment = types
+            ? Array.from(types, Number).some((value) => value === 1)
+            : false;
+        if (!hasPassageSegment) {
+            throw new PipelineLoadError(`${model.id}: pair encoding carries no passage segment`, false, false);
+        }
+    }
+    const [relevant, irrelevant] = scores;
+    if (relevant === undefined || irrelevant === undefined || relevant <= irrelevant + 0.05) {
+        throw new PipelineLoadError(`${model.id}: failed its self-check (relevant ${relevant?.toFixed(3)} vs irrelevant ${irrelevant?.toFixed(3)})`, false, false);
+    }
+}
+export async function scoreRelevancePairs(model, query, passages, deadlineAt, transformers) {
+    const ready = await loadRelevanceModel(model, transformers);
+    const started = performance.now();
+    const scores = passages.map(() => null);
+    let truncatedPassages = 0;
+    let partial = false;
+    const trimmedQuery = trimToTokens(ready.tokenizer, query, model.queryMaxTokens);
+    const queryTokens = ready.tokenizer.encode(trimmedQuery, { add_special_tokens: false }).length;
+    const passageBudget = Math.max(16, model.maxTokens - queryTokens - ready.pairOverhead - 2);
+    let slowestBatchMs = 0;
+    for (let start = 0; start < passages.length; start += BATCH) {
+        // The caller stops waiting shortly after the deadline and then discards
+        // the whole reply, so a batch that cannot finish in time costs every batch
+        // already scored. On a contended CPU the last batch started just inside
+        // the deadline and overran it, and the search kept its unjudged order.
+        if (deadlineAt !== undefined && Date.now() + slowestBatchMs > deadlineAt) {
+            partial = true;
+            break;
+        }
+        const batchStarted = performance.now();
+        const batch = passages.slice(start, start + BATCH).map((passage) => {
+            const trimmed = trimToTokens(ready.tokenizer, passage, passageBudget);
+            if (trimmed !== passage)
+                truncatedPassages++;
+            return trimmed;
+        });
+        const batchScores = await runBatch(model, ready, trimmedQuery, batch);
+        batchScores.forEach((score, i) => {
+            scores[start + i] = score;
+        });
+        slowestBatchMs = Math.max(slowestBatchMs, performance.now() - batchStarted);
+    }
+    return { scores, partial, truncatedPassages, inferMs: Math.round(performance.now() - started) };
+}
+async function runBatch(model, ready, query, passages) {
+    const inputs = ready.tokenizer(passages.map(() => query), { text_pair: [...passages], padding: true, truncation: true, max_length: model.maxTokens });
+    const { logits } = await ready.model(inputs);
+    const values = Array.from(logits.data, Number);
+    const labels = logits.dims[1] ?? 1;
+    return passages.map((_, row) => {
+        const rowLogits = values.slice(row * labels, row * labels + labels);
+        return activate(rowLogits, model.scoreActivation);
+    });
+}
+export function activate(logits, activation) {
+    if (activation === 'sigmoid' || logits.length === 1)
+        return 1 / (1 + Math.exp(-(logits[0] ?? 0)));
+    const max = Math.max(...logits);
+    const exps = logits.map((logit) => Math.exp(logit - max));
+    return (exps[1] ?? 0) / exps.reduce((sum, value) => sum + value, 0);
+}
+/**
+ * Bound a text to `maxTokens` WITHOUT the special tokens, so the tokenizer's
+ * own truncation — which cuts the tail and would drop the closing separator
+ * of a pair — never has to act. A character cap first keeps tokenization of a
+ * huge passage cheap.
+ */
+function trimToTokens(tokenizer, text, maxTokens) {
+    const capped = text.length > maxTokens * 6 ? text.slice(0, maxTokens * 6) : text;
+    const ids = tokenizer.encode(capped, { add_special_tokens: false });
+    if (ids.length <= maxTokens)
+        return capped;
+    return tokenizer.decode(ids.slice(0, maxTokens), { skip_special_tokens: true });
+}
+function sha256File(path) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        const stream = createReadStream(path, { highWaterMark: 4 * 1024 * 1024 });
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+        stream.on('error', reject);
+    });
+}

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

@@ -0,0 +1,42 @@
+import { type RelevanceScoreOutcome, type ResolvedRelevanceModel } from './relevance-core.js';
+export type RelevanceRunStatus = 'scored' | 'partial' | 'timeout' | 'cold' | 'unavailable' | 'disabled';
+export interface RelevanceScoreResult {
+    status: RelevanceRunStatus;
+    /** Activated 0–1 scores, one per passage; null where none was computed. */
+    scores?: Array<number | null>;
+    ms: number;
+    modelId: string;
+    truncatedPassages?: number;
+    reason?: string;
+}
+/** What SearchService and the preview route depend on — swappable in tests. */
+export interface RelevanceScorer {
+    status(modelId: string): 'cold' | 'warming' | 'ready' | 'unavailable' | 'disabled';
+    score(request: {
+        model: ResolvedRelevanceModel;
+        query: string;
+        passages: string[];
+        budgetMs: number;
+        waitForLoad?: boolean;
+    }): Promise<RelevanceScoreResult>;
+    warm(model: ResolvedRelevanceModel): Promise<boolean>;
+}
+/** Where in-process inference runs (tests and the VITEST fallback). */
+export interface RelevanceBackend {
+    warm(model: ResolvedRelevanceModel): Promise<void>;
+    score(model: ResolvedRelevanceModel, query: string, passages: string[], deadlineAt: number): Promise<RelevanceScoreOutcome>;
+}
+/** The process-wide relevance scorer. */
+export declare function relevanceScorer(): RelevanceScorer & {
+    dispose(): void;
+};
+/** Shut the process-wide scorer down for service shutdown; see `RelevanceModelHost.shutdown`. */
+export declare function shutdownRelevanceScorer(drainMs: number): Promise<void>;
+/** Reopen the process-wide scorer when a service starts. */
+export declare function openRelevanceScorer(): void;
+/** A private scorer over an explicit backend — tests, and nothing else. */
+export declare function createRelevanceScorer(backend: RelevanceBackend): RelevanceScorer & {
+    dispose(): void;
+    shutdown(drainMs: number): Promise<void>;
+    open(): void;
+};

package/dist/relevance/relevance-model.js

@@ -0,0 +1,292 @@
+import { Worker } from 'node:worker_threads';
+import { createLogger } from '@bendyline/gezel';
+import { retireModelWorker } from '../utils/retire-model-worker.js';
+import { findServiceWorkerEntry } from '../utils/service-worker-entry.js';
+import { disposeRelevanceModels, loadRelevanceModel, scoreRelevancePairs, } from './relevance-core.js';
+/**
+ * Host side of the relevance model: owns its worker, per-model readiness,
+ * outages, and the "never hold a turn for a model load" rule. A cold model
+ * answers `cold` immediately and warms in the background; the next query gets
+ * scores. Callers never see an exception — every outcome is a status.
+ */
+const log = createLogger('relevance');
+const RETRY_COOLDOWN_MS = 60_000;
+const DEFAULT_IDLE_MS = 30 * 60_000;
+function disabledByEnv() {
+    const raw = process.env.GEZEL_DISABLE_RELEVANCE_MODEL;
+    return raw === '1' || raw?.toLowerCase() === 'true';
+}
+function idleMs() {
+    const raw = Number(process.env.GEZEL_RELEVANCE_IDLE_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_IDLE_MS;
+}
+const coreBackend = {
+    warm: async (model) => {
+        await loadRelevanceModel(model);
+    },
+    score: (model, query, passages, deadlineAt) => scoreRelevancePairs(model, query, passages, deadlineAt),
+};
+class RelevanceModelHost {
+    backend;
+    constructor(backend = coreBackend) {
+        this.backend = backend;
+    }
+    worker = null;
+    workerUsable = true;
+    /** Set by service shutdown: no new worker or request until reopened. */
+    closed = false;
+    crashCount = 0;
+    nextId = 1;
+    pending = new Map();
+    readiness = new Map();
+    warming = new Map();
+    outages = new Map();
+    idleTimer = null;
+    status(modelId) {
+        if (disabledByEnv() || !this.workerUsableOrTest())
+            return 'disabled';
+        if (this.outage(modelId))
+            return 'unavailable';
+        return this.readiness.get(modelId) ?? 'cold';
+    }
+    async warm(model) {
+        // During shutdown a warm-up would start (or load) a worker as the process exits.
+        if (this.closed)
+            return false;
+        if (this.status(model.id) === 'ready')
+            return true;
+        const running = this.warming.get(model.id);
+        if (running)
+            return running;
+        this.readiness.set(model.id, 'warming');
+        const promise = this.request({ kind: 'warm', model }).then((reply) => {
+            this.warming.delete(model.id);
+            if (reply.ok) {
+                this.readiness.set(model.id, 'ready');
+                return true;
+            }
+            this.readiness.delete(model.id);
+            this.recordFailure(model.id, reply);
+            return false;
+        });
+        this.warming.set(model.id, promise);
+        return promise;
+    }
+    async score(request) {
+        const started = performance.now();
+        const modelId = request.model.id;
+        const done = (result) => ({
+            ...result,
+            ms: Math.round(performance.now() - started),
+            modelId,
+        });
+        if (this.closed)
+            return done({ status: 'unavailable', reason: 'the service is shutting down' });
+        const status = this.status(modelId);
+        if (status === 'disabled')
+            return done({ status: 'disabled' });
+        if (status === 'unavailable') {
+            return done({ status: 'unavailable', reason: this.outage(modelId) ?? undefined });
+        }
+        if (status !== 'ready') {
+            const warming = this.warm(request.model);
+            if (!request.waitForLoad)
+                return done({ status: 'cold' });
+            if (!(await warming)) {
+                return done({ status: 'unavailable', reason: this.outage(modelId) ?? undefined });
+            }
+        }
+        this.touch();
+        const deadlineAt = Date.now() + request.budgetMs;
+        let timer;
+        const reply = await Promise.race([
+            this.request({
+                kind: 'score',
+                model: request.model,
+                query: request.query,
+                passages: request.passages,
+                deadlineAt,
+            }),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), request.budgetMs + 50);
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+        if (!reply || reply.expired)
+            return done({ status: 'timeout' });
+        if (reply.error) {
+            this.recordFailure(modelId, reply);
+            return done({ status: 'unavailable', reason: reply.error });
+        }
+        return done({
+            status: reply.partial ? 'partial' : 'scored',
+            scores: reply.scores ?? [],
+            truncatedPassages: reply.truncatedPassages ?? 0,
+        });
+    }
+    recordFailure(modelId, reply) {
+        const reason = reply.error ?? 'unknown failure';
+        const until = reply.fatal ? Number.POSITIVE_INFINITY : Date.now() + RETRY_COOLDOWN_MS;
+        this.outages.set(modelId, { reason, until });
+        log.warn(`[relevance] ${modelId} ${reply.fatal ? 'disabled until restart' : `unavailable for ${RETRY_COOLDOWN_MS / 1000}s`}: ${reason}`);
+    }
+    outage(modelId) {
+        const outage = this.outages.get(modelId);
+        if (!outage)
+            return null;
+        if (Date.now() < outage.until)
+            return outage.reason;
+        this.outages.delete(modelId);
+        return null;
+    }
+    workerUsableOrTest() {
+        return this.workerUsable || Boolean(process.env.VITEST);
+    }
+    // ── transport: the worker in production, in-process under VITEST ──────
+    async request(msg) {
+        const worker = this.ensureWorker();
+        if (!worker)
+            return this.inProcess(msg);
+        const id = this.nextId++;
+        return new Promise((resolve) => {
+            this.pending.set(id, { resolve });
+            worker.postMessage({ id, ...msg });
+        });
+    }
+    async inProcess(msg) {
+        try {
+            if (msg.kind === 'warm') {
+                await this.backend.warm(msg.model);
+                return { id: 0, ok: true };
+            }
+            if (Date.now() > msg.deadlineAt)
+                return { id: 0, expired: true };
+            const outcome = await this.backend.score(msg.model, msg.query, msg.passages, msg.deadlineAt);
+            return { id: 0, ...outcome };
+        }
+        catch (err) {
+            return {
+                id: 0,
+                error: err instanceof Error ? err.message : String(err),
+                fatal: true,
+            };
+        }
+    }
+    ensureWorker() {
+        if (this.closed || process.env.VITEST || !this.workerUsable)
+            return null;
+        if (this.worker)
+            return this.worker;
+        const entry = findServiceWorkerEntry(import.meta.url, 'relevance-model');
+        if (!entry) {
+            this.workerUsable = false;
+            log.warn('[relevance] worker entry is missing; the relevance model is disabled');
+            return null;
+        }
+        try {
+            const worker = new Worker(entry);
+            worker.on('message', (reply) => {
+                const pending = this.pending.get(reply.id);
+                if (!pending)
+                    return;
+                this.pending.delete(reply.id);
+                pending.resolve(reply);
+            });
+            worker.on('error', (err) => this.onWorkerDown(err instanceof Error ? err.message : String(err)));
+            worker.on('exit', (code) => {
+                if (code !== 0)
+                    this.onWorkerDown(`worker exited with code ${code}`);
+            });
+            worker.unref();
+            this.worker = worker;
+            return worker;
+        }
+        catch (err) {
+            this.workerUsable = false;
+            log.warn(`[relevance] worker failed to start: ${err instanceof Error ? err.message : err}`);
+            return null;
+        }
+    }
+    onWorkerDown(reason) {
+        const dead = this.worker;
+        this.worker = null;
+        if (dead)
+            void dead.terminate().catch(() => { });
+        for (const pending of this.pending.values()) {
+            pending.resolve({ id: 0, error: `relevance worker stopped: ${reason}`, retryable: true });
+        }
+        this.pending.clear();
+        this.readiness.clear();
+        this.warming.clear();
+        this.crashCount++;
+        if (this.crashCount >= 3) {
+            this.workerUsable = false;
+            log.warn(`[relevance] worker crashed ${this.crashCount} times; disabled until restart`);
+        }
+    }
+    /** Drop the worker (and its resident model) after it sits idle. */
+    touch() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => this.dispose(), idleMs());
+        this.idleTimer.unref();
+    }
+    /**
+     * Close for service shutdown: refuse new work, then terminate the worker once
+     * its in-flight warm-up or scoring has finished, waiting at most `drainMs`
+     * (see retire-model-worker.ts for why it must never be torn down mid-run).
+     */
+    async shutdown(drainMs) {
+        this.closed = true;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = null;
+        const worker = this.worker;
+        if (!worker)
+            return;
+        if (await retireModelWorker(worker, () => this.pending.size === 0, drainMs)) {
+            if (this.worker === worker)
+                this.worker = null;
+            this.readiness.clear();
+            this.warming.clear();
+            return;
+        }
+        log.warn('[relevance] scoring was still running at shutdown; leaving its worker to exit');
+    }
+    /** Reopen after shutdown — an embedded service can be started again in the same process. */
+    open() {
+        this.closed = false;
+    }
+    dispose() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = null;
+        this.readiness.clear();
+        this.warming.clear();
+        const worker = this.worker;
+        this.worker = null;
+        if (worker)
+            void worker.terminate().catch(() => { });
+        if (process.env.VITEST)
+            disposeRelevanceModels();
+    }
+}
+let host = null;
+/** The process-wide relevance scorer. */
+export function relevanceScorer() {
+    host ??= new RelevanceModelHost();
+    return host;
+}
+/** Shut the process-wide scorer down for service shutdown; see `RelevanceModelHost.shutdown`. */
+export async function shutdownRelevanceScorer(drainMs) {
+    await host?.shutdown(drainMs);
+}
+/** Reopen the process-wide scorer when a service starts. */
+export function openRelevanceScorer() {
+    host?.open();
+}
+/** A private scorer over an explicit backend — tests, and nothing else. */
+export function createRelevanceScorer(backend) {
+    return new RelevanceModelHost(backend);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Worker-thread host for relevance-model inference. Its own worker, not the
+ * text-embedding one: ONNX runs synchronously and would stall `embedQuery`
+ * for the titlebar search, and a relevance-model crash must never count
+ * toward the embed worker's crash limit (three crashes there move all text
+ * embedding onto the main thread for good).
+ *
+ * Protocol (structured clone over the worker port):
+ *   host → worker: { id, kind: 'warm', model }
+ *                  { id, kind: 'score', model, query, passages, deadlineAt }
+ *                  { id, kind: 'dispose' }
+ *   worker → host: { id, ok: true }                         (warm, dispose)
+ *                  { id, scores, partial, truncatedPassages, inferMs }
+ *                  { id, expired: true }                     (deadline passed in the queue)
+ *                  { id, error, fatal, retryable }
+ *
+ * One ONNX run at a time: requests queue FIFO, and a request whose deadline
+ * passed while it waited is answered `expired` without running.
+ */
+export {};

package/dist/relevance/relevance-worker.js

@@ -0,0 +1,57 @@
+/**
+ * Worker-thread host for relevance-model inference. Its own worker, not the
+ * text-embedding one: ONNX runs synchronously and would stall `embedQuery`
+ * for the titlebar search, and a relevance-model crash must never count
+ * toward the embed worker's crash limit (three crashes there move all text
+ * embedding onto the main thread for good).
+ *
+ * Protocol (structured clone over the worker port):
+ *   host → worker: { id, kind: 'warm', model }
+ *                  { id, kind: 'score', model, query, passages, deadlineAt }
+ *                  { id, kind: 'dispose' }
+ *   worker → host: { id, ok: true }                         (warm, dispose)
+ *                  { id, scores, partial, truncatedPassages, inferMs }
+ *                  { id, expired: true }                     (deadline passed in the queue)
+ *                  { id, error, fatal, retryable }
+ *
+ * One ONNX run at a time: requests queue FIFO, and a request whose deadline
+ * passed while it waited is answered `expired` without running.
+ */
+import { parentPort } from 'node:worker_threads';
+import { PipelineLoadError } from '../memory/embed-core.js';
+import { disposeRelevanceModels, loadRelevanceModel, scoreRelevancePairs, } from './relevance-core.js';
+if (!parentPort)
+    throw new Error('relevance-worker must be run as a worker thread');
+const port = parentPort;
+let queue = Promise.resolve();
+port.on('message', (msg) => {
+    queue = queue.then(() => handle(msg));
+});
+async function handle(msg) {
+    try {
+        if (msg.kind === 'dispose') {
+            disposeRelevanceModels();
+            port.postMessage({ id: msg.id, ok: true });
+            return;
+        }
+        if (msg.kind === 'warm') {
+            await loadRelevanceModel(msg.model);
+            port.postMessage({ id: msg.id, ok: true });
+            return;
+        }
+        if (msg.deadlineAt !== undefined && Date.now() > msg.deadlineAt) {
+            port.postMessage({ id: msg.id, expired: true });
+            return;
+        }
+        const outcome = await scoreRelevancePairs(msg.model, msg.query, msg.passages, msg.deadlineAt);
+        port.postMessage({ id: msg.id, ...outcome });
+    }
+    catch (err) {
+        port.postMessage({
+            id: msg.id,
+            error: err instanceof Error ? err.message : String(err),
+            fatal: err instanceof PipelineLoadError && !err.retryable,
+            retryable: err instanceof PipelineLoadError && err.retryable,
+        });
+    }
+}

package/dist/relevance/settings.d.ts

@@ -0,0 +1,30 @@
+import { type GezelConfig, type RelevanceModelSpec, type RelevanceThresholds, type RetrievalTraceSurface } from '@bendyline/gezel';
+import type { ResolvedRelevanceModel } from './relevance-core.js';
+/**
+ * The single owner of "is the relevance model on, which one, and how is it
+ * used". Precedence: eval env override → config → off. Evals drive every
+ * lever through the env so an arm never needs a config write:
+ *
+ *   GEZEL_RELEVANCE_MODEL       off | on | <model id>
+ *   GEZEL_RELEVANCE_SURFACES    turn,references,search
+ *   GEZEL_RELEVANCE_THRESHOLDS  drop,keep,strong   (activated-score space)
+ *   GEZEL_RELEVANCE_BUDGET_MS   turn:250,references:700,search:400
+ *   GEZEL_RELEVANCE_KNOWLEDGE_KEEP  0.5   (relevance space; knowledge on filter surfaces)
+ *   GEZEL_RELEVANCE_ORDER       weighted | flat
+ */
+export interface ResolvedRelevanceSetting {
+    enabled: boolean;
+    spec: RelevanceModelSpec | null;
+    source: 'env' | 'config' | 'default';
+    surfaces: ReadonlySet<RetrievalTraceSurface>;
+    /** Null when the model is uncalibrated: it may reorder, never drop. */
+    thresholds: RelevanceThresholds | null;
+    budgets: Record<RetrievalTraceSurface, number>;
+    /** `flat`: order by model relevance across corpora instead of weighted score. */
+    order: 'weighted' | 'flat';
+    /** Relevance a knowledge passage needs to survive a filter surface. */
+    knowledgeKeep: number;
+}
+export declare function resolveRelevanceSetting(config: Pick<GezelConfig, 'relevanceModel'> | null, env?: NodeJS.ProcessEnv): ResolvedRelevanceSetting;
+/** What the scorer needs to load a spec from its installed folder. */
+export declare function toResolvedModel(home: string, spec: RelevanceModelSpec): ResolvedRelevanceModel;