You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e52fb02
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.md
+83-17Lines changed: 83 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,28 @@
1
1
# @corbits/reranking
2
2
3
-
Cross-encoder reranking for retrieval pipelines. Send a query plus candidates, get scored ids back in ranked order.
3
+
Cross-encoder reranking over Hugging Face Text Embeddings Inference (TEI), Cohere/Jina and Voyage rerank endpoints, built on `@intx/inference` retries and error classification. A retrieval building block for Corbits and Interchange agents that also works standalone.
4
4
5
-
Give `rerankDocuments` a query and your own `{id, text}` docs; it posts them to the reranker, maps the reply back to your ids, and returns `{id, score}` sorted descending.
5
+
## Why @corbits/reranking?
6
+
7
+
1.**One call for three wire formats.**`rerankDocuments` speaks TEI, Cohere (also Jina) and Voyage. Switching providers is a config change.
8
+
2.**Your ids back, sorted.** Providers score by array position. The client maps each score back to your `id` and returns `{ id, score }`, best first.
9
+
3.**Interchange retry semantics.** 429s and 5xx are retried under the `@intx/inference` retry policy, and every failure is a `RerankRequestError` carrying a classified `InferenceError`.
10
+
11
+
## Install
12
+
13
+
```bash
14
+
bun add @corbits/reranking @intx/inference@^0.4.0 @intx/types@^0.4.0
15
+
```
16
+
17
+
Runs on Bun >= 1.2 or Node >= 24.
6
18
7
19
## Quickstart
8
20
21
+
This example needs a local TEI reranker:
22
+
9
23
```bash
10
-
bun add @corbits/reranking
24
+
docker run -p 8080:80 ghcr.io/huggingface/text-embeddings-inference:cpu-latest \
25
+
--model-id BAAI/bge-reranker-base
11
26
```
12
27
13
28
```ts
@@ -23,24 +38,61 @@ const ranked = await rerankDocuments("What is the capital of France?", docs, {
Config takes `baseURL` and `apiStyle`, with optional `model` (required by Cohere and Voyage), `apiKey`, and `timeoutMs`. The optional fourth argument takes `deps` (defaults to global `fetch` and `createDefaultScheduler()`), `retryPolicy`, `registry`, and `signal`.
44
+
## Where it fits
45
+
46
+
[Interchange](https://github.com/faremeter/interchange) runs AI agents with their own identity and permissions. Corbits packages add the parts an agent product needs around it.
47
+
48
+
-**Runs in:** any process. That can be the Interchange hub (the server that manages tenants and agents), an agent sidecar (the runtime next to each agent), or a plain script. No hub is needed.
49
+
-**Plugs into:**[`@intx/inference`](https://github.com/faremeter/interchange) for retries and error types, and [`@intx/types`](https://github.com/faremeter/interchange).
50
+
-**Pairs with:**[`@corbits/embedding`](https://github.com/corbitsdev/corbits-embedding) to turn text into vectors, and [`@corbits/memory`](https://github.com/corbitsdev/corbits-memory) to store and search them.
Providers reply with positions into the request array, so each score maps back to your `id` through that index.
118
+
### Errors
119
+
120
+
- A failed request throws `RerankRequestError`. Its `reason` says what went wrong, and `url` says where. Network errors, timeouts, rate limits and server errors are retried first under the retry policy.
121
+
- A bad config throws arktype's `TraversalError` before any request is sent.
122
+
- With non-empty `docs`, a missing `model` for `cohere` or `voyage` throws `TraversalError`, and an `apiStyle` the registry does not know throws an `Error` that names it.
123
+
- A custom `parseResponse` should throw `ProtocolMismatchError` from `@intx/inference` so the failure becomes a `RerankRequestError`. Anything else it throws is rethrown as is.
124
+
125
+
An empty `docs` list returns `[]` without a request. To keep search working when the reranker is down, catch the error and keep your original order.
126
+
127
+
## Using with Interchange
67
128
68
-
## Errors
129
+
To share your host's retry scheduler, pass it as `options.deps.scheduler` along with `fetch`.
69
130
70
-
Failures throw `RerankRequestError` (`extends Error`), carrying the classified `InferenceError`from `@intx/inference` as `reason` and the request `url`. That covers transport failures, HTTP errors, and replies in the wrong shape; retryable errors are retried first under the `retryPolicy` option, which defaults to `createDefaultRetryPolicy()`. An invalid config throws arktype's `TraversalError` before any request is sent, as does a missing `model` for Cohere or Voyage once `docs` is non-empty (an empty `docs` returns `[]` without building a request); an `apiStyle` the registry does not know throws a plain `Error` naming it.
131
+
## Upgrading from 0.1
71
132
72
-
Fallback is left to the caller: catch the error and keep your own ordering if a reranker outage should not fail search.
133
+
- Install `@intx/inference` and `@intx/types` (^0.4.0) yourself. They are now peer dependencies.
134
+
-`ModelRequestError` is renamed to `RerankRequestError`.
135
+
-`rerankAdapters` is no longer exported. Use `rerankAdapterRegistry` or `createRerankAdapterRegistry`.
136
+
-`runJSONRequest`, `extractRetryAfterMs` and `RunRequestOptions` are no longer exported.
137
+
- A missing `model` for Cohere or Voyage now throws `TraversalError` instead of a plain `Error`.
138
+
- Config, wire requests and results are unchanged.
0 commit comments