@taodigital/reranker 0.0.0-stage → 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Cross-Encoder Semantic Re-ranker
+ *
+ * Uses Xenova/ms-marco-MiniLM-L-6-v2 (22MB ONNX, int8 quantised) to
+ * re-rank BM25 candidates by semantic relevance. Zero API cost — runs
+ * entirely in-process via ONNX Runtime.
+ *
+ * Architecture:
+ *   BM25 (PostgreSQL ts_rank) → top-25 candidates
+ *   → Cross-Encoder scores all 25 (query, chunk) pairs
+ *   → Returns top-8 by semantic relevance
+ *
+ * Graceful fallback: if ONNX model unavailable (first cold start, no disk),
+ * returns BM25 order unchanged. Zero degradation.
+ *
+ * NOTE: Reranker is a standalone service without @taodigital/core — reads tuning
+ * values from process.env. Configure via RERANKER_* env vars or the
+ * RerankerConfig passed to initialize(). To tune from admin UI, set
+ * ENV_FALLBACKS in the admin panel and restart the service.
+ */
+export interface RerankerConfig {
+    modelId?: string;
+    cacheDir?: string;
+    cacheDirAllowlist?: string[];
+    numThreads?: number;
+    minScore?: number;
+    inputMaxChars?: number;
+    defaultTopK?: number;
+    defaultTopKStrings?: number;
+}
+/**
+ * Configure the reranker before first use. All fields are optional — omitted
+ * fields fall back to environment variables or built-in defaults, preserving
+ * existing behaviour when called with no arguments.
+ */
+export declare function initialize(config?: RerankerConfig): void;
+export interface RerankChunk {
+    heading: string;
+    sourceType: string;
+    sourceId: string;
+    content: string;
+    bm25Score?: number;
+}
+/**
+ * Re-rank BM25 candidates by cross-encoder semantic relevance.
+ *
+ * @param query      The user's search string.
+ * @param candidates BM25 top-K (typically 20–25).
+ * @param topK       How many to return after re-ranking (default 8).
+ */
+export declare function rerank(query: string, candidates: RerankChunk[], topK?: number): Promise<RerankChunk[]>;
+/**
+ * Re-rank arbitrary string texts by relevance to a query.
+ * Returns scored results sorted highest-first (indices into original array).
+ * Use for requirement similarity, trace link suggestions, defect dedup — anywhere
+ * you need semantic ranking of plain strings without the RerankChunk structure.
+ *
+ * @param query   The reference text (TC title, requirement description, search string).
+ * @param texts   Array of candidate texts to rank against the query.
+ * @param topK    How many to return (default 5).
+ * @param minScore  Minimum relevance score to include (default MIN_SCORE env var).
+ */
+export declare function rerankStrings(query: string, texts: string[], topK?: number, minScore?: number): Promise<Array<{
+    index: number;
+    score: number;
+}>>;
+/** Warm up the model on server start (non-blocking). */
+export declare function warmup(): void;

package/dist/index.js

@@ -0,0 +1,189 @@
+/**
+ * Cross-Encoder Semantic Re-ranker
+ *
+ * Uses Xenova/ms-marco-MiniLM-L-6-v2 (22MB ONNX, int8 quantised) to
+ * re-rank BM25 candidates by semantic relevance. Zero API cost — runs
+ * entirely in-process via ONNX Runtime.
+ *
+ * Architecture:
+ *   BM25 (PostgreSQL ts_rank) → top-25 candidates
+ *   → Cross-Encoder scores all 25 (query, chunk) pairs
+ *   → Returns top-8 by semantic relevance
+ *
+ * Graceful fallback: if ONNX model unavailable (first cold start, no disk),
+ * returns BM25 order unchanged. Zero degradation.
+ *
+ * NOTE: Reranker is a standalone service without @taodigital/core — reads tuning
+ * values from process.env. Configure via RERANKER_* env vars or the
+ * RerankerConfig passed to initialize(). To tune from admin UI, set
+ * ENV_FALLBACKS in the admin panel and restart the service.
+ */
+import { resolve, isAbsolute } from 'path';
+let _config = {};
+let _pipe = null;
+let _loadingPromise = null;
+let _failed = false;
+/**
+ * Validate that a model cache/path stays within an allowlisted base directory,
+ * preventing directory traversal via a misconfigured MODEL_CACHE_DIR env var.
+ */
+function validateModelCacheDir(dir, allowlist) {
+    const resolved = isAbsolute(dir) ? resolve(dir) : resolve(process.cwd(), dir);
+    const isAllowed = allowlist.some((base) => resolved === base || resolved.startsWith(base + '/'));
+    if (!isAllowed) {
+        throw new Error(`[reranker] MODEL_CACHE_DIR "${resolved}" is not within an allowed directory. ` +
+            `Allowed: ${allowlist.join(', ')}`);
+    }
+    return resolved;
+}
+const DEFAULT_CACHE_ALLOWLIST = [
+    process.cwd(),
+    '/app/.model-cache',
+    '/models',
+    '/app/models',
+];
+function resolvedAllowlist() {
+    const envExtra = process.env.RERANKER_CACHE_ALLOWLIST
+        ? process.env.RERANKER_CACHE_ALLOWLIST.split(':').filter(Boolean)
+        : [];
+    return (_config.cacheDirAllowlist ?? [...DEFAULT_CACHE_ALLOWLIST, ...envExtra]).map((d) => resolve(d));
+}
+function resolvedCacheDir() {
+    const raw = _config.cacheDir ?? process.env.MODEL_CACHE_DIR ?? '/app/.model-cache';
+    return validateModelCacheDir(raw, resolvedAllowlist());
+}
+function resolvedMinScore() {
+    if (_config.minScore !== undefined)
+        return _config.minScore;
+    return parseFloat(process.env.RERANKER_MIN_SCORE ?? '0.1');
+}
+/**
+ * Configure the reranker before first use. All fields are optional — omitted
+ * fields fall back to environment variables or built-in defaults, preserving
+ * existing behaviour when called with no arguments.
+ */
+export function initialize(config = {}) {
+    if (_pipe || _loadingPromise) {
+        throw new Error('[reranker] initialize() must be called before the pipeline is loaded.');
+    }
+    _config = config;
+}
+async function loadPipeline() {
+    try {
+        const { pipeline, env } = await import('@xenova/transformers');
+        env.cacheDir = resolvedCacheDir();
+        env.allowLocalModels = true;
+        env.allowRemoteModels = true;
+        const numThreads = _config.numThreads ?? parseInt(process.env.RERANKER_NUM_THREADS ?? '2', 10);
+        env.backends = { onnx: { wasm: { numThreads } } };
+        const modelId = _config.modelId ?? process.env.RERANKER_MODEL_ID ?? 'Xenova/ms-marco-MiniLM-L-6-v2';
+        console.log('[reranker] Loading cross-encoder...');
+        const loaded = await pipeline('text-classification', modelId, { quantized: true });
+        console.log('[reranker] Cross-encoder ready ✓');
+        _pipe = loaded;
+        return loaded;
+    }
+    catch (err) {
+        console.warn('[reranker] Cross-encoder unavailable — BM25 order preserved:', err.message);
+        _failed = true;
+        return null;
+    }
+}
+async function getPipeline() {
+    if (_pipe)
+        return _pipe;
+    if (_failed)
+        return null;
+    if (!_loadingPromise)
+        _loadingPromise = loadPipeline();
+    return _loadingPromise;
+}
+/** Score an array of (query, text) pairs using the cross-encoder. Returns raw scores. */
+async function scoreAll(query, texts) {
+    const pipe = await getPipeline();
+    if (!pipe)
+        return texts.map(() => 0);
+    const maxChars = _config.inputMaxChars ?? parseInt(process.env.RERANKER_INPUT_MAX_CHARS ?? '512', 10);
+    const pairs = texts.map((t) => ({ text: query, text_pair: t.slice(0, maxChars) }));
+    const results = await pipe(pairs, { topk: null });
+    return results.map((res, _i) => {
+        const r = Array.isArray(res) ? res : [res];
+        return r.find((x) => x.label === 'LABEL_1')?.score
+            ?? r.find((x) => x.label !== 'LABEL_0')?.score
+            ?? r[0]?.score
+            ?? 0;
+    });
+}
+/**
+ * Re-rank BM25 candidates by cross-encoder semantic relevance.
+ *
+ * @param query      The user's search string.
+ * @param candidates BM25 top-K (typically 20–25).
+ * @param topK       How many to return after re-ranking (default 8).
+ */
+export async function rerank(query, candidates, topK) {
+    const k = topK ?? _config.defaultTopK ?? 8;
+    if (candidates.length === 0)
+        return [];
+    if (candidates.length < 2)
+        return candidates;
+    const pipe = await getPipeline();
+    if (!pipe)
+        return candidates.slice(0, k);
+    try {
+        const t0 = Date.now();
+        const texts = candidates.map((c) => `${c.heading}: ${c.content}`);
+        const scores = await scoreAll(query, texts);
+        const minScore = resolvedMinScore();
+        const reranked = candidates
+            .map((chunk, i) => ({ chunk, score: scores[i] }))
+            .filter((s) => s.score >= minScore)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k)
+            .map((s) => s.chunk);
+        const result = reranked.length > 0 ? reranked : candidates.slice(0, k);
+        console.log(`[reranker] Reranked ${candidates.length}→${result.length} in ${Date.now() - t0}ms`);
+        return result;
+    }
+    catch (err) {
+        console.warn('[reranker] Inference error — returning BM25 order:', err.message);
+        return candidates.slice(0, k);
+    }
+}
+/**
+ * Re-rank arbitrary string texts by relevance to a query.
+ * Returns scored results sorted highest-first (indices into original array).
+ * Use for requirement similarity, trace link suggestions, defect dedup — anywhere
+ * you need semantic ranking of plain strings without the RerankChunk structure.
+ *
+ * @param query   The reference text (TC title, requirement description, search string).
+ * @param texts   Array of candidate texts to rank against the query.
+ * @param topK    How many to return (default 5).
+ * @param minScore  Minimum relevance score to include (default MIN_SCORE env var).
+ */
+export async function rerankStrings(query, texts, topK, minScore) {
+    const k = topK ?? _config.defaultTopKStrings ?? 5;
+    const threshold = minScore ?? resolvedMinScore();
+    if (texts.length === 0)
+        return [];
+    const pipe = await getPipeline();
+    if (!pipe) {
+        return texts.slice(0, k).map((_, i) => ({ index: i, score: 0 }));
+    }
+    try {
+        const scores = await scoreAll(query, texts);
+        return scores
+            .map((score, index) => ({ index, score }))
+            .filter((s) => s.score >= threshold)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k);
+    }
+    catch (err) {
+        console.warn('[reranker] rerankStrings error — returning original order:', err.message);
+        return texts.slice(0, k).map((_, i) => ({ index: i, score: 0 }));
+    }
+}
+/** Warm up the model on server start (non-blocking). */
+export function warmup() {
+    getPipeline().catch(() => { });
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@taodigital/reranker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist"
+  ],
+  "description": "Cross-encoder semantic re-ranking for knowledge search",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@xenova/transformers": "^2.17.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.