@graphorin/reranker-transformersjs 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @graphorin/reranker-transformersjs
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release of the cross-encoder reranker adapter for the Graphorin
+  framework. Wraps `@huggingface/transformers@^4.1.0`, automatically picks
+  the BGE reranker model from the agent locale, supports lazy load + idle
+  unload, and implements the `ReRanker` contract from
+  `@graphorin/memory/search`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @graphorin/reranker-transformersjs
+
+> Cross-encoder reranker adapter for the
+> [Graphorin](https://github.com/o-stepper/graphorin) framework. Wraps
+> [`@huggingface/transformers`](https://www.npmjs.com/package/@huggingface/transformers)
+> to score `(query, passage)` pairs with a BGE cross-encoder running
+> entirely in-process. Implements the `ReRanker` contract from
+> `@graphorin/memory/search`.
+>
+> Project Graphorin · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko ·
+> <https://github.com/o-stepper/graphorin>
+
+---
+
+## Status
+
+- **Published:** v0.5.0 (optional sub-pack)
+- **Default model:** locale-aware (`Xenova/bge-reranker-base` for
+  English, `BAAI/bge-reranker-v2-m3` for everything else).
+- **Default precision:** FP16 (`'fp16'` dtype).
+- **Default device:** CPU.
+
+---
+
+## Install
+
+```bash
+pnpm add @graphorin/reranker-transformersjs @huggingface/transformers
+```
+
+The first call to `rerank(...)` lazily downloads the reranker weights
+into the Hugging Face cache directory (`~/.cache/huggingface/hub` by
+default; honours `GRAPHORIN_CACHE_DIR`). To pre-warm in CI:
+
+```bash
+node -e "import('@graphorin/reranker-transformersjs').then(m => m.createCrossEncoderReranker({ locale: 'en' }).rerank('warmup', [[]], {}))"
+```
+
+---
+
+## Usage
+
+### Drop-in replacement for the built-in RRF reranker
+
+```ts
+import { createMemory } from '@graphorin/memory';
+import { createCrossEncoderReranker } from '@graphorin/reranker-transformersjs';
+
+const memory = createMemory({
+  store,
+  embedder,
+  reranker: createCrossEncoderReranker({ locale: 'en' }),
+});
+```
+
+### Multilingual deployment
+
+```ts
+const reranker = createCrossEncoderReranker({
+  locale: 'pt-BR',
+  // Falls back to BAAI/bge-reranker-v2-m3 (568M, multilingual).
+});
+```
+
+### Override the model explicitly
+
+For narrow language-pair scenarios (e.g. CJK, low-resource European
+languages) plug in a specialised cross-encoder of your choice:
+
+```ts
+const reranker = createCrossEncoderReranker({
+  model: 'cross-encoder/ms-marco-MiniLM-L-6-v2',
+  dtype: 'q8',
+});
+```
+
+### Idle eviction (bound resident memory)
+
+```ts
+// Drop the loaded ONNX session after 10 minutes of inactivity.
+const reranker = createCrossEncoderReranker({
+  locale: 'en',
+  idleEvictionMs: 10 * 60 * 1000,
+});
+```
+
+### Custom passage extractor
+
+The default extractor walks `text → summary → value → label → id`.
+Override when your custom `MemoryRecord` schema attaches the canonical
+text elsewhere:
+
+```ts
+const reranker = createCrossEncoderReranker<MyRecord>({
+  passageExtractor: (record) => `${record.title}. ${record.body}`,
+});
+```
+
+---
+
+## Acceptance criteria
+
+- [x] Reranks fixture results.
+- [x] Locale auto-pick verified (`'en' → bge-reranker-base`, every
+      other locale → `bge-reranker-v2-m3`).
+- [x] Lazy load + idle unload works.
+- [x] Implements `ReRanker` from `@graphorin/memory/search`.
+
+---
+
+## Related decisions
+
+- ADR-024 — Reciprocal Rank Fusion default + pluggable rerankers.
+
+---
+
+## License
+
+MIT © 2026 Oleksiy Stepurenko
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/cross-encoder.d.ts

@@ -0,0 +1,84 @@
+//#region src/cross-encoder.d.ts
+/**
+ * Lazy `@huggingface/transformers` text-classification pipeline used to
+ * score query / passage pairs. The runner caches the first-loaded
+ * pipeline per `(model, dtype, device, revision, cacheDir)` tuple so
+ * repeated `rerank(...)` calls inside the same process do not pay the
+ * model-load cost twice.
+ *
+ * Tests inject a stub `pipelineFactory`; the production path lazily
+ * imports `@huggingface/transformers` so plain inspection of the
+ * package (e.g. for documentation generation) does not pull in the
+ * native ONNX runtime.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Numeric dtype hint. Default `'fp16'` per Phase 16 §
+ * `@graphorin/reranker-transformersjs`.
+ *
+ * @stable
+ */
+type RerankerDtype = 'fp32' | 'fp16' | 'q8' | 'q4';
+/**
+ * Output shape returned by `@huggingface/transformers`'
+ * text-classification pipeline. Each pair returns either a single
+ * `{ label, score }` object (top-k = 1) or an array of them. We
+ * normalise on the array form upstream so the cross-encoder always
+ * sees a consistent shape.
+ *
+ * @internal
+ */
+interface ClassifierResult {
+  readonly label: string;
+  readonly score: number;
+}
+/** @internal */
+type CrossEncoderPipeline = (pairs: ReadonlyArray<{
+  text: string;
+  text_pair: string;
+}>, options?: {
+  topk?: number;
+  signal?: AbortSignal;
+}) => Promise<ReadonlyArray<ClassifierResult> | ReadonlyArray<ReadonlyArray<ClassifierResult>>>;
+/** @internal */
+type CrossEncoderPipelineFactory = (task: 'text-classification', model: string, options: {
+  revision?: string;
+  cache_dir?: string;
+  dtype?: RerankerDtype;
+  device?: string;
+}) => Promise<CrossEncoderPipeline>;
+/**
+ * Raised when the `@huggingface/transformers` peer is missing or the
+ * configured cross-encoder model fails to load.
+ *
+ * @stable
+ */
+declare class CrossEncoderLoadError extends Error {
+  readonly name = "CrossEncoderLoadError";
+}
+/** @internal */
+declare function loadDefaultPipelineFactory(): Promise<CrossEncoderPipelineFactory>;
+/**
+ * Test-only helper. Drops the cached pipeline factory so the next
+ * loader call re-imports the peer.
+ *
+ * @internal
+ */
+declare function _resetPipelineFactoryCacheForTesting(): void;
+/**
+ * Normalises the raw pipeline output to a flat `score[]` aligned with the input
+ * pair order. Cross-encoder classifiers return either a single-best
+ * `{label, score}` per pair (the default single-logit bge exports) or an array
+ * of `topk` entries. For the array shape we read the POSITIVE label's
+ * confidence — NOT the max of any label (PS-16): an irrelevant pair's most
+ * confident class is the *negative* one, so taking the max would invert the
+ * ranking for any 2-label classifier. When no label looks positive (single-logit
+ * or unrecognised labels) we fall back to the top score.
+ *
+ * @internal
+ */
+declare function extractPairScores(raw: ReadonlyArray<ClassifierResult> | ReadonlyArray<ReadonlyArray<ClassifierResult>>, pairCount: number): number[];
+//#endregion
+export { ClassifierResult, CrossEncoderLoadError, CrossEncoderPipeline, CrossEncoderPipelineFactory, RerankerDtype, _resetPipelineFactoryCacheForTesting, extractPairScores, loadDefaultPipelineFactory };
+//# sourceMappingURL=cross-encoder.d.ts.map

package/dist/cross-encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-encoder.d.ts","names":[],"sources":["../src/cross-encoder.ts"],"sourcesContent":[],"mappings":";;AAqBA;AAWA;AAMA;;;;;;;;;;AAMA;;;;;AAiBA;AAQA;AAsBgB,KAtEJ,aAAA,GAsEI,MAAA,GAAA,MAAoC,GAAA,IAAA,GAAA,IAAA;AA4BpD;;;;;;;;;UAvFiB,gBAAA;;;;;KAML,oBAAA,WACH;;;;;WAC6B;MACjC,QAAQ,cAAc,oBAAoB,cAAc,cAAc;;KAG/D,2BAAA;;;UAMA;;MAGP,QAAQ;;;;;;;cAQA,qBAAA,SAA8B,KAAA;;;;iBAQrB,0BAAA,CAAA,GAA8B,QAAQ;;;;;;;iBAsB5C,oCAAA,CAAA;;;;;;;;;;;;;iBA4BA,iBAAA,MACT,cAAc,oBAAoB,cAAc,cAAc"}

package/dist/cross-encoder.js

@@ -0,0 +1,81 @@
+//#region src/cross-encoder.ts
+/**
+* Raised when the `@huggingface/transformers` peer is missing or the
+* configured cross-encoder model fails to load.
+*
+* @stable
+*/
+var CrossEncoderLoadError = class extends Error {
+	name = "CrossEncoderLoadError";
+};
+/** @internal */
+let CACHED_PIPELINE_FACTORY = null;
+/** @internal */
+async function loadDefaultPipelineFactory() {
+	if (CACHED_PIPELINE_FACTORY !== null) return CACHED_PIPELINE_FACTORY;
+	try {
+		CACHED_PIPELINE_FACTORY = (await import("@huggingface/transformers")).pipeline;
+		return CACHED_PIPELINE_FACTORY;
+	} catch (err) {
+		throw new CrossEncoderLoadError("[graphorin/reranker-transformersjs] required peer '@huggingface/transformers' is not installed.", { cause: err });
+	}
+}
+/**
+* Test-only helper. Drops the cached pipeline factory so the next
+* loader call re-imports the peer.
+*
+* @internal
+*/
+function _resetPipelineFactoryCacheForTesting() {
+	CACHED_PIPELINE_FACTORY = null;
+}
+/**
+* True when a classifier label names the *positive* (relevant) class. Matches
+* the conventional binary forms — `LABEL_1`, `positive`, `relevant`,
+* `entailment`, `true`, `yes` — using exact words so it does not mis-fire on a
+* negative label that merely contains one (`irrelevant` ⊃ `relevant`).
+*/
+function isPositiveLabel(label) {
+	const l = label.toLowerCase().trim();
+	if (l === "1" || /(?:^|[_-])1$/.test(l)) return true;
+	return /^(?:positive|relevant|entailment|true|yes|pos)$/.test(l);
+}
+/**
+* Normalises the raw pipeline output to a flat `score[]` aligned with the input
+* pair order. Cross-encoder classifiers return either a single-best
+* `{label, score}` per pair (the default single-logit bge exports) or an array
+* of `topk` entries. For the array shape we read the POSITIVE label's
+* confidence — NOT the max of any label (PS-16): an irrelevant pair's most
+* confident class is the *negative* one, so taking the max would invert the
+* ranking for any 2-label classifier. When no label looks positive (single-logit
+* or unrecognised labels) we fall back to the top score.
+*
+* @internal
+*/
+function extractPairScores(raw, pairCount) {
+	const out = new Array(pairCount).fill(0);
+	for (let i = 0; i < pairCount; i++) {
+		const cell = raw[i];
+		if (cell === void 0) continue;
+		if (Array.isArray(cell)) {
+			let best = Number.NEGATIVE_INFINITY;
+			let positive = Number.NEGATIVE_INFINITY;
+			let sawPositive = false;
+			for (const entry of cell) {
+				if (entry === void 0) continue;
+				if (entry.score > best) best = entry.score;
+				if (isPositiveLabel(entry.label)) {
+					sawPositive = true;
+					if (entry.score > positive) positive = entry.score;
+				}
+			}
+			const chosen = sawPositive ? positive : best;
+			out[i] = Number.isFinite(chosen) ? chosen : 0;
+		} else out[i] = cell.score;
+	}
+	return out;
+}
+
+//#endregion
+export { CrossEncoderLoadError, _resetPipelineFactoryCacheForTesting, extractPairScores, loadDefaultPipelineFactory };
+//# sourceMappingURL=cross-encoder.js.map

package/dist/cross-encoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-encoder.js","names":["CACHED_PIPELINE_FACTORY: CrossEncoderPipelineFactory | null","out: number[]"],"sources":["../src/cross-encoder.ts"],"sourcesContent":["/**\n * Lazy `@huggingface/transformers` text-classification pipeline used to\n * score query / passage pairs. The runner caches the first-loaded\n * pipeline per `(model, dtype, device, revision, cacheDir)` tuple so\n * repeated `rerank(...)` calls inside the same process do not pay the\n * model-load cost twice.\n *\n * Tests inject a stub `pipelineFactory`; the production path lazily\n * imports `@huggingface/transformers` so plain inspection of the\n * package (e.g. for documentation generation) does not pull in the\n * native ONNX runtime.\n *\n * @packageDocumentation\n */\n\n/**\n * Numeric dtype hint. Default `'fp16'` per Phase 16 §\n * `@graphorin/reranker-transformersjs`.\n *\n * @stable\n */\nexport type RerankerDtype = 'fp32' | 'fp16' | 'q8' | 'q4';\n\n/**\n * Output shape returned by `@huggingface/transformers`'\n * text-classification pipeline. Each pair returns either a single\n * `{ label, score }` object (top-k = 1) or an array of them. We\n * normalise on the array form upstream so the cross-encoder always\n * sees a consistent shape.\n *\n * @internal\n */\nexport interface ClassifierResult {\n  readonly label: string;\n  readonly score: number;\n}\n\n/** @internal */\nexport type CrossEncoderPipeline = (\n  pairs: ReadonlyArray<{ text: string; text_pair: string }>,\n  options?: { topk?: number; signal?: AbortSignal },\n) => Promise<ReadonlyArray<ClassifierResult> | ReadonlyArray<ReadonlyArray<ClassifierResult>>>;\n\n/** @internal */\nexport type CrossEncoderPipelineFactory = (\n  task: 'text-classification',\n  model: string,\n  options: {\n    revision?: string;\n    cache_dir?: string;\n    dtype?: RerankerDtype;\n    device?: string;\n  },\n) => Promise<CrossEncoderPipeline>;\n\n/**\n * Raised when the `@huggingface/transformers` peer is missing or the\n * configured cross-encoder model fails to load.\n *\n * @stable\n */\nexport class CrossEncoderLoadError extends Error {\n  override readonly name = 'CrossEncoderLoadError';\n}\n\n/** @internal */\nlet CACHED_PIPELINE_FACTORY: CrossEncoderPipelineFactory | null = null;\n\n/** @internal */\nexport async function loadDefaultPipelineFactory(): Promise<CrossEncoderPipelineFactory> {\n  if (CACHED_PIPELINE_FACTORY !== null) return CACHED_PIPELINE_FACTORY;\n  try {\n    const mod = (await import('@huggingface/transformers')) as unknown as {\n      pipeline: CrossEncoderPipelineFactory;\n    };\n    CACHED_PIPELINE_FACTORY = mod.pipeline;\n    return CACHED_PIPELINE_FACTORY;\n  } catch (err) {\n    throw new CrossEncoderLoadError(\n      \"[graphorin/reranker-transformersjs] required peer '@huggingface/transformers' is not installed.\",\n      { cause: err },\n    );\n  }\n}\n\n/**\n * Test-only helper. Drops the cached pipeline factory so the next\n * loader call re-imports the peer.\n *\n * @internal\n */\nexport function _resetPipelineFactoryCacheForTesting(): void {\n  CACHED_PIPELINE_FACTORY = null;\n}\n\n/**\n * True when a classifier label names the *positive* (relevant) class. Matches\n * the conventional binary forms — `LABEL_1`, `positive`, `relevant`,\n * `entailment`, `true`, `yes` — using exact words so it does not mis-fire on a\n * negative label that merely contains one (`irrelevant` ⊃ `relevant`).\n */\nfunction isPositiveLabel(label: string): boolean {\n  const l = label.toLowerCase().trim();\n  if (l === '1' || /(?:^|[_-])1$/.test(l)) return true; // '1', 'label_1', 'class-1'\n  return /^(?:positive|relevant|entailment|true|yes|pos)$/.test(l);\n}\n\n/**\n * Normalises the raw pipeline output to a flat `score[]` aligned with the input\n * pair order. Cross-encoder classifiers return either a single-best\n * `{label, score}` per pair (the default single-logit bge exports) or an array\n * of `topk` entries. For the array shape we read the POSITIVE label's\n * confidence — NOT the max of any label (PS-16): an irrelevant pair's most\n * confident class is the *negative* one, so taking the max would invert the\n * ranking for any 2-label classifier. When no label looks positive (single-logit\n * or unrecognised labels) we fall back to the top score.\n *\n * @internal\n */\nexport function extractPairScores(\n  raw: ReadonlyArray<ClassifierResult> | ReadonlyArray<ReadonlyArray<ClassifierResult>>,\n  pairCount: number,\n): number[] {\n  const out: number[] = new Array(pairCount).fill(0) as number[];\n  for (let i = 0; i < pairCount; i++) {\n    const cell = raw[i];\n    if (cell === undefined) continue;\n    if (Array.isArray(cell)) {\n      let best = Number.NEGATIVE_INFINITY;\n      let positive = Number.NEGATIVE_INFINITY;\n      let sawPositive = false;\n      for (const entry of cell) {\n        if (entry === undefined) continue;\n        if (entry.score > best) best = entry.score;\n        if (isPositiveLabel(entry.label)) {\n          sawPositive = true;\n          if (entry.score > positive) positive = entry.score;\n        }\n      }\n      const chosen = sawPositive ? positive : best;\n      out[i] = Number.isFinite(chosen) ? chosen : 0;\n    } else {\n      const single = cell as ClassifierResult;\n      out[i] = single.score;\n    }\n  }\n  return out;\n}\n"],"mappings":";;;;;;;AA6DA,IAAa,wBAAb,cAA2C,MAAM;CAC/C,AAAkB,OAAO;;;AAI3B,IAAIA,0BAA8D;;AAGlE,eAAsB,6BAAmE;AACvF,KAAI,4BAA4B,KAAM,QAAO;AAC7C,KAAI;AAIF,6BAHa,MAAM,OAAO,8BAGI;AAC9B,SAAO;UACA,KAAK;AACZ,QAAM,IAAI,sBACR,mGACA,EAAE,OAAO,KAAK,CACf;;;;;;;;;AAUL,SAAgB,uCAA6C;AAC3D,2BAA0B;;;;;;;;AAS5B,SAAS,gBAAgB,OAAwB;CAC/C,MAAM,IAAI,MAAM,aAAa,CAAC,MAAM;AACpC,KAAI,MAAM,OAAO,eAAe,KAAK,EAAE,CAAE,QAAO;AAChD,QAAO,kDAAkD,KAAK,EAAE;;;;;;;;;;;;;;AAelE,SAAgB,kBACd,KACA,WACU;CACV,MAAMC,MAAgB,IAAI,MAAM,UAAU,CAAC,KAAK,EAAE;AAClD,MAAK,IAAI,IAAI,GAAG,IAAI,WAAW,KAAK;EAClC,MAAM,OAAO,IAAI;AACjB,MAAI,SAAS,OAAW;AACxB,MAAI,MAAM,QAAQ,KAAK,EAAE;GACvB,IAAI,OAAO,OAAO;GAClB,IAAI,WAAW,OAAO;GACtB,IAAI,cAAc;AAClB,QAAK,MAAM,SAAS,MAAM;AACxB,QAAI,UAAU,OAAW;AACzB,QAAI,MAAM,QAAQ,KAAM,QAAO,MAAM;AACrC,QAAI,gBAAgB,MAAM,MAAM,EAAE;AAChC,mBAAc;AACd,SAAI,MAAM,QAAQ,SAAU,YAAW,MAAM;;;GAGjD,MAAM,SAAS,cAAc,WAAW;AACxC,OAAI,KAAK,OAAO,SAAS,OAAO,GAAG,SAAS;QAG5C,KAAI,KADW,KACC;;AAGpB,QAAO"}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { ClassifierResult, CrossEncoderLoadError, CrossEncoderPipeline, CrossEncoderPipelineFactory, RerankerDtype, _resetPipelineFactoryCacheForTesting, extractPairScores, loadDefaultPipelineFactory } from "./cross-encoder.js";
+import { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, LocaleTag, pickRerankerModel } from "./model-selection.js";
+import { PassageExtractor, defaultPassageExtractor } from "./text-extraction.js";
+import { CrossEncoderRerankerOptions, RERANKER_ID, TransformersJsReRanker, createCrossEncoderReranker, mergeAndDedupe } from "./reranker.js";
+
+//#region src/index.d.ts
+
+/**
+ * @graphorin/reranker-transformersjs — cross-encoder reranker adapter
+ * for the Graphorin framework.
+ *
+ * Wraps `@huggingface/transformers@^4.1.0` to score `(query, passage)`
+ * pairs in-process. Plug into the memory hybrid-search pipeline as a
+ * drop-in replacement for the built-in `RRFReranker`:
+ *
+ * ```ts
+ * import { createMemory } from '@graphorin/memory';
+ * import { createCrossEncoderReranker } from '@graphorin/reranker-transformersjs';
+ *
+ * const memory = createMemory({
+ *   store,
+ *   embedder,
+ *   reranker: createCrossEncoderReranker({ locale: 'en' }),
+ * });
+ * ```
+ *
+ * Locale-aware default model:
+ *
+ *  - `'en'` / `'en-*'` → `Xenova/bge-reranker-base` (278M parameters,
+ *    FP16 quantized).
+ *  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M parameters,
+ *    multilingual baseline).
+ *
+ * Operators that want a narrower / language-specific cross-encoder
+ * pass an explicit `model` option — the package's defaults
+ * deliberately avoid privileging any single language pair.
+ *
+ * @packageDocumentation
+ */
+/** Canonical version constant. Mirrors the `package.json` version. */
+declare const VERSION = "0.5.0";
+//#endregion
+export { type ClassifierResult, CrossEncoderLoadError, type CrossEncoderPipeline, type CrossEncoderPipelineFactory, type CrossEncoderRerankerOptions, DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, type LocaleTag, type PassageExtractor, RERANKER_ID, type RerankerDtype, TransformersJsReRanker, VERSION, _resetPipelineFactoryCacheForTesting, createCrossEncoderReranker, defaultPassageExtractor, extractPairScores, loadDefaultPipelineFactory, mergeAndDedupe, pickRerankerModel };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,OAAA"}

package/dist/index.js

@@ -0,0 +1,44 @@
+import { CrossEncoderLoadError, _resetPipelineFactoryCacheForTesting, extractPairScores, loadDefaultPipelineFactory } from "./cross-encoder.js";
+import { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, pickRerankerModel } from "./model-selection.js";
+import { defaultPassageExtractor } from "./text-extraction.js";
+import { RERANKER_ID, TransformersJsReRanker, createCrossEncoderReranker, mergeAndDedupe } from "./reranker.js";
+
+//#region src/index.ts
+/**
+* @graphorin/reranker-transformersjs — cross-encoder reranker adapter
+* for the Graphorin framework.
+*
+* Wraps `@huggingface/transformers@^4.1.0` to score `(query, passage)`
+* pairs in-process. Plug into the memory hybrid-search pipeline as a
+* drop-in replacement for the built-in `RRFReranker`:
+*
+* ```ts
+* import { createMemory } from '@graphorin/memory';
+* import { createCrossEncoderReranker } from '@graphorin/reranker-transformersjs';
+*
+* const memory = createMemory({
+*   store,
+*   embedder,
+*   reranker: createCrossEncoderReranker({ locale: 'en' }),
+* });
+* ```
+*
+* Locale-aware default model:
+*
+*  - `'en'` / `'en-*'` → `Xenova/bge-reranker-base` (278M parameters,
+*    FP16 quantized).
+*  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M parameters,
+*    multilingual baseline).
+*
+* Operators that want a narrower / language-specific cross-encoder
+* pass an explicit `model` option — the package's defaults
+* deliberately avoid privileging any single language pair.
+*
+* @packageDocumentation
+*/
+/** Canonical version constant. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+
+//#endregion
+export { CrossEncoderLoadError, DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, RERANKER_ID, TransformersJsReRanker, VERSION, _resetPipelineFactoryCacheForTesting, createCrossEncoderReranker, defaultPassageExtractor, extractPairScores, loadDefaultPipelineFactory, mergeAndDedupe, pickRerankerModel };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/reranker-transformersjs — cross-encoder reranker adapter\n * for the Graphorin framework.\n *\n * Wraps `@huggingface/transformers@^4.1.0` to score `(query, passage)`\n * pairs in-process. Plug into the memory hybrid-search pipeline as a\n * drop-in replacement for the built-in `RRFReranker`:\n *\n * ```ts\n * import { createMemory } from '@graphorin/memory';\n * import { createCrossEncoderReranker } from '@graphorin/reranker-transformersjs';\n *\n * const memory = createMemory({\n *   store,\n *   embedder,\n *   reranker: createCrossEncoderReranker({ locale: 'en' }),\n * });\n * ```\n *\n * Locale-aware default model:\n *\n *  - `'en'` / `'en-*'` → `Xenova/bge-reranker-base` (278M parameters,\n *    FP16 quantized).\n *  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M parameters,\n *    multilingual baseline).\n *\n * Operators that want a narrower / language-specific cross-encoder\n * pass an explicit `model` option — the package's defaults\n * deliberately avoid privileging any single language pair.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.5.0';\n\nexport {\n  _resetPipelineFactoryCacheForTesting,\n  type ClassifierResult,\n  CrossEncoderLoadError,\n  type CrossEncoderPipeline,\n  type CrossEncoderPipelineFactory,\n  extractPairScores,\n  loadDefaultPipelineFactory,\n  type RerankerDtype,\n} from './cross-encoder.js';\nexport {\n  DEFAULT_ENGLISH_MODEL,\n  DEFAULT_MULTILINGUAL_MODEL,\n  type LocaleTag,\n  pickRerankerModel,\n} from './model-selection.js';\nexport {\n  type CrossEncoderRerankerOptions,\n  createCrossEncoderReranker,\n  mergeAndDedupe,\n  RERANKER_ID,\n  TransformersJsReRanker,\n} from './reranker.js';\nexport {\n  defaultPassageExtractor,\n  type PassageExtractor,\n} from './text-extraction.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAa,UAAU"}

package/dist/model-selection.d.ts

@@ -0,0 +1,36 @@
+//#region src/model-selection.d.ts
+/**
+ * Locale-aware default model selector. Mirrors ADR-024 / DEC-120 § BGE
+ * model family:
+ *
+ *  - English-only deployments → `Xenova/bge-reranker-base` (278M, FP16).
+ *  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M, multilingual).
+ *
+ * The selector deliberately stays language-pair-agnostic outside the
+ * English fast path; operators that want a narrower / language-specific
+ * cross-encoder pass an explicit `model` to {@link
+ * createCrossEncoderReranker}.
+ *
+ * @packageDocumentation
+ */
+/**
+ * BCP 47 locale tag (e.g. `'en'`, `'en-GB'`, `'pt-BR'`, `'zh-Hans-CN'`).
+ *
+ * @stable
+ */
+type LocaleTag = string;
+/** @stable */
+declare const DEFAULT_ENGLISH_MODEL = "Xenova/bge-reranker-base";
+/** @stable */
+declare const DEFAULT_MULTILINGUAL_MODEL = "BAAI/bge-reranker-v2-m3";
+/**
+ * Pick a reranker model from the agent locale. Pure function so callers
+ * (and tests) can pre-resolve the choice without constructing the
+ * reranker.
+ *
+ * @stable
+ */
+declare function pickRerankerModel(locale: LocaleTag | undefined): string;
+//#endregion
+export { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, LocaleTag, pickRerankerModel };
+//# sourceMappingURL=model-selection.d.ts.map

package/dist/model-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-selection.d.ts","names":[],"sources":["../src/model-selection.ts"],"sourcesContent":[],"mappings":";;AAoBA;AAGA;AAEA;AASA;;;;;;;;;;;;;;;KAdY,SAAA;;cAGC,qBAAA;;cAEA,0BAAA;;;;;;;;iBASG,iBAAA,SAA0B"}

package/dist/model-selection.js

@@ -0,0 +1,22 @@
+//#region src/model-selection.ts
+/** @stable */
+const DEFAULT_ENGLISH_MODEL = "Xenova/bge-reranker-base";
+/** @stable */
+const DEFAULT_MULTILINGUAL_MODEL = "BAAI/bge-reranker-v2-m3";
+/**
+* Pick a reranker model from the agent locale. Pure function so callers
+* (and tests) can pre-resolve the choice without constructing the
+* reranker.
+*
+* @stable
+*/
+function pickRerankerModel(locale) {
+	if (locale === void 0 || locale.length === 0) return DEFAULT_MULTILINGUAL_MODEL;
+	const normalized = locale.toLowerCase();
+	if (normalized === "en" || normalized.startsWith("en-")) return DEFAULT_ENGLISH_MODEL;
+	return DEFAULT_MULTILINGUAL_MODEL;
+}
+
+//#endregion
+export { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, pickRerankerModel };
+//# sourceMappingURL=model-selection.js.map

package/dist/model-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-selection.js","names":[],"sources":["../src/model-selection.ts"],"sourcesContent":["/**\n * Locale-aware default model selector. Mirrors ADR-024 / DEC-120 § BGE\n * model family:\n *\n *  - English-only deployments → `Xenova/bge-reranker-base` (278M, FP16).\n *  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M, multilingual).\n *\n * The selector deliberately stays language-pair-agnostic outside the\n * English fast path; operators that want a narrower / language-specific\n * cross-encoder pass an explicit `model` to {@link\n * createCrossEncoderReranker}.\n *\n * @packageDocumentation\n */\n\n/**\n * BCP 47 locale tag (e.g. `'en'`, `'en-GB'`, `'pt-BR'`, `'zh-Hans-CN'`).\n *\n * @stable\n */\nexport type LocaleTag = string;\n\n/** @stable */\nexport const DEFAULT_ENGLISH_MODEL = 'Xenova/bge-reranker-base';\n/** @stable */\nexport const DEFAULT_MULTILINGUAL_MODEL = 'BAAI/bge-reranker-v2-m3';\n\n/**\n * Pick a reranker model from the agent locale. Pure function so callers\n * (and tests) can pre-resolve the choice without constructing the\n * reranker.\n *\n * @stable\n */\nexport function pickRerankerModel(locale: LocaleTag | undefined): string {\n  if (locale === undefined || locale.length === 0) return DEFAULT_MULTILINGUAL_MODEL;\n  const normalized = locale.toLowerCase();\n  if (normalized === 'en' || normalized.startsWith('en-')) return DEFAULT_ENGLISH_MODEL;\n  return DEFAULT_MULTILINGUAL_MODEL;\n}\n"],"mappings":";;AAuBA,MAAa,wBAAwB;;AAErC,MAAa,6BAA6B;;;;;;;;AAS1C,SAAgB,kBAAkB,QAAuC;AACvE,KAAI,WAAW,UAAa,OAAO,WAAW,EAAG,QAAO;CACxD,MAAM,aAAa,OAAO,aAAa;AACvC,KAAI,eAAe,QAAQ,WAAW,WAAW,MAAM,CAAE,QAAO;AAChE,QAAO"}

package/dist/reranker.d.ts

@@ -0,0 +1,123 @@
+import { CrossEncoderPipelineFactory, RerankerDtype } from "./cross-encoder.js";
+import { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, LocaleTag } from "./model-selection.js";
+import { PassageExtractor } from "./text-extraction.js";
+import { MemoryHit, MemoryRecord } from "@graphorin/core";
+import { ReRankOptions, ReRanker } from "@graphorin/memory/search";
+
+//#region src/reranker.d.ts
+
+/**
+ * Options accepted by {@link createCrossEncoderReranker}.
+ *
+ * @stable
+ */
+interface CrossEncoderRerankerOptions<TRecord extends MemoryRecord = MemoryRecord> {
+  /** Override the auto-picked model. Default: derived from `locale`. */
+  readonly model?: string;
+  /** BCP 47 locale tag used to select the default model. Default `'en'`. */
+  readonly locale?: LocaleTag;
+  /** Default `'fp16'`. */
+  readonly dtype?: RerankerDtype;
+  /** Optional revision pin (`'main'` if unset). */
+  readonly revision?: string;
+  /** Optional cache directory. Honours `GRAPHORIN_CACHE_DIR` when unset. */
+  readonly cacheDir?: string;
+  /** Override device (`'cpu'`, `'webgpu'`, …). Default `'cpu'`. */
+  readonly device?: string;
+  /**
+   * Maximum batch size sent to the cross-encoder per inference call.
+   * Default `32`. Larger batches improve throughput at the cost of
+   * resident memory.
+   */
+  readonly batchSize?: number;
+  /**
+   * Optional idle-eviction timeout in milliseconds. When the reranker
+   * does not score a pair within this window, the loaded pipeline is
+   * dropped so the OS can reclaim the underlying ONNX session. Default
+   * `undefined` (eviction disabled).
+   */
+  readonly idleEvictionMs?: number;
+  /**
+   * Optional passage extractor — replaces the default heuristic that
+   * walks `text → summary → value → label → id`. Useful when a custom
+   * `MemoryRecord` schema attaches the canonical text elsewhere.
+   */
+  readonly passageExtractor?: PassageExtractor<TRecord>;
+  /**
+   * Inject a `pipelineFactory`. Used by tests to stub the underlying
+   * `@huggingface/transformers` pipeline. Production callers leave
+   * this unset so the package lazily loads the peer.
+   */
+  readonly pipelineFactory?: CrossEncoderPipelineFactory;
+  /**
+   * Override the wall-clock provider. Used by tests so the
+   * idle-eviction timer can be exercised deterministically.
+   *
+   * @internal
+   */
+  readonly now?: () => number;
+}
+/** @stable */
+declare const RERANKER_ID: "transformersjs-cross-encoder";
+/**
+ * Build a cross-encoder reranker. Lazy: the pipeline is constructed on
+ * the first `rerank()` call so packaging the reranker pays no
+ * model-load cost.
+ *
+ * @stable
+ */
+declare function createCrossEncoderReranker<TRecord extends MemoryRecord = MemoryRecord>(options?: CrossEncoderRerankerOptions<TRecord>): TransformersJsReRanker<TRecord>;
+/**
+ * `ReRanker` implementation. Matches the contract from
+ * `@graphorin/memory/search`.
+ *
+ * @stable
+ */
+declare class TransformersJsReRanker<TRecord extends MemoryRecord = MemoryRecord> implements ReRanker {
+  #private;
+  readonly id: "transformersjs-cross-encoder";
+  readonly model: string;
+  readonly locale: LocaleTag;
+  readonly dtype: RerankerDtype;
+  readonly batchSize: number;
+  readonly idleEvictionMs: number | undefined;
+  constructor(options: CrossEncoderRerankerOptions<TRecord>);
+  /**
+   * Number of `rerank(...)` invocations since construction. Surfaced
+   * for observability + the test suite.
+   *
+   * @stable
+   */
+  get invocationCount(): number;
+  /**
+   * Whether the underlying ONNX pipeline is currently loaded in
+   * memory. Surfaced for the idle-eviction integration test.
+   *
+   * @stable
+   */
+  get pipelineLoaded(): boolean;
+  /**
+   * Drop the loaded pipeline. Equivalent to letting the idle-eviction
+   * timer fire. Idempotent.
+   *
+   * @stable
+   */
+  unload(): void;
+  rerank<TInputRecord extends MemoryRecord>(query: string, lists: ReadonlyArray<ReadonlyArray<MemoryHit<TInputRecord>>>, options?: ReRankOptions): Promise<ReadonlyArray<MemoryHit<TInputRecord>>>;
+}
+interface MergedEntry<TRecord extends MemoryRecord> {
+  readonly hit: MemoryHit<TRecord>;
+  readonly firstSeenOrder: number;
+}
+/**
+ * Merge the per-source lists into a single deduplicated array,
+ * preserving the **highest** initial score per record id and the
+ * **first-seen order** for stable tie-breaking. Pure function;
+ * exported for the unit test fixture.
+ *
+ * @stable
+ */
+declare function mergeAndDedupe<TRecord extends MemoryRecord>(lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>): ReadonlyArray<MergedEntry<TRecord>>;
+//#endregion
+export { CrossEncoderRerankerOptions, RERANKER_ID, TransformersJsReRanker, createCrossEncoderReranker, mergeAndDedupe };
+//# sourceMappingURL=reranker.d.ts.map

package/dist/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","names":[],"sources":["../src/reranker.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAgFA;AASgB,UAzDC,2BAyDyB,CAAA,gBAzDmB,YAyDnB,GAzDkC,YAyDlC,CAAA,CAAA;EAAiB;EAAe,SAAA,KAAA,CAAA,EAAA,MAAA;EACnC;EAA5B,SAAA,MAAA,CAAA,EAtDS,SAsDT;EACe;EAAvB,SAAA,KAAA,CAAA,EArDgB,aAqDhB;EAAsB;EAUZ,SAAA,QAAA,CAAA,EAAA,MAAsB;EAAiB;EAAe,SAAA,QAAA,CAAA,EAAA,MAAA;EAKhD;EACD,SAAA,MAAA,CAAA,EAAA,MAAA;EAgBiC;;;;;EA2D1B,SAAA,SAAA,CAAA,EAAA,MAAA;EAAd;;;;;;EAhFE,SAAA,cAAA,CAAA,EAAA,MAAA;EAAQ;AAiLpB;;;;EAGwB,SAAA,gBAAA,CAAA,EA3NK,gBA2NL,CA3NsB,OA2NtB,CAAA;EAYT;;;;;EACP,SAAA,eAAA,CAAA,EAlOoB,2BAkOpB;EACoB;;;;;;;;;cAxNhB;;;;;;;;iBASG,2CAA2C,eAAe,wBAC/D,4BAA4B,WACpC,uBAAuB;;;;;;;cAUb,uCAAuC,eAAe,yBACtD;;;;mBAIM;kBACD;;;uBAgBK,4BAA4B;;;;;;;;;;;;;;;;;;;;;;8BAyDf,oCAEzB,cAAc,cAAc,UAAU,2BACpC,gBACR,QAAQ,cAAc,UAAU;;UAiG3B,4BAA4B;gBACtB,UAAU;;;;;;;;;;;iBAYV,+BAA+B,qBACtC,cAAc,cAAc,UAAU,aAC5C,cAAc,YAAY"}

package/dist/reranker.js

@@ -0,0 +1,190 @@
+import { CrossEncoderLoadError, extractPairScores, loadDefaultPipelineFactory } from "./cross-encoder.js";
+import { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, pickRerankerModel } from "./model-selection.js";
+import { defaultPassageExtractor } from "./text-extraction.js";
+
+//#region src/reranker.ts
+/** @stable */
+const RERANKER_ID = "transformersjs-cross-encoder";
+/**
+* Build a cross-encoder reranker. Lazy: the pipeline is constructed on
+* the first `rerank()` call so packaging the reranker pays no
+* model-load cost.
+*
+* @stable
+*/
+function createCrossEncoderReranker(options = {}) {
+	return new TransformersJsReRanker(options);
+}
+/**
+* `ReRanker` implementation. Matches the contract from
+* `@graphorin/memory/search`.
+*
+* @stable
+*/
+var TransformersJsReRanker = class {
+	id = RERANKER_ID;
+	model;
+	locale;
+	dtype;
+	batchSize;
+	idleEvictionMs;
+	#revision;
+	#cacheDir;
+	#device;
+	#pipelineFactory;
+	#passageExtractor;
+	#now;
+	#pipeline = null;
+	#loading = null;
+	#lastUsedAt = 0;
+	#idleTimer = null;
+	#invocationCount = 0;
+	constructor(options) {
+		this.locale = options.locale ?? "en";
+		this.model = options.model ?? pickRerankerModel(this.locale);
+		this.dtype = options.dtype ?? "fp16";
+		this.batchSize = options.batchSize ?? 32;
+		if (!Number.isInteger(this.batchSize) || this.batchSize <= 0) throw new RangeError(`[graphorin/reranker-transformersjs] batchSize must be a positive integer; got ${String(options.batchSize)}.`);
+		this.idleEvictionMs = options.idleEvictionMs;
+		this.#revision = options.revision;
+		this.#cacheDir = options.cacheDir ?? process.env.GRAPHORIN_CACHE_DIR;
+		this.#device = options.device;
+		this.#pipelineFactory = options.pipelineFactory;
+		this.#passageExtractor = options.passageExtractor ?? ((record) => defaultPassageExtractor(record));
+		this.#now = options.now ?? Date.now;
+	}
+	/**
+	* Number of `rerank(...)` invocations since construction. Surfaced
+	* for observability + the test suite.
+	*
+	* @stable
+	*/
+	get invocationCount() {
+		return this.#invocationCount;
+	}
+	/**
+	* Whether the underlying ONNX pipeline is currently loaded in
+	* memory. Surfaced for the idle-eviction integration test.
+	*
+	* @stable
+	*/
+	get pipelineLoaded() {
+		return this.#pipeline !== null;
+	}
+	/**
+	* Drop the loaded pipeline. Equivalent to letting the idle-eviction
+	* timer fire. Idempotent.
+	*
+	* @stable
+	*/
+	unload() {
+		this.#pipeline = null;
+		this.#loading = null;
+		if (this.#idleTimer !== null) {
+			clearTimeout(this.#idleTimer);
+			this.#idleTimer = null;
+		}
+	}
+	async rerank(query, lists, options = {}) {
+		if (options.signal?.aborted === true) throw new DOMException("TransformersJsReRanker aborted", "AbortError");
+		this.#invocationCount += 1;
+		const merged = mergeAndDedupe(lists);
+		if (merged.length === 0) return [];
+		const pipeline = await this.#getPipeline();
+		const passages = merged.map((entry) => this.#passageExtractor(entry.hit.record));
+		const scores = await this.#scoreInBatches(pipeline, query, passages, options.signal);
+		const fused = merged.map((entry, idx) => {
+			const score = scores[idx] ?? 0;
+			const signals = {
+				...entry.hit.signals ?? {},
+				cross_encoder: score
+			};
+			return Object.freeze({
+				record: entry.hit.record,
+				score,
+				signals: Object.freeze(signals)
+			});
+		});
+		fused.sort((a, b) => b.score - a.score);
+		const topK = options.topK ?? 10;
+		return fused.slice(0, Math.max(0, topK));
+	}
+	async #scoreInBatches(pipeline, query, passages, signal) {
+		const out = [];
+		for (let i = 0; i < passages.length; i += this.batchSize) {
+			if (signal?.aborted === true) throw new DOMException("TransformersJsReRanker aborted", "AbortError");
+			const batch = passages.slice(i, i + this.batchSize);
+			const scores = extractPairScores(await pipeline(batch.map((text_pair) => ({
+				text: query,
+				text_pair
+			})), {
+				topk: 1,
+				...signal !== void 0 ? { signal } : {}
+			}), batch.length);
+			for (const s of scores) out.push(s);
+		}
+		return out;
+	}
+	async #getPipeline() {
+		this.#lastUsedAt = this.#now();
+		this.#scheduleIdleEviction();
+		if (this.#pipeline !== null) return this.#pipeline;
+		if (this.#loading !== null) return this.#loading;
+		this.#loading = (this.#pipelineFactory ?? await loadDefaultPipelineFactory())("text-classification", this.model, {
+			...this.#revision !== void 0 ? { revision: this.#revision } : {},
+			...this.#cacheDir !== void 0 ? { cache_dir: this.#cacheDir } : {},
+			...this.dtype !== void 0 ? { dtype: this.dtype } : {},
+			...this.#device !== void 0 ? { device: this.#device } : {}
+		}).then((pipe) => {
+			this.#pipeline = pipe;
+			this.#loading = null;
+			return pipe;
+		}).catch((err) => {
+			this.#loading = null;
+			throw new CrossEncoderLoadError(`[graphorin/reranker-transformersjs] failed to load model '${this.model}'.`, { cause: err });
+		});
+		return this.#loading;
+	}
+	#scheduleIdleEviction() {
+		if (this.idleEvictionMs === void 0) return;
+		if (this.#idleTimer !== null) clearTimeout(this.#idleTimer);
+		this.#idleTimer = setTimeout(() => {
+			if (this.#now() - this.#lastUsedAt >= (this.idleEvictionMs ?? 0)) {
+				this.#pipeline = null;
+				this.#loading = null;
+			}
+			this.#idleTimer = null;
+		}, this.idleEvictionMs);
+		this.#idleTimer.unref?.();
+	}
+};
+/**
+* Merge the per-source lists into a single deduplicated array,
+* preserving the **highest** initial score per record id and the
+* **first-seen order** for stable tie-breaking. Pure function;
+* exported for the unit test fixture.
+*
+* @stable
+*/
+function mergeAndDedupe(lists) {
+	const out = /* @__PURE__ */ new Map();
+	let order = 0;
+	for (const list of lists) for (const hit of list) {
+		const existing = out.get(hit.record.id);
+		if (existing === void 0) out.set(hit.record.id, {
+			hit,
+			firstSeenOrder: order++
+		});
+		else if (hit.score > existing.hit.score) out.set(hit.record.id, {
+			hit,
+			firstSeenOrder: existing.firstSeenOrder
+		});
+	}
+	const arr = Array.from(out.values());
+	arr.sort((a, b) => a.firstSeenOrder - b.firstSeenOrder);
+	return arr;
+}
+
+//#endregion
+export { RERANKER_ID, TransformersJsReRanker, createCrossEncoderReranker, mergeAndDedupe };
+//# sourceMappingURL=reranker.js.map

package/dist/reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.js","names":["#revision","#cacheDir","#device","#pipelineFactory","#passageExtractor","#now","#invocationCount","#pipeline","#loading","#idleTimer","#getPipeline","#scoreInBatches","fused: MemoryHit<TInputRecord>[]","signals: Record<string, number>","out: number[]","#lastUsedAt","#scheduleIdleEviction"],"sources":["../src/reranker.ts"],"sourcesContent":["/**\n * Cross-encoder `ReRanker` implementation backed by\n * `@huggingface/transformers`. Lazy-loaded, optional idle eviction,\n * locale-aware default model.\n *\n * @packageDocumentation\n */\n\nimport type { MemoryHit, MemoryRecord } from '@graphorin/core';\nimport type { ReRanker, ReRankOptions } from '@graphorin/memory/search';\n\nimport {\n  CrossEncoderLoadError,\n  type CrossEncoderPipeline,\n  type CrossEncoderPipelineFactory,\n  extractPairScores,\n  loadDefaultPipelineFactory,\n  type RerankerDtype,\n} from './cross-encoder.js';\nimport {\n  DEFAULT_ENGLISH_MODEL,\n  DEFAULT_MULTILINGUAL_MODEL,\n  type LocaleTag,\n  pickRerankerModel,\n} from './model-selection.js';\nimport { defaultPassageExtractor, type PassageExtractor } from './text-extraction.js';\n\n/**\n * Options accepted by {@link createCrossEncoderReranker}.\n *\n * @stable\n */\nexport interface CrossEncoderRerankerOptions<TRecord extends MemoryRecord = MemoryRecord> {\n  /** Override the auto-picked model. Default: derived from `locale`. */\n  readonly model?: string;\n  /** BCP 47 locale tag used to select the default model. Default `'en'`. */\n  readonly locale?: LocaleTag;\n  /** Default `'fp16'`. */\n  readonly dtype?: RerankerDtype;\n  /** Optional revision pin (`'main'` if unset). */\n  readonly revision?: string;\n  /** Optional cache directory. Honours `GRAPHORIN_CACHE_DIR` when unset. */\n  readonly cacheDir?: string;\n  /** Override device (`'cpu'`, `'webgpu'`, …). Default `'cpu'`. */\n  readonly device?: string;\n  /**\n   * Maximum batch size sent to the cross-encoder per inference call.\n   * Default `32`. Larger batches improve throughput at the cost of\n   * resident memory.\n   */\n  readonly batchSize?: number;\n  /**\n   * Optional idle-eviction timeout in milliseconds. When the reranker\n   * does not score a pair within this window, the loaded pipeline is\n   * dropped so the OS can reclaim the underlying ONNX session. Default\n   * `undefined` (eviction disabled).\n   */\n  readonly idleEvictionMs?: number;\n  /**\n   * Optional passage extractor — replaces the default heuristic that\n   * walks `text → summary → value → label → id`. Useful when a custom\n   * `MemoryRecord` schema attaches the canonical text elsewhere.\n   */\n  readonly passageExtractor?: PassageExtractor<TRecord>;\n  /**\n   * Inject a `pipelineFactory`. Used by tests to stub the underlying\n   * `@huggingface/transformers` pipeline. Production callers leave\n   * this unset so the package lazily loads the peer.\n   */\n  readonly pipelineFactory?: CrossEncoderPipelineFactory;\n  /**\n   * Override the wall-clock provider. Used by tests so the\n   * idle-eviction timer can be exercised deterministically.\n   *\n   * @internal\n   */\n  readonly now?: () => number;\n}\n\n/** @stable */\nexport const RERANKER_ID = 'transformersjs-cross-encoder' as const;\n\n/**\n * Build a cross-encoder reranker. Lazy: the pipeline is constructed on\n * the first `rerank()` call so packaging the reranker pays no\n * model-load cost.\n *\n * @stable\n */\nexport function createCrossEncoderReranker<TRecord extends MemoryRecord = MemoryRecord>(\n  options: CrossEncoderRerankerOptions<TRecord> = {},\n): TransformersJsReRanker<TRecord> {\n  return new TransformersJsReRanker<TRecord>(options);\n}\n\n/**\n * `ReRanker` implementation. Matches the contract from\n * `@graphorin/memory/search`.\n *\n * @stable\n */\nexport class TransformersJsReRanker<TRecord extends MemoryRecord = MemoryRecord>\n  implements ReRanker\n{\n  readonly id = RERANKER_ID;\n  readonly model: string;\n  readonly locale: LocaleTag;\n  readonly dtype: RerankerDtype;\n  readonly batchSize: number;\n  readonly idleEvictionMs: number | undefined;\n\n  readonly #revision: string | undefined;\n  readonly #cacheDir: string | undefined;\n  readonly #device: string | undefined;\n  readonly #pipelineFactory: CrossEncoderPipelineFactory | undefined;\n  readonly #passageExtractor: PassageExtractor<TRecord>;\n  readonly #now: () => number;\n  #pipeline: CrossEncoderPipeline | null = null;\n  #loading: Promise<CrossEncoderPipeline> | null = null;\n  #lastUsedAt: number = 0;\n  #idleTimer: ReturnType<typeof setTimeout> | null = null;\n  #invocationCount = 0;\n\n  constructor(options: CrossEncoderRerankerOptions<TRecord>) {\n    this.locale = options.locale ?? 'en';\n    this.model = options.model ?? pickRerankerModel(this.locale);\n    this.dtype = options.dtype ?? 'fp16';\n    this.batchSize = options.batchSize ?? 32;\n    if (!Number.isInteger(this.batchSize) || this.batchSize <= 0) {\n      throw new RangeError(\n        `[graphorin/reranker-transformersjs] batchSize must be a positive integer; got ${String(\n          options.batchSize,\n        )}.`,\n      );\n    }\n    this.idleEvictionMs = options.idleEvictionMs;\n    this.#revision = options.revision;\n    this.#cacheDir = options.cacheDir ?? process.env.GRAPHORIN_CACHE_DIR;\n    this.#device = options.device;\n    this.#pipelineFactory = options.pipelineFactory;\n    this.#passageExtractor =\n      options.passageExtractor ?? ((record: TRecord) => defaultPassageExtractor(record));\n    this.#now = options.now ?? Date.now;\n  }\n\n  /**\n   * Number of `rerank(...)` invocations since construction. Surfaced\n   * for observability + the test suite.\n   *\n   * @stable\n   */\n  get invocationCount(): number {\n    return this.#invocationCount;\n  }\n\n  /**\n   * Whether the underlying ONNX pipeline is currently loaded in\n   * memory. Surfaced for the idle-eviction integration test.\n   *\n   * @stable\n   */\n  get pipelineLoaded(): boolean {\n    return this.#pipeline !== null;\n  }\n\n  /**\n   * Drop the loaded pipeline. Equivalent to letting the idle-eviction\n   * timer fire. Idempotent.\n   *\n   * @stable\n   */\n  unload(): void {\n    this.#pipeline = null;\n    this.#loading = null;\n    if (this.#idleTimer !== null) {\n      clearTimeout(this.#idleTimer);\n      this.#idleTimer = null;\n    }\n  }\n\n  async rerank<TInputRecord extends MemoryRecord>(\n    query: string,\n    lists: ReadonlyArray<ReadonlyArray<MemoryHit<TInputRecord>>>,\n    options: ReRankOptions = {},\n  ): Promise<ReadonlyArray<MemoryHit<TInputRecord>>> {\n    if (options.signal?.aborted === true) {\n      throw new DOMException('TransformersJsReRanker aborted', 'AbortError');\n    }\n    this.#invocationCount += 1;\n    const merged = mergeAndDedupe(lists);\n    if (merged.length === 0) return [];\n    const pipeline = await this.#getPipeline();\n    const passages = merged.map((entry) =>\n      this.#passageExtractor(entry.hit.record as unknown as TRecord),\n    );\n    const scores = await this.#scoreInBatches(pipeline, query, passages, options.signal);\n    const fused: MemoryHit<TInputRecord>[] = merged.map((entry, idx) => {\n      const score = scores[idx] ?? 0;\n      const baseSignals = entry.hit.signals ?? {};\n      const signals: Record<string, number> = {\n        ...baseSignals,\n        cross_encoder: score,\n      };\n      return Object.freeze({\n        record: entry.hit.record,\n        score,\n        signals: Object.freeze(signals),\n      });\n    });\n    fused.sort((a, b) => b.score - a.score);\n    const topK = options.topK ?? 10;\n    return fused.slice(0, Math.max(0, topK));\n  }\n\n  async #scoreInBatches(\n    pipeline: CrossEncoderPipeline,\n    query: string,\n    passages: ReadonlyArray<string>,\n    signal: AbortSignal | undefined,\n  ): Promise<number[]> {\n    const out: number[] = [];\n    for (let i = 0; i < passages.length; i += this.batchSize) {\n      if (signal?.aborted === true) {\n        throw new DOMException('TransformersJsReRanker aborted', 'AbortError');\n      }\n      const batch = passages.slice(i, i + this.batchSize);\n      const pairs = batch.map((text_pair) => ({ text: query, text_pair }));\n      const raw = await pipeline(pairs, {\n        topk: 1,\n        ...(signal !== undefined ? { signal } : {}),\n      });\n      const scores = extractPairScores(raw, batch.length);\n      for (const s of scores) out.push(s);\n    }\n    return out;\n  }\n\n  async #getPipeline(): Promise<CrossEncoderPipeline> {\n    this.#lastUsedAt = this.#now();\n    this.#scheduleIdleEviction();\n    if (this.#pipeline !== null) return this.#pipeline;\n    if (this.#loading !== null) return this.#loading;\n    const factory = this.#pipelineFactory ?? (await loadDefaultPipelineFactory());\n    this.#loading = factory('text-classification', this.model, {\n      ...(this.#revision !== undefined ? { revision: this.#revision } : {}),\n      ...(this.#cacheDir !== undefined ? { cache_dir: this.#cacheDir } : {}),\n      ...(this.dtype !== undefined ? { dtype: this.dtype } : {}),\n      ...(this.#device !== undefined ? { device: this.#device } : {}),\n    })\n      .then((pipe) => {\n        this.#pipeline = pipe;\n        this.#loading = null;\n        return pipe;\n      })\n      .catch((err) => {\n        this.#loading = null;\n        throw new CrossEncoderLoadError(\n          `[graphorin/reranker-transformersjs] failed to load model '${this.model}'.`,\n          { cause: err },\n        );\n      });\n    return this.#loading;\n  }\n\n  #scheduleIdleEviction(): void {\n    if (this.idleEvictionMs === undefined) return;\n    if (this.#idleTimer !== null) {\n      clearTimeout(this.#idleTimer);\n    }\n    this.#idleTimer = setTimeout(() => {\n      const elapsed = this.#now() - this.#lastUsedAt;\n      if (elapsed >= (this.idleEvictionMs ?? 0)) {\n        this.#pipeline = null;\n        this.#loading = null;\n      }\n      this.#idleTimer = null;\n    }, this.idleEvictionMs);\n    this.#idleTimer.unref?.();\n  }\n}\n\ninterface MergedEntry<TRecord extends MemoryRecord> {\n  readonly hit: MemoryHit<TRecord>;\n  readonly firstSeenOrder: number;\n}\n\n/**\n * Merge the per-source lists into a single deduplicated array,\n * preserving the **highest** initial score per record id and the\n * **first-seen order** for stable tie-breaking. Pure function;\n * exported for the unit test fixture.\n *\n * @stable\n */\nexport function mergeAndDedupe<TRecord extends MemoryRecord>(\n  lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>,\n): ReadonlyArray<MergedEntry<TRecord>> {\n  const out = new Map<string, MergedEntry<TRecord>>();\n  let order = 0;\n  for (const list of lists) {\n    for (const hit of list) {\n      const existing = out.get(hit.record.id);\n      if (existing === undefined) {\n        out.set(hit.record.id, { hit, firstSeenOrder: order++ });\n      } else if (hit.score > existing.hit.score) {\n        out.set(hit.record.id, {\n          hit,\n          firstSeenOrder: existing.firstSeenOrder,\n        });\n      }\n    }\n  }\n  const arr = Array.from(out.values());\n  arr.sort((a, b) => a.firstSeenOrder - b.firstSeenOrder);\n  return arr;\n}\n\nexport { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL };\n"],"mappings":"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"}

package/dist/text-extraction.d.ts

@@ -0,0 +1,27 @@
+import { MemoryRecord } from "@graphorin/core";
+
+//#region src/text-extraction.d.ts
+
+/**
+ * Returns the best-effort passage text for a {@link MemoryRecord}. The
+ * order of preference, top-down:
+ *
+ *   1. `text` — facts, rules, generic text-bearing tiers.
+ *   2. `summary` — episodes.
+ *   3. `value` — working-memory blocks.
+ *   4. `id` fallback so the reranker never sees an empty passage.
+ *
+ * @stable
+ */
+declare function defaultPassageExtractor(record: MemoryRecord): string;
+/**
+ * Caller-supplied passage extractor. Receives the record + the
+ * surrounding metadata (kind, sensitivity, tags) and returns the
+ * passage to feed into the cross-encoder.
+ *
+ * @stable
+ */
+type PassageExtractor<TRecord extends MemoryRecord = MemoryRecord> = (record: TRecord) => string;
+//#endregion
+export { PassageExtractor, defaultPassageExtractor };
+//# sourceMappingURL=text-extraction.d.ts.map

package/dist/text-extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-extraction.d.ts","names":[],"sources":["../src/text-extraction.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;iBA0BgB,uBAAA,SAAgC;;;;;;;;KAoBpC,iCAAiC,eAAe,yBAClD"}

package/dist/text-extraction.js

@@ -0,0 +1,28 @@
+//#region src/text-extraction.ts
+/**
+* Returns the best-effort passage text for a {@link MemoryRecord}. The
+* order of preference, top-down:
+*
+*   1. `text` — facts, rules, generic text-bearing tiers.
+*   2. `summary` — episodes.
+*   3. `value` — working-memory blocks.
+*   4. `id` fallback so the reranker never sees an empty passage.
+*
+* @stable
+*/
+function defaultPassageExtractor(record) {
+	const obj = record;
+	const text = obj.text;
+	if (typeof text === "string" && text.length > 0) return text;
+	const summary = obj.summary;
+	if (typeof summary === "string" && summary.length > 0) return summary;
+	const value = obj.value;
+	if (typeof value === "string" && value.length > 0) return value;
+	const label = obj.label;
+	if (typeof label === "string" && label.length > 0) return label;
+	return record.id;
+}
+
+//#endregion
+export { defaultPassageExtractor };
+//# sourceMappingURL=text-extraction.js.map

package/dist/text-extraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-extraction.js","names":[],"sources":["../src/text-extraction.ts"],"sourcesContent":["/**\n * Heuristic text-extraction helpers. The reranker scores `(query,\n * passage)` pairs; this module turns a `MemoryRecord` of any concrete\n * tier into the best single-passage approximation.\n *\n * The defaults are conservative — text-bearing fields take precedence\n * over IDs / labels — and operators may inject a custom\n * `passageExtractor` when their schema attaches the canonical text\n * elsewhere.\n *\n * @packageDocumentation\n */\n\nimport type { MemoryRecord } from '@graphorin/core';\n\n/**\n * Returns the best-effort passage text for a {@link MemoryRecord}. The\n * order of preference, top-down:\n *\n *   1. `text` — facts, rules, generic text-bearing tiers.\n *   2. `summary` — episodes.\n *   3. `value` — working-memory blocks.\n *   4. `id` fallback so the reranker never sees an empty passage.\n *\n * @stable\n */\nexport function defaultPassageExtractor(record: MemoryRecord): string {\n  const obj = record as unknown as Record<string, unknown>;\n  const text = obj.text;\n  if (typeof text === 'string' && text.length > 0) return text;\n  const summary = obj.summary;\n  if (typeof summary === 'string' && summary.length > 0) return summary;\n  const value = obj.value;\n  if (typeof value === 'string' && value.length > 0) return value;\n  const label = obj.label;\n  if (typeof label === 'string' && label.length > 0) return label;\n  return record.id;\n}\n\n/**\n * Caller-supplied passage extractor. Receives the record + the\n * surrounding metadata (kind, sensitivity, tags) and returns the\n * passage to feed into the cross-encoder.\n *\n * @stable\n */\nexport type PassageExtractor<TRecord extends MemoryRecord = MemoryRecord> = (\n  record: TRecord,\n) => string;\n"],"mappings":";;;;;;;;;;;;AA0BA,SAAgB,wBAAwB,QAA8B;CACpE,MAAM,MAAM;CACZ,MAAM,OAAO,IAAI;AACjB,KAAI,OAAO,SAAS,YAAY,KAAK,SAAS,EAAG,QAAO;CACxD,MAAM,UAAU,IAAI;AACpB,KAAI,OAAO,YAAY,YAAY,QAAQ,SAAS,EAAG,QAAO;CAC9D,MAAM,QAAQ,IAAI;AAClB,KAAI,OAAO,UAAU,YAAY,MAAM,SAAS,EAAG,QAAO;CAC1D,MAAM,QAAQ,IAAI;AAClB,KAAI,OAAO,UAAU,YAAY,MAAM,SAAS,EAAG,QAAO;AAC1D,QAAO,OAAO"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@graphorin/reranker-transformersjs",
+  "version": "0.5.0",
+  "description": "Cross-encoder reranker adapter for the Graphorin framework. Wraps `@huggingface/transformers@^4.1.0` to score query / passage pairs in-process via the BAAI BGE family of cross-encoder models. Automatic model selection from the agent locale: `'en'` defaults to `Xenova/bge-reranker-base` (278M); every other locale defaults to `BAAI/bge-reranker-v2-m3` (568M, multilingual). FP16 quantization default; FP32 / Q8 opt-in. Lazy-loaded with an optional idle-eviction timer to bound resident memory. Implements the `ReRanker` contract exposed by `@graphorin/memory/search`. Created and maintained by Oleksiy Stepurenko.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/reranker-transformersjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/reranker-transformersjs"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "rerank",
+    "reranker",
+    "cross-encoder",
+    "huggingface",
+    "transformersjs",
+    "bge",
+    "bge-reranker"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/core": "0.5.0",
+    "@graphorin/memory": "0.5.0"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": "^4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": false
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}