Initial commit: rerank client on the Interchange inference primitives

`rerankDocuments` posts a query and candidate set to a reranker, maps the reply
back to caller-supplied document ids, and returns {id, score} sorted descending.

Three wire formats, because reranking has no OpenAI-compatible standard and is
not converging on one — TEI does not serve an OpenAI-shaped rerank route at all
(huggingface/text-embeddings-inference#683):

  tei      /rerank      {query, texts}      -> [{index, score}]
  cohere   /v2/rerank   {query, documents}  -> {results: [{index, relevance_score}]}
  voyage   /v1/rerank   {query, documents}  -> {data: [{index, relevance_score}]}

Jina's /rerank uses Cohere's shape and is served by that adapter. This is a real
adapter boundary rather than a knob, which is the opposite conclusion from
@corbits/embedding — there, every provider serves one /v1/embeddings shape and
only the parameters differ. Cohere and Voyage require a model and fail by name
at request-build time rather than as a 400 in production; TEI serves whatever
model it was started with.

Scores are mapped through docs[index], never by reply position. Every protocol
addresses documents by their offset in the request array and TEI's reply is
explicitly unordered, so trusting position would attach the top score to the
wrong document. An out-of-range index raises. RerankDoc.id exists for this
reason: the wire formats only speak in offsets, so translating back to a stable
identifier belongs here rather than in every caller.

Built on @intx/inference rather than reimplementing it. Requests are
BuiltRequests sent through the single deps.fetch path; deps.scheduler drives
elapsed time and backoff so virtual-clock tests run the retry loop with no wall
time; failures classify through the shared taxonomy, including a 200 whose body
is not JSON (classifyProtocolMismatch), which a local model server behind a
proxy will produce; createDefaultRetryPolicy decides back-off vs abort, and an
abort mid-delay wakes immediately as the harness documents. The client this
replaces had no retry at all.

RerankAdapter mirrors ProviderAdapter — same buildRequest/parseResponse members,
same optional extractRetryAfterMs. Styles resolve through a Map-backed registry
mirroring createAdapterRegistry, so an apiStyle from config cannot reach an
inherited Object.prototype member and fail later as an opaque TypeError. deps is
Pick<Dependencies, "fetch" | "scheduler">: callers should not have to assemble a
registry of inference providers in order to rerank a list.

Failures raise rather than degrading soft. A reranker outage should be a policy
decision at the call site — a retrieval pipeline usually wants to fall back to
fused ordering — and it cannot make that choice if the failure is hidden here.

Naming follows the published @intX surface rather than assumption: baseURL (used
18 times upstream, baseUrl zero), uppercase acronyms in type names, lowercase
leading acronym in apiKey/apiStyle to match upstream's own apiKey.

Tests: 21 pass. Typecheck, prettier and build clean, all four gated in CI. The
index-mapping and retry paths were regression-verified by reintroducing each bug
and confirming the tests fail.

Refs CL-4539, CL-4549, CL-4550

Claude-Session: https://claude.ai/code/session_017GTgGzn5xAwvkU2GAPAHpF

Author: TheGreatAxios

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bunx tsc --noEmit
+      - run: bun test ./src
+      - run: bunx prettier --check src
+      - run: bun run build

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.tsbuildinfo

.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false
+}

LICENSE

@@ -0,0 +1,96 @@
+# @corbits/reranking
+
+Cross-encoder rerank client. Given a query and a candidate set, `rerankDocuments`
+posts them to a reranker, maps the reply back to your own document ids, and
+returns `{id, score}` sorted descending.
+
+Unlike embeddings, reranking has **no OpenAI-compatible standard** and is not
+converging on one — TEI does not serve an OpenAI-shaped rerank route at all
+([text-embeddings-inference#683](https://github.com/huggingface/text-embeddings-inference/issues/683)).
+So this is a real adapter boundary, not a knob:
+
+| `apiStyle` | endpoint     | request              | response                                |
+| ---------- | ------------ | -------------------- | --------------------------------------- |
+| `tei`      | `/rerank`    | `{query, texts}`     | `[{index, score}]`                      |
+| `cohere`   | `/v2/rerank` | `{query, documents}` | `{results: [{index, relevance_score}]}` |
+| `voyage`   | `/v1/rerank` | `{query, documents}` | `{data: [{index, relevance_score}]}`    |
+
+Jina's `/rerank` uses Cohere's shape and is served by the `cohere` adapter.
+
+Transport, error classification and retry come from `@intx/inference` rather
+than being reimplemented: requests are `BuiltRequest`s sent through the single
+`deps.fetch` path, failures become an `InferenceError` through the same
+classifiers a chat call uses, and `createDefaultRetryPolicy` decides whether to
+back off or abort.
+
+`RerankAdapter` deliberately mirrors inference's `ProviderAdapter` — same
+`buildRequest` / `parseResponse` members, same optional `extractRetryAfterMs`
+for a provider that signals pacing its own way. Styles resolve through
+`createRerankAdapterRegistry`, which closes over a private `Map` copy so an
+`apiStyle` arriving from config or an environment variable cannot reach an
+inherited member of `Object.prototype` and fail later as an opaque `TypeError`.
+Pass your own `registry` to add a house format without forking the package.
+
+```ts
+import { createDefaultScheduler } from "@intx/inference";
+import { rerankDocuments } from "@corbits/reranking";
+
+// Only `fetch` and `scheduler` are needed — a full harness `Dependencies`
+// also satisfies this if you already have one.
+const deps = { fetch, scheduler: createDefaultScheduler() };
+
+const ranked = await rerankDocuments(
+  "how do I deploy to staging?",
+  [
+    { id: "doc-1", text: "Staging deploys run from main…" },
+    { id: "doc-2", text: "On-call rotation is weekly…" },
+  ],
+  { baseURL: "http://localhost:8085", apiStyle: "tei" },
+  { deps },
+);
+```
+
+## Scores are mapped by index, never by position
+
+Every one of these protocols addresses documents by their position in the
+_request_ array, and TEI's reply is explicitly unordered. Results are therefore
+mapped back through `docs[index]`, and an out-of-range index raises rather than
+silently attaching a score to the wrong document.
+
+`RerankDoc.id` exists for this reason: the wire formats only speak in array
+offsets, so translating back to a stable identifier is this package's job rather
+than the caller's.
+
+## Degrading soft is the caller's decision
+
+This package raises on failure. It does not swallow errors, because a reranker
+outage should be a policy decision at the call site — a retrieval pipeline
+typically wants to fall back to its fused ordering and carry on, which it cannot
+do if the failure is hidden here.
+
+## Errors
+
+Every failure — transport, HTTP status, or a 200 whose body is not JSON —
+raises `ModelRequestError`, carrying the classified `InferenceError` as `reason`
+and the URL.
+
+Note that `@corbits/embedding` and `@corbits/reranking` each carry their own
+copy of this class until the shared transport is upstreamed, so `instanceof`
+does not hold across the two. Catching both? Discriminate on
+`error.name === "ModelRequestError"`.
+
+## Versioning
+
+Semver. Released manually with `bun run build && npm publish` once CI is green.
+
+## Development
+
+```bash
+bun install
+bun test ./src
+bunx tsc --noEmit
+```
+
+## License
+
+LGPL-2.1-only — see [`LICENSE`](LICENSE).

README.md

@@ -0,0 +1,44 @@
+{
+  "name": "@corbits/reranking",
+  "description": "Cross-encoder rerank client with TEI, Cohere/Jina and Voyage adapters, built on the Interchange inference primitives",
+  "version": "0.1.0",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "intx-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test ./src",
+    "format": "prettier -w ."
+  },
+  "dependencies": {
+    "@intx/inference": "0.2.2",
+    "@intx/log": "0.2.2",
+    "@intx/types": "0.2.2",
+    "arktype": "^2.1.29"
+  },
+  "devDependencies": {
+    "@intx/inference-testing": "0.2.2",
+    "@types/bun": "1.3.9",
+    "prettier": "3.6.2",
+    "typescript": "5.9.3"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/corbitsdev/corbits-reranking.git"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}