feat: add rerank() activity with Cohere and OpenRouter adapters

.changeset/openrouter-rerank.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-openrouter': minor
+---
+
+feat: add `openRouterRerank` / `createOpenRouterRerank` rerank adapters
+
+Rerank documents by relevance to a query through OpenRouter's unified
+`/v1/rerank` endpoint (e.g. `cohere/rerank-v3.5`) with the `rerank()` activity.
+Reads `OPENROUTER_API_KEY` from the environment and forwards the optional
+`httpReferer` / `appTitle` attribution headers, consistent with the other
+OpenRouter adapters.

.changeset/rerank-cohere.md

@@ -0,0 +1,19 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-event-client': minor
+'@tanstack/ai-cohere': minor
+---
+
+feat: add `rerank()` activity for reordering documents by relevance to a query
+
+Adds a provider-agnostic `rerank()` activity (with `createRerankOptions`, the
+`RerankAdapter` interface, and `BaseRerankAdapter`). Documents may be strings
+or JSON-serializable objects — object documents are serialized for the
+provider and the original element is returned in the result, fully typed.
+Supports `topN`, per-request cancellation via `abortSignal`, and the standard
+observe-only `GenerationMiddleware` (`onStart`/`onUsage`/`onFinish`/`onAbort`/
+`onError`) plus `rerank:*` devtools events. Rerank bills in provider-defined
+search units, surfaced on `usage.unitsBilled`.
+
+The first adapter ships in the new `@tanstack/ai-cohere` package as
+`cohereRerank` / `createCohereRerank`.

docs/adapters/cohere.md

@@ -0,0 +1,132 @@
+---
+title: Cohere
+id: cohere-adapter
+order: 11
+description: "Rerank documents by relevance to a query with Cohere's rerank models in TanStack AI via the @tanstack/ai-cohere adapter."
+keywords:
+  - tanstack ai
+  - cohere
+  - rerank
+  - reranking
+  - relevance
+  - retrieval
+  - adapter
+---
+
+The Cohere adapter is **rerank-focused**. It exposes one capability:
+
+- **Reranking** (`cohereRerank`) — reorder documents by relevance to a query via `rerank()`.
+
+It does not support text `chat()`, `summarize()`, embeddings, or media — use
+OpenAI, Anthropic, or Gemini for those. The adapter talks to Cohere's
+`/v2/rerank` endpoint directly over `fetch` (no SDK dependency).
+
+## Installation
+
+```bash
+npm install @tanstack/ai-cohere
+```
+
+Peer dependency:
+
+```bash
+npm install @tanstack/ai
+```
+
+## Basic Usage
+
+```typescript
+import { rerank } from '@tanstack/ai'
+import { cohereRerank } from '@tanstack/ai-cohere'
+
+const { rerankedDocuments } = await rerank({
+  adapter: cohereRerank('rerank-v3.5'),
+  query: 'talk about rain',
+  documents: ['sunny day at the beach', 'rainy afternoon in the city'],
+})
+
+console.log(rerankedDocuments[0]) // 'rainy afternoon in the city'
+```
+
+For the full reranking guide — object documents, RAG pipelines, options, and
+the result shape — see [Reranking](../rerank/rerank).
+
+## Models
+
+| Model                      | Description                              |
+| -------------------------- | ---------------------------------------- |
+| `rerank-v3.5`              | Latest multilingual reranker (recommended) |
+| `rerank-english-v3.0`      | English-optimized reranker               |
+| `rerank-multilingual-v3.0` | Multilingual reranker                    |
+
+## Configuration
+
+`cohereRerank(model, config?)` reads `COHERE_API_KEY` from the environment.
+`config` accepts:
+
+| Option    | Type                       | Default                    | Description                          |
+| --------- | -------------------------- | -------------------------- | ------------------------------------ |
+| `baseUrl` | `string`                   | `https://api.cohere.com`   | Override the API base URL            |
+| `headers` | `Record<string, string>`  | —                          | Extra headers merged into requests   |
+
+### Provider Options
+
+Per-request options are passed via `modelOptions` on `rerank()`:
+
+```typescript
+import { rerank } from '@tanstack/ai'
+import { cohereRerank } from '@tanstack/ai-cohere'
+
+const { ranking } = await rerank({
+  adapter: cohereRerank('rerank-v3.5'),
+  query: 'refund policy',
+  documents: ['Returns accepted within 30 days.', 'Free shipping over $50.'],
+  modelOptions: {
+    maxTokensPerDoc: 512, // Cap tokens kept per document (Cohere default: 4096)
+  },
+})
+
+console.log(ranking)
+```
+
+## Explicit API Keys
+
+To pass an API key directly instead of reading the environment:
+
+```typescript
+import { createCohereRerank } from '@tanstack/ai-cohere'
+
+const adapter = createCohereRerank('rerank-v3.5', 'your-cohere-api-key')
+```
+
+## Environment Variables
+
+```bash
+COHERE_API_KEY=your-cohere-api-key
+```
+
+| Variable         | Required | Description         |
+| ---------------- | -------- | ------------------- |
+| `COHERE_API_KEY` | Yes      | Your Cohere API key |
+
+Get your API key from the [Cohere dashboard](https://dashboard.cohere.com/).
+
+## API Reference
+
+### `cohereRerank(model, config?)`
+
+Creates a Cohere rerank adapter for use with `rerank()`, reading
+`COHERE_API_KEY` from the environment.
+
+### `createCohereRerank(model, apiKey, config?)`
+
+Same as `cohereRerank`, but takes an explicit API key.
+
+## Limitations
+
+- **Rerank only** — Use OpenAI, Anthropic, or Gemini for `chat()`, `summarize()`, embeddings, or media generation.
+
+## Next Steps
+
+- [Reranking Guide](../rerank/rerank) — full walkthrough including RAG pipelines
+- [OpenAI Adapter](./openai) — text, embeddings, and media

docs/adapters/openrouter.md

@@ -247,10 +247,42 @@ fields are simply absent and the stream completes normally. Both
 `openRouterText` and `openRouterResponsesText` populate cost when OpenRouter
 returns it.
 
+## Reranking
+
+OpenRouter exposes rerank models through its unified `/v1/rerank` endpoint
+(served via the `@openrouter/sdk` SDK). Any rerank model OpenRouter offers works
+by passing its slug — for example `cohere/rerank-v3.5`, `cohere/rerank-4-fast`,
+`cohere/rerank-4-pro`, or `nvidia/llama-nemotron-rerank-vl-1b-v2`. Use
+`openRouterRerank` with the `rerank()` activity to reorder candidate documents
+by relevance to a query:
+
+```typescript
+import { rerank } from "@tanstack/ai";
+import { openRouterRerank } from "@tanstack/ai-openrouter";
+
+const { rerankedDocuments } = await rerank({
+  adapter: openRouterRerank("cohere/rerank-v3.5"),
+  query: "talk about rain",
+  documents: ["sunny day at the beach", "rainy afternoon in the city"],
+  topN: 2,
+});
+
+console.log(rerankedDocuments[0]); // 'rainy afternoon in the city'
+```
+
+`openRouterRerank` reads `OPENROUTER_API_KEY` from the environment; pass a key
+explicitly with `createOpenRouterRerank("cohere/rerank-v3.5", "sk-or-...")`. The
+optional `httpReferer` / `appTitle` config fields are forwarded as OpenRouter
+attribution headers, just like the chat adapter.
+
+See the [Reranking guide](../rerank/rerank) for object documents, RAG
+pipelines, options, and the result shape.
+
 ## Next Steps
 
 - [Getting Started](../getting-started/quick-start) - Learn the basics
 - [Tools Guide](../tools/tools) - Learn about tools
+- [Reranking](../rerank/rerank) - Reorder documents by relevance
 
 ## Provider Tools
 

docs/config.json

@@ -277,6 +277,16 @@
         }
       ]
     },
+    {
+      "label": "Reranking",
+      "children": [
+        {
+          "label": "Reranking",
+          "to": "rerank/rerank",
+          "addedAt": "2026-06-25"
+        }
+      ]
+    },
     {
       "label": "Middleware",
       "children": [
@@ -461,13 +471,19 @@
         {
           "label": "OpenRouter Adapter",
           "to": "adapters/openrouter",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-06-25"
         },
         {
           "label": "OpenAI-Compatible",
           "to": "adapters/openai-compatible",
           "addedAt": "2026-06-01",
           "updatedAt": "2026-06-20"
+        },
+        {
+          "label": "Cohere",
+          "to": "adapters/cohere",
+          "addedAt": "2026-06-25"
         }
       ]
     },