@shadowforge0/aquifer-memory 0.6.0 → 0.7.0

package/consumers/shared/config.js

@@ -29,8 +29,19 @@ const DEFAULTS = {
     maxRetries: 3,
     temperature: 0,
   },
-  entities: { enabled: false, mergeCall: true },
+  entities: { enabled: false, mergeCall: true, scope: 'default' },
   rank: { rrf: 0.65, timeDecay: 0.25, access: 0.10, entityBoost: 0.18 },
+  rerank: {
+    enabled: false,
+    provider: null,    // 'tei' | 'jina' | 'custom'
+    baseUrl: null,     // TEI base URL
+    apiKey: null,      // Jina API key
+    model: null,       // Jina model override
+    topK: 20,
+    maxChars: 1600,
+    timeoutMs: 2000,
+    maxRetries: 1,
+  },
 };
 
 // ---------------------------------------------------------------------------
@@ -57,6 +68,15 @@ const ENV_MAP = [
   ['AQUIFER_LLM_TIMEOUT_MS',    'llm.timeoutMs',     Number],
   ['AQUIFER_LLM_TEMPERATURE',   'llm.temperature',   Number],
   ['AQUIFER_ENTITIES_ENABLED',  'entities.enabled',  Boolean],
+  ['AQUIFER_ENTITY_SCOPE',     'entities.scope'],
+  ['AQUIFER_RERANK_ENABLED',   'rerank.enabled',    Boolean],
+  ['AQUIFER_RERANK_PROVIDER',  'rerank.provider'],
+  ['AQUIFER_RERANK_BASE_URL',  'rerank.baseUrl'],
+  ['AQUIFER_RERANK_API_KEY',   'rerank.apiKey'],
+  ['AQUIFER_RERANK_MODEL',     'rerank.model'],
+  ['AQUIFER_RERANK_TOP_K',     'rerank.topK',       Number],
+  ['AQUIFER_RERANK_MAX_CHARS', 'rerank.maxChars',   Number],
+  ['AQUIFER_RERANK_TIMEOUT_MS','rerank.timeoutMs',   Number],
 ];
 
 // ---------------------------------------------------------------------------

package/consumers/shared/factory.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { Pool } = require('pg');
-const { createAquifer, createEmbedder } = require('../../index');
+const { createAquifer, createEmbedder, createReranker } = require('../../index');
 const { loadConfig } = require('./config');
 const { createLlmFn } = require('./llm');
 
@@ -57,6 +57,24 @@ function createAquiferFromConfig(overrides) {
     llmFn = createLlmFn(config.llm);
   }
 
+  // Rerank config (optional)
+  let rerankOpts = null;
+  if (config.rerank && config.rerank.enabled && config.rerank.provider) {
+    const rc = config.rerank;
+    const rerankConfig = { provider: rc.provider, topK: rc.topK, maxChars: rc.maxChars };
+    if (rc.provider === 'tei') {
+      rerankConfig.teiBaseUrl = rc.baseUrl || 'http://localhost:8080';
+      rerankConfig.timeout = rc.timeoutMs || 2000;
+      rerankConfig.maxRetries = rc.maxRetries ?? 1;
+    } else if (rc.provider === 'jina') {
+      rerankConfig.jinaApiKey = rc.apiKey;
+      if (rc.model) rerankConfig.jinaModel = rc.model;
+      rerankConfig.timeout = rc.timeoutMs || 2000;
+      rerankConfig.maxRetries = rc.maxRetries ?? 1;
+    }
+    rerankOpts = rerankConfig;
+  }
+
   const aquifer = createAquifer({
     db: pool,
     schema: config.schema,
@@ -65,6 +83,7 @@ function createAquiferFromConfig(overrides) {
     llm: llmFn ? { fn: llmFn } : null,
     entities: config.entities,
     rank: config.rank,
+    rerank: rerankOpts,
   });
 
   // Attach pool for lifecycle management

package/core/aquifer.js

@@ -36,6 +36,24 @@ function loadSql(filename, schema) {
   return raw.replace(/\$\{schema\}/g, qi(schema));
 }
 
+// ---------------------------------------------------------------------------
+// buildRerankDocument — assemble text for cross-encoder reranking
+// ---------------------------------------------------------------------------
+
+function buildRerankDocument(row, maxChars) {
+  let text = (row.summary_text || row.summary_snippet || '').replace(/\s+/g, ' ').trim();
+  const turn = (row.matched_turn_text || '').replace(/\s+/g, ' ').trim();
+
+  if (!text) {
+    text = turn;
+  } else if (turn && !text.includes(turn)) {
+    text = `${text}\n\nMatched turn:\n${turn}`;
+  }
+
+  if (text.length > maxChars) text = text.slice(0, maxChars);
+  return text;
+}
+
 // ---------------------------------------------------------------------------
 // createAquifer
 // ---------------------------------------------------------------------------
@@ -81,6 +99,9 @@ function createAquifer(config) {
   const entityPromptFn = config.entities && config.entities.prompt ? config.entities.prompt : null;
   const entityScope = (config.entities && config.entities.scope) || 'default';
 
+  // FTS config (default: 'simple'; set to 'zhcfg' for Chinese tokenization)
+  const ftsConfig = config.ftsConfig || 'simple';
+
   // Rank weights
   const rankWeights = {
     rrf: 0.65,
@@ -90,6 +111,16 @@ function createAquifer(config) {
     ...(config.rank || {}),
   };
 
+  // Reranker config (optional)
+  const rerankConfig = config.rerank || null;
+  let reranker = null;
+  if (rerankConfig) {
+    const { createReranker } = require('../pipeline/rerank');
+    reranker = createReranker(rerankConfig);
+  }
+  const defaultRerankTopK = rerankConfig ? Math.max(1, rerankConfig.topK || 20) : 0;
+  const rerankMaxChars = rerankConfig ? Math.max(200, rerankConfig.maxChars || 1600) : 0;
+
   // Source registry (in-memory)
   const sources = new Map();
 
@@ -106,7 +137,7 @@ function createAquifer(config) {
 
   // --- Helper: embed search on summaries ---
   async function embeddingSearchSummaries(queryVec, opts) {
-    const { agentId, source, dateFrom, dateTo, limit = 20 } = opts;
+    const { agentIds, source, dateFrom, dateTo, limit = 20 } = opts;
     const where = [`s.tenant_id = $1`];
     const params = [tenantId];
 
@@ -121,9 +152,9 @@ function createAquifer(config) {
       params.push(dateTo);
       where.push(`($${params.length}::date IS NULL OR s.started_at::date <= $${params.length}::date)`);
     }
-    if (agentId) {
-      params.push(agentId);
-      where.push(`s.agent_id = $${params.length}`);
+    if (agentIds && agentIds.length > 0) {
+      params.push(agentIds);
+      where.push(`s.agent_id = ANY($${params.length})`);
     }
     if (source) {
       params.push(source);
@@ -524,6 +555,7 @@ function createAquifer(config) {
 
       const {
         agentId,
+        agentIds: rawAgentIds,
         source,
         dateFrom,
         dateTo,
@@ -533,6 +565,12 @@ function createAquifer(config) {
         entityMode = 'any',
       } = opts;
 
+      // Normalize agentId/agentIds into a single resolved value
+      // agentIds takes precedence; agentId is sugar for agentIds: [agentId]
+      const resolvedAgentIds = rawAgentIds && rawAgentIds.length > 0
+        ? rawAgentIds
+        : (agentId ? [agentId] : null);
+
       // Validate before touching DB
       if (explicitEntities && explicitEntities.length > 0 && !entitiesEnabled) {
         throw new Error('Entities are not enabled');
@@ -540,7 +578,9 @@ function createAquifer(config) {
 
       await ensureMigrated();
 
-      const fetchLimit = limit * 4;
+      const rerankEnabled = !!reranker && opts.rerank !== false;
+      const rerankTopK = rerankEnabled ? Math.max(limit, opts.rerankTopK || defaultRerankTopK) : limit;
+      const fetchLimit = rerankTopK * 4;
 
       // 1. Embed query
       const queryVecResult = await embedFn([query]);
@@ -624,13 +664,13 @@ function createAquifer(config) {
       // 3. Run 3 search paths in parallel
       const [ftsRows, embRows, turnResult] = await Promise.all([
         storage.searchSessions(pool, query, {
-          schema, tenantId, agentId, source, dateFrom, dateTo, limit: fetchLimit,
+          schema, tenantId, agentIds: resolvedAgentIds, source, dateFrom, dateTo, limit: fetchLimit, ftsConfig,
         }).catch(() => []),
         embeddingSearchSummaries(queryVec, {
-          agentId, source, dateFrom, dateTo, limit: fetchLimit,
+          agentIds: resolvedAgentIds, source, dateFrom, dateTo, limit: fetchLimit,
         }).catch(() => []),
         storage.searchTurnEmbeddings(pool, {
-          schema, tenantId, queryVec, dateFrom, dateTo, agentId, source, limit: fetchLimit,
+          schema, tenantId, queryVec, dateFrom, dateTo, agentIds: resolvedAgentIds, source, limit: fetchLimit,
         }).catch(() => ({ rows: [] })),
       ]);
 
@@ -691,15 +731,45 @@ function createAquifer(config) {
         [...filteredEmb, ...filterFn(externalRows)],
         filteredTurn,
         {
-          limit,
+          limit: rerankTopK,
           weights: mergedWeights,
           entityScoreBySession,
           openLoopSet,
         },
       );
 
+      // 6b. Rerank (optional)
+      let finalRanked = ranked;
+      if (rerankEnabled && ranked.length > 1) {
+        try {
+          const docs = ranked.map(r => buildRerankDocument(r, rerankMaxChars));
+          const rerankResult = await reranker.rerank(query, docs, { topN: ranked.length });
+          const scoreMap = new Map(rerankResult.map(r => [r.index, r.score]));
+
+          finalRanked = ranked.map((r, i) => ({
+            ...r,
+            _hybridScore: r._score,
+            _rerankScore: scoreMap.has(i) ? scoreMap.get(i) : null,
+          }));
+
+          finalRanked.sort((a, b) => {
+            const aR = a._rerankScore ?? -Infinity;
+            const bR = b._rerankScore ?? -Infinity;
+            if (aR !== bR) return bR - aR;
+            return (b._hybridScore || 0) - (a._hybridScore || 0);
+          });
+          finalRanked = finalRanked.slice(0, limit);
+        } catch (rerankErr) {
+          // Fallback: use original hybrid-rank order, flag in debug
+          if (process.env.AQUIFER_DEBUG) console.error('[aquifer] rerank error:', rerankErr.message);
+          finalRanked = ranked.slice(0, limit).map(r => ({ ...r, _rerankFallback: true }));
+        }
+      } else {
+        finalRanked = ranked.slice(0, limit);
+      }
+
       // 7. Record access
-      const sessionRowIds = ranked
+      const sessionRowIds = finalRanked
         .map(r => r.id || r.session_row_id)
         .filter(Boolean);
 
@@ -710,7 +780,7 @@ function createAquifer(config) {
       }
 
       // 8. Format results
-      return ranked.map(r => ({
+      return finalRanked.map(r => ({
         sessionId: r.session_id,
         agentId: r.agent_id,
         source: r.source,
@@ -720,7 +790,7 @@ function createAquifer(config) {
         summarySnippet: r.summary_snippet || null,
         matchedTurnText: r.matched_turn_text || null,
         matchedTurnIndex: r.matched_turn_index || null,
-        score: r._score,
+        score: r._rerankScore ?? r._score,
         trustScore: r._trustScore ?? 0.5,
         _debug: {
           rrf: r._rrf,
@@ -730,6 +800,9 @@ function createAquifer(config) {
           trustScore: r._trustScore,
           trustMultiplier: r._trustMultiplier,
           openLoopBoost: r._openLoopBoost,
+          hybridScore: r._hybridScore ?? r._score,
+          rerankScore: r._rerankScore ?? null,
+          rerankFallback: r._rerankFallback || false,
         },
       }));
     },

package/core/storage.js

@@ -331,12 +331,46 @@ async function searchSessions(pool, query, {
   schema,
   tenantId,
   agentId,
+  agentIds: rawAgentIds,
   source,
   dateFrom,  // m1: add date filtering
   dateTo,
   limit = 20,
+  ftsConfig = 'simple',
 } = {}) {
   const clampedLimit = Math.max(1, Math.min(100, limit));
+  // Sanitize ftsConfig to prevent SQL injection (must be a valid regconfig name)
+  const safeFts = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(ftsConfig) ? ftsConfig : 'simple';
+
+  // Normalize agentId/agentIds
+  const agentIds = rawAgentIds && rawAgentIds.length > 0
+    ? rawAgentIds
+    : (agentId ? [agentId] : null);
+
+  const where = [
+    `ss.search_tsv @@ plainto_tsquery('${safeFts}', $1)`,
+    `s.tenant_id = $2`,
+  ];
+  const params = [query, tenantId];
+
+  if (agentIds) {
+    params.push(agentIds);
+    where.push(`s.agent_id = ANY($${params.length})`);
+  }
+  if (source) {
+    params.push(source);
+    where.push(`s.source = $${params.length}`);
+  }
+  if (dateFrom) {
+    params.push(dateFrom);
+    where.push(`s.started_at::date >= $${params.length}::date`);
+  }
+  if (dateTo) {
+    params.push(dateTo);
+    where.push(`s.started_at::date <= $${params.length}::date`);
+  }
+  params.push(clampedLimit);
+
   const result = await pool.query(
     `SELECT
       s.id,
@@ -351,19 +385,14 @@ async function searchSessions(pool, query, {
       ss.access_count,
       ss.last_accessed_at,
       ss.trust_score,
-      ts_headline('simple', COALESCE(ss.summary_text, ''), plainto_tsquery('simple', $1)) AS summary_snippet,
-      ts_rank(ss.search_tsv, plainto_tsquery('simple', $1)) AS fts_rank
+      ts_headline('${safeFts}', COALESCE(ss.summary_text, ''), plainto_tsquery('${safeFts}', $1)) AS summary_snippet,
+      ts_rank(ss.search_tsv, plainto_tsquery('${safeFts}', $1)) AS fts_rank
     FROM ${qi(schema)}.sessions s
     LEFT JOIN ${qi(schema)}.session_summaries ss ON ss.session_row_id = s.id
-    WHERE ss.search_tsv @@ plainto_tsquery('simple', $1)
-      AND s.tenant_id = $2
-      AND ($3::text IS NULL OR s.agent_id = $3)
-      AND ($4::text IS NULL OR s.source = $4)
-      AND ($5::date IS NULL OR s.started_at::date >= $5::date)
-      AND ($6::date IS NULL OR s.started_at::date <= $6::date)
+    WHERE ${where.join(' AND ')}
     ORDER BY fts_rank DESC, s.last_message_at DESC NULLS LAST
-    LIMIT $7`,
-    [query, tenantId, agentId || null, source || null, dateFrom || null, dateTo || null, clampedLimit]
+    LIMIT $${params.length}`,
+    params
   );
   return result.rows;
 }
@@ -479,23 +508,29 @@ async function searchTurnEmbeddings(pool, {
   dateFrom,
   dateTo,
   agentId,
+  agentIds: rawAgentIds,
   source,
   limit = 15,
 }) {
   const where = ['s.tenant_id = $1'];
   const params = [tenantId];
 
+  // Normalize agentId/agentIds
+  const agentIds = rawAgentIds && rawAgentIds.length > 0
+    ? rawAgentIds
+    : (agentId ? [agentId] : null);
+
   if (dateFrom) {
     params.push(dateFrom);
-    where.push(`($${params.length}::date IS NULL OR s.started_at::date >= $${params.length}::date)`);
+    where.push(`s.started_at::date >= $${params.length}::date`);
   }
   if (dateTo) {
     params.push(dateTo);
-    where.push(`($${params.length}::date IS NULL OR s.started_at::date <= $${params.length}::date)`);
+    where.push(`s.started_at::date <= $${params.length}::date`);
   }
-  if (agentId) {
-    params.push(agentId);
-    where.push(`t.agent_id = $${params.length}`);
+  if (agentIds) {
+    params.push(agentIds);
+    where.push(`t.agent_id = ANY($${params.length})`);
   }
   if (source) {
     params.push(source);

package/index.js

@@ -2,5 +2,6 @@
 
 const { createAquifer } = require('./core/aquifer');
 const { createEmbedder } = require('./pipeline/embed');
+const { createReranker } = require('./pipeline/rerank');
 
-module.exports = { createAquifer, createEmbedder };
+module.exports = { createAquifer, createEmbedder, createReranker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "PG-native long-term memory for AI agents. Turn-level embedding, hybrid RRF ranking, optional knowledge graph. Includes CLI, MCP server, and OpenClaw plugin.",
   "main": "index.js",
   "files": [

package/pipeline/_http.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const http = require('http');
+const https = require('https');
+
+// ---------------------------------------------------------------------------
+// HTTP helpers (shared by embed.js and rerank.js)
+// ---------------------------------------------------------------------------
+
+function httpRequest(url, options, body) {
+  return new Promise((resolve, reject) => {
+    const parsedUrl = new URL(url);
+    const transport = parsedUrl.protocol === 'https:' ? https : http;
+
+    // M8 fix: settled flag to prevent double-settle on timeout race
+    let settled = false;
+    const finish = (fn, val) => { if (!settled) { settled = true; fn(val); } };
+
+    const req = transport.request(parsedUrl, options, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        if (timer) clearTimeout(timer);
+        const raw = Buffer.concat(chunks).toString();
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          finish(reject, new Error(`HTTP ${res.statusCode}: ${raw.slice(0, 500)}`));
+          return;
+        }
+        try {
+          finish(resolve, JSON.parse(raw));
+        } catch (e) {
+          finish(reject, new Error(`Invalid JSON response: ${raw.slice(0, 200)}`));
+        }
+      });
+    });
+
+    const timer = options.timeout
+      ? setTimeout(() => { req.destroy(); finish(reject, new Error('Request timeout')); }, options.timeout)
+      : null;
+
+    req.on('error', (err) => { if (timer) clearTimeout(timer); finish(reject, err); });
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Retry wrapper
+// ---------------------------------------------------------------------------
+
+async function withRetry(fn, { maxRetries = 3, initialBackoffMs = 2000 } = {}) {
+  let lastErr;
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (attempt < maxRetries - 1) {
+        const delay = initialBackoffMs * Math.pow(2, attempt);
+        await new Promise(r => setTimeout(r, delay));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+module.exports = { httpRequest, withRetry };

package/pipeline/embed.js

@@ -1,68 +1,6 @@
 'use strict';
 
-const http = require('http');
-const https = require('https');
-
-// ---------------------------------------------------------------------------
-// HTTP helpers
-// ---------------------------------------------------------------------------
-
-function httpRequest(url, options, body) {
-  return new Promise((resolve, reject) => {
-    const parsedUrl = new URL(url);
-    const transport = parsedUrl.protocol === 'https:' ? https : http;
-
-    // M8 fix: settled flag to prevent double-settle on timeout race
-    let settled = false;
-    const finish = (fn, val) => { if (!settled) { settled = true; fn(val); } };
-
-    const req = transport.request(parsedUrl, options, (res) => {
-      const chunks = [];
-      res.on('data', (chunk) => chunks.push(chunk));
-      res.on('end', () => {
-        if (timer) clearTimeout(timer);
-        const raw = Buffer.concat(chunks).toString();
-        if (res.statusCode < 200 || res.statusCode >= 300) {
-          finish(reject, new Error(`HTTP ${res.statusCode}: ${raw.slice(0, 500)}`));
-          return;
-        }
-        try {
-          finish(resolve, JSON.parse(raw));
-        } catch (e) {
-          finish(reject, new Error(`Invalid JSON response: ${raw.slice(0, 200)}`));
-        }
-      });
-    });
-
-    const timer = options.timeout
-      ? setTimeout(() => { req.destroy(); finish(reject, new Error('Request timeout')); }, options.timeout)
-      : null;
-
-    req.on('error', (err) => { if (timer) clearTimeout(timer); finish(reject, err); });
-    if (body) req.write(JSON.stringify(body));
-    req.end();
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Retry wrapper
-// ---------------------------------------------------------------------------
-
-async function withRetry(fn, { maxRetries = 3, initialBackoffMs = 2000 } = {}) {
-  let lastErr;
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (err) {
-      lastErr = err;
-      if (attempt < maxRetries - 1) {
-        const delay = initialBackoffMs * Math.pow(2, attempt);
-        await new Promise(r => setTimeout(r, delay));
-      }
-    }
-  }
-  throw lastErr;
-}
+const { httpRequest, withRetry } = require('./_http');
 
 // ---------------------------------------------------------------------------
 // Ollama adapter

package/pipeline/rerank.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const { httpRequest, withRetry } = require('./_http');
+
+// ---------------------------------------------------------------------------
+// Custom adapter
+// ---------------------------------------------------------------------------
+
+function validateResults(results) {
+  return results.filter(r =>
+    r && typeof r.index === 'number' && Number.isFinite(r.index)
+      && typeof r.score === 'number' && Number.isFinite(r.score)
+  );
+}
+
+function createCustomReranker(config) {
+  const fn = config.fn;
+  if (!fn) throw new Error('fn is required for custom reranker');
+
+  return {
+    async rerank(query, documents, opts = {}) {
+      if (!query || !documents || documents.length === 0) return [];
+      const topN = opts.topN || documents.length;
+      const results = await fn({ query, documents, topN });
+      if (!Array.isArray(results)) throw new Error('Custom reranker fn must return an array');
+      return validateResults(results).sort((a, b) => b.score - a.score);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// TEI adapter (HuggingFace Text Embeddings Inference)
+// ---------------------------------------------------------------------------
+
+function createTEIReranker(config) {
+  const baseUrl = (config.teiBaseUrl || config.baseUrl || 'http://localhost:8080').replace(/\/+$/, '');
+  const timeout = config.timeout || 2000;
+  const maxRetries = config.maxRetries ?? 1;
+  const initialBackoffMs = config.initialBackoffMs || 250;
+
+  return {
+    async rerank(query, documents, opts = {}) {
+      if (!query || !documents || documents.length === 0) return [];
+
+      const result = await withRetry(
+        () => httpRequest(`${baseUrl}/rerank`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          timeout,
+        }, { query, texts: documents, raw_scores: false }),
+        { maxRetries, initialBackoffMs },
+      );
+
+      // TEI returns array of { index, score }
+      const arr = Array.isArray(result) ? result : [];
+      return validateResults(arr.map(r => ({ index: r.index, score: r.score })))
+        .sort((a, b) => b.score - a.score);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Jina adapter
+// ---------------------------------------------------------------------------
+
+function createJinaReranker(config) {
+  const apiKey = config.jinaApiKey;
+  if (!apiKey) throw new Error('jinaApiKey is required for Jina reranker');
+
+  const model = config.jinaModel || 'jina-reranker-v2-base-multilingual';
+  const baseUrl = (config.jinaBaseUrl || 'https://api.jina.ai/v1/rerank').replace(/\/+$/, '');
+  const timeout = config.timeout || 2000;
+  const maxRetries = config.maxRetries ?? 1;
+  const initialBackoffMs = config.initialBackoffMs || 250;
+
+  return {
+    async rerank(query, documents, opts = {}) {
+      if (!query || !documents || documents.length === 0) return [];
+      const topN = opts.topN || documents.length;
+
+      const result = await withRetry(
+        () => httpRequest(baseUrl, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+          },
+          timeout,
+        }, { model, query, documents, top_n: topN }),
+        { maxRetries, initialBackoffMs },
+      );
+
+      // Jina returns { results: [{ index, relevance_score }] }
+      const arr = result.results || [];
+      return validateResults(arr.map(r => ({ index: r.index, score: r.relevance_score })))
+        .sort((a, b) => b.score - a.score);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// OpenRouter adapter (Cohere rerank etc. via OpenRouter)
+// ---------------------------------------------------------------------------
+
+function createOpenRouterReranker(config) {
+  const apiKey = config.openrouterApiKey || config.apiKey;
+  if (!apiKey) throw new Error('openrouterApiKey is required for OpenRouter reranker');
+
+  const model = config.model || 'cohere/rerank-v3.5';
+  const baseUrl = (config.openrouterBaseUrl || 'https://openrouter.ai/api/v1/rerank').replace(/\/+$/, '');
+  const timeout = config.timeout || 5000;
+  const maxRetries = config.maxRetries ?? 1;
+  const initialBackoffMs = config.initialBackoffMs || 250;
+
+  return {
+    async rerank(query, documents, opts = {}) {
+      if (!query || !documents || documents.length === 0) return [];
+      const topN = opts.topN || documents.length;
+
+      const result = await withRetry(
+        () => httpRequest(baseUrl, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+          },
+          timeout,
+        }, { model, query, documents, top_n: topN }),
+        { maxRetries, initialBackoffMs },
+      );
+
+      // OpenRouter returns { results: [{ index, relevance_score }] }
+      const arr = result.results || [];
+      return validateResults(arr.map(r => ({ index: r.index, score: r.relevance_score })))
+        .sort((a, b) => b.score - a.score);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+function createReranker(config = {}) {
+  const provider = config.provider || 'custom';
+
+  switch (provider) {
+    case 'custom':
+      return createCustomReranker(config);
+    case 'tei':
+      return createTEIReranker(config);
+    case 'jina':
+      return createJinaReranker(config);
+    case 'openrouter':
+      return createOpenRouterReranker(config);
+    default:
+      throw new Error(`Unknown rerank provider: ${provider}`);
+  }
+}
+
+module.exports = { createReranker };