chub-dev 0.1.0 → 0.1.2-beta.0

package/dist/cohere/docs/llm/DOC.md

@@ -0,0 +1,1335 @@
+---
+name: llm
+description: "Cohere API JavaScript/TypeScript SDK coding guide for LLM, embeddings, and rerank"
+metadata:
+  languages: "javascript"
+  versions: "7.19.0"
+  updated-on: "2026-03-02"
+  source: maintainer
+  tags: "cohere,llm,ai,embeddings,rerank"
+---
+
+# Cohere API JavaScript/TypeScript SDK Coding Guide
+
+## 1. Golden Rule
+
+**Always use the official Cohere JavaScript SDK package:** `cohere-ai` (GitHub: https://github.com/cohere-ai/cohere-typescript)
+
+**Never use deprecated or unofficial libraries.** The `cohere-ai` npm package is the only officially supported Cohere SDK for JavaScript/TypeScript maintained by Cohere. Avoid `cohere-js` (unofficial, different product), `cohere-api-web` (legacy/unofficial), and any other variants.
+
+**Always use `CohereClientV2` for accessing the latest v2 API with current models like `command-a-03-2025`.**
+
+## 2. Installation
+
+### npm
+```bash
+npm install cohere-ai
+```
+
+### yarn
+```bash
+yarn add cohere-ai
+```
+
+### pnpm
+```bash
+pnpm add cohere-ai
+```
+
+**Environment Variables:**
+```bash
+COHERE_API_KEY=your_api_key_here
+# Alternative:
+CO_API_KEY=your_api_key_here
+```
+
+The SDK automatically reads from either `COHERE_API_KEY` or `CO_API_KEY` environment variables.
+
+## 3. Initialization
+
+### Basic Client Initialization
+
+```javascript
+import { CohereClientV2 } from "cohere-ai";
+
+// Uses COHERE_API_KEY or CO_API_KEY environment variable
+const cohere = new CohereClientV2({});
+
+// Or pass API key directly
+const cohere = new CohereClientV2({
+  token: "your-api-key"
+});
+```
+
+### Authentication Methods
+
+The Cohere API uses Bearer token authentication. The SDK handles this automatically when you provide the API key via the constructor or environment variables.
+
+```javascript
+import { CohereClientV2 } from "cohere-ai";
+
+// Best practice: use environment variables
+const cohere = new CohereClientV2({
+  token: process.env.COHERE_API_KEY
+});
+```
+
+**Important:** Never hardcode API keys in your source code. Always use environment variables or secure configuration management.
+
+## 4. Core API Surfaces
+
+### Chat API
+
+The Chat API enables conversational AI, text generation, and summarization with Cohere's Command models.
+
+**Minimal Example:**
+```javascript
+import { CohereClientV2 } from "cohere-ai";
+
+const cohere = new CohereClientV2({});
+
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [
+    { role: "user", content: "Explain quantum computing in simple terms" }
+  ]
+});
+
+console.log(response.message.content[0].text);
+```
+
+**Advanced Example with Configuration:**
+```javascript
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [
+    {
+      role: "system",
+      content: "You are a helpful AI assistant specialized in science education."
+    },
+    {
+      role: "user",
+      content: "Explain quantum computing"
+    }
+  ],
+  temperature: 0.3,
+  maxTokens: 500,
+  k: 0,
+  p: 0.75,
+  stopSequences: ["--END--"],
+  frequencyPenalty: 0.0,
+  presencePenalty: 0.0,
+  safetyMode: "CONTEXTUAL"
+});
+
+console.log(response.message.content[0].text);
+```
+
+**Multi-turn Conversation:**
+```javascript
+const messages = [
+  { role: "user", content: "What is machine learning?" },
+  { role: "assistant", content: "Machine learning is a subset of AI..." },
+  { role: "user", content: "Can you give me an example?" }
+];
+
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: messages
+});
+```
+
+### Chat Streaming API
+
+Stream responses in real-time to reduce perceived latency.
+
+**Minimal Example:**
+```javascript
+import { CohereClientV2 } from "cohere-ai";
+
+const cohere = new CohereClientV2({});
+
+const stream = await cohere.chatStream({
+  model: "command-a-03-2025",
+  messages: [
+    { role: "user", content: "Write a short story about a robot" }
+  ]
+});
+
+for await (const chatEvent of stream) {
+  if (chatEvent.type === "content-delta") {
+    process.stdout.write(chatEvent.delta?.message?.content?.text || "");
+  }
+}
+console.log(); // final newline
+```
+
+**Advanced Streaming with Event Handling:**
+```javascript
+const stream = await cohere.chatStream({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "Explain photosynthesis" }],
+  temperature: 0.5
+});
+
+for await (const event of stream) {
+  switch (event.type) {
+    case "message-start":
+      console.log("Stream started");
+      break;
+    case "content-start":
+      console.log("Content generation began");
+      break;
+    case "content-delta":
+      process.stdout.write(event.delta?.message?.content?.text || "");
+      break;
+    case "content-end":
+      console.log("\nContent generation complete");
+      break;
+    case "message-end":
+      console.log("Stream ended");
+      console.log(`Tokens used: ${event.delta?.usage?.tokens}`);
+      break;
+  }
+}
+```
+
+### Embed API
+
+Generate vector embeddings for text data to enable semantic search, clustering, and classification.
+
+**Minimal Example:**
+```javascript
+const embedResponse = await cohere.embed({
+  model: "embed-english-v3.0",
+  texts: ["Hello world", "Cohere embeddings are powerful"],
+  inputType: "search_document"
+});
+
+console.log(embedResponse.embeddings);
+// Returns array of embedding vectors
+```
+
+**Advanced Example with Classification Input Type:**
+```javascript
+const embedResponse = await cohere.embed({
+  model: "embed-multilingual-v3.0",
+  texts: [
+    "This product is amazing!",
+    "Terrible customer service",
+    "Neutral statement"
+  ],
+  inputType: "classification",
+  embeddingTypes: ["float"]
+});
+
+console.log(`Generated ${embedResponse.embeddings.length} embeddings`);
+console.log(`Embedding dimension: ${embedResponse.embeddings[0].length}`);
+```
+
+**Available Input Types:** `"search_document"` (for embeddings stored in vector databases), `"search_query"` (for search queries run against vector databases), `"classification"` (for embeddings passed through text classifiers), and `"clustering"` (for embeddings used in clustering algorithms). The `inputType` parameter is **required** for embed-v3 models and later.
+
+**Multilingual Embeddings:**
+```javascript
+const multilingualEmbed = await cohere.embed({
+  model: "embed-multilingual-v3.0",
+  texts: [
+    "Hello, how are you?",
+    "Bonjour, comment allez-vous?",
+    "Hola, ¿cómo estás?",
+    "こんにちは、お元気ですか？"
+  ],
+  inputType: "search_document"
+});
+```
+
+The `embed-multilingual-v3.0` model supports 100+ languages.
+
+### Rerank API
+
+Rerank search results by semantic relevance to improve retrieval quality.
+
+**Minimal Example:**
+```javascript
+const rerankResponse = await cohere.rerank({
+  model: "rerank-english-v3.0",
+  query: "What is machine learning?",
+  documents: [
+    "Machine learning is a subset of artificial intelligence.",
+    "Python is a programming language.",
+    "Neural networks are computational models inspired by the brain.",
+    "JavaScript is used for web development."
+  ]
+});
+
+// Results ordered by relevance score
+rerankResponse.results.forEach((result, idx) => {
+  console.log(`${idx + 1}. Score: ${result.relevanceScore}`);
+  console.log(`   Document: ${result.document.text}\n`);
+});
+```
+
+**Advanced Example with Top-N and Metadata:**
+```javascript
+const documents = [
+  { text: "Machine learning algorithms learn from data", id: "doc1" },
+  { text: "Supervised learning uses labeled data", id: "doc2" },
+  { text: "Deep learning uses neural networks", id: "doc3" },
+  { text: "Cooking recipes for dinner", id: "doc4" }
+];
+
+const rerankResponse = await cohere.rerank({
+  model: "rerank-english-v3.0",
+  query: "What are machine learning techniques?",
+  documents: documents,
+  topN: 3,
+  returnDocuments: true
+});
+
+console.log("Top ranked documents:");
+rerankResponse.results.forEach((result) => {
+  console.log(`Document ID: ${result.document.id}`);
+  console.log(`Relevance: ${result.relevanceScore}`);
+  console.log(`Text: ${result.document.text}\n`);
+});
+```
+
+**Rerank with Raw Strings:**
+```javascript
+const query = "artificial intelligence applications";
+const docs = [
+  "AI is used in healthcare for diagnosis",
+  "Machine learning powers recommendation systems",
+  "The weather is sunny today",
+  "Natural language processing enables chatbots"
+];
+
+const result = await cohere.rerank({
+  model: "rerank-english-v3.0",
+  query: query,
+  documents: docs,
+  topN: 2
+});
+```
+
+### Classify API
+
+Classify text into predefined categories using few-shot learning.
+
+**Minimal Example:**
+```javascript
+const classifyResponse = await cohere.classify({
+  model: "embed-english-v3.0",
+  inputs: [
+    "This movie was fantastic!",
+    "Worst experience ever.",
+    "It was okay, nothing special."
+  ],
+  examples: [
+    { text: "I loved this!", label: "positive" },
+    { text: "Amazing product", label: "positive" },
+    { text: "Terrible quality", label: "negative" },
+    { text: "Very disappointed", label: "negative" },
+    { text: "It's fine", label: "neutral" },
+    { text: "Average performance", label: "neutral" }
+  ]
+});
+
+classifyResponse.classifications.forEach((classification) => {
+  console.log(`Text: "${classification.input}"`);
+  console.log(`Prediction: ${classification.prediction}`);
+  console.log(`Confidence: ${classification.confidence}\n`);
+});
+```
+
+**Advanced Classification with Multiple Categories:**
+```javascript
+const trainingExamples = [
+  { text: "Fix login bug", label: "bug" },
+  { text: "Login page not working", label: "bug" },
+  { text: "Add dark mode feature", label: "feature" },
+  { text: "Implement user profiles", label: "feature" },
+  { text: "Update documentation", label: "documentation" },
+  { text: "Improve README", label: "documentation" },
+  { text: "How do I install this?", label: "question" },
+  { text: "Where is the config file?", label: "question" }
+];
+
+const classifyResponse = await cohere.classify({
+  model: "embed-english-v3.0",
+  inputs: [
+    "Cannot reset my password",
+    "Need help with setup",
+    "Add support for webhooks"
+  ],
+  examples: trainingExamples
+});
+
+classifyResponse.classifications.forEach((item) => {
+  console.log(`"${item.input}" → ${item.prediction}`);
+
+  // Show confidence for all labels
+  item.labels.forEach((labelConf) => {
+    console.log(`  ${labelConf.labelName}: ${labelConf.confidence}`);
+  });
+});
+```
+
+**Requirements:** Minimum 2 examples per label, maximum 2500 examples total, and can classify up to 96 texts in a single request.
+
+## 5. Advanced Features
+
+### RAG (Retrieval Augmented Generation)
+
+Combine Chat, Embed, and Rerank for production-grade RAG systems.
+
+**Complete RAG Example:**
+```javascript
+import { CohereClientV2 } from "cohere-ai";
+
+const cohere = new CohereClientV2({});
+
+async function ragPipeline(query, documents) {
+  // Step 1: Embed documents
+  const embedResponse = await cohere.embed({
+    model: "embed-english-v3.0",
+    texts: documents,
+    inputType: "search_document"
+  });
+
+  // Step 2: Embed query
+  const queryEmbedResponse = await cohere.embed({
+    model: "embed-english-v3.0",
+    texts: [query],
+    inputType: "search_query"
+  });
+
+  // Step 3: Find top candidates using similarity (simplified)
+  const topDocs = documents.slice(0, 10); // In production, use vector DB
+
+  // Step 4: Rerank for precision
+  const rerankResponse = await cohere.rerank({
+    model: "rerank-english-v3.0",
+    query: query,
+    documents: topDocs,
+    topN: 3
+  });
+
+  // Step 5: Generate answer with context
+  const context = rerankResponse.results
+    .map(r => r.document.text)
+    .join("\n\n");
+
+  const chatResponse = await cohere.chat({
+    model: "command-a-03-2025",
+    messages: [
+      {
+        role: "system",
+        content: `Answer the question based on this context:\n\n${context}`
+      },
+      { role: "user", content: query }
+    ]
+  });
+
+  return {
+    answer: chatResponse.message.content[0].text,
+    sources: rerankResponse.results
+  };
+}
+
+// Usage
+const docs = [
+  "Machine learning is a subset of AI that enables systems to learn from data.",
+  "Deep learning uses neural networks with multiple layers.",
+  "Supervised learning requires labeled training data.",
+  // ... more documents
+];
+
+const result = await ragPipeline("What is machine learning?", docs);
+console.log(result.answer);
+```
+
+### Tool Use (Function Calling)
+
+Enable the model to call external functions and APIs.
+
+**Minimal Example:**
+```javascript
+const tools = [
+  {
+    type: "function",
+    function: {
+      name: "get_weather",
+      description: "Get current weather for a location",
+      parameters: {
+        type: "object",
+        properties: {
+          location: {
+            type: "string",
+            description: "City name"
+          },
+          unit: {
+            type: "string",
+            enum: ["celsius", "fahrenheit"]
+          }
+        },
+        required: ["location"]
+      }
+    }
+  }
+];
+
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [
+    { role: "user", content: "What's the weather in San Francisco?" }
+  ],
+  tools: tools
+});
+
+if (response.message.toolCalls) {
+  console.log("Function to call:", response.message.toolCalls[0].function.name);
+  console.log("Arguments:", response.message.toolCalls[0].function.arguments);
+}
+```
+
+**Advanced Multi-Step Tool Use:**
+```javascript
+const tools = [
+  {
+    type: "function",
+    function: {
+      name: "search_database",
+      description: "Search internal knowledge base",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+          limit: { type: "integer", default: 5 }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "calculate",
+      description: "Perform mathematical calculations",
+      parameters: {
+        type: "object",
+        properties: {
+          expression: { type: "string" }
+        },
+        required: ["expression"]
+      }
+    }
+  }
+];
+
+// Initial request
+let messages = [
+  { role: "user", content: "Search for quantum computing papers and calculate citations" }
+];
+
+const firstResponse = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: messages,
+  tools: tools
+});
+
+// Execute tool calls
+if (firstResponse.message.toolCalls) {
+  for (const toolCall of firstResponse.message.toolCalls) {
+    const functionName = toolCall.function.name;
+    const args = JSON.parse(toolCall.function.arguments);
+
+    // Execute function (mock example)
+    let result;
+    if (functionName === "search_database") {
+      result = { papers: ["Paper A", "Paper B"], citations: [42, 38] };
+    }
+
+    // Add tool result to conversation
+    messages.push({
+      role: "tool",
+      content: JSON.stringify(result),
+      toolCallId: toolCall.id
+    });
+  }
+
+  // Get final response
+  const finalResponse = await cohere.chat({
+    model: "command-a-03-2025",
+    messages: messages,
+    tools: tools
+  });
+
+  console.log(finalResponse.message.content[0].text);
+}
+```
+
+### Web Search Connector
+
+Use Cohere's built-in web search to ground responses in current information.
+
+**Example:**
+```javascript
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [
+    { role: "user", content: "What are the latest developments in fusion energy?" }
+  ],
+  connectors: [{ id: "web-search" }]
+});
+
+console.log(response.message.content[0].text);
+
+// Access citations
+if (response.message.citations) {
+  console.log("\nSources:");
+  response.message.citations.forEach((citation) => {
+    console.log(`- ${citation.sources[0]}`);
+  });
+}
+```
+
+### Citations
+
+Enable inline citations for transparency and verification.
+
+**Example:**
+```javascript
+const documents = [
+  { id: "doc1", text: "AI was founded as an academic discipline in 1956." },
+  { id: "doc2", text: "Machine learning is a subset of AI." },
+  { id: "doc3", text: "Deep learning breakthrough occurred in 2012." }
+];
+
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [
+    { role: "user", content: "When was AI founded?" }
+  ],
+  documents: documents
+});
+
+console.log(response.message.content[0].text);
+
+// Access citations
+if (response.message.citations) {
+  response.message.citations.forEach((citation) => {
+    console.log(`\nCitation: "${citation.text}"`);
+    console.log(`Source: Document ${citation.documentIds.join(", ")}`);
+  });
+}
+```
+
+## 6. TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions.
+
+### Type Imports
+
+```typescript
+import {
+  CohereClientV2,
+  ChatRequest,
+  ChatResponse,
+  ChatStreamRequest,
+  EmbedRequest,
+  EmbedResponse,
+  RerankRequest,
+  RerankResponse,
+  CohereError,
+  CohereTimeoutError
+} from "cohere-ai";
+```
+
+### Type-Safe Chat
+
+```typescript
+import { CohereClientV2, ChatRequest } from "cohere-ai";
+
+const cohere = new CohereClientV2({ token: process.env.COHERE_API_KEY });
+
+const request: ChatRequest = {
+  model: "command-a-03-2025",
+  messages: [
+    { role: "user", content: "Explain TypeScript benefits" }
+  ],
+  temperature: 0.3,
+  maxTokens: 1000
+};
+
+const response = await cohere.chat(request);
+const text: string = response.message.content[0].text;
+```
+
+### Type-Safe Embeddings
+
+```typescript
+import { EmbedRequest, EmbedResponse } from "cohere-ai";
+
+const embedRequest: EmbedRequest = {
+  model: "embed-english-v3.0",
+  texts: ["Sample text"],
+  inputType: "classification"
+};
+
+const embedResponse: EmbedResponse = await cohere.embed(embedRequest);
+const embeddings: number[][] = embedResponse.embeddings;
+```
+
+### Custom Types
+
+```typescript
+interface DocumentWithMetadata {
+  id: string;
+  text: string;
+  category: string;
+  timestamp: Date;
+}
+
+async function embedDocuments(docs: DocumentWithMetadata[]) {
+  const texts = docs.map(d => d.text);
+
+  const response = await cohere.embed({
+    model: "embed-english-v3.0",
+    texts: texts,
+    inputType: "search_document"
+  });
+
+  return docs.map((doc, idx) => ({
+    ...doc,
+    embedding: response.embeddings[idx]
+  }));
+}
+```
+
+## 7. Best Practices
+
+### Error Handling
+
+**Always wrap API calls in try-catch blocks:**
+
+```javascript
+import { CohereClientV2, CohereError, CohereTimeoutError } from "cohere-ai";
+
+const cohere = new CohereClientV2({});
+
+async function generateText(prompt) {
+  try {
+    const response = await cohere.chat({
+      model: "command-a-03-2025",
+      messages: [{ role: "user", content: prompt }]
+    });
+    return response.message.content[0].text;
+  } catch (err) {
+    if (err instanceof CohereTimeoutError) {
+      console.error("Request timed out:", err.message);
+      // Retry logic here
+    } else if (err instanceof CohereError) {
+      console.error(`API Error ${err.statusCode}:`, err.message);
+      console.error("Error body:", err.body);
+
+      // Handle specific error codes
+      if (err.statusCode === 429) {
+        console.error("Rate limit exceeded");
+        // Implement backoff strategy
+      } else if (err.statusCode === 401) {
+        console.error("Invalid API key");
+      } else if (err.statusCode === 402) {
+        console.error("Billing limit reached");
+      }
+    } else {
+      console.error("Unexpected error:", err);
+    }
+    throw err;
+  }
+}
+```
+
+### Timeout Configuration
+
+```javascript
+// Set custom timeout (default is 60 seconds)
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "Hello" }]
+}, {
+  timeoutInSeconds: 10
+});
+```
+
+### Retry Configuration
+
+```javascript
+// Configure retries (default: 2 retries with exponential backoff)
+// 409 Conflict, 429 Rate Limit, and >=500 errors are automatically retried
+
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "Hello" }]
+}, {
+  maxRetries: 3
+});
+
+// Disable retries
+const responseNoRetry = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "Hello" }]
+}, {
+  maxRetries: 0
+});
+```
+
+### Rate Limiting
+
+**Trial Keys:** Chat 20 calls/minute, Embed 5 calls/minute, all endpoints 1,000 calls/month total.
+
+**Production Keys:** Chat 500 requests/minute, Embed (Text) 2,000 requests/minute, Embed (Images) 400 requests/minute, Rerank 1,000 requests/minute, unlimited monthly usage.
+
+**Handle rate limits gracefully:**
+
+```javascript
+async function chatWithBackoff(messages, retries = 3, delay = 1000) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await cohere.chat({
+        model: "command-a-03-2025",
+        messages: messages
+      });
+    } catch (err) {
+      if (err instanceof CohereError && err.statusCode === 429) {
+        if (i < retries - 1) {
+          console.log(`Rate limited, retrying in ${delay}ms...`);
+          await new Promise(resolve => setTimeout(resolve, delay));
+          delay *= 2; // Exponential backoff
+        } else {
+          throw err;
+        }
+      } else {
+        throw err;
+      }
+    }
+  }
+}
+```
+
+### Model Selection
+
+**Current Production Models (as of 2025):** `command-a-03-2025` (latest Command A model with 256K context, 111B parameters, highest throughput - 150% faster than Command R+), `command-r-plus-08-2024` (Command R+ with strong reasoning capabilities), `embed-english-v3.0` (English embeddings with 1024 dimensions), `embed-multilingual-v3.0` (multilingual embeddings supporting 100+ languages), `rerank-english-v3.0` (English reranking model), and `rerank-multilingual-v3.0` (multilingual reranking).
+
+**Choosing the right model:**
+
+```javascript
+// For general chat and high throughput
+const model = "command-a-03-2025";
+
+// For embeddings - English only
+const embedModel = "embed-english-v3.0";
+
+// For embeddings - Multilingual
+const multilingualEmbedModel = "embed-multilingual-v3.0";
+
+// For reranking search results
+const rerankModel = "rerank-english-v3.0";
+```
+
+### Temperature Guidelines
+
+**Temperature** controls randomness (0.0 to 1.0, default 0.3):
+
+```javascript
+// Deterministic, factual responses
+const factualResponse = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "What is 2+2?" }],
+  temperature: 0
+});
+
+// Balanced (default)
+const balancedResponse = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "Explain photosynthesis" }],
+  temperature: 0.3
+});
+
+// Creative, varied responses
+const creativeResponse = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "Write a poem" }],
+  temperature: 0.8
+});
+```
+
+**Warning:** High temperatures (>0.9) can introduce hallucinations and factually incorrect information.
+
+### Token Management
+
+```javascript
+// Control max output length
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "Summarize this in 50 words" }],
+  maxTokens: 100
+});
+
+// Monitor token usage (available in streaming)
+const stream = await cohere.chatStream({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "Hello" }]
+});
+
+for await (const event of stream) {
+  if (event.type === "message-end" && event.delta?.usage) {
+    console.log(`Input tokens: ${event.delta.usage.inputTokens}`);
+    console.log(`Output tokens: ${event.delta.usage.outputTokens}`);
+  }
+}
+```
+
+### Security Best Practices
+
+**API Key Management:**
+
+```javascript
+// ✅ CORRECT: Use environment variables
+const cohere = new CohereClientV2({
+  token: process.env.COHERE_API_KEY
+});
+
+// ❌ WRONG: Never hardcode API keys
+const cohere = new CohereClientV2({
+  token: "sk-xxxxxx" // DON'T DO THIS
+});
+```
+
+**Input Validation:**
+
+```javascript
+function validateInput(text) {
+  if (!text || typeof text !== "string") {
+    throw new Error("Invalid input: text must be a non-empty string");
+  }
+  if (text.length > 100000) {
+    throw new Error("Input too long");
+  }
+  return text.trim();
+}
+
+async function safeChat(userInput) {
+  const validatedInput = validateInput(userInput);
+
+  return await cohere.chat({
+    model: "command-a-03-2025",
+    messages: [{ role: "user", content: validatedInput }]
+  });
+}
+```
+
+**Safety Mode:**
+
+```javascript
+// Enable contextual safety filtering
+const response = await cohere.chat({
+  model: "command-a-03-2025",
+  messages: [{ role: "user", content: "User message" }],
+  safetyMode: "CONTEXTUAL" // or "STRICT" or "NONE"
+});
+```
+
+### Performance Optimization
+
+**Batch Embeddings:**
+
+```javascript
+// ✅ GOOD: Batch multiple texts in one request
+const texts = ["text1", "text2", "text3", /* ... up to 96 texts */];
+const response = await cohere.embed({
+  model: "embed-english-v3.0",
+  texts: texts,
+  inputType: "search_document"
+});
+
+// ❌ INEFFICIENT: Multiple individual requests
+for (const text of texts) {
+  await cohere.embed({
+    model: "embed-english-v3.0",
+    texts: [text],
+    inputType: "search_document"
+  });
+}
+```
+
+**Streaming for Long Responses:**
+
+```javascript
+// Use streaming for better user experience
+async function streamResponse(prompt) {
+  const stream = await cohere.chatStream({
+    model: "command-a-03-2025",
+    messages: [{ role: "user", content: prompt }]
+  });
+
+  for await (const event of stream) {
+    if (event.type === "content-delta") {
+      // Display partial results immediately
+      process.stdout.write(event.delta?.message?.content?.text || "");
+    }
+  }
+}
+```
+
+**Caching Strategy:**
+
+```javascript
+// Cache embeddings to avoid redundant API calls
+class EmbeddingCache {
+  constructor() {
+    this.cache = new Map();
+  }
+
+  async getEmbedding(text, cohere) {
+    if (this.cache.has(text)) {
+      return this.cache.get(text);
+    }
+
+    const response = await cohere.embed({
+      model: "embed-english-v3.0",
+      texts: [text],
+      inputType: "search_document"
+    });
+
+    const embedding = response.embeddings[0];
+    this.cache.set(text, embedding);
+    return embedding;
+  }
+}
+```
+
+## 8. Production Checklist
+
+### Version Management
+
+```json
+// package.json - Pin exact SDK version
+{
+  "dependencies": {
+    "cohere-ai": "7.14.0"
+  }
+}
+```
+
+- Pin exact SDK version in `package.json`
+- Review changelog before upgrading
+- Test thoroughly in staging before production deployment
+- Monitor Cohere's release notes for breaking changes
+
+### Environment Configuration
+
+```javascript
+// config.js
+const config = {
+  development: {
+    cohereApiKey: process.env.COHERE_API_KEY_DEV,
+    model: "command-a-03-2025",
+    timeout: 30,
+    maxRetries: 2
+  },
+  production: {
+    cohereApiKey: process.env.COHERE_API_KEY_PROD,
+    model: "command-a-03-2025",
+    timeout: 60,
+    maxRetries: 3
+  }
+};
+
+const env = process.env.NODE_ENV || "development";
+export default config[env];
+```
+
+**Environment variables:** Set `COHERE_API_KEY` or `CO_API_KEY`, `NODE_ENV` (development/staging/production), use separate API keys for each environment, and use secret management systems (AWS Secrets Manager, Azure Key Vault, etc.).
+
+### Error Handling & Monitoring
+
+```javascript
+import { CohereClientV2, CohereError, CohereTimeoutError } from "cohere-ai";
+
+class CohereService {
+  constructor(logger, metrics) {
+    this.cohere = new CohereClientV2({
+      token: process.env.COHERE_API_KEY
+    });
+    this.logger = logger;
+    this.metrics = metrics;
+  }
+
+  async chat(messages, options = {}) {
+    const startTime = Date.now();
+
+    try {
+      const response = await this.cohere.chat({
+        model: "command-a-03-2025",
+        messages: messages,
+        ...options
+      }, {
+        timeoutInSeconds: 60,
+        maxRetries: 3
+      });
+
+      // Log success metrics
+      const duration = Date.now() - startTime;
+      this.metrics.recordSuccess("chat", duration);
+      this.logger.info("Chat request succeeded", {
+        duration,
+        model: "command-a-03-2025"
+      });
+
+      return response;
+
+    } catch (err) {
+      const duration = Date.now() - startTime;
+
+      if (err instanceof CohereTimeoutError) {
+        this.metrics.recordError("chat", "timeout");
+        this.logger.error("Chat request timed out", { duration });
+      } else if (err instanceof CohereError) {
+        this.metrics.recordError("chat", `http_${err.statusCode}`);
+        this.logger.error("Chat request failed", {
+          statusCode: err.statusCode,
+          message: err.message,
+          duration
+        });
+
+        // Alert on specific errors
+        if (err.statusCode === 429) {
+          this.logger.warn("Rate limit exceeded");
+        } else if (err.statusCode >= 500) {
+          this.logger.error("Cohere service error", { statusCode: err.statusCode });
+        }
+      } else {
+        this.metrics.recordError("chat", "unknown");
+        this.logger.error("Unexpected error", { error: err });
+      }
+
+      throw err;
+    }
+  }
+}
+```
+
+### Validate Responses
+
+```javascript
+function validateChatResponse(response) {
+  if (!response || !response.message) {
+    throw new Error("Invalid response: missing message");
+  }
+
+  if (!response.message.content || response.message.content.length === 0) {
+    throw new Error("Invalid response: empty content");
+  }
+
+  if (!response.message.content[0].text) {
+    throw new Error("Invalid response: missing text");
+  }
+
+  return true;
+}
+
+async function safeChat(messages) {
+  const response = await cohere.chat({
+    model: "command-a-03-2025",
+    messages: messages
+  });
+
+  validateChatResponse(response);
+  return response.message.content[0].text;
+}
+```
+
+### Testing Strategy
+
+```javascript
+// Mock Cohere client for testing
+class MockCohereClient {
+  async chat({ messages }) {
+    return {
+      message: {
+        content: [{ text: "Mocked response" }],
+        role: "assistant"
+      }
+    };
+  }
+
+  async embed({ texts }) {
+    return {
+      embeddings: texts.map(() => Array(1024).fill(0))
+    };
+  }
+}
+
+// Test example
+describe("CohereService", () => {
+  it("should handle chat requests", async () => {
+    const mockClient = new MockCohereClient();
+    const service = new CohereService(mockClient);
+
+    const response = await service.chat([
+      { role: "user", content: "test" }
+    ]);
+
+    expect(response.message.content[0].text).toBe("Mocked response");
+  });
+});
+```
+
+### Monitoring Checklist
+
+**Metrics to track:** Request count (by endpoint, model), success rate, error rate (by error type, status code), latency (p50, p95, p99), token usage, rate limit hits, and timeout frequency.
+
+**Logging requirements:** All API errors with context, rate limit warnings, unusual latency spikes, and token usage patterns.
+
+**Alerting:** Error rate > 5%, rate limit exceeded, average latency > 10 seconds, service availability < 99%.
+
+### API Key Rotation
+
+```javascript
+class CohereClientManager {
+  constructor() {
+    this.client = null;
+    this.apiKey = null;
+  }
+
+  initialize(apiKey) {
+    this.apiKey = apiKey;
+    this.client = new CohereClientV2({ token: apiKey });
+  }
+
+  rotateApiKey(newApiKey) {
+    console.log("Rotating API key...");
+    this.apiKey = newApiKey;
+    this.client = new CohereClientV2({ token: newApiKey });
+    console.log("API key rotated successfully");
+  }
+
+  getClient() {
+    if (!this.client) {
+      throw new Error("Client not initialized");
+    }
+    return this.client;
+  }
+}
+
+// Usage
+const manager = new CohereClientManager();
+manager.initialize(process.env.COHERE_API_KEY);
+
+// When rotating keys
+manager.rotateApiKey(process.env.NEW_COHERE_API_KEY);
+```
+
+### Cost Optimization
+
+**Monitor usage:**
+
+```javascript
+class UsageTracker {
+  constructor() {
+    this.usage = {
+      requests: 0,
+      inputTokens: 0,
+      outputTokens: 0
+    };
+  }
+
+  async trackChat(messages) {
+    this.usage.requests++;
+
+    const stream = await cohere.chatStream({
+      model: "command-a-03-2025",
+      messages: messages
+    });
+
+    for await (const event of stream) {
+      if (event.type === "message-end" && event.delta?.usage) {
+        this.usage.inputTokens += event.delta.usage.inputTokens || 0;
+        this.usage.outputTokens += event.delta.usage.outputTokens || 0;
+      }
+    }
+
+    return this.getUsage();
+  }
+
+  getUsage() {
+    return { ...this.usage };
+  }
+}
+```
+
+**Optimize costs:** Use appropriate models (don't use command-a-03-2025 for simple tasks), set reasonable `maxTokens` limits, cache embeddings and rerank results, batch requests when possible, and use streaming to cancel long-running requests early if needed.
+
+### Upgrade to Production API Key
+
+**Trial key limitations:** 20 chat calls/minute, 5 embed calls/minute, 1,000 calls/month total.
+
+**To upgrade:** Add payment method in Cohere dashboard, get production API key, update `COHERE_API_KEY` environment variable, and verify rate limits increased.
+
+**Production benefits:** 500+ requests/minute (varies by endpoint), unlimited monthly usage, priority support, and higher rate limits available on request.
+
+### Compliance & Safety
+
+```javascript
+// Content moderation example
+async function moderatedChat(userMessage) {
+  const response = await cohere.chat({
+    model: "command-a-03-2025",
+    messages: [{ role: "user", content: userMessage }],
+    safetyMode: "STRICT"
+  });
+
+  // Log for compliance audit
+  auditLogger.log({
+    timestamp: new Date().toISOString(),
+    userId: getCurrentUserId(),
+    input: userMessage,
+    output: response.message.content[0].text,
+    model: "command-a-03-2025"
+  });
+
+  return response;
+}
+```
+
+**Compliance considerations:** Log all interactions for audit trails, implement content filtering, handle PII appropriately, follow data retention policies, and comply with regional regulations (GDPR, CCPA, etc.)
+
+### Deployment Checklist
+
+Ensure API key is stored in secure secret management system, exact SDK version is pinned in `package.json`, comprehensive error handling is implemented, timeout and retry configuration is set, response validation is in place, logging and monitoring is configured, rate limiting is handled gracefully, tests cover error scenarios, load testing is completed, alerting rules are configured, documentation is updated, staging environment is tested, rollback plan is prepared, and team is trained on debugging procedures.
+
+---
+
+## Additional Resources
+
+Access comprehensive documentation and resources using the npm CLI:
+
+```bash
+# View package information and links
+npm info cohere-ai
+
+# Open package homepage in browser
+npm home cohere-ai
+
+# Open package repository in browser
+npm repo cohere-ai
+
+# Open package issues page
+npm bugs cohere-ai
+
+# View package documentation
+npm docs cohere-ai
+```
+
+Official documentation available at: https://docs.cohere.com/reference/about