/ai-provider-cohere-sdk

name: ai-provider-cohere-sdk
description: Official Cohere TypeScript SDK patterns -- CohereClientV2, chat, embeddings, rerank, RAG with citations, tool use, streaming, and model selection

Cohere SDK Patterns

> **Quick Guide:** Use the `cohere-ai` npm package with `CohereClientV2` for all new Cohere integrations. V2 API requires `model` on every call. Use `chatStream` for streaming with `content-delta` events. Embeddings require `inputType` matching your use case (`search_document` for indexing, `search_query` for querying). Rerank scores documents by relevance. RAG works by passing `documents` to `chat()` -- the model returns inline citations automatically. Tool use follows a 4-step loop: user message, model returns `tool_calls`, you execute and return results, model generates cited response.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `CohereClientV2` (not `CohereClient`) for all new code -- V2 is the current API with required `model` parameter)**

**(You MUST specify `inputType` on every embed call -- `search_document` for indexing, `search_query` for querying -- mismatched types produce garbage similarity scores)**

**(You MUST handle the tool use loop correctly: append the full assistant message (with `tool_calls`) to messages, then append `tool` role results with matching `tool_call_id`)**

**(You MUST check `finish_reason` in responses -- `MAX_TOKENS` means the output was truncated)**

**(You MUST never hardcode API keys -- pass via `token` constructor parameter sourced from environment variables)**

</critical_requirements>

---

**Auto-detection:** Cohere, cohere-ai, CohereClientV2, CohereClient, command-a, command-r, command-r-plus, embed-v4, rerank-v4, chatStream, content-delta, inputType, search_document, search_query, embeddingTypes, topN, CO_API_KEY, COHERE_API_KEY

**When to use:**

• Building applications with Cohere Command models (chat, generation, summarization)
• Creating semantic search pipelines with Cohere embeddings
• Adding relevance scoring to search results with Cohere Rerank
• Implementing RAG with inline document grounding and automatic citations
• Building agentic workflows with Cohere tool use / function calling
• Streaming chat responses for real-time user interfaces

**Key patterns covered:**

• Client setup with `CohereClientV2` (token, timeout, platform configs)
• Chat and streaming (`chat`, `chatStream`, event types)
• Embeddings with `inputType` for search/classification/clustering
• Rerank for relevance scoring and search result ordering
• RAG with documents and automatic citation handling
• Tool use / function calling with multi-step loops
• Model selection (Command-A, Command-R, Embed v4, Rerank v4)

**When NOT to use:**

• Multi-provider applications needing OpenAI/Anthropic/Google switching -- use a unified provider SDK
• React-specific chat UI hooks -- use a framework-integrated AI SDK
• Simple text completion without Cohere-specific features (rerank, citations)

---

Examples Index

• [Core: Setup, Chat & Error Handling](examples/core.md) -- CohereClientV2 init, basic chat, streaming, error handling
• [Embeddings & Rerank](examples/embeddings-rerank.md) -- Semantic search, input types, rerank scoring, RAG pipeline
• [Tool Use & RAG](examples/tools-rag.md) -- Function calling, document grounding, citation handling
• [Quick API Reference](reference.md) -- Model IDs, method signatures, event types, error classes

---

<philosophy>

Philosophy

The Cohere TypeScript SDK (`cohere-ai`) provides **direct access to Cohere's API surface** -- chat, embeddings, rerank, and RAG with citations. The SDK is auto-generated from Cohere's API spec using Fern.

**Core principles:**

1. **V2 API is current** -- `CohereClientV2` provides the modern API. `model` is required on every call. V1 methods on `CohereClient` are legacy. 2. **Embeddings are typed** -- The `inputType` parameter (`search_document`, `search_query`, `classification`, `clustering`) is mandatory for v3+ models. Mismatching input types between indexing and querying silently degrades results. 3. **RAG is first-class** -- Pass `documents` directly to `chat()` and the model returns grounded answers with inline citations. No external retrieval framework required for the grounding step. 4. **Rerank is a standalone primitive** -- Score and reorder search results without building a full RAG pipeline. Feed any list of documents and a query, get relevance scores back. 5. **Citations are automatic** -- When documents are provided (via RAG or tool results), the model generates fine-grained citations with start/end positions and source references.

**When to use the Cohere SDK directly:**

• You want Cohere-specific features: rerank, citation grounding, multilingual embeddings
• You need semantic search with embed + rerank pipeline
• You want RAG with automatic inline citations
• You are building on Cohere's platform (or Bedrock/Azure/OCI with Cohere models)

**When NOT to use:**

• You need to switch between multiple LLM providers -- use a unified provider SDK
• You want React-specific chat UI hooks -- use a framework-integrated AI SDK
• You only need basic chat completion without Cohere differentiators

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client Setup

Initialize `CohereClientV2`. The `token` parameter is required (pass from environment).

// lib/cohere.ts -- basic setup
import { CohereClientV2 } from "cohere-ai";

const client = new CohereClientV2({
  token: process.env.CO_API_KEY,
});

export { client };

// lib/cohere.ts -- production configuration
const TIMEOUT_MS = 30_000;

const client = new CohereClientV2({
  token: process.env.CO_API_KEY,
  timeout: TIMEOUT_MS,
});

**Why good:** Explicit token from env var, named timeout constant, named export