@tanstack/ai-cohere 0.0.0 → 0.1.1

package/README.md

@@ -15,12 +15,11 @@
 
 # @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.
+Cohere adapter for [TanStack AI](https://tanstack.com/ai). It gives you two
+things: multimodal embeddings with `embed-v4.0`, and document reranking 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.
+For chat, summarization, or media, use OpenAI, Anthropic, or Gemini.
 
 ## Install
 
@@ -28,8 +27,63 @@ use OpenAI, Anthropic, or Gemini.
 pnpm add @tanstack/ai @tanstack/ai-cohere
 ```
 
+## Setup
+
+Get your API key from the [Cohere Dashboard](https://dashboard.cohere.com/api-keys) and set it as an environment variable:
+
+```bash
+export COHERE_API_KEY="..."
+```
+
 ## Usage
 
+### Embedding Adapter
+
+```typescript
+import { cohereEmbedding } from '@tanstack/ai-cohere'
+import { embed } from '@tanstack/ai'
+
+const adapter = cohereEmbedding('embed-v4.0')
+
+const result = await embed({
+  adapter,
+  input: ['a red guitar', 'a blue drum kit'],
+  modelOptions: { inputType: 'search_document' },
+})
+
+console.log(result.embeddings[0].vector)
+```
+
+### Multimodal Inputs
+
+embed-v4.0 embeds text, images, and fused text+image items (one vector per input item). Fuse parts by nesting them in an array — the outer array is the item list:
+
+```typescript
+const result = await embed({
+  adapter,
+  input: [
+    'a red guitar',
+    {
+      type: 'image',
+      source: { type: 'data', value: base64Png, mimeType: 'image/png' },
+    },
+    // A nested array fuses its parts into a single vector.
+    [
+      { type: 'text', content: 'product photo' },
+      {
+        type: 'image',
+        source: { type: 'data', value: base64Jpeg, mimeType: 'image/jpeg' },
+      },
+    ],
+  ],
+  modelOptions: { inputType: 'search_document' },
+})
+```
+
+Cohere does not fetch remote image URLs. Pass base64 data or a `data:` URI, or enable `allowUrlFetch` in the adapter config to have the adapter download http(s) URLs and inline them.
+
+### Rerank Adapter
+
 ```typescript
 import { rerank } from '@tanstack/ai'
 import { cohereRerank } from '@tanstack/ai-cohere'
@@ -44,12 +98,57 @@ const { ranking, rerankedDocuments } = await rerank({
 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-...')`.
+### With Explicit API Key
+
+Both adapters read `COHERE_API_KEY` from the environment. To pass a key
+explicitly, use the `create*` factories:
+
+```typescript
+import { createCohereEmbedding, createCohereRerank } from '@tanstack/ai-cohere'
+
+const embedAdapter = createCohereEmbedding(
+  'embed-v4.0',
+  process.env.COHERE_API_KEY!,
+)
+const rerankAdapter = createCohereRerank('rerank-v3.5', 'co-...')
+```
+
+## Supported Models
+
+### Embedding Models
+
+- `embed-v4.0` - Multimodal embedding model (text + images, Matryoshka dimensions via the top-level `dimensions` option)
+
+### Rerank Models
 
-## <a href="https://tanstack.com/ai/latest/docs/rerank/rerank">Read the docs -></a>
+- `rerank-v3.5`
+- `rerank-english-v3.0`
+- `rerank-multilingual-v3.0`
+
+## Features
+
+- ✅ Embeddings (batch, one request per input array)
+- ✅ Multimodal embedding input (text + images + fused text/image items)
+- ✅ Dimension reduction (`dimensions` → Cohere `output_dimension`)
+- ✅ Document reranking
+- ❌ Chat / text generation
+- ❌ Image generation
+
+## Tree-Shakeable Adapters
+
+This package uses tree-shakeable adapters, so you only import what you need:
+
+```typescript
+import { cohereEmbedding, cohereRerank } from '@tanstack/ai-cohere'
+```
+
+## <a href="https://tanstack.com/ai/latest/docs/adapters/cohere">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.
+
+## License
+
+MIT

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

@@ -0,0 +1,86 @@
+import { BaseEmbeddingAdapter } from '@tanstack/ai/adapters';
+import { EmbeddingOptions, EmbeddingResult, ImagePart } from '@tanstack/ai';
+import { CohereEmbeddingModel, CohereEmbeddingModelInputModalitiesByName, CohereEmbeddingModelProviderOptionsByName } from '../model-meta.js';
+import { CohereEmbeddingProviderOptions } from '../embedding/embedding-provider-options.js';
+import { CohereClientConfig } from '../utils/client.js';
+/**
+ * Configuration for Cohere embedding adapter.
+ */
+export interface CohereEmbeddingConfig extends CohereClientConfig {
+}
+/**
+ * Cohere Embedding Adapter
+ *
+ * Tree-shakeable adapter for Cohere multimodal embeddings (embed-v4.0),
+ * implemented with plain `fetch` against the v2/embed endpoint — no Cohere
+ * SDK dependency.
+ *
+ * Features:
+ * - Batch embedding (one request for the whole input array)
+ * - Multimodal inputs: text, images, and fused text+image items (one vector
+ *   per input item)
+ * - Matryoshka dimension reduction via the top-level `dimensions` option
+ *   (mapped to Cohere's `output_dimension`)
+ */
+export declare class CohereEmbeddingAdapter<TModel extends CohereEmbeddingModel> extends BaseEmbeddingAdapter<TModel, CohereEmbeddingProviderOptions, CohereEmbeddingModelProviderOptionsByName, CohereEmbeddingModelInputModalitiesByName> {
+    readonly name: "cohere";
+    protected clientConfig: CohereEmbeddingConfig;
+    constructor(config: CohereEmbeddingConfig, model: TModel);
+    createEmbeddings(options: EmbeddingOptions<CohereEmbeddingProviderOptions>): Promise<EmbeddingResult>;
+    /**
+     * Resolves an image part to a URL Cohere accepts. Cohere does not fetch
+     * remote image URLs, so everything is normalized to a `data:` URI unless
+     * the caller already provided one.
+     */
+    protected resolveImageUrl(image: ImagePart): Promise<string>;
+}
+/**
+ * Creates a Cohere embedding adapter with explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @param model - The model name (e.g., 'embed-v4.0')
+ * @param apiKey - Your Cohere API key
+ * @param config - Optional additional configuration
+ * @returns Configured Cohere embedding adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createCohereEmbedding('embed-v4.0', 'api_key');
+ *
+ * const result = await embed({
+ *   adapter,
+ *   input: 'a red guitar',
+ *   modelOptions: { inputType: 'search_document' }
+ * });
+ * ```
+ */
+export declare function createCohereEmbedding<TModel extends CohereEmbeddingModel>(model: TModel, apiKey: string, config?: Omit<CohereEmbeddingConfig, 'apiKey'>): CohereEmbeddingAdapter<TModel>;
+/**
+ * Creates a Cohere embedding adapter using the `COHERE_API_KEY` environment variable.
+ * Type resolution happens here at the call site.
+ *
+ * Looks for `COHERE_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @param model - The model name (e.g., 'embed-v4.0')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Cohere embedding adapter instance with resolved types
+ * @throws Error if COHERE_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses COHERE_API_KEY from environment
+ * const adapter = cohereEmbedding('embed-v4.0');
+ *
+ * const result = await embed({
+ *   adapter,
+ *   input: ['a red guitar', 'a blue drum kit'],
+ *   modelOptions: { inputType: 'search_query' },
+ *   dimensions: 1024
+ * });
+ *
+ * console.log(result.embeddings[0].vector)
+ * ```
+ */
+export declare function cohereEmbedding<TModel extends CohereEmbeddingModel>(model: TModel, config?: Omit<CohereEmbeddingConfig, 'apiKey'>): CohereEmbeddingAdapter<TModel>;

package/dist/esm/adapters/embedding.js

@@ -0,0 +1,210 @@
+import { getCohereApiKeyFromEnv } from "../utils/client.js";
+import { BaseEmbeddingAdapter } from "@tanstack/ai/adapters";
+import { toRunErrorPayload } from "@tanstack/ai/adapter-internals";
+import { arrayBufferToBase64, generateId } from "@tanstack/ai-utils";
+import { resolveEmbeddingInput } from "@tanstack/ai";
+//#region src/adapters/embedding.ts
+var DEFAULT_BASE_URL = "https://api.cohere.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* Returns true when `url` is malformed, non-http(s), or targets a private /
+* loopback / link-local host. Used to block SSRF via `allowUrlFetch`.
+*/
+function isPrivateOrInternalUrl(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return true;
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return true;
+	const host = parsed.hostname.toLowerCase();
+	if (host === "localhost" || host.endsWith(".localhost") || host === "::1" || host === "[::1]" || host.startsWith("127.") || host.startsWith("10.") || host.startsWith("192.168.") || host.startsWith("169.254.") || /^172\.(1[6-9]|2\d|3[01])\./.test(host)) return true;
+	return false;
+}
+async function fetchWithTimeout(url, init, timeoutMs) {
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetch(url, {
+			...init,
+			signal: controller.signal
+		});
+	} finally {
+		clearTimeout(timeoutId);
+	}
+}
+/**
+* Cohere Embedding Adapter
+*
+* Tree-shakeable adapter for Cohere multimodal embeddings (embed-v4.0),
+* implemented with plain `fetch` against the v2/embed endpoint — no Cohere
+* SDK dependency.
+*
+* Features:
+* - Batch embedding (one request for the whole input array)
+* - Multimodal inputs: text, images, and fused text+image items (one vector
+*   per input item)
+* - Matryoshka dimension reduction via the top-level `dimensions` option
+*   (mapped to Cohere's `output_dimension`)
+*/
+var CohereEmbeddingAdapter = class extends BaseEmbeddingAdapter {
+	name = "cohere";
+	clientConfig;
+	constructor(config, model) {
+		super(model, {});
+		this.clientConfig = config;
+	}
+	async createEmbeddings(options) {
+		const { model, logger, modelOptions } = options;
+		try {
+			const inputType = modelOptions?.inputType;
+			if (!inputType) throw new Error(`Cohere embeddings require modelOptions.inputType ('search_document' | 'search_query' | 'classification' | 'clustering').`);
+			const resolved = resolveEmbeddingInput(options.input);
+			const inputs = await Promise.all(resolved.map(async (item) => {
+				const content = item.texts.map((text) => ({
+					type: "text",
+					text
+				}));
+				for (const image of item.images) content.push({
+					type: "image_url",
+					image_url: { url: await this.resolveImageUrl(image) }
+				});
+				return { content };
+			}));
+			const body = {
+				model,
+				inputs,
+				input_type: inputType,
+				embedding_types: ["float"]
+			};
+			const truncate = modelOptions?.truncate;
+			if (truncate !== void 0) body.truncate = truncate;
+			if (options.dimensions !== void 0) body.output_dimension = options.dimensions;
+			logger.request(`activity=embed provider=${this.name} model=${model} inputs=${inputs.length}`, {
+				provider: this.name,
+				model
+			});
+			const timeoutMs = this.clientConfig.timeout ?? DEFAULT_TIMEOUT_MS;
+			const response = await fetchWithTimeout(`${this.clientConfig.baseUrl ?? DEFAULT_BASE_URL}/v2/embed`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.clientConfig.apiKey}`,
+					"Content-Type": "application/json",
+					...this.clientConfig.headers
+				},
+				body: JSON.stringify(body)
+			}, timeoutMs);
+			if (!response.ok) {
+				const bodyText = await response.text();
+				let message = bodyText;
+				try {
+					const parsed = JSON.parse(bodyText);
+					if (typeof parsed === "object" && parsed !== null && "message" in parsed && typeof parsed.message === "string") message = parsed.message;
+				} catch {}
+				throw new Error(`Cohere embed failed (${response.status}): ${message}`);
+			}
+			const data = await response.json();
+			const vectors = data.embeddings?.float;
+			if (!vectors) throw new Error("Cohere embed response did not include float embeddings");
+			if (vectors.length !== inputs.length) throw new Error(`Cohere embed returned ${vectors.length} embeddings for ${inputs.length} inputs`);
+			const result = {
+				id: generateId(this.name),
+				model,
+				embeddings: vectors.map((vector, index) => ({
+					vector,
+					index
+				}))
+			};
+			const inputTokens = data.meta?.billed_units?.input_tokens;
+			if (inputTokens !== void 0) result.usage = {
+				promptTokens: inputTokens,
+				completionTokens: 0,
+				totalTokens: inputTokens
+			};
+			return result;
+		} catch (error) {
+			logger.errors(`${this.name}.createEmbeddings fatal`, {
+				error: toRunErrorPayload(error, `${this.name}.createEmbeddings failed`),
+				source: `${this.name}.createEmbeddings`
+			});
+			throw error;
+		}
+	}
+	/**
+	* Resolves an image part to a URL Cohere accepts. Cohere does not fetch
+	* remote image URLs, so everything is normalized to a `data:` URI unless
+	* the caller already provided one.
+	*/
+	async resolveImageUrl(image) {
+		const source = image.source;
+		if (source.type === "data") return `data:${source.mimeType};base64,${source.value}`;
+		if (source.value.startsWith("data:")) return source.value;
+		if (!this.clientConfig.allowUrlFetch) throw new Error("Cohere does not fetch remote image URLs; pass base64 data or a data: URI (or enable config.allowUrlFetch to have the adapter download it)");
+		if (isPrivateOrInternalUrl(source.value)) throw new Error(`Refusing to fetch internal or private URL for Cohere embedding: ${source.value}`);
+		const response = await fetchWithTimeout(source.value, void 0, this.clientConfig.timeout ?? DEFAULT_TIMEOUT_MS);
+		if (!response.ok) throw new Error(`Failed to fetch image URL for Cohere embedding (${response.status}): ${source.value}`);
+		return `data:${response.headers.get("content-type") ?? source.mimeType ?? "application/octet-stream"};base64,${arrayBufferToBase64(await response.arrayBuffer())}`;
+	}
+};
+/**
+* Creates a Cohere embedding adapter with explicit API key.
+* Type resolution happens here at the call site.
+*
+* @param model - The model name (e.g., 'embed-v4.0')
+* @param apiKey - Your Cohere API key
+* @param config - Optional additional configuration
+* @returns Configured Cohere embedding adapter instance with resolved types
+*
+* @example
+* ```typescript
+* const adapter = createCohereEmbedding('embed-v4.0', 'api_key');
+*
+* const result = await embed({
+*   adapter,
+*   input: 'a red guitar',
+*   modelOptions: { inputType: 'search_document' }
+* });
+* ```
+*/
+function createCohereEmbedding(model, apiKey, config) {
+	return new CohereEmbeddingAdapter({
+		apiKey,
+		...config
+	}, model);
+}
+/**
+* Creates a Cohere embedding adapter using the `COHERE_API_KEY` environment variable.
+* Type resolution happens here at the call site.
+*
+* Looks for `COHERE_API_KEY` in:
+* - `process.env` (Node.js)
+* - `window.env` (Browser with injected env)
+*
+* @param model - The model name (e.g., 'embed-v4.0')
+* @param config - Optional configuration (excluding apiKey which is auto-detected)
+* @returns Configured Cohere embedding adapter instance with resolved types
+* @throws Error if COHERE_API_KEY is not found in environment
+*
+* @example
+* ```typescript
+* // Automatically uses COHERE_API_KEY from environment
+* const adapter = cohereEmbedding('embed-v4.0');
+*
+* const result = await embed({
+*   adapter,
+*   input: ['a red guitar', 'a blue drum kit'],
+*   modelOptions: { inputType: 'search_query' },
+*   dimensions: 1024
+* });
+*
+* console.log(result.embeddings[0].vector)
+* ```
+*/
+function cohereEmbedding(model, config) {
+	return createCohereEmbedding(model, getCohereApiKeyFromEnv(), config);
+}
+//#endregion
+export { CohereEmbeddingAdapter, cohereEmbedding, createCohereEmbedding };
+
+//# sourceMappingURL=embedding.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.js","names":[],"sources":["../../../src/adapters/embedding.ts"],"sourcesContent":["import { BaseEmbeddingAdapter } from '@tanstack/ai/adapters'\nimport { toRunErrorPayload } from '@tanstack/ai/adapter-internals'\nimport { arrayBufferToBase64, generateId } from '@tanstack/ai-utils'\nimport { resolveEmbeddingInput } from '@tanstack/ai'\nimport { getCohereApiKeyFromEnv } from '../utils/client'\nimport type {\n  EmbeddingOptions,\n  EmbeddingResult,\n  ImagePart,\n  TokenUsage,\n} from '@tanstack/ai'\nimport type {\n  CohereEmbeddingModel,\n  CohereEmbeddingModelInputModalitiesByName,\n  CohereEmbeddingModelProviderOptionsByName,\n} from '../model-meta'\nimport type { CohereEmbeddingProviderOptions } from '../embedding/embedding-provider-options'\nimport type { CohereClientConfig } from '../utils/client'\n\n/**\n * Configuration for Cohere embedding adapter.\n */\nexport interface CohereEmbeddingConfig extends CohereClientConfig {}\n\nconst DEFAULT_BASE_URL = 'https://api.cohere.com'\nconst DEFAULT_TIMEOUT_MS = 30_000\n\n/**\n * Returns true when `url` is malformed, non-http(s), or targets a private /\n * loopback / link-local host. Used to block SSRF via `allowUrlFetch`.\n */\nfunction isPrivateOrInternalUrl(url: string): boolean {\n  let parsed: URL\n  try {\n    parsed = new URL(url)\n  } catch {\n    return true\n  }\n  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n    return true\n  }\n  const host = parsed.hostname.toLowerCase()\n  if (\n    host === 'localhost' ||\n    host.endsWith('.localhost') ||\n    host === '::1' ||\n    host === '[::1]' ||\n    host.startsWith('127.') ||\n    host.startsWith('10.') ||\n    host.startsWith('192.168.') ||\n    host.startsWith('169.254.') ||\n    /^172\\.(1[6-9]|2\\d|3[01])\\./.test(host)\n  ) {\n    return true\n  }\n  return false\n}\n\nasync function fetchWithTimeout(\n  url: string,\n  init: RequestInit | undefined,\n  timeoutMs: number,\n): Promise<Response> {\n  const controller = new AbortController()\n  const timeoutId = setTimeout(() => controller.abort(), timeoutMs)\n  try {\n    return await fetch(url, { ...init, signal: controller.signal })\n  } finally {\n    clearTimeout(timeoutId)\n  }\n}\n\n/** One content part of a Cohere v2/embed fused input. */\ntype CohereEmbedContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image_url'; image_url: { url: string } }\n\n/** Wire shape of the Cohere v2/embed request body. */\ninterface CohereEmbedRequestBody {\n  model: string\n  inputs: Array<{ content: Array<CohereEmbedContentPart> }>\n  input_type: CohereEmbeddingProviderOptions['inputType']\n  embedding_types: ['float']\n  truncate?: 'NONE' | 'START' | 'END'\n  output_dimension?: number\n}\n\n/** Wire shape of the Cohere v2/embed response (fields the adapter reads). */\ninterface CohereEmbedResponse {\n  id?: string\n  embeddings?: {\n    float?: Array<Array<number>>\n  }\n  meta?: {\n    billed_units?: {\n      input_tokens?: number\n      images?: number\n    }\n  }\n}\n\n/**\n * Cohere Embedding Adapter\n *\n * Tree-shakeable adapter for Cohere multimodal embeddings (embed-v4.0),\n * implemented with plain `fetch` against the v2/embed endpoint — no Cohere\n * SDK dependency.\n *\n * Features:\n * - Batch embedding (one request for the whole input array)\n * - Multimodal inputs: text, images, and fused text+image items (one vector\n *   per input item)\n * - Matryoshka dimension reduction via the top-level `dimensions` option\n *   (mapped to Cohere's `output_dimension`)\n */\nexport class CohereEmbeddingAdapter<\n  TModel extends CohereEmbeddingModel,\n> extends BaseEmbeddingAdapter<\n  TModel,\n  CohereEmbeddingProviderOptions,\n  CohereEmbeddingModelProviderOptionsByName,\n  CohereEmbeddingModelInputModalitiesByName\n> {\n  readonly name = 'cohere' as const\n\n  protected clientConfig: CohereEmbeddingConfig\n\n  constructor(config: CohereEmbeddingConfig, model: TModel) {\n    super(model, {})\n    this.clientConfig = config\n  }\n\n  async createEmbeddings(\n    options: EmbeddingOptions<CohereEmbeddingProviderOptions>,\n  ): Promise<EmbeddingResult> {\n    const { model, logger, modelOptions } = options\n\n    try {\n      // The provider options type makes `modelOptions` required at the\n      // embed() call site; this guard covers untyped/dynamic callers.\n      const inputType: CohereEmbeddingProviderOptions['inputType'] | undefined =\n        modelOptions?.inputType\n      if (!inputType) {\n        throw new Error(\n          `Cohere embeddings require modelOptions.inputType ('search_document' | 'search_query' | 'classification' | 'clustering').`,\n        )\n      }\n\n      const resolved = resolveEmbeddingInput(options.input)\n      const inputs = await Promise.all(\n        resolved.map(async (item) => {\n          const content: Array<CohereEmbedContentPart> = item.texts.map(\n            (text) => ({ type: 'text', text }),\n          )\n          for (const image of item.images) {\n            content.push({\n              type: 'image_url',\n              image_url: { url: await this.resolveImageUrl(image) },\n            })\n          }\n          return { content }\n        }),\n      )\n\n      // embedding_types is pinned to ['float'] (overriding any disagreeing\n      // modelOptions.embeddingTypes) so vectors are always number[].\n      const body: CohereEmbedRequestBody = {\n        model,\n        inputs,\n        input_type: inputType,\n        embedding_types: ['float'],\n      }\n      const truncate = modelOptions?.truncate\n      if (truncate !== undefined) {\n        body.truncate = truncate\n      }\n      if (options.dimensions !== undefined) {\n        body.output_dimension = options.dimensions\n      }\n\n      logger.request(\n        `activity=embed provider=${this.name} model=${model} inputs=${inputs.length}`,\n        { provider: this.name, model },\n      )\n\n      const timeoutMs = this.clientConfig.timeout ?? DEFAULT_TIMEOUT_MS\n      const response = await fetchWithTimeout(\n        `${this.clientConfig.baseUrl ?? DEFAULT_BASE_URL}/v2/embed`,\n        {\n          method: 'POST',\n          headers: {\n            Authorization: `Bearer ${this.clientConfig.apiKey}`,\n            'Content-Type': 'application/json',\n            ...this.clientConfig.headers,\n          },\n          body: JSON.stringify(body),\n        },\n        timeoutMs,\n      )\n\n      if (!response.ok) {\n        const bodyText = await response.text()\n        let message = bodyText\n        try {\n          const parsed: unknown = JSON.parse(bodyText)\n          if (\n            typeof parsed === 'object' &&\n            parsed !== null &&\n            'message' in parsed &&\n            typeof parsed.message === 'string'\n          ) {\n            message = parsed.message\n          }\n        } catch {\n          // Not JSON — fall back to the raw body text.\n        }\n        throw new Error(`Cohere embed failed (${response.status}): ${message}`)\n      }\n\n      const data = (await response.json()) as CohereEmbedResponse\n\n      const vectors = data.embeddings?.float\n      if (!vectors) {\n        throw new Error(\n          'Cohere embed response did not include float embeddings',\n        )\n      }\n      if (vectors.length !== inputs.length) {\n        throw new Error(\n          `Cohere embed returned ${vectors.length} embeddings for ${inputs.length} inputs`,\n        )\n      }\n\n      const result: EmbeddingResult = {\n        id: generateId(this.name),\n        model,\n        embeddings: vectors.map((vector, index) => ({ vector, index })),\n      }\n\n      const inputTokens = data.meta?.billed_units?.input_tokens\n      if (inputTokens !== undefined) {\n        const usage: TokenUsage = {\n          promptTokens: inputTokens,\n          completionTokens: 0,\n          totalTokens: inputTokens,\n        }\n        result.usage = usage\n      }\n\n      return result\n    } catch (error: unknown) {\n      logger.errors(`${this.name}.createEmbeddings fatal`, {\n        error: toRunErrorPayload(error, `${this.name}.createEmbeddings failed`),\n        source: `${this.name}.createEmbeddings`,\n      })\n      throw error\n    }\n  }\n\n  /**\n   * Resolves an image part to a URL Cohere accepts. Cohere does not fetch\n   * remote image URLs, so everything is normalized to a `data:` URI unless\n   * the caller already provided one.\n   */\n  protected async resolveImageUrl(image: ImagePart): Promise<string> {\n    const source = image.source\n\n    if (source.type === 'data') {\n      return `data:${source.mimeType};base64,${source.value}`\n    }\n\n    if (source.value.startsWith('data:')) {\n      return source.value\n    }\n\n    if (!this.clientConfig.allowUrlFetch) {\n      throw new Error(\n        'Cohere does not fetch remote image URLs; pass base64 data or a data: URI (or enable config.allowUrlFetch to have the adapter download it)',\n      )\n    }\n\n    if (isPrivateOrInternalUrl(source.value)) {\n      throw new Error(\n        `Refusing to fetch internal or private URL for Cohere embedding: ${source.value}`,\n      )\n    }\n\n    const response = await fetchWithTimeout(\n      source.value,\n      undefined,\n      this.clientConfig.timeout ?? DEFAULT_TIMEOUT_MS,\n    )\n    if (!response.ok) {\n      throw new Error(\n        `Failed to fetch image URL for Cohere embedding (${response.status}): ${source.value}`,\n      )\n    }\n    const mimeType =\n      response.headers.get('content-type') ??\n      source.mimeType ??\n      'application/octet-stream'\n    const base64 = arrayBufferToBase64(await response.arrayBuffer())\n    return `data:${mimeType};base64,${base64}`\n  }\n}\n\n/**\n * Creates a Cohere embedding adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'embed-v4.0')\n * @param apiKey - Your Cohere API key\n * @param config - Optional additional configuration\n * @returns Configured Cohere embedding adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createCohereEmbedding('embed-v4.0', 'api_key');\n *\n * const result = await embed({\n *   adapter,\n *   input: 'a red guitar',\n *   modelOptions: { inputType: 'search_document' }\n * });\n * ```\n */\nexport function createCohereEmbedding<TModel extends CohereEmbeddingModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<CohereEmbeddingConfig, 'apiKey'>,\n): CohereEmbeddingAdapter<TModel> {\n  return new CohereEmbeddingAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Cohere embedding adapter using the `COHERE_API_KEY` environment variable.\n * Type resolution happens here at the call site.\n *\n * Looks for `COHERE_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'embed-v4.0')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Cohere embedding adapter instance with resolved types\n * @throws Error if COHERE_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses COHERE_API_KEY from environment\n * const adapter = cohereEmbedding('embed-v4.0');\n *\n * const result = await embed({\n *   adapter,\n *   input: ['a red guitar', 'a blue drum kit'],\n *   modelOptions: { inputType: 'search_query' },\n *   dimensions: 1024\n * });\n *\n * console.log(result.embeddings[0].vector)\n * ```\n */\nexport function cohereEmbedding<TModel extends CohereEmbeddingModel>(\n  model: TModel,\n  config?: Omit<CohereEmbeddingConfig, 'apiKey'>,\n): CohereEmbeddingAdapter<TModel> {\n  const apiKey = getCohereApiKeyFromEnv()\n  return createCohereEmbedding(model, apiKey, config)\n}\n"],"mappings":"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"}

package/dist/esm/embedding/embedding-provider-options.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Provider options for Cohere embedding models.
+ *
+ * `dimensions` is deliberately absent: it's a first-class top-level option on
+ * `embed()` and is mapped to Cohere's `output_dimension` request field by the
+ * adapter.
+ */
+/**
+ * Provider options for `embed-v4.0`.
+ *
+ * `inputType` is required by Cohere's v2 embed API, which makes
+ * `modelOptions` required at the `embed()` call site.
+ */
+export interface CohereEmbeddingProviderOptions {
+    /**
+     * The intended downstream use of the embeddings. Cohere requires this to
+     * pick the right embedding space:
+     * - `search_document` — corpus items stored for later retrieval
+     * - `search_query` — queries run against stored documents
+     * - `classification` — inputs embedded for classification tasks
+     * - `clustering` — inputs embedded for clustering tasks
+     */
+    inputType: 'search_document' | 'search_query' | 'classification' | 'clustering';
+    /**
+     * Requested embedding value encodings. The adapter always pins this to
+     * `['float']` so vectors are plain `number[]`; other encodings are not
+     * supported through TanStack AI.
+     */
+    embeddingTypes?: ['float'];
+    /**
+     * How to handle inputs longer than the model's maximum token length.
+     * `NONE` returns an error for over-long inputs; `START`/`END` truncate
+     * from the respective side. Defaults to Cohere's server-side default
+     * (`END`) when omitted.
+     */
+    truncate?: 'NONE' | 'START' | 'END';
+}

package/dist/esm/index.d.ts

@@ -1,3 +1,15 @@
+/**
+ * @module @tanstack/ai-cohere
+ *
+ * Cohere provider adapter for TanStack AI.
+ * Provides tree-shakeable adapters for Cohere's v2/embed API (multimodal
+ * embeddings) and v2/rerank API (document reranking) using plain fetch —
+ * no SDK dependency.
+ */
+export { CohereEmbeddingAdapter, createCohereEmbedding, cohereEmbedding, type CohereEmbeddingConfig, } from './adapters/embedding.js';
+export type { CohereEmbeddingProviderOptions } from './embedding/embedding-provider-options.js';
 export { CohereRerankAdapter, createCohereRerank, cohereRerank, } from './adapters/rerank.js';
+export { getCohereApiKeyFromEnv, type CohereClientConfig } from './utils/client.js';
+export type { CohereEmbeddingModel, CohereEmbeddingModelProviderOptionsByName, CohereEmbeddingModelInputModalitiesByName, } from './model-meta.js';
+export { COHERE_EMBEDDING_MODELS } from './model-meta.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

@@ -1,3 +1,5 @@
+import { getCohereApiKeyFromEnv } from "./utils/client.js";
+import { CohereEmbeddingAdapter, cohereEmbedding, createCohereEmbedding } from "./adapters/embedding.js";
 import { CohereRerankAdapter, cohereRerank, createCohereRerank } from "./adapters/rerank.js";
-import { COHERE_RERANK_MODELS } from "./model-meta.js";
-export { COHERE_RERANK_MODELS, CohereRerankAdapter, cohereRerank, createCohereRerank };
+import { COHERE_EMBEDDING_MODELS, COHERE_RERANK_MODELS } from "./model-meta.js";
+export { COHERE_EMBEDDING_MODELS, COHERE_RERANK_MODELS, CohereEmbeddingAdapter, CohereRerankAdapter, cohereEmbedding, cohereRerank, createCohereEmbedding, createCohereRerank, getCohereApiKeyFromEnv };

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

@@ -1,3 +1,26 @@
+import { CohereEmbeddingProviderOptions } from './embedding/embedding-provider-options.js';
+/**
+ * Embedding models (based on endpoints: "v2/embed")
+ */
+export declare const COHERE_EMBEDDING_MODELS: readonly ["embed-v4.0"];
+/**
+ * Union type of all supported Cohere embedding model names.
+ */
+export type CohereEmbeddingModel = (typeof COHERE_EMBEDDING_MODELS)[number];
+/**
+ * Type-only map from embedding model name to its provider options type.
+ */
+export type CohereEmbeddingModelProviderOptionsByName = {
+    'embed-v4.0': CohereEmbeddingProviderOptions;
+};
+/**
+ * Per-model input modalities for embedding models. embed-v4.0 is
+ * multimodal: it accepts text and image inputs (including fused
+ * text+image items that produce a single vector).
+ */
+export type CohereEmbeddingModelInputModalitiesByName = {
+    'embed-v4.0': readonly ['text', 'image'];
+};
 /**
  * Cohere rerank model metadata.
  *

package/dist/esm/model-meta.js

@@ -1,5 +1,9 @@
 //#region src/model-meta.ts
 /**
+* Embedding models (based on endpoints: "v2/embed")
+*/
+var COHERE_EMBEDDING_MODELS = ["embed-v4.0"];
+/**
 * Cohere rerank model metadata.
 *
 * Provider options are resolved per model at the `cohereRerank('model')` call
@@ -15,6 +19,6 @@ var COHERE_RERANK_MODELS = [
 	"rerank-multilingual-v3.0"
 ];
 //#endregion
-export { COHERE_RERANK_MODELS };
+export { COHERE_EMBEDDING_MODELS, COHERE_RERANK_MODELS };
 
 //# sourceMappingURL=model-meta.js.map

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

@@ -1 +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"}
+{"version":3,"file":"model-meta.js","names":[],"sources":["../../src/model-meta.ts"],"sourcesContent":["import type { CohereEmbeddingProviderOptions } from './embedding/embedding-provider-options'\n\n/**\n * Embedding models (based on endpoints: \"v2/embed\")\n */\nexport const COHERE_EMBEDDING_MODELS = ['embed-v4.0'] as const\n\n/**\n * Union type of all supported Cohere embedding model names.\n */\nexport type CohereEmbeddingModel = (typeof COHERE_EMBEDDING_MODELS)[number]\n\n/**\n * Type-only map from embedding model name to its provider options type.\n */\nexport type CohereEmbeddingModelProviderOptionsByName = {\n  'embed-v4.0': CohereEmbeddingProviderOptions\n}\n\n/**\n * Per-model input modalities for embedding models. embed-v4.0 is\n * multimodal: it accepts text and image inputs (including fused\n * text+image items that produce a single vector).\n */\nexport type CohereEmbeddingModelInputModalitiesByName = {\n  'embed-v4.0': readonly ['text', 'image']\n}\n\n/**\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":";;;;AAKA,IAAa,0BAA0B,CAAC,YAAY;;;;;;;;;;;AAkCpD,IAAa,uBAAuB;CAClC;CACA;CACA;AACF"}

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

@@ -1,21 +1,31 @@
 /**
- * Cohere client configuration shared by the rerank adapter.
+ * Configuration for the Cohere HTTP client used by the adapters in this
+ * package. Requests are made with plain `fetch` — no Cohere SDK dependency.
  */
 export interface CohereClientConfig {
-    /** Cohere API key. Required by the adapter factories. */
+    /** Cohere API key. */
     apiKey: string;
-    /** Override the API base URL. Defaults to `https://api.cohere.com`. */
+    /** Optional base URL override (defaults to `https://api.cohere.com`). */
     baseUrl?: string;
-    /** Extra headers merged into every request. */
+    /** Optional default headers to include with every request. */
     headers?: Record<string, string>;
+    /**
+     * Cohere's embed API does not fetch remote image URLs itself. When this is
+     * enabled the adapter downloads http(s) image URLs and inlines them as
+     * base64 `data:` URIs before sending the request. Disabled by default.
+     */
+    allowUrlFetch?: boolean;
+    /** Request timeout in milliseconds for API and image URL fetches (default: 30_000). */
+    timeout?: number;
 }
 export declare const COHERE_DEFAULT_BASE_URL = "https://api.cohere.com";
 /**
- * Reads the Cohere API key from the environment.
+ * Gets Cohere API key from environment variables.
  *
- * Looks for `COHERE_API_KEY` in `process.env` (Node) or `window.env`
- * (browser with injected env).
+ * Looks for `COHERE_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
  *
- * @throws Error if `COHERE_API_KEY` is not found.
+ * @throws Error if COHERE_API_KEY is not found
  */
 export declare function getCohereApiKeyFromEnv(): string;

package/dist/esm/utils/client.js

@@ -1,19 +1,17 @@
+import { getApiKeyFromEnv } from "@tanstack/ai-utils";
 //#region src/utils/client.ts
 var COHERE_DEFAULT_BASE_URL = "https://api.cohere.com";
 /**
-* Reads the Cohere API key from the environment.
+* Gets Cohere API key from environment variables.
 *
-* Looks for `COHERE_API_KEY` in `process.env` (Node) or `window.env`
-* (browser with injected env).
+* Looks for `COHERE_API_KEY` in:
+* - `process.env` (Node.js)
+* - `window.env` (Browser with injected env)
 *
-* @throws Error if `COHERE_API_KEY` is not found.
+* @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;
+	return getApiKeyFromEnv("COHERE_API_KEY");
 }
 //#endregion
 export { COHERE_DEFAULT_BASE_URL, getCohereApiKeyFromEnv };

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

@@ -1 +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"}
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/utils/client.ts"],"sourcesContent":["import { getApiKeyFromEnv } from '@tanstack/ai-utils'\n\n/**\n * Configuration for the Cohere HTTP client used by the adapters in this\n * package. Requests are made with plain `fetch` — no Cohere SDK dependency.\n */\nexport interface CohereClientConfig {\n  /** Cohere API key. */\n  apiKey: string\n\n  /** Optional base URL override (defaults to `https://api.cohere.com`). */\n  baseUrl?: string\n\n  /** Optional default headers to include with every request. */\n  headers?: Record<string, string>\n\n  /**\n   * Cohere's embed API does not fetch remote image URLs itself. When this is\n   * enabled the adapter downloads http(s) image URLs and inlines them as\n   * base64 `data:` URIs before sending the request. Disabled by default.\n   */\n  allowUrlFetch?: boolean\n\n  /** Request timeout in milliseconds for API and image URL fetches (default: 30_000). */\n  timeout?: number\n}\n\nexport const COHERE_DEFAULT_BASE_URL = 'https://api.cohere.com'\n\n/**\n * Gets Cohere API key from environment variables.\n *\n * Looks for `COHERE_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @throws Error if COHERE_API_KEY is not found\n */\nexport function getCohereApiKeyFromEnv(): string {\n  return getApiKeyFromEnv('COHERE_API_KEY')\n}\n"],"mappings":";;AA2BA,IAAa,0BAA0B;;;;;;;;;;AAWvC,SAAgB,yBAAiC;CAC/C,OAAO,iBAAiB,gBAAgB;AAC1C"}

package/package.json

@@ -1,10 +1,7 @@
 {
   "name": "@tanstack/ai-cohere",
-  "version": "0.0.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "description": "Cohere adapter for TanStack AI — document reranking.",
+  "version": "0.1.1",
+  "description": "Cohere adapter for TanStack AI — multimodal embeddings and document reranking.",
   "author": "Tanner Linsley",
   "license": "MIT",
   "homepage": "https://tanstack.com/ai",
@@ -27,6 +24,10 @@
     ".": {
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
+    },
+    "./adapters/embedding": {
+      "types": "./dist/esm/adapters/embedding.d.ts",
+      "import": "./dist/esm/adapters/embedding.js"
     }
   },
   "files": [
@@ -39,19 +40,24 @@
     "typescript",
     "tanstack",
     "cohere",
+    "adapter",
+    "embeddings",
+    "multimodal",
     "rerank",
     "reranking",
     "search",
-    "retrieval",
-    "adapter"
+    "retrieval"
   ],
   "peerDependencies": {
-    "@tanstack/ai": "^0.43.1"
+    "@tanstack/ai": "^0.45.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.14",
-    "vite": "^8.1.4",
-    "@tanstack/ai": "0.43.1"
+    "@vitest/coverage-v8": "4.1.10",
+    "vite": "^8.2.1",
+    "@tanstack/ai": "0.45.0"
+  },
+  "dependencies": {
+    "@tanstack/ai-utils": "^0.4.0"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/embedding.ts

@@ -0,0 +1,369 @@
+import { BaseEmbeddingAdapter } from '@tanstack/ai/adapters'
+import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
+import { arrayBufferToBase64, generateId } from '@tanstack/ai-utils'
+import { resolveEmbeddingInput } from '@tanstack/ai'
+import { getCohereApiKeyFromEnv } from '../utils/client'
+import type {
+  EmbeddingOptions,
+  EmbeddingResult,
+  ImagePart,
+  TokenUsage,
+} from '@tanstack/ai'
+import type {
+  CohereEmbeddingModel,
+  CohereEmbeddingModelInputModalitiesByName,
+  CohereEmbeddingModelProviderOptionsByName,
+} from '../model-meta'
+import type { CohereEmbeddingProviderOptions } from '../embedding/embedding-provider-options'
+import type { CohereClientConfig } from '../utils/client'
+
+/**
+ * Configuration for Cohere embedding adapter.
+ */
+export interface CohereEmbeddingConfig extends CohereClientConfig {}
+
+const DEFAULT_BASE_URL = 'https://api.cohere.com'
+const DEFAULT_TIMEOUT_MS = 30_000
+
+/**
+ * Returns true when `url` is malformed, non-http(s), or targets a private /
+ * loopback / link-local host. Used to block SSRF via `allowUrlFetch`.
+ */
+function isPrivateOrInternalUrl(url: string): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return true
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return true
+  }
+  const host = parsed.hostname.toLowerCase()
+  if (
+    host === 'localhost' ||
+    host.endsWith('.localhost') ||
+    host === '::1' ||
+    host === '[::1]' ||
+    host.startsWith('127.') ||
+    host.startsWith('10.') ||
+    host.startsWith('192.168.') ||
+    host.startsWith('169.254.') ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(host)
+  ) {
+    return true
+  }
+  return false
+}
+
+async function fetchWithTimeout(
+  url: string,
+  init: RequestInit | undefined,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetch(url, { ...init, signal: controller.signal })
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/** One content part of a Cohere v2/embed fused input. */
+type CohereEmbedContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: { url: string } }
+
+/** Wire shape of the Cohere v2/embed request body. */
+interface CohereEmbedRequestBody {
+  model: string
+  inputs: Array<{ content: Array<CohereEmbedContentPart> }>
+  input_type: CohereEmbeddingProviderOptions['inputType']
+  embedding_types: ['float']
+  truncate?: 'NONE' | 'START' | 'END'
+  output_dimension?: number
+}
+
+/** Wire shape of the Cohere v2/embed response (fields the adapter reads). */
+interface CohereEmbedResponse {
+  id?: string
+  embeddings?: {
+    float?: Array<Array<number>>
+  }
+  meta?: {
+    billed_units?: {
+      input_tokens?: number
+      images?: number
+    }
+  }
+}
+
+/**
+ * Cohere Embedding Adapter
+ *
+ * Tree-shakeable adapter for Cohere multimodal embeddings (embed-v4.0),
+ * implemented with plain `fetch` against the v2/embed endpoint — no Cohere
+ * SDK dependency.
+ *
+ * Features:
+ * - Batch embedding (one request for the whole input array)
+ * - Multimodal inputs: text, images, and fused text+image items (one vector
+ *   per input item)
+ * - Matryoshka dimension reduction via the top-level `dimensions` option
+ *   (mapped to Cohere's `output_dimension`)
+ */
+export class CohereEmbeddingAdapter<
+  TModel extends CohereEmbeddingModel,
+> extends BaseEmbeddingAdapter<
+  TModel,
+  CohereEmbeddingProviderOptions,
+  CohereEmbeddingModelProviderOptionsByName,
+  CohereEmbeddingModelInputModalitiesByName
+> {
+  readonly name = 'cohere' as const
+
+  protected clientConfig: CohereEmbeddingConfig
+
+  constructor(config: CohereEmbeddingConfig, model: TModel) {
+    super(model, {})
+    this.clientConfig = config
+  }
+
+  async createEmbeddings(
+    options: EmbeddingOptions<CohereEmbeddingProviderOptions>,
+  ): Promise<EmbeddingResult> {
+    const { model, logger, modelOptions } = options
+
+    try {
+      // The provider options type makes `modelOptions` required at the
+      // embed() call site; this guard covers untyped/dynamic callers.
+      const inputType: CohereEmbeddingProviderOptions['inputType'] | undefined =
+        modelOptions?.inputType
+      if (!inputType) {
+        throw new Error(
+          `Cohere embeddings require modelOptions.inputType ('search_document' | 'search_query' | 'classification' | 'clustering').`,
+        )
+      }
+
+      const resolved = resolveEmbeddingInput(options.input)
+      const inputs = await Promise.all(
+        resolved.map(async (item) => {
+          const content: Array<CohereEmbedContentPart> = item.texts.map(
+            (text) => ({ type: 'text', text }),
+          )
+          for (const image of item.images) {
+            content.push({
+              type: 'image_url',
+              image_url: { url: await this.resolveImageUrl(image) },
+            })
+          }
+          return { content }
+        }),
+      )
+
+      // embedding_types is pinned to ['float'] (overriding any disagreeing
+      // modelOptions.embeddingTypes) so vectors are always number[].
+      const body: CohereEmbedRequestBody = {
+        model,
+        inputs,
+        input_type: inputType,
+        embedding_types: ['float'],
+      }
+      const truncate = modelOptions?.truncate
+      if (truncate !== undefined) {
+        body.truncate = truncate
+      }
+      if (options.dimensions !== undefined) {
+        body.output_dimension = options.dimensions
+      }
+
+      logger.request(
+        `activity=embed provider=${this.name} model=${model} inputs=${inputs.length}`,
+        { provider: this.name, model },
+      )
+
+      const timeoutMs = this.clientConfig.timeout ?? DEFAULT_TIMEOUT_MS
+      const response = await fetchWithTimeout(
+        `${this.clientConfig.baseUrl ?? DEFAULT_BASE_URL}/v2/embed`,
+        {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${this.clientConfig.apiKey}`,
+            'Content-Type': 'application/json',
+            ...this.clientConfig.headers,
+          },
+          body: JSON.stringify(body),
+        },
+        timeoutMs,
+      )
+
+      if (!response.ok) {
+        const bodyText = await response.text()
+        let message = bodyText
+        try {
+          const parsed: unknown = JSON.parse(bodyText)
+          if (
+            typeof parsed === 'object' &&
+            parsed !== null &&
+            'message' in parsed &&
+            typeof parsed.message === 'string'
+          ) {
+            message = parsed.message
+          }
+        } catch {
+          // Not JSON — fall back to the raw body text.
+        }
+        throw new Error(`Cohere embed failed (${response.status}): ${message}`)
+      }
+
+      const data = (await response.json()) as CohereEmbedResponse
+
+      const vectors = data.embeddings?.float
+      if (!vectors) {
+        throw new Error(
+          'Cohere embed response did not include float embeddings',
+        )
+      }
+      if (vectors.length !== inputs.length) {
+        throw new Error(
+          `Cohere embed returned ${vectors.length} embeddings for ${inputs.length} inputs`,
+        )
+      }
+
+      const result: EmbeddingResult = {
+        id: generateId(this.name),
+        model,
+        embeddings: vectors.map((vector, index) => ({ vector, index })),
+      }
+
+      const inputTokens = data.meta?.billed_units?.input_tokens
+      if (inputTokens !== undefined) {
+        const usage: TokenUsage = {
+          promptTokens: inputTokens,
+          completionTokens: 0,
+          totalTokens: inputTokens,
+        }
+        result.usage = usage
+      }
+
+      return result
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.createEmbeddings fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.createEmbeddings failed`),
+        source: `${this.name}.createEmbeddings`,
+      })
+      throw error
+    }
+  }
+
+  /**
+   * Resolves an image part to a URL Cohere accepts. Cohere does not fetch
+   * remote image URLs, so everything is normalized to a `data:` URI unless
+   * the caller already provided one.
+   */
+  protected async resolveImageUrl(image: ImagePart): Promise<string> {
+    const source = image.source
+
+    if (source.type === 'data') {
+      return `data:${source.mimeType};base64,${source.value}`
+    }
+
+    if (source.value.startsWith('data:')) {
+      return source.value
+    }
+
+    if (!this.clientConfig.allowUrlFetch) {
+      throw new Error(
+        'Cohere does not fetch remote image URLs; pass base64 data or a data: URI (or enable config.allowUrlFetch to have the adapter download it)',
+      )
+    }
+
+    if (isPrivateOrInternalUrl(source.value)) {
+      throw new Error(
+        `Refusing to fetch internal or private URL for Cohere embedding: ${source.value}`,
+      )
+    }
+
+    const response = await fetchWithTimeout(
+      source.value,
+      undefined,
+      this.clientConfig.timeout ?? DEFAULT_TIMEOUT_MS,
+    )
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch image URL for Cohere embedding (${response.status}): ${source.value}`,
+      )
+    }
+    const mimeType =
+      response.headers.get('content-type') ??
+      source.mimeType ??
+      'application/octet-stream'
+    const base64 = arrayBufferToBase64(await response.arrayBuffer())
+    return `data:${mimeType};base64,${base64}`
+  }
+}
+
+/**
+ * Creates a Cohere embedding adapter with explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @param model - The model name (e.g., 'embed-v4.0')
+ * @param apiKey - Your Cohere API key
+ * @param config - Optional additional configuration
+ * @returns Configured Cohere embedding adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createCohereEmbedding('embed-v4.0', 'api_key');
+ *
+ * const result = await embed({
+ *   adapter,
+ *   input: 'a red guitar',
+ *   modelOptions: { inputType: 'search_document' }
+ * });
+ * ```
+ */
+export function createCohereEmbedding<TModel extends CohereEmbeddingModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<CohereEmbeddingConfig, 'apiKey'>,
+): CohereEmbeddingAdapter<TModel> {
+  return new CohereEmbeddingAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * Creates a Cohere embedding adapter using the `COHERE_API_KEY` environment variable.
+ * Type resolution happens here at the call site.
+ *
+ * Looks for `COHERE_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @param model - The model name (e.g., 'embed-v4.0')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Cohere embedding adapter instance with resolved types
+ * @throws Error if COHERE_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses COHERE_API_KEY from environment
+ * const adapter = cohereEmbedding('embed-v4.0');
+ *
+ * const result = await embed({
+ *   adapter,
+ *   input: ['a red guitar', 'a blue drum kit'],
+ *   modelOptions: { inputType: 'search_query' },
+ *   dimensions: 1024
+ * });
+ *
+ * console.log(result.embeddings[0].vector)
+ * ```
+ */
+export function cohereEmbedding<TModel extends CohereEmbeddingModel>(
+  model: TModel,
+  config?: Omit<CohereEmbeddingConfig, 'apiKey'>,
+): CohereEmbeddingAdapter<TModel> {
+  const apiKey = getCohereApiKeyFromEnv()
+  return createCohereEmbedding(model, apiKey, config)
+}

package/src/embedding/embedding-provider-options.ts

@@ -0,0 +1,44 @@
+/**
+ * Provider options for Cohere embedding models.
+ *
+ * `dimensions` is deliberately absent: it's a first-class top-level option on
+ * `embed()` and is mapped to Cohere's `output_dimension` request field by the
+ * adapter.
+ */
+
+/**
+ * Provider options for `embed-v4.0`.
+ *
+ * `inputType` is required by Cohere's v2 embed API, which makes
+ * `modelOptions` required at the `embed()` call site.
+ */
+export interface CohereEmbeddingProviderOptions {
+  /**
+   * The intended downstream use of the embeddings. Cohere requires this to
+   * pick the right embedding space:
+   * - `search_document` — corpus items stored for later retrieval
+   * - `search_query` — queries run against stored documents
+   * - `classification` — inputs embedded for classification tasks
+   * - `clustering` — inputs embedded for clustering tasks
+   */
+  inputType:
+    | 'search_document'
+    | 'search_query'
+    | 'classification'
+    | 'clustering'
+
+  /**
+   * Requested embedding value encodings. The adapter always pins this to
+   * `['float']` so vectors are plain `number[]`; other encodings are not
+   * supported through TanStack AI.
+   */
+  embeddingTypes?: ['float']
+
+  /**
+   * How to handle inputs longer than the model's maximum token length.
+   * `NONE` returns an error for over-long inputs; `START`/`END` truncate
+   * from the respective side. Defaults to Cohere's server-side default
+   * (`END`) when omitted.
+   */
+  truncate?: 'NONE' | 'START' | 'END'
+}

package/src/index.ts

@@ -1,7 +1,25 @@
+/**
+ * @module @tanstack/ai-cohere
+ *
+ * Cohere provider adapter for TanStack AI.
+ * Provides tree-shakeable adapters for Cohere's v2/embed API (multimodal
+ * embeddings) and v2/rerank API (document reranking) using plain fetch —
+ * no SDK dependency.
+ */
+
 // ============================================================================
 // Cohere Adapters (tree-shakeable)
 // ============================================================================
 
+// Embedding adapter - for embedding vectors
+export {
+  CohereEmbeddingAdapter,
+  createCohereEmbedding,
+  cohereEmbedding,
+  type CohereEmbeddingConfig,
+} from './adapters/embedding'
+export type { CohereEmbeddingProviderOptions } from './embedding/embedding-provider-options'
+
 // Rerank adapter - document reranking via Cohere's /v2/rerank endpoint
 export {
   CohereRerankAdapter,
@@ -9,10 +27,20 @@ export {
   cohereRerank,
 } from './adapters/rerank'
 
+// Client config + env helpers
+export { getCohereApiKeyFromEnv, type CohereClientConfig } from './utils/client'
+
 // ============================================================================
 // Type Exports
 // ============================================================================
 
+export type {
+  CohereEmbeddingModel,
+  CohereEmbeddingModelProviderOptionsByName,
+  CohereEmbeddingModelInputModalitiesByName,
+} from './model-meta'
+export { COHERE_EMBEDDING_MODELS } from './model-meta'
+
 export {
   COHERE_RERANK_MODELS,
   type CohereRerankModel,
@@ -20,5 +48,3 @@ export {
   type CohereRerankModelProviderOptionsByName,
   type InferCohereRerankProviderOptions,
 } from './model-meta'
-
-export type { CohereClientConfig } from './utils/client'

package/src/model-meta.ts

@@ -1,3 +1,31 @@
+import type { CohereEmbeddingProviderOptions } from './embedding/embedding-provider-options'
+
+/**
+ * Embedding models (based on endpoints: "v2/embed")
+ */
+export const COHERE_EMBEDDING_MODELS = ['embed-v4.0'] as const
+
+/**
+ * Union type of all supported Cohere embedding model names.
+ */
+export type CohereEmbeddingModel = (typeof COHERE_EMBEDDING_MODELS)[number]
+
+/**
+ * Type-only map from embedding model name to its provider options type.
+ */
+export type CohereEmbeddingModelProviderOptionsByName = {
+  'embed-v4.0': CohereEmbeddingProviderOptions
+}
+
+/**
+ * Per-model input modalities for embedding models. embed-v4.0 is
+ * multimodal: it accepts text and image inputs (including fused
+ * text+image items that produce a single vector).
+ */
+export type CohereEmbeddingModelInputModalitiesByName = {
+  'embed-v4.0': readonly ['text', 'image']
+}
+
 /**
  * Cohere rerank model metadata.
  *

package/src/utils/client.ts

@@ -1,45 +1,41 @@
+import { getApiKeyFromEnv } from '@tanstack/ai-utils'
+
 /**
- * Cohere client configuration shared by the rerank adapter.
+ * Configuration for the Cohere HTTP client used by the adapters in this
+ * package. Requests are made with plain `fetch` — no Cohere SDK dependency.
  */
 export interface CohereClientConfig {
-  /** Cohere API key. Required by the adapter factories. */
+  /** Cohere API key. */
   apiKey: string
-  /** Override the API base URL. Defaults to `https://api.cohere.com`. */
+
+  /** Optional base URL override (defaults to `https://api.cohere.com`). */
   baseUrl?: string
-  /** Extra headers merged into every request. */
+
+  /** Optional default headers to include with every request. */
   headers?: Record<string, string>
+
+  /**
+   * Cohere's embed API does not fetch remote image URLs itself. When this is
+   * enabled the adapter downloads http(s) image URLs and inlines them as
+   * base64 `data:` URIs before sending the request. Disabled by default.
+   */
+  allowUrlFetch?: boolean
+
+  /** Request timeout in milliseconds for API and image URL fetches (default: 30_000). */
+  timeout?: number
 }
 
 export const COHERE_DEFAULT_BASE_URL = 'https://api.cohere.com'
 
 /**
- * Reads the Cohere API key from the environment.
+ * Gets Cohere API key from environment variables.
  *
- * Looks for `COHERE_API_KEY` in `process.env` (Node) or `window.env`
- * (browser with injected env).
+ * Looks for `COHERE_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
  *
- * @throws Error if `COHERE_API_KEY` is not found.
+ * @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
+  return getApiKeyFromEnv('COHERE_API_KEY')
 }