Cohere Rerank

View as Markdown

A RocketRide rerank node that reorders retrieved documents by relevance to the query using Cohere's Rerank API.

About Cohere

Cohere provides the Rerank API used by this node to score a query against a list of document strings. The node sends the configured model, query, document list, and requested result count to that API, then uses the returned relevance scores to construct RocketRide documents.

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.

---

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).

Profiles

Default: Rerank v3.0 (rerank-english-v3.0). The Model dropdown selects a preconfigured profile:

Profile	Title	Model
rerank-english-v3.0 (default)	Rerank v3.0	rerank-english-v3.0
rerank-v3.5	Rerank v3.5	rerank-v3.5
custom	Custom	(free-form model name)

All preset profiles expose top_n, min_score, and the API key; custom additionally takes a free-form model name.

Configuration

Select a preset for the supplied model name, or use Custom to enter a model name. Most tuning is the trade-off between how many candidates Cohere considers worth returning and how selective the local score filter should be.

Model

The named profiles provide their declared model values. Use Custom only when the API key is authorized for the name entered; the node rejects an empty or whitespace-only model before it can make a request.

Top N and Min Score

top_n determines how many results are requested from Cohere before local filtering. It must be an integer of at least 1; whole-number numeric values are accepted, while booleans and fractional values are rejected. Keep the default of 5 for a small candidate set, increase it when later pipeline stages need more alternatives, and lower it to limit the resulting context.

min_score is then applied to those returned results and must be between 0.0 and 1.0. The default 0.0 preserves all returned results. Raise it to remove weak matches, but expect fewer than top_n documents because the threshold is applied after Cohere's top-N result set has been returned.

---

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.

---

Notes

API failures

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

Wiring with a vector store

Reranking sits between the vector store and the LLM. The store enriches the question with its matches and emits it on the questions lane; this node reranks those documents and emits the reordered set on documents; the prompt and LLM then build their context from the reranked documents:

… → embedding → store ──questions──▶ rerank_cohere ──documents──▶ prompt → llm → response

To maximise quality, retrieve generously and rerank down: give the reranker more candidates than the store would return on its own, then keep a small top_n here (for example 5) for the final context. The store's default candidate pool on the data lane is 25, so the widening must go above that. Only the Chroma store (store_chroma) exposes a Top K field for this; set it comfortably above the default, for example 50. A value such as 20 is below the default and narrows retrieval instead of widening it. A complete, runnable pipeline is at examples/rag-rerank-pipeline.pipe.

Upstream docs

• Cohere Rerank API reference

---

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