memorix 1.7.2 → 1.7.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codebuddy/memorix/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Local-first project memory for CodeBuddy Code and other coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.7.2",
+  "version": "1.7.3",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.7.2",
+      "version": "1.7.3",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/commands/config-migrate.ts

@@ -69,6 +69,13 @@ export function serializeResolvedConfigToToml(
     dimensions: config.embedding.dimensions,
   });
 
+  writeSection(lines, 'rerank', {
+    provider: config.rerank.provider,
+    model: config.rerank.model,
+    base_url: config.rerank.baseUrl,
+    api_key: includeSecrets ? config.rerank.apiKey : undefined,
+  });
+
   writeSection(lines, 'memory', {
     inject: config.memory.inject,
     formation: config.memory.formation,

package/src/cli/commands/doctor.ts

@@ -517,7 +517,11 @@ export default defineCommand({
       if (isLLMEnabled()) {
         const config = getLLMConfig();
         lines.push(ok(`Provider: ${config?.provider}/${config?.model}`));
-        lines.push(info('Capabilities: fact extraction, auto-dedup, LLM rerank'));
+        const { isNeuralRerankEnabled } = await import('../../rerank/index.js');
+        const rerankCap = isNeuralRerankEnabled()
+          ? 'HTTP rerank'
+          : 'LLM rerank';
+        lines.push(info(`Capabilities: fact extraction, auto-dedup, ${rerankCap}`));
         report.llm = { enabled: true, provider: config?.provider, model: config?.model };
       } else {
         lines.push(info('LLM mode: off (heuristic dedup only)'));

package/src/cli/commands/init.ts

@@ -183,6 +183,12 @@ export default defineCommand({
       envLines.push('');
     }
 
+    envLines.push('# Optional HTTP rerank (Cohere-compatible POST {base_url}/rerank)');
+    envLines.push('# MEMORIX_RERANK_PROVIDER=http');
+    envLines.push('# MEMORIX_RERANK_MODEL=rerank-model');
+    envLines.push('# MEMORIX_RERANK_BASE_URL=https://api.example.com/v1');
+    envLines.push('# MEMORIX_RERANK_API_KEY=  # required when BASE_URL is not the memory LLM endpoint');
+    envLines.push('');
     envLines.push('# Optional memory LLM simple key (does not apply to embedding or agent lanes)');
     envLines.push('# MEMORIX_API_KEY=sk-your-key-here');
     envLines.push('');
@@ -310,6 +316,17 @@ export function buildInitTomlConfig(options: {
   }
   lines.push('');
 
+  lines.push('[rerank]');
+  lines.push('# Optional HTTP rerank against any Cohere-compatible /rerank API.');
+  lines.push('# provider = "http"');
+  lines.push('# model = "rerank-model"');
+  lines.push('# base_url inherits [memory.llm] when unset.');
+  if (isGlobal) {
+    lines.push('# Bearer inherits the memory LLM key only when that endpoint matches.');
+    lines.push('# A different rerank URL needs MEMORIX_RERANK_API_KEY.');
+  }
+  lines.push('');
+
   lines.push('[git]');
   lines.push(`auto_hook = ${options.gitAutoHook}`);
   lines.push('ingest_on_commit = true');

package/src/cli/commands/status.ts

@@ -104,6 +104,7 @@ export default defineCommand({
       diagLines.push(`  Agent lane:      ${formatLane(agent.provider, agent.model, agent.baseUrl, agent.apiKey)}`);
       diagLines.push(`  Memory LLM lane: ${formatLane(resolved.memory.llm.provider, resolved.memory.llm.model, resolved.memory.llm.baseUrl, resolved.memory.llm.apiKey)}`);
       diagLines.push(`  Embedding lane:  ${formatLane(resolved.embedding.provider, resolved.embedding.model, resolved.embedding.baseUrl, resolved.embedding.apiKey)}`);
+      diagLines.push(`  Rerank lane:     ${formatLane(resolved.rerank.provider, resolved.rerank.model, resolved.rerank.baseUrl, resolved.rerank.apiKey)}`);
       diagLines.push(`  Memory behavior: inject=${resolved.memory.inject ?? 'default'}, formation=${resolved.memory.formation ?? 'default'}, autoCleanup=${resolved.memory.autoCleanup ?? 'default'}`);
       diagLines.push(`  Git behavior:    autoHook=${resolved.git.autoHook ?? 'default'}, ingestOnCommit=${resolved.git.ingestOnCommit ?? 'default'}, maxDiffSize=${resolved.git.maxDiffSize ?? 'default'}, skipMergeCommits=${resolved.git.skipMergeCommits ?? 'default'}`);
       diagLines.push(`  Server:          transport=${resolved.server.transport ?? 'default'}, dashboard=${resolved.server.dashboard ?? 'default'}, dashboardPort=${resolved.server.dashboardPort ?? 'default'}`);
@@ -141,6 +142,7 @@ export default defineCommand({
           agent: summarizeLane(agent.provider, agent.model, agent.baseUrl, agent.apiKey),
           memoryLlm: summarizeLane(resolved.memory.llm.provider, resolved.memory.llm.model, resolved.memory.llm.baseUrl, resolved.memory.llm.apiKey),
           embedding: summarizeLane(resolved.embedding.provider, resolved.embedding.model, resolved.embedding.baseUrl, resolved.embedding.apiKey),
+          rerank: summarizeLane(resolved.rerank.provider, resolved.rerank.model, resolved.rerank.baseUrl, resolved.rerank.apiKey),
         },
         memory: {
           inject: resolved.memory.inject ?? 'default',

package/src/config/resolved-config.ts

@@ -9,8 +9,8 @@ import {
   getProjectYamlPath,
 } from './config-paths.js';
 import { loadFileConfig } from './legacy-loader.js';
-import { loadTomlConfig } from './toml-loader.js';
-import { loadYamlConfig } from './yaml-loader.js';
+import { loadTomlConfig, type MemorixTomlConfig } from './toml-loader.js';
+import { loadYamlConfig, type MemorixYamlConfig } from './yaml-loader.js';
 import { loadDotenv } from './dotenv-loader.js';
 
 export interface ResolvedLaneOptions {
@@ -44,6 +44,14 @@ export interface ResolvedMemorixConfig {
     apiKey?: string;
     dimensions?: number;
   };
+  rerank: {
+    provider: 'off' | 'http';
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    /** False when a Memory LLM key exists and the rerank URL is a different host without a dedicated key. */
+    canSendRequest: boolean;
+  };
   git: {
     autoHook?: boolean;
     ingestOnCommit?: boolean;
@@ -109,6 +117,16 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
   const openRouterMemoryLlmApiKey = isOpenRouterMemoryLane(memoryLlmProvider, memoryLlmBaseUrl)
     ? process.env.OPENROUTER_API_KEY
     : undefined;
+  const memoryLlmApiKey = first(
+    process.env.MEMORIX_LLM_API_KEY,
+    process.env.MEMORIX_API_KEY,
+    toml.memory?.llm?.api_key,
+    yaml.llm?.apiKey,
+    legacy.llm?.apiKey,
+    process.env.OPENAI_API_KEY,
+    process.env.ANTHROPIC_API_KEY,
+    openRouterMemoryLlmApiKey,
+  );
 
   const resolved: ResolvedMemorixConfig = {
     agent: {
@@ -150,16 +168,7 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
         provider: memoryLlmProvider,
         model: memoryLlmModel,
         baseUrl: memoryLlmBaseUrl,
-        apiKey: first(
-          process.env.MEMORIX_LLM_API_KEY,
-          process.env.MEMORIX_API_KEY,
-          toml.memory?.llm?.api_key,
-          yaml.llm?.apiKey,
-          legacy.llm?.apiKey,
-          process.env.OPENAI_API_KEY,
-          process.env.ANTHROPIC_API_KEY,
-          openRouterMemoryLlmApiKey,
-        ),
+        apiKey: memoryLlmApiKey,
       },
     },
     embedding: {
@@ -169,6 +178,12 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
       apiKey: first(process.env.MEMORIX_EMBEDDING_API_KEY, toml.embedding?.api_key, yaml.embedding?.apiKey, legacy.embeddingApi?.apiKey, openRouterEmbeddingApiKey),
       dimensions: firstNumber(parseNumber(process.env.MEMORIX_EMBEDDING_DIMENSIONS), toml.embedding?.dimensions, yaml.embedding?.dimensions, legacy.embeddingApi?.dimensions),
     },
+    rerank: resolveRerankLane({
+      toml,
+      yaml,
+      memoryLlmApiKey,
+      memoryLlmBaseUrl,
+    }),
     git: {
       autoHook: firstBool(toml.git?.auto_hook, yaml.git?.autoHook),
       ingestOnCommit: firstBool(toml.git?.ingest_on_commit, yaml.git?.ingestOnCommit),
@@ -244,6 +259,10 @@ export function getResolvedEmbeddingLane(options: ResolvedLaneOptions = {}): Res
   return getResolvedConfig(options).embedding;
 }
 
+export function getResolvedRerankLane(options: ResolvedLaneOptions = {}): ResolvedMemorixConfig['rerank'] {
+  return getResolvedConfig(options).rerank;
+}
+
 export function resetResolvedConfigCache(): void {
   // Kept as a public test helper. File-level caches live in individual loaders.
 }
@@ -294,6 +313,10 @@ function getEnvSourceNames(): string[] {
     'MEMORIX_EMBEDDING_BASE_URL',
     'MEMORIX_EMBEDDING_MODEL',
     'MEMORIX_EMBEDDING_DIMENSIONS',
+    'MEMORIX_RERANK_PROVIDER',
+    'MEMORIX_RERANK_MODEL',
+    'MEMORIX_RERANK_BASE_URL',
+    'MEMORIX_RERANK_API_KEY',
     'MEMORIX_CODEGRAPH_EXTERNAL_CONTEXT',
     'MEMORIX_CODEGRAPH_EXTERNAL_COMMAND',
     'MEMORIX_CODEGRAPH_EXTERNAL_TIMEOUT_MS',
@@ -320,3 +343,78 @@ function normalizeExternalContext(value: string | undefined): 'auto' | 'off' | u
   if (normalized === 'auto' || normalized === 'off') return normalized;
   return undefined;
 }
+
+function normalizeRerankProvider(value: string | undefined): 'off' | 'http' {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === 'http') return 'http';
+  return 'off';
+}
+
+function resolveRerankLane(args: {
+  toml: MemorixTomlConfig;
+  yaml: MemorixYamlConfig;
+  memoryLlmApiKey?: string;
+  memoryLlmBaseUrl?: string;
+}): ResolvedMemorixConfig['rerank'] {
+  const provider = normalizeRerankProvider(first(
+    process.env.MEMORIX_RERANK_PROVIDER,
+    args.toml.rerank?.provider,
+    args.yaml.rerank?.provider,
+    'off',
+  ));
+  const model = first(
+    process.env.MEMORIX_RERANK_MODEL,
+    args.toml.rerank?.model,
+    args.yaml.rerank?.model,
+  );
+  const explicitBaseUrl = first(
+    process.env.MEMORIX_RERANK_BASE_URL,
+    args.toml.rerank?.base_url,
+    args.yaml.rerank?.baseUrl,
+  );
+  const baseUrl = provider === 'http'
+    ? first(explicitBaseUrl, args.memoryLlmBaseUrl)
+    : explicitBaseUrl;
+  const dedicatedApiKey = first(
+    process.env.MEMORIX_RERANK_API_KEY,
+    args.toml.rerank?.api_key,
+    args.yaml.rerank?.apiKey,
+  );
+  const sameEndpoint = provider === 'http' && sameTrustedEndpoint(baseUrl, args.memoryLlmBaseUrl);
+  const inheritedApiKey = sameEndpoint ? args.memoryLlmApiKey : undefined;
+  const apiKey = first(dedicatedApiKey, inheritedApiKey);
+  const canSendRequest = provider === 'http' && Boolean(baseUrl)
+    && (Boolean(apiKey) || !args.memoryLlmApiKey || sameEndpoint);
+
+  return { provider, model, baseUrl, apiKey, canSendRequest };
+}
+
+/**
+ * True when two API roots are the same host+path after trailing-slash
+ * and optional `/rerank` normalization. Used so a Memory LLM bearer is
+ * never sent to a different rerank provider.
+ */
+function sameTrustedEndpoint(left?: string, right?: string): boolean {
+  const a = normalizeTrustedEndpoint(left);
+  const b = normalizeTrustedEndpoint(right);
+  return Boolean(a && b && a === b);
+}
+
+function normalizeTrustedEndpoint(value?: string): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  try {
+    const url = new URL(trimmed);
+    const protocol = url.protocol.toLowerCase();
+    const hostname = url.hostname.toLowerCase();
+    const port = url.port;
+    let pathname = url.pathname.replace(/\/+$/, '');
+    if (pathname.toLowerCase().endsWith('/rerank')) {
+      pathname = pathname.slice(0, -'/rerank'.length).replace(/\/+$/, '');
+    }
+    return `${protocol}//${hostname}${port ? `:${port}` : ''}${pathname}`;
+  } catch {
+    const fallback = trimmed.replace(/\/+$/, '').replace(/\/rerank$/i, '').replace(/\/+$/, '');
+    return fallback.toLowerCase() || undefined;
+  }
+}

package/src/config/toml-loader.ts

@@ -28,6 +28,13 @@ export interface MemorixTomlConfig {
     api_key?: string;
     dimensions?: number;
   };
+  /** Optional HTTP rerank against a compatible /rerank API. */
+  rerank?: {
+    provider?: 'off' | 'http' | string;
+    model?: string;
+    base_url?: string;
+    api_key?: string;
+  };
   hooks?: {
     native_memcode?: boolean;
     external_agents?: boolean;
@@ -97,6 +104,7 @@ function mergeTomlConfig(base: MemorixTomlConfig, override: MemorixTomlConfig):
       llm: { ...base.memory?.llm, ...override.memory?.llm },
     },
     embedding: { ...base.embedding, ...override.embedding },
+    rerank: { ...base.rerank, ...override.rerank },
     hooks: { ...base.hooks, ...override.hooks },
     git: { ...base.git, ...override.git },
     codegraph: { ...base.codegraph, ...override.codegraph },

package/src/config/yaml-loader.ts

@@ -48,6 +48,14 @@ export interface MemorixYamlConfig {
     dimensions?: number;
   };
 
+  /** Remote neural rerank (HTTP only) */
+  rerank?: {
+    provider?: 'off' | 'http' | string;
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+  };
+
   /** Git-Memory pipeline configuration */
   git?: {
     /** Auto-install post-commit hook on first run (default: false) */
@@ -190,6 +198,7 @@ export function loadYamlConfig(projectRoot?: string | null): MemorixYamlConfig {
     llm: { ...userConfig.llm, ...projectConfig.llm },
     agent: { ...userConfig.agent, ...projectConfig.agent },
     embedding: { ...userConfig.embedding, ...projectConfig.embedding },
+    rerank: { ...userConfig.rerank, ...projectConfig.rerank },
     git: { ...userConfig.git, ...projectConfig.git },
     codegraph: { ...userConfig.codegraph, ...projectConfig.codegraph },
     behavior: { ...userConfig.behavior, ...projectConfig.behavior },

package/src/llm/provider.ts

@@ -31,6 +31,36 @@ const LLM_TIMEOUT_MIN_MS = 1_000;
 const LLM_TIMEOUT_MAX_MS = 300_000;
 const MAX_LLM_RESPONSE_BYTES = 2 * 1024 * 1024;
 
+const OPENAI_API_VERSION_SEGMENT = /^v\d+(?:[a-z][a-z0-9-]*)?$/i;
+
+/**
+ * Normalize an OpenAI-compatible API root without rewriting an explicit
+ * provider version such as `/api/v3` or `/v1beta`.
+ *
+ * Bare hosts keep the historical convenience of receiving `/v1`. Once a
+ * caller supplies a versioned path, that path is authoritative.
+ */
+export function normalizeOpenAICompatibleBaseUrl(baseUrl: string): string {
+  const base = baseUrl.trim().replace(/\/+$/, '');
+  if (!base) return base;
+
+  let pathname = '';
+  try {
+    pathname = new URL(base).pathname.replace(/\/+$/, '');
+  } catch {
+    pathname = base.split(/[?#]/, 1)[0].replace(/\/+$/, '');
+  }
+
+  const lastSegment = pathname.split('/').filter(Boolean).at(-1);
+  if (lastSegment && OPENAI_API_VERSION_SEGMENT.test(lastSegment)) {
+    return base;
+  }
+
+  const queryOrHash = base.match(/[?#].*$/)?.[0] ?? '';
+  const pathWithoutQuery = base.slice(0, base.length - queryOrHash.length).replace(/\/+$/, '');
+  return `${pathWithoutQuery}/v1${queryOrHash}`;
+}
+
 /**
  * Parse and validate MEMORIX_LLM_TIMEOUT_MS environment variable.
  * - Must be a valid integer in the range 1000–300000ms.
@@ -259,9 +289,7 @@ async function callOpenAICompatible(
   signal?: AbortSignal,
 ): Promise<LLMResponse> {
   const config = currentConfig!;
-  // Auto-fix: append /v1 if baseUrl doesn't end with it (common user mistake)
-  let base = config.baseUrl!.replace(/\/+$/, '');
-  if (!base.endsWith('/v1')) base += '/v1';
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl!);
   const url = `${base}/chat/completions`;
 
   const fetchSignal = signal
@@ -387,8 +415,7 @@ async function callOpenAIWithTools(
   signal?: AbortSignal,
 ): Promise<LLMToolResponse> {
   const config = currentConfig!;
-  let base = config.baseUrl!.replace(/\/+$/, '');
-  if (!base.endsWith('/v1')) base += '/v1';
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl!);
   const url = `${base}/chat/completions`;
 
   // Convert ChatMessage[] to OpenAI format
@@ -603,8 +630,7 @@ async function* callOpenAIWithToolsStream(
   tools: ToolDefinition[],
 ): AsyncGenerator<LLMStreamEvent, void, undefined> {
   const config = currentConfig!;
-  let base = config.baseUrl!.replace(/\/+$/, '');
-  if (!base.endsWith('/v1')) base += '/v1';
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl!);
   const url = `${base}/chat/completions`;
 
   const openaiMessages: Array<Record<string, unknown>> = messages.map((msg) => {

package/src/multimodal/image-loader.ts

@@ -6,7 +6,11 @@
  */
 
 import { getLLMApiKey, getLLMBaseUrl, getLLMModel } from '../config.js';
-import { isLLMEnabled, getLLMConfig } from '../llm/provider.js';
+import {
+  isLLMEnabled,
+  getLLMConfig,
+  normalizeOpenAICompatibleBaseUrl,
+} from '../llm/provider.js';
 import { sanitizeCredentials } from '../memory/secret-filter.js';
 import {
   decodeBase64ImagePayload,
@@ -55,8 +59,7 @@ async function callVisionLLM(
     throw new Error('No LLM API key configured for image analysis.');
   }
 
-  let baseUrl = getLLMBaseUrl('https://api.openai.com/v1').replace(/\/+$/, '');
-  if (!baseUrl.endsWith('/v1')) baseUrl += '/v1';
+  const baseUrl = normalizeOpenAICompatibleBaseUrl(getLLMBaseUrl('https://api.openai.com/v1'));
   const model = getLLMModel('gpt-4o');
 
   const response = await fetch(`${baseUrl}/chat/completions`, {

package/src/rerank/http-provider.ts

@@ -0,0 +1,125 @@
+/**
+ * Optional HTTP rerank client.
+ *
+ * Posts a Cohere-compatible `{model, query, documents}` body to
+ * `{base_url}/rerank` (or an explicit `/rerank` path). Compatible with
+ * any `/rerank` endpoint that accepts that body. The model id is
+ * whatever the user configured — Memorix does not rewrite it.
+ */
+
+import { resolveRerankTimeoutMs } from './policy.js';
+
+export type NeuralRerankProviderName = 'http';
+
+export interface NeuralRerankRequestConfig {
+  provider: NeuralRerankProviderName;
+  model?: string;
+  baseUrl: string;
+  apiKey?: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+export interface RerankedDocument {
+  index: number;
+  score: number;
+}
+
+/**
+ * Join a provider base URL with `/rerank`, leaving an explicit path intact.
+ */
+export function buildRerankUrl(baseUrl: string): string {
+  const trimmed = baseUrl.trim().replace(/\/+$/, '');
+  if (trimmed.endsWith('/rerank')) return trimmed;
+  return `${trimmed}/rerank`;
+}
+
+/**
+ * Accept Cohere-compatible `{results:[{index,relevance_score}]}` and TEI `[{index,score}]`.
+ */
+export function parseRerankResponse(payload: unknown): RerankedDocument[] {
+  const rows = extractRows(payload);
+  if (rows.length === 0) {
+    throw new Error('Neural rerank response contained no ranked results');
+  }
+  return rows.sort((a, b) => b.score - a.score);
+}
+
+function extractRows(payload: unknown): RerankedDocument[] {
+  if (Array.isArray(payload)) {
+    return payload.map(rowFromUnknown).filter((row): row is RerankedDocument => row !== null);
+  }
+  if (payload && typeof payload === 'object' && 'results' in payload) {
+    const results = (payload as { results: unknown }).results;
+    if (Array.isArray(results)) {
+      return results.map(rowFromUnknown).filter((row): row is RerankedDocument => row !== null);
+    }
+  }
+  throw new Error('Neural rerank response was not Cohere or TEI shaped');
+}
+
+function rowFromUnknown(value: unknown): RerankedDocument | null {
+  if (!value || typeof value !== 'object') return null;
+  const row = value as { index?: unknown; relevance_score?: unknown; score?: unknown };
+  if (typeof row.index !== 'number' || !Number.isFinite(row.index)) return null;
+  const score = typeof row.relevance_score === 'number'
+    ? row.relevance_score
+    : typeof row.score === 'number'
+      ? row.score
+      : null;
+  if (score === null || !Number.isFinite(score)) return null;
+  return { index: row.index, score };
+}
+
+function buildRerankBody(query: string, documents: string[], model?: string): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    query,
+    documents,
+    top_n: documents.length,
+    return_documents: false,
+  };
+  const trimmed = model?.trim();
+  if (trimmed) body.model = trimmed;
+  return body;
+}
+
+/**
+ * POST query + documents to a compatible `/rerank` endpoint and return ranked indexes.
+ */
+export async function rerankViaHttp(
+  query: string,
+  documents: string[],
+  config: NeuralRerankRequestConfig,
+): Promise<RerankedDocument[]> {
+  if (documents.length === 0) return [];
+
+  const url = buildRerankUrl(config.baseUrl);
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+  };
+  if (config.apiKey) {
+    headers.authorization = `Bearer ${config.apiKey}`;
+  }
+
+  const controller = new AbortController();
+  const timeoutMs = resolveRerankTimeoutMs(config.timeoutMs);
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers,
+      signal: controller.signal,
+      body: JSON.stringify(buildRerankBody(query, documents, config.model)),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Neural rerank HTTP ${response.status} from ${url}`);
+    }
+
+    return parseRerankResponse(await response.json());
+  } finally {
+    clearTimeout(timer);
+  }
+}