ai-provider-cohere-sdk

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

// BAD: Hardcoded key, default CohereClient (V1)
import { CohereClient } from "cohere-ai";
const client = new CohereClient({ token: "sk-abc123" });

Why bad: Hardcoded API key is a security breach risk, CohereClient is the legacy V1 client

See: [examples/core.md](examples/core.md) for error handling, platform configs (Bedrock, Azure)

Pattern 2: Chat Completion

V2 chat uses messages array with system, user, assistant, and tool roles.

const response = await client.chat({
  model: "command-a-03-2025",
  messages: [
    { role: "system", content: "You are a helpful coding assistant." },
    { role: "user", content: "Explain TypeScript generics." },
  ],
});

console.log(response.message.content[0].text);

Why good: System message for instruction, model explicitly specified, correct V2 content access path

// BAD: Missing model (required in V2), wrong response access
const response = await client.chat({
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.text); // WRONG: V2 uses response.message.content[0].text

Why bad: V2 requires model, response shape is response.message.content[0].text not response.text

See: [examples/core.md](examples/core.md) for multi-turn, token tracking, temperature control

Pattern 3: Streaming

Use chatStream with for await and check event type for content-delta.

const stream = await client.chatStream({
  model: "command-a-03-2025",
  messages: [{ role: "user", content: "Explain async/await." }],
});

for await (const event of stream) {
  if (event.type === "content-delta") {
    process.stdout.write(event.delta?.message?.content?.text ?? "");
  }
}

Why good: Checks event type before accessing delta, handles nullable content safely

// BAD: Not checking event type
for await (const event of stream) {
  console.log(event.delta?.message); // Many events don't have message delta
}

Why bad: Only content-delta events have text content -- other events (message-start, citation-start, tool-plan-delta) have different shapes

See: [examples/c