@tanstack/ai-cohere 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/TanStack/ai/main/media/header_ai.png" alt="TanStack AI" />
+</div>
+
+<br />
+
+<div align="center">
+  <a href="https://npmjs.com/package/@tanstack/ai-cohere" target="_parent">
+    <img alt="NPM downloads" src="https://img.shields.io/npm/dm/@tanstack/ai-cohere.svg" />
+  </a>
+  <a href="https://github.com/TanStack/ai" target="_parent">
+    <img alt="GitHub stars" src="https://img.shields.io/github/stars/TanStack/ai.svg?style=social&label=Star" />
+  </a>
+</div>
+
+# @tanstack/ai-cohere
+
+Cohere adapter for [TanStack AI](https://tanstack.com/ai). Reorder candidate
+documents by relevance to a query with Cohere's rerank models — the precision
+step for RAG and search pipelines.
+
+This adapter is **rerank-only**. For chat, summarization, embeddings, or media,
+use OpenAI, Anthropic, or Gemini.
+
+## Install
+
+```bash
+pnpm add @tanstack/ai @tanstack/ai-cohere
+```
+
+## Usage
+
+```typescript
+import { rerank } from '@tanstack/ai'
+import { cohereRerank } from '@tanstack/ai-cohere'
+
+const { ranking, rerankedDocuments } = await rerank({
+  adapter: cohereRerank('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'
+```
+
+The adapter reads `COHERE_API_KEY` from the environment. To pass a key
+explicitly, use `createCohereRerank('rerank-v3.5', 'co-...')`.
+
+## <a href="https://tanstack.com/ai/latest/docs/rerank/rerank">Read the docs -></a>
+
+- [Reranking Guide](https://tanstack.com/ai/latest/docs/rerank/rerank) — object
+  documents, RAG pipelines, options, and the result shape.
+- [Cohere Adapter](https://tanstack.com/ai/latest/docs/adapters/cohere) —
+  models, configuration, and explicit API keys.

package/dist/esm/adapters/rerank.d.ts

@@ -0,0 +1,48 @@
+import { BaseRerankAdapter } from '@tanstack/ai/adapters';
+import { CohereClientConfig } from '../utils/client.js';
+import { CohereRerankModel, InferCohereRerankProviderOptions } from '../model-meta.js';
+import { RerankAdapterResult, RerankOptions } from '@tanstack/ai';
+/**
+ * Cohere rerank adapter.
+ *
+ * Talks to Cohere's `/v2/rerank` endpoint over raw `fetch` — no SDK. Returns
+ * scored indices into the submitted documents; the `rerank()` activity maps
+ * those back to the caller's original documents.
+ */
+export declare class CohereRerankAdapter<TModel extends CohereRerankModel> extends BaseRerankAdapter<TModel, InferCohereRerankProviderOptions<TModel>> {
+    readonly name: "cohere";
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(config: CohereClientConfig, model: TModel);
+    rerank(options: RerankOptions<InferCohereRerankProviderOptions<TModel>>): Promise<RerankAdapterResult>;
+}
+/**
+ * Creates a Cohere rerank adapter with an explicit API key. Type resolution
+ * (per-model provider options) happens here at the call site.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createCohereRerank('rerank-v3.5', 'co-...')
+ * ```
+ */
+export declare function createCohereRerank<TModel extends CohereRerankModel>(model: TModel, apiKey: string, config?: Omit<CohereClientConfig, 'apiKey'>): CohereRerankAdapter<TModel>;
+/**
+ * Creates a Cohere rerank adapter, reading `COHERE_API_KEY` from the
+ * environment.
+ *
+ * @throws Error if `COHERE_API_KEY` is not found.
+ *
+ * @example
+ * ```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', 'rainy afternoon'],
+ * })
+ * ```
+ */
+export declare function cohereRerank<TModel extends CohereRerankModel>(model: TModel, config?: Omit<CohereClientConfig, 'apiKey'>): CohereRerankAdapter<TModel>;

package/dist/esm/adapters/rerank.js

@@ -0,0 +1,126 @@
+import { getCohereApiKeyFromEnv } from "../utils/client.js";
+import { BaseRerankAdapter } from "@tanstack/ai/adapters";
+//#region src/adapters/rerank.ts
+function isCohereRerankResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const results = value.results;
+	return Array.isArray(results) && results.every((r) => typeof r === "object" && r !== null && typeof r.index === "number" && typeof r.relevance_score === "number");
+}
+/**
+* Cohere rerank adapter.
+*
+* Talks to Cohere's `/v2/rerank` endpoint over raw `fetch` — no SDK. Returns
+* scored indices into the submitted documents; the `rerank()` activity maps
+* those back to the caller's original documents.
+*/
+var CohereRerankAdapter = class extends BaseRerankAdapter {
+	name = "cohere";
+	apiKey;
+	baseUrl;
+	headers;
+	constructor(config, model) {
+		super({}, model);
+		this.apiKey = config.apiKey;
+		this.baseUrl = (config.baseUrl ?? "https://api.cohere.com").replace(/\/+$/, "");
+		this.headers = config.headers ?? {};
+	}
+	async rerank(options) {
+		const { model, query, documents, topN, modelOptions, abortSignal, logger } = options;
+		const body = {
+			model,
+			query,
+			documents
+		};
+		if (topN !== void 0) body["top_n"] = topN;
+		if (modelOptions?.maxTokensPerDoc !== void 0) body["max_tokens_per_doc"] = modelOptions.maxTokensPerDoc;
+		logger.request(`activity=rerank provider=${this.name} model=${model} documents=${documents.length}`, {
+			provider: this.name,
+			model
+		});
+		let response;
+		try {
+			response = await fetch(`${this.baseUrl}/v2/rerank`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.apiKey}`,
+					"Content-Type": "application/json",
+					...this.headers
+				},
+				body: JSON.stringify(body),
+				...abortSignal ? { signal: abortSignal } : {}
+			});
+		} catch (error) {
+			logger.errors(`${this.name}.rerank fatal`, {
+				error,
+				source: `${this.name}.rerank`
+			});
+			throw error;
+		}
+		if (!response.ok) {
+			const detail = await response.text().catch(() => "");
+			const error = /* @__PURE__ */ new Error(`Cohere rerank request failed: ${response.status} ${response.statusText}${detail ? ` — ${detail}` : ""}`);
+			logger.errors(`${this.name}.rerank fatal`, {
+				error,
+				source: `${this.name}.rerank`
+			});
+			throw error;
+		}
+		const json = await response.json();
+		if (!isCohereRerankResponse(json)) throw new Error("Cohere rerank response had an unexpected shape");
+		const searchUnits = json.meta?.billed_units?.search_units;
+		const usage = {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			...searchUnits !== void 0 ? { unitsBilled: searchUnits } : {}
+		};
+		return {
+			id: json.id ?? this.generateId(),
+			ranking: json.results.map((r) => ({
+				index: r.index,
+				score: r.relevance_score
+			})),
+			usage
+		};
+	}
+};
+/**
+* Creates a Cohere rerank adapter with an explicit API key. Type resolution
+* (per-model provider options) happens here at the call site.
+*
+* @example
+* ```typescript
+* const adapter = createCohereRerank('rerank-v3.5', 'co-...')
+* ```
+*/
+function createCohereRerank(model, apiKey, config) {
+	return new CohereRerankAdapter({
+		apiKey,
+		...config
+	}, model);
+}
+/**
+* Creates a Cohere rerank adapter, reading `COHERE_API_KEY` from the
+* environment.
+*
+* @throws Error if `COHERE_API_KEY` is not found.
+*
+* @example
+* ```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', 'rainy afternoon'],
+* })
+* ```
+*/
+function cohereRerank(model, config) {
+	return createCohereRerank(model, getCohereApiKeyFromEnv(), config);
+}
+//#endregion
+export { CohereRerankAdapter, cohereRerank, createCohereRerank };
+
+//# sourceMappingURL=rerank.js.map

package/dist/esm/adapters/rerank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.js","names":[],"sources":["../../../src/adapters/rerank.ts"],"sourcesContent":["import { BaseRerankAdapter } from '@tanstack/ai/adapters'\nimport {\n  COHERE_DEFAULT_BASE_URL,\n  getCohereApiKeyFromEnv,\n} from '../utils/client'\nimport type { CohereClientConfig } from '../utils/client'\nimport type {\n  CohereRerankModel,\n  InferCohereRerankProviderOptions,\n} from '../model-meta'\nimport type {\n  RerankAdapterResult,\n  RerankOptions,\n  TokenUsage,\n} from '@tanstack/ai'\n\n/** Shape of the Cohere `/v2/rerank` response we depend on. */\ninterface CohereRerankResponse {\n  id?: string\n  results: Array<{ index: number; relevance_score: number }>\n  meta?: { billed_units?: { search_units?: number } }\n}\n\nfunction isCohereRerankResponse(value: unknown): value is CohereRerankResponse {\n  if (typeof value !== 'object' || value === null) return false\n  const results = (value as { results?: unknown }).results\n  return (\n    Array.isArray(results) &&\n    results.every(\n      (r) =>\n        typeof r === 'object' &&\n        r !== null &&\n        typeof (r as { index?: unknown }).index === 'number' &&\n        typeof (r as { relevance_score?: unknown }).relevance_score ===\n          'number',\n    )\n  )\n}\n\n/**\n * Cohere rerank adapter.\n *\n * Talks to Cohere's `/v2/rerank` endpoint over raw `fetch` — no SDK. Returns\n * scored indices into the submitted documents; the `rerank()` activity maps\n * those back to the caller's original documents.\n */\nexport class CohereRerankAdapter<\n  TModel extends CohereRerankModel,\n> extends BaseRerankAdapter<TModel, InferCohereRerankProviderOptions<TModel>> {\n  readonly name = 'cohere' as const\n\n  private readonly apiKey: string\n  private readonly baseUrl: string\n  private readonly headers: Record<string, string>\n\n  constructor(config: CohereClientConfig, model: TModel) {\n    super({}, model)\n    this.apiKey = config.apiKey\n    this.baseUrl = (config.baseUrl ?? COHERE_DEFAULT_BASE_URL).replace(\n      /\\/+$/,\n      '',\n    )\n    this.headers = config.headers ?? {}\n  }\n\n  async rerank(\n    options: RerankOptions<InferCohereRerankProviderOptions<TModel>>,\n  ): Promise<RerankAdapterResult> {\n    const { model, query, documents, topN, modelOptions, abortSignal, logger } =\n      options\n\n    const body: Record<string, unknown> = { model, query, documents }\n    if (topN !== undefined) body['top_n'] = topN\n    if (modelOptions?.maxTokensPerDoc !== undefined) {\n      body['max_tokens_per_doc'] = modelOptions.maxTokensPerDoc\n    }\n\n    logger.request(\n      `activity=rerank provider=${this.name} model=${model} documents=${documents.length}`,\n      { provider: this.name, model },\n    )\n\n    let response: Response\n    try {\n      response = await fetch(`${this.baseUrl}/v2/rerank`, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n          ...this.headers,\n        },\n        body: JSON.stringify(body),\n        ...(abortSignal ? { signal: abortSignal } : {}),\n      })\n    } catch (error) {\n      logger.errors(`${this.name}.rerank fatal`, {\n        error,\n        source: `${this.name}.rerank`,\n      })\n      throw error\n    }\n\n    if (!response.ok) {\n      const detail = await response.text().catch(() => '')\n      const error = new Error(\n        `Cohere rerank request failed: ${response.status} ${response.statusText}${\n          detail ? ` — ${detail}` : ''\n        }`,\n      )\n      logger.errors(`${this.name}.rerank fatal`, {\n        error,\n        source: `${this.name}.rerank`,\n      })\n      throw error\n    }\n\n    const json: unknown = await response.json()\n    if (!isCohereRerankResponse(json)) {\n      throw new Error('Cohere rerank response had an unexpected shape')\n    }\n\n    const searchUnits = json.meta?.billed_units?.search_units\n    const usage: TokenUsage = {\n      promptTokens: 0,\n      completionTokens: 0,\n      totalTokens: 0,\n      ...(searchUnits !== undefined ? { unitsBilled: searchUnits } : {}),\n    }\n\n    return {\n      id: json.id ?? this.generateId(),\n      ranking: json.results.map((r) => ({\n        index: r.index,\n        score: r.relevance_score,\n      })),\n      usage,\n    }\n  }\n}\n\n/**\n * Creates a Cohere rerank adapter with an explicit API key. Type resolution\n * (per-model provider options) happens here at the call site.\n *\n * @example\n * ```typescript\n * const adapter = createCohereRerank('rerank-v3.5', 'co-...')\n * ```\n */\nexport function createCohereRerank<TModel extends CohereRerankModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<CohereClientConfig, 'apiKey'>,\n): CohereRerankAdapter<TModel> {\n  return new CohereRerankAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Cohere rerank adapter, reading `COHERE_API_KEY` from the\n * environment.\n *\n * @throws Error if `COHERE_API_KEY` is not found.\n *\n * @example\n * ```typescript\n * import { rerank } from '@tanstack/ai'\n * import { cohereRerank } from '@tanstack/ai-cohere'\n *\n * const { rerankedDocuments } = await rerank({\n *   adapter: cohereRerank('rerank-v3.5'),\n *   query: 'talk about rain',\n *   documents: ['sunny day', 'rainy afternoon'],\n * })\n * ```\n */\nexport function cohereRerank<TModel extends CohereRerankModel>(\n  model: TModel,\n  config?: Omit<CohereClientConfig, 'apiKey'>,\n): CohereRerankAdapter<TModel> {\n  return createCohereRerank(model, getCohereApiKeyFromEnv(), config)\n}\n"],"mappings":";;;AAuBA,SAAS,uBAAuB,OAA+C;CAC7E,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,UAAW,MAAgC;CACjD,OACE,MAAM,QAAQ,OAAO,KACrB,QAAQ,OACL,MACC,OAAO,MAAM,YACb,MAAM,QACN,OAAQ,EAA0B,UAAU,YAC5C,OAAQ,EAAoC,oBAC1C,QACN;AAEJ;;;;;;;;AASA,IAAa,sBAAb,cAEU,kBAAoE;CAC5E,OAAgB;CAEhB;CACA;CACA;CAEA,YAAY,QAA4B,OAAe;EACrD,MAAM,CAAC,GAAG,KAAK;EACf,KAAK,SAAS,OAAO;EACrB,KAAK,WAAW,OAAO,WAAA,yBAAA,CAAoC,QACzD,QACA,EACF;EACA,KAAK,UAAU,OAAO,WAAW,CAAC;CACpC;CAEA,MAAM,OACJ,SAC8B;EAC9B,MAAM,EAAE,OAAO,OAAO,WAAW,MAAM,cAAc,aAAa,WAChE;EAEF,MAAM,OAAgC;GAAE;GAAO;GAAO;EAAU;EAChE,IAAI,SAAS,KAAA,GAAW,KAAK,WAAW;EACxC,IAAI,cAAc,oBAAoB,KAAA,GACpC,KAAK,wBAAwB,aAAa;EAG5C,OAAO,QACL,4BAA4B,KAAK,KAAK,SAAS,MAAM,aAAa,UAAU,UAC5E;GAAE,UAAU,KAAK;GAAM;EAAM,CAC/B;EAEA,IAAI;EACJ,IAAI;GACF,WAAW,MAAM,MAAM,GAAG,KAAK,QAAQ,aAAa;IAClD,QAAQ;IACR,SAAS;KACP,eAAe,UAAU,KAAK;KAC9B,gBAAgB;KAChB,GAAG,KAAK;IACV;IACA,MAAM,KAAK,UAAU,IAAI;IACzB,GAAI,cAAc,EAAE,QAAQ,YAAY,IAAI,CAAC;GAC/C,CAAC;EACH,SAAS,OAAO;GACd,OAAO,OAAO,GAAG,KAAK,KAAK,gBAAgB;IACzC;IACA,QAAQ,GAAG,KAAK,KAAK;GACvB,CAAC;GACD,MAAM;EACR;EAEA,IAAI,CAAC,SAAS,IAAI;GAChB,MAAM,SAAS,MAAM,SAAS,KAAK,CAAC,CAAC,YAAY,EAAE;GACnD,MAAM,wBAAQ,IAAI,MAChB,iCAAiC,SAAS,OAAO,GAAG,SAAS,aAC3D,SAAS,MAAM,WAAW,IAE9B;GACA,OAAO,OAAO,GAAG,KAAK,KAAK,gBAAgB;IACzC;IACA,QAAQ,GAAG,KAAK,KAAK;GACvB,CAAC;GACD,MAAM;EACR;EAEA,MAAM,OAAgB,MAAM,SAAS,KAAK;EAC1C,IAAI,CAAC,uBAAuB,IAAI,GAC9B,MAAM,IAAI,MAAM,gDAAgD;EAGlE,MAAM,cAAc,KAAK,MAAM,cAAc;EAC7C,MAAM,QAAoB;GACxB,cAAc;GACd,kBAAkB;GAClB,aAAa;GACb,GAAI,gBAAgB,KAAA,IAAY,EAAE,aAAa,YAAY,IAAI,CAAC;EAClE;EAEA,OAAO;GACL,IAAI,KAAK,MAAM,KAAK,WAAW;GAC/B,SAAS,KAAK,QAAQ,KAAK,OAAO;IAChC,OAAO,EAAE;IACT,OAAO,EAAE;GACX,EAAE;GACF;EACF;CACF;AACF;;;;;;;;;;AAWA,SAAgB,mBACd,OACA,QACA,QAC6B;CAC7B,OAAO,IAAI,oBAAoB;EAAE;EAAQ,GAAG;CAAO,GAAG,KAAK;AAC7D;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,aACd,OACA,QAC6B;CAC7B,OAAO,mBAAmB,OAAO,uBAAuB,GAAG,MAAM;AACnE"}

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { CohereRerankAdapter, createCohereRerank, cohereRerank, } from './adapters/rerank.js';
+export { COHERE_RERANK_MODELS, type CohereRerankModel, type CohereRerankProviderOptions, type CohereRerankModelProviderOptionsByName, type InferCohereRerankProviderOptions, } from './model-meta.js';
+export type { CohereClientConfig } from './utils/client.js';

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+import { CohereRerankAdapter, cohereRerank, createCohereRerank } from "./adapters/rerank.js";
+import { COHERE_RERANK_MODELS } from "./model-meta.js";
+export { COHERE_RERANK_MODELS, CohereRerankAdapter, cohereRerank, createCohereRerank };

package/dist/esm/model-meta.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cohere rerank model metadata.
+ *
+ * Provider options are resolved per model at the `cohereRerank('model')` call
+ * site via {@link CohereRerankModelProviderOptionsByName}. Cohere's rerank
+ * models currently share the same options, but the per-model map keeps the
+ * surface symmetric with the other adapters and lets divergent options be
+ * expressed later without changing the adapter contract.
+ */
+/** Available Cohere rerank models. */
+export declare const COHERE_RERANK_MODELS: readonly ["rerank-v3.5", "rerank-english-v3.0", "rerank-multilingual-v3.0"];
+/** Union of supported Cohere rerank model names. */
+export type CohereRerankModel = (typeof COHERE_RERANK_MODELS)[number];
+/**
+ * Provider-specific options for a Cohere rerank request. Forwarded on the
+ * `modelOptions` field of `rerank()`.
+ */
+export interface CohereRerankProviderOptions {
+    /**
+     * Long documents are chunked to fit the model's context. This caps the
+     * number of tokens kept per document. Cohere defaults to 4096.
+     */
+    maxTokensPerDoc?: number;
+}
+/**
+ * Per-model provider-options map. Each model resolves to its own options type
+ * at the factory call site (see {@link InferCohereRerankProviderOptions}).
+ */
+export interface CohereRerankModelProviderOptionsByName {
+    'rerank-v3.5': CohereRerankProviderOptions;
+    'rerank-english-v3.0': CohereRerankProviderOptions;
+    'rerank-multilingual-v3.0': CohereRerankProviderOptions;
+}
+/**
+ * Resolve the provider options for a given rerank model. Falls back to the
+ * base options for any model not in the map.
+ */
+export type InferCohereRerankProviderOptions<TModel extends string> = TModel extends keyof CohereRerankModelProviderOptionsByName ? CohereRerankModelProviderOptionsByName[TModel] : CohereRerankProviderOptions;

package/dist/esm/model-meta.js

@@ -0,0 +1,20 @@
+//#region src/model-meta.ts
+/**
+* Cohere rerank model metadata.
+*
+* Provider options are resolved per model at the `cohereRerank('model')` call
+* site via {@link CohereRerankModelProviderOptionsByName}. Cohere's rerank
+* models currently share the same options, but the per-model map keeps the
+* surface symmetric with the other adapters and lets divergent options be
+* expressed later without changing the adapter contract.
+*/
+/** Available Cohere rerank models. */
+var COHERE_RERANK_MODELS = [
+	"rerank-v3.5",
+	"rerank-english-v3.0",
+	"rerank-multilingual-v3.0"
+];
+//#endregion
+export { COHERE_RERANK_MODELS };
+
+//# sourceMappingURL=model-meta.js.map

package/dist/esm/model-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-meta.js","names":[],"sources":["../../src/model-meta.ts"],"sourcesContent":["/**\n * Cohere rerank model metadata.\n *\n * Provider options are resolved per model at the `cohereRerank('model')` call\n * site via {@link CohereRerankModelProviderOptionsByName}. Cohere's rerank\n * models currently share the same options, but the per-model map keeps the\n * surface symmetric with the other adapters and lets divergent options be\n * expressed later without changing the adapter contract.\n */\n\n/** Available Cohere rerank models. */\nexport const COHERE_RERANK_MODELS = [\n  'rerank-v3.5',\n  'rerank-english-v3.0',\n  'rerank-multilingual-v3.0',\n] as const\n\n/** Union of supported Cohere rerank model names. */\nexport type CohereRerankModel = (typeof COHERE_RERANK_MODELS)[number]\n\n/**\n * Provider-specific options for a Cohere rerank request. Forwarded on the\n * `modelOptions` field of `rerank()`.\n */\nexport interface CohereRerankProviderOptions {\n  /**\n   * Long documents are chunked to fit the model's context. This caps the\n   * number of tokens kept per document. Cohere defaults to 4096.\n   */\n  maxTokensPerDoc?: number\n}\n\n/**\n * Per-model provider-options map. Each model resolves to its own options type\n * at the factory call site (see {@link InferCohereRerankProviderOptions}).\n */\nexport interface CohereRerankModelProviderOptionsByName {\n  'rerank-v3.5': CohereRerankProviderOptions\n  'rerank-english-v3.0': CohereRerankProviderOptions\n  'rerank-multilingual-v3.0': CohereRerankProviderOptions\n}\n\n/**\n * Resolve the provider options for a given rerank model. Falls back to the\n * base options for any model not in the map.\n */\nexport type InferCohereRerankProviderOptions<TModel extends string> =\n  TModel extends keyof CohereRerankModelProviderOptionsByName\n    ? CohereRerankModelProviderOptionsByName[TModel]\n    : CohereRerankProviderOptions\n"],"mappings":";;;;;;;;;;;AAWA,IAAa,uBAAuB;CAClC;CACA;CACA;AACF"}

package/dist/esm/utils/client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cohere client configuration shared by the rerank adapter.
+ */
+export interface CohereClientConfig {
+    /** Cohere API key. Required by the adapter factories. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to `https://api.cohere.com`. */
+    baseUrl?: string;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+}
+export declare const COHERE_DEFAULT_BASE_URL = "https://api.cohere.com";
+/**
+ * Reads the Cohere API key from the environment.
+ *
+ * Looks for `COHERE_API_KEY` in `process.env` (Node) or `window.env`
+ * (browser with injected env).
+ *
+ * @throws Error if `COHERE_API_KEY` is not found.
+ */
+export declare function getCohereApiKeyFromEnv(): string;

package/dist/esm/utils/client.js

@@ -0,0 +1,21 @@
+//#region src/utils/client.ts
+var COHERE_DEFAULT_BASE_URL = "https://api.cohere.com";
+/**
+* Reads the Cohere API key from the environment.
+*
+* Looks for `COHERE_API_KEY` in `process.env` (Node) or `window.env`
+* (browser with injected env).
+*
+* @throws Error if `COHERE_API_KEY` is not found.
+*/
+function getCohereApiKeyFromEnv() {
+	const windowEnv = typeof globalThis !== "undefined" && globalThis.window ? globalThis.window.env : void 0;
+	const processEnv = typeof process !== "undefined" ? process.env : void 0;
+	const key = windowEnv?.["COHERE_API_KEY"] ?? processEnv?.["COHERE_API_KEY"];
+	if (!key) throw new Error("COHERE_API_KEY not found in environment. Pass an API key explicitly via createCohereRerank(model, apiKey).");
+	return key;
+}
+//#endregion
+export { COHERE_DEFAULT_BASE_URL, getCohereApiKeyFromEnv };
+
+//# sourceMappingURL=client.js.map

package/dist/esm/utils/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/utils/client.ts"],"sourcesContent":["/**\n * Cohere client configuration shared by the rerank adapter.\n */\nexport interface CohereClientConfig {\n  /** Cohere API key. Required by the adapter factories. */\n  apiKey: string\n  /** Override the API base URL. Defaults to `https://api.cohere.com`. */\n  baseUrl?: string\n  /** Extra headers merged into every request. */\n  headers?: Record<string, string>\n}\n\nexport const COHERE_DEFAULT_BASE_URL = 'https://api.cohere.com'\n\n/**\n * Reads the Cohere API key from the environment.\n *\n * Looks for `COHERE_API_KEY` in `process.env` (Node) or `window.env`\n * (browser with injected env).\n *\n * @throws Error if `COHERE_API_KEY` is not found.\n */\nexport function getCohereApiKeyFromEnv(): string {\n  const windowEnv =\n    typeof globalThis !== 'undefined' &&\n    (globalThis as Record<string, unknown>).window\n      ? ((\n          (globalThis as Record<string, unknown>).window as Record<\n            string,\n            unknown\n          >\n        ).env as Record<string, string> | undefined)\n      : undefined\n  const processEnv = typeof process !== 'undefined' ? process.env : undefined\n  // Prefer an injected `window.env` (browser builds) but fall back to\n  // `process.env` — bundlers and Electron can populate it even when `window`\n  // exists.\n  const key = windowEnv?.['COHERE_API_KEY'] ?? processEnv?.['COHERE_API_KEY']\n  if (!key) {\n    throw new Error(\n      'COHERE_API_KEY not found in environment. Pass an API key explicitly via createCohereRerank(model, apiKey).',\n    )\n  }\n  return key\n}\n"],"mappings":";AAYA,IAAa,0BAA0B;;;;;;;;;AAUvC,SAAgB,yBAAiC;CAC/C,MAAM,YACJ,OAAO,eAAe,eACrB,WAAuC,SAEjC,WAAuC,OAIxC,MACF,KAAA;CACN,MAAM,aAAa,OAAO,YAAY,cAAc,QAAQ,MAAM,KAAA;CAIlE,MAAM,MAAM,YAAY,qBAAqB,aAAa;CAC1D,IAAI,CAAC,KACH,MAAM,IAAI,MACR,4GACF;CAEF,OAAO;AACT"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@tanstack/ai-cohere",
+  "version": "0.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Cohere adapter for TanStack AI — document reranking.",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-cohere"
+  },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "cohere",
+    "rerank",
+    "reranking",
+    "search",
+    "retrieval",
+    "adapter"
+  ],
+  "peerDependencies": {
+    "@tanstack/ai": "^0.43.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14",
+    "vite": "^8.1.4",
+    "@tanstack/ai": "0.43.1"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  }
+}

package/src/adapters/rerank.ts

@@ -0,0 +1,181 @@
+import { BaseRerankAdapter } from '@tanstack/ai/adapters'
+import {
+  COHERE_DEFAULT_BASE_URL,
+  getCohereApiKeyFromEnv,
+} from '../utils/client'
+import type { CohereClientConfig } from '../utils/client'
+import type {
+  CohereRerankModel,
+  InferCohereRerankProviderOptions,
+} from '../model-meta'
+import type {
+  RerankAdapterResult,
+  RerankOptions,
+  TokenUsage,
+} from '@tanstack/ai'
+
+/** Shape of the Cohere `/v2/rerank` response we depend on. */
+interface CohereRerankResponse {
+  id?: string
+  results: Array<{ index: number; relevance_score: number }>
+  meta?: { billed_units?: { search_units?: number } }
+}
+
+function isCohereRerankResponse(value: unknown): value is CohereRerankResponse {
+  if (typeof value !== 'object' || value === null) return false
+  const results = (value as { results?: unknown }).results
+  return (
+    Array.isArray(results) &&
+    results.every(
+      (r) =>
+        typeof r === 'object' &&
+        r !== null &&
+        typeof (r as { index?: unknown }).index === 'number' &&
+        typeof (r as { relevance_score?: unknown }).relevance_score ===
+          'number',
+    )
+  )
+}
+
+/**
+ * Cohere rerank adapter.
+ *
+ * Talks to Cohere's `/v2/rerank` endpoint over raw `fetch` — no SDK. Returns
+ * scored indices into the submitted documents; the `rerank()` activity maps
+ * those back to the caller's original documents.
+ */
+export class CohereRerankAdapter<
+  TModel extends CohereRerankModel,
+> extends BaseRerankAdapter<TModel, InferCohereRerankProviderOptions<TModel>> {
+  readonly name = 'cohere' as const
+
+  private readonly apiKey: string
+  private readonly baseUrl: string
+  private readonly headers: Record<string, string>
+
+  constructor(config: CohereClientConfig, model: TModel) {
+    super({}, model)
+    this.apiKey = config.apiKey
+    this.baseUrl = (config.baseUrl ?? COHERE_DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      '',
+    )
+    this.headers = config.headers ?? {}
+  }
+
+  async rerank(
+    options: RerankOptions<InferCohereRerankProviderOptions<TModel>>,
+  ): Promise<RerankAdapterResult> {
+    const { model, query, documents, topN, modelOptions, abortSignal, logger } =
+      options
+
+    const body: Record<string, unknown> = { model, query, documents }
+    if (topN !== undefined) body['top_n'] = topN
+    if (modelOptions?.maxTokensPerDoc !== undefined) {
+      body['max_tokens_per_doc'] = modelOptions.maxTokensPerDoc
+    }
+
+    logger.request(
+      `activity=rerank provider=${this.name} model=${model} documents=${documents.length}`,
+      { provider: this.name, model },
+    )
+
+    let response: Response
+    try {
+      response = await fetch(`${this.baseUrl}/v2/rerank`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+          ...this.headers,
+        },
+        body: JSON.stringify(body),
+        ...(abortSignal ? { signal: abortSignal } : {}),
+      })
+    } catch (error) {
+      logger.errors(`${this.name}.rerank fatal`, {
+        error,
+        source: `${this.name}.rerank`,
+      })
+      throw error
+    }
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '')
+      const error = new Error(
+        `Cohere rerank request failed: ${response.status} ${response.statusText}${
+          detail ? ` — ${detail}` : ''
+        }`,
+      )
+      logger.errors(`${this.name}.rerank fatal`, {
+        error,
+        source: `${this.name}.rerank`,
+      })
+      throw error
+    }
+
+    const json: unknown = await response.json()
+    if (!isCohereRerankResponse(json)) {
+      throw new Error('Cohere rerank response had an unexpected shape')
+    }
+
+    const searchUnits = json.meta?.billed_units?.search_units
+    const usage: TokenUsage = {
+      promptTokens: 0,
+      completionTokens: 0,
+      totalTokens: 0,
+      ...(searchUnits !== undefined ? { unitsBilled: searchUnits } : {}),
+    }
+
+    return {
+      id: json.id ?? this.generateId(),
+      ranking: json.results.map((r) => ({
+        index: r.index,
+        score: r.relevance_score,
+      })),
+      usage,
+    }
+  }
+}
+
+/**
+ * Creates a Cohere rerank adapter with an explicit API key. Type resolution
+ * (per-model provider options) happens here at the call site.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createCohereRerank('rerank-v3.5', 'co-...')
+ * ```
+ */
+export function createCohereRerank<TModel extends CohereRerankModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<CohereClientConfig, 'apiKey'>,
+): CohereRerankAdapter<TModel> {
+  return new CohereRerankAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * Creates a Cohere rerank adapter, reading `COHERE_API_KEY` from the
+ * environment.
+ *
+ * @throws Error if `COHERE_API_KEY` is not found.
+ *
+ * @example
+ * ```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', 'rainy afternoon'],
+ * })
+ * ```
+ */
+export function cohereRerank<TModel extends CohereRerankModel>(
+  model: TModel,
+  config?: Omit<CohereClientConfig, 'apiKey'>,
+): CohereRerankAdapter<TModel> {
+  return createCohereRerank(model, getCohereApiKeyFromEnv(), config)
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// ============================================================================
+// Cohere Adapters (tree-shakeable)
+// ============================================================================
+
+// Rerank adapter - document reranking via Cohere's /v2/rerank endpoint
+export {
+  CohereRerankAdapter,
+  createCohereRerank,
+  cohereRerank,
+} from './adapters/rerank'
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export {
+  COHERE_RERANK_MODELS,
+  type CohereRerankModel,
+  type CohereRerankProviderOptions,
+  type CohereRerankModelProviderOptionsByName,
+  type InferCohereRerankProviderOptions,
+} from './model-meta'
+
+export type { CohereClientConfig } from './utils/client'

package/src/model-meta.ts

@@ -0,0 +1,50 @@
+/**
+ * Cohere rerank model metadata.
+ *
+ * Provider options are resolved per model at the `cohereRerank('model')` call
+ * site via {@link CohereRerankModelProviderOptionsByName}. Cohere's rerank
+ * models currently share the same options, but the per-model map keeps the
+ * surface symmetric with the other adapters and lets divergent options be
+ * expressed later without changing the adapter contract.
+ */
+
+/** Available Cohere rerank models. */
+export const COHERE_RERANK_MODELS = [
+  'rerank-v3.5',
+  'rerank-english-v3.0',
+  'rerank-multilingual-v3.0',
+] as const
+
+/** Union of supported Cohere rerank model names. */
+export type CohereRerankModel = (typeof COHERE_RERANK_MODELS)[number]
+
+/**
+ * Provider-specific options for a Cohere rerank request. Forwarded on the
+ * `modelOptions` field of `rerank()`.
+ */
+export interface CohereRerankProviderOptions {
+  /**
+   * Long documents are chunked to fit the model's context. This caps the
+   * number of tokens kept per document. Cohere defaults to 4096.
+   */
+  maxTokensPerDoc?: number
+}
+
+/**
+ * Per-model provider-options map. Each model resolves to its own options type
+ * at the factory call site (see {@link InferCohereRerankProviderOptions}).
+ */
+export interface CohereRerankModelProviderOptionsByName {
+  'rerank-v3.5': CohereRerankProviderOptions
+  'rerank-english-v3.0': CohereRerankProviderOptions
+  'rerank-multilingual-v3.0': CohereRerankProviderOptions
+}
+
+/**
+ * Resolve the provider options for a given rerank model. Falls back to the
+ * base options for any model not in the map.
+ */
+export type InferCohereRerankProviderOptions<TModel extends string> =
+  TModel extends keyof CohereRerankModelProviderOptionsByName
+    ? CohereRerankModelProviderOptionsByName[TModel]
+    : CohereRerankProviderOptions

package/src/utils/client.ts

@@ -0,0 +1,45 @@
+/**
+ * Cohere client configuration shared by the rerank adapter.
+ */
+export interface CohereClientConfig {
+  /** Cohere API key. Required by the adapter factories. */
+  apiKey: string
+  /** Override the API base URL. Defaults to `https://api.cohere.com`. */
+  baseUrl?: string
+  /** Extra headers merged into every request. */
+  headers?: Record<string, string>
+}
+
+export const COHERE_DEFAULT_BASE_URL = 'https://api.cohere.com'
+
+/**
+ * Reads the Cohere API key from the environment.
+ *
+ * Looks for `COHERE_API_KEY` in `process.env` (Node) or `window.env`
+ * (browser with injected env).
+ *
+ * @throws Error if `COHERE_API_KEY` is not found.
+ */
+export function getCohereApiKeyFromEnv(): string {
+  const windowEnv =
+    typeof globalThis !== 'undefined' &&
+    (globalThis as Record<string, unknown>).window
+      ? ((
+          (globalThis as Record<string, unknown>).window as Record<
+            string,
+            unknown
+          >
+        ).env as Record<string, string> | undefined)
+      : undefined
+  const processEnv = typeof process !== 'undefined' ? process.env : undefined
+  // Prefer an injected `window.env` (browser builds) but fall back to
+  // `process.env` — bundlers and Electron can populate it even when `window`
+  // exists.
+  const key = windowEnv?.['COHERE_API_KEY'] ?? processEnv?.['COHERE_API_KEY']
+  if (!key) {
+    throw new Error(
+      'COHERE_API_KEY not found in environment. Pass an API key explicitly via createCohereRerank(model, apiKey).',
+    )
+  }
+  return key
+}