# rerank_cohere
A RocketRide rerank node that reorders retrieved documents by relevance to the query using Cohere's Rerank API.
## What it does
Takes questions that already carry retrieved documents and reorders those documents by how well they match the query. Cohere scores each document, results are sorted by relevance, cut to the top N, and anything below the minimum score threshold is dropped. Put it downstream of a retrieval or vector-store node so it can rerank the documents attached to each question.
Uses the **cohere** Python SDK (`ClientV2`). Supports the `rerank-english-v3.0` (default) and `rerank-v3.5` models, or any custom model name.
Key behavior to know:
- The incoming question is **deep-copied** before processing, so shared question objects in fan-out pipelines are never mutated.
- The query text is taken from the question's **first** question entry; a missing or whitespace-only query raises an error.
- Documents whose `page_content` is missing, non-string, or whitespace-only are **silently skipped** (Cohere rejects whitespace-only documents). If no usable document content remains, the node raises an error.
- Reranked documents preserve the original document `metadata`; the `score` field is replaced with Cohere's `relevance_score`.
- The `min_score` filter is applied **after** the top-N cut, so you can receive fewer than `top_n` results.
- Config validation only checks presence and format of required fields. It does **not** make a live API call, so a Cohere outage or rate limit at config time cannot surface a misleading error.
---
## Configuration
### Lanes
| Lane in | Lane out | Description |
|-------------|-------------|-----------------------------------------------|
| `questions` | `documents` | Reranked documents ordered by relevance score |
| `questions` | `answers` | An answer with the reranked documents |
The `documents` lane is written only when at least one document survives the `min_score` filter. The `answers` lane is **always** written, so downstream nodes receive a result even when every document was filtered out: the answer text is the surviving documents' content joined by blank lines (empty string if none survived).
### Fields
| Field | Type | Description |
|---|---|---|
| `model` | string | Default "rerank-english-v3.0". Cohere rerank model name |
| `top_n` | number | Number of top results to return |
| `min_score` | number | Minimum relevance score threshold (0.0-1.0) |
| `profile` | string | Default "rerank-english-v3.0". Rerank model |
`top_n` must be a whole number >= 1 (whole-number floats like `5.0` are accepted; booleans and fractional values are rejected). `min_score` must be a number between 0.0 and 1.0.
### Profiles
The **Model** dropdown selects a preconfigured profile:
| Profile | Title | Model |
|-----------------------|-------------|---------------------------------|
| `rerank-english-v3.0` | Rerank v3.0 | `rerank-english-v3.0` (default) |
| `rerank-v3.5` | Rerank v3.5 | `rerank-v3.5` |
| `custom` | Custom | free-form `model` field |
All profiles expose `top_n`, `min_score`, and the API key. The Custom profile additionally exposes the `model` field.
---
## Authentication
A Cohere API key is required. Set it in the node's **API Key** field. The node fails to initialize (with a warning) if the key is missing or blank.
The built-in pipeline test cases require the `ROCKETRIDE_RERANK_COHERE_KEY` environment variable to run against the live API.
---
## Error handling
Cohere API errors are mapped to a custom exception hierarchy whose class names let retry/circuit-breaker heuristics classify them correctly:
| Cohere error | Raised as | Retryable |
|------------------------|-----------------------------|-----------|
| `UnauthorizedError` | `RerankAuthenticationError` | No |
| `BadRequestError` | `RerankBadRequestError` | No |
| `TooManyRequestsError` | `RerankRateLimitError` | Yes |
| `InternalServerError` | `RerankServerError` | Yes |
| Any other exception | `RerankServerError` | Yes |
---
## Schema
| Field | Type | Description | Default |
|---|---|---|---|
| `min_score` | `number` | **Min Score** Minimum relevance score threshold (0.0-1.0) | |
| `model` | `string` | **Model** Cohere rerank model name | `"rerank-english-v3.0"` |
| `rerank_cohere.profile` | `string` | **Model** Rerank model | `"rerank-english-v3.0"` |
| `top_n` | `number` | **Top N** Number of top results to return | |
## Dependencies
- `cohere` `>=6.1.0,<7.0.0`
## Source
[ View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/rerank_cohere)