@traceai/cohere 0.1.0 → 0.1.1

package/README.md

@@ -1,436 +1,145 @@
 # @traceai/cohere
 
-OpenTelemetry instrumentation for the [Cohere](https://cohere.com/) TypeScript/JavaScript SDK.
+Trace Cohere chat, streaming chat, embeddings and reranking in Future AGI with the maintained Cohere SDK instrumentor.
 
-## Installation
+## Install
 
 ```bash
-npm install @traceai/cohere
-# or
-pnpm add @traceai/cohere
-# or
-yarn add @traceai/cohere
+npm install @traceai/cohere @traceai/fi-core cohere-ai
 ```
 
-## Features
+Use Node.js 18 or later and `cohere-ai` 7.x or 8.x. Use `cohere-ai` 8.3.0 for the v2 examples below. The 7.0.0 SDK only exposes the older v1 operations; streaming requires a version with `chatStream`.
 
-- Automatic instrumentation of Cohere API calls
-- Supports chat, embed, and rerank APIs
-- Captures request parameters, model information, and responses
-- Configurable input/output hiding for privacy
-- Compatible with OpenTelemetry ecosystem
+## Configure tracing
 
-## Usage
+Set `FI_API_KEY`, `FI_SECRET_KEY` and `COHERE_API_KEY` in your environment. Get your Future AGI credentials from your organization's settings.
 
-### Basic Setup
+Initialize tracing **before constructing any Cohere clients**. Explicit module instrumentation works with both CommonJS and native ESM, without an import hook or copied tracing helpers.
 
 ```typescript
+import { register, ProjectType } from "@traceai/fi-core";
 import { CohereInstrumentation } from "@traceai/cohere";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { registerInstrumentations } from "@opentelemetry/instrumentation";
-
-// Set up the tracer provider
-const provider = new NodeTracerProvider();
-provider.register();
-
-// Register the Cohere instrumentation
-registerInstrumentations({
-  instrumentations: [new CohereInstrumentation()],
-});
-
-// Now use the Cohere SDK as normal
-import { CohereClient } from "cohere-ai";
-
-const cohere = new CohereClient({
-  token: process.env.COHERE_API_KEY,
-});
-
-// Chat example
-const chatResponse = await cohere.chat({
-  message: "Hello, how are you?",
-  model: "command-r-08-2024",
-});
-
-// Embed example
-const embedResponse = await cohere.embed({
-  texts: ["hello", "goodbye"],
-  model: "embed-english-v3.0",
-  inputType: "search_document",
-});
+import * as Cohere from "cohere-ai";
 
-// Rerank example
-const rerankResponse = await cohere.rerank({
-  query: "What is the capital of France?",
-  documents: [
-    "Paris is the capital of France.",
-    "Berlin is the capital of Germany.",
-    "London is the capital of the United Kingdom.",
-  ],
-  model: "rerank-english-v3.0",
+const provider = register({
+  projectName: "cohere-app",
+  projectType: ProjectType.OBSERVE,
 });
-```
-
-### Manual Instrumentation
-
-If automatic instrumentation doesn't work (e.g., with bundlers), you can manually instrument:
-
-```typescript
-import { CohereInstrumentation } from "@traceai/cohere";
-import * as CohereModule from "cohere-ai";
 
-const instrumentation = new CohereInstrumentation();
-instrumentation.manuallyInstrument(CohereModule);
-```
-
-### Configuration Options
-
-```typescript
 const instrumentation = new CohereInstrumentation({
-  // OpenTelemetry instrumentation config
-  instrumentationConfig: {
-    enabled: true,
-  },
-  // TraceAI-specific config
   traceConfig: {
-    hideInputs: false, // Set to true to hide input content in traces
-    hideOutputs: false, // Set to true to hide output content in traces
+    hideInputs: true,
+    hideOutputs: true,
+    hideEmbeddingVectors: true,
   },
 });
-```
-
-### With TraceAI Core
+instrumentation.setTracerProvider(provider);
+instrumentation.manuallyInstrument(Cohere);
 
-```typescript
-import { register, ProjectType } from "@traceai/fi-core";
-import { CohereInstrumentation } from "@traceai/cohere";
-import { registerInstrumentations } from "@opentelemetry/instrumentation";
-
-// 1. Register TraceAI Core TracerProvider
-const tracerProvider = register({
-  projectName: "my-cohere-app",
-  projectType: ProjectType.OBSERVE,
-  sessionName: "cohere-session-" + Date.now(),
-});
-
-// 2. Register instrumentation BEFORE importing Cohere SDK
-registerInstrumentations({
-  tracerProvider: tracerProvider,
-  instrumentations: [new CohereInstrumentation()],
-});
-
-// 3. NOW import and use Cohere
-const { CohereClient } = await import("cohere-ai");
-const client = new CohereClient({ token: process.env.COHERE_API_KEY });
-
-// 4. Use normally - all calls are traced
-const response = await client.chat({
-  message: "Hello!",
-  model: "command-r-08-2024",
+const client = new Cohere.CohereClientV2({
+  token: process.env.COHERE_API_KEY,
 });
 
-// 5. Shutdown when done
-await tracerProvider.shutdown();
-```
-
-## Real-World Use Cases
-
-### 1. Conversational AI with Chat History
-
-```typescript
-const { CohereClient } = await import("cohere-ai");
-const client = new CohereClient({ token: process.env.COHERE_API_KEY });
-
-async function chat(message: string, history: Array<{ role: string; message: string }>) {
+try {
   const response = await client.chat({
-    message,
     model: "command-r-08-2024",
-    chatHistory: history,
-    preamble: "You are a helpful customer support agent for an e-commerce platform.",
+    messages: [{ role: "user", content: "Explain semantic search in one sentence." }],
   });
-
-  // Add to history
-  history.push({ role: "USER", message });
-  history.push({ role: "CHATBOT", message: response.text });
-
-  return response.text;
+  console.log(response.message);
+} finally {
+  instrumentation.disable();
+  await provider.shutdown();
 }
-
-// Usage
-const history: Array<{ role: string; message: string }> = [];
-const answer1 = await chat("I have a problem with my order", history);
-const answer2 = await chat("Order ID is 12345", history);
 ```
 
-### 2. Semantic Search with Embeddings
-
-```typescript
-async function semanticSearch(query: string, documents: string[]) {
-  // Get query embedding (use 'search_query' for queries)
-  const queryEmbedding = await client.embed({
-    texts: [query],
-    model: "embed-english-v3.0",
-    inputType: "search_query",
-  });
+Open the **cohere-app** project in Future AGI to inspect the `Cohere Chat` span, model and token usage. This example hides request/response content, embedding vectors and error details. To inspect content in traces, explicitly turn off the corresponding hiding options only when it is safe for your application.
 
-  // Get document embeddings (use 'search_document' for documents)
-  const docEmbeddings = await client.embed({
-    texts: documents,
-    model: "embed-english-v3.0",
-    inputType: "search_document",
-  });
+If you already have an OpenTelemetry tracer provider, pass it to `setTracerProvider` instead of creating a second provider. For CommonJS auto-instrumentation, register `CohereInstrumentation` with OpenTelemetry before requiring `cohere-ai`; do not also install another Cohere instrumentor.
 
-  // Calculate cosine similarities
-  const queryVector = queryEmbedding.embeddings[0] as number[];
-  const similarities = (docEmbeddings.embeddings as number[][]).map((docVector, i) => ({
-    document: documents[i],
-    score: cosineSimilarity(queryVector, docVector),
-  }));
+## Stream a response
 
-  return similarities.sort((a, b) => b.score - a.score);
-}
-```
-
-### 3. Document Reranking for RAG
+With the same initialized client, replace the chat call with:
 
 ```typescript
-async function rerankDocuments(query: string, documents: string[]) {
-  const response = await client.rerank({
-    query,
-    documents,
-    model: "rerank-english-v3.0",
-    topN: 5,
-    returnDocuments: true,
-  });
-
-  return response.results.map((result) => ({
-    document: result.document?.text,
-    score: result.relevanceScore,
-    originalIndex: result.index,
-  }));
-}
-
-// Usage in RAG pipeline
-const retrievedDocs = await vectorSearch(userQuery, 20); // Get top 20 from vector DB
-const rerankedDocs = await rerankDocuments(userQuery, retrievedDocs);
-const topDocs = rerankedDocs.slice(0, 3); // Use top 3 for context
-```
-
-### 4. Tool-Augmented Chatbot
-
-```typescript
-async function chatWithTools(message: string) {
-  const response = await client.chat({
-    message,
-    model: "command-r-08-2024",
-    tools: [
-      {
-        name: "search_database",
-        description: "Search the product database",
-        parameterDefinitions: {
-          query: { type: "str", description: "Search query", required: true },
-          category: { type: "str", description: "Product category", required: false },
-        },
-      },
-      {
-        name: "get_order_status",
-        description: "Get status of a customer order",
-        parameterDefinitions: {
-          orderId: { type: "str", description: "Order ID", required: true },
-        },
-      },
-    ],
-  });
+const stream = await client.chatStream({
+  model: "command-r-08-2024",
+  messages: [{ role: "user", content: "Explain semantic search in one sentence." }],
+});
 
-  if (response.toolCalls && response.toolCalls.length > 0) {
-    // Execute tool calls and continue conversation
-    for (const toolCall of response.toolCalls) {
-      console.log(`Tool: ${toolCall.name}, Args:`, toolCall.parameters);
-    }
+for await (const event of stream) {
+  if (event.type === "content-start" || event.type === "content-delta") {
+    process.stdout.write(event.delta?.message?.content?.text ?? "");
   }
-
-  return response;
 }
 ```
 
-### 5. Multilingual Embeddings
+The span stays open while you consume the stream. It finishes at the terminal event, iterator completion, failure, early return or controller abort. Breaking or returning from the iterator, aborting its controller, or receiving `USER_CANCEL` sets `cohere.stream.cancelled` and leaves the span status unset. A stream that ends without a terminal event is an error, not a cancellation.
 
-```typescript
-async function multilingualSearch(query: string, documents: string[]) {
-  // Use multilingual model for cross-language search
-  const queryEmbedding = await client.embed({
-    texts: [query],
-    model: "embed-multilingual-v3.0",
-    inputType: "search_query",
-  });
+For both chat and streaming chat, `ERROR`, `ERROR_TOXIC`, `ERROR_LIMIT` and `TIMEOUT` finish reasons mark the span as an error. A nonstreaming `USER_CANCEL` response sets `cohere.request.cancelled` with an unset status. Partial generated output is retained when content capture is enabled; token counts are available only if Cohere sends usage. These telemetry statuses do not change SDK results or turn resolved responses into exceptions.
 
-  const docEmbeddings = await client.embed({
-    texts: documents,
-    model: "embed-multilingual-v3.0",
-    inputType: "search_document",
-  });
-
-  // Works across languages!
-  // Query in English can match documents in French, German, Spanish, etc.
-  return calculateSimilarities(queryEmbedding, docEmbeddings);
-}
-```
+Consume the stream or explicitly close/abort it rather than abandoning it. SDK stream controllers, events and `withRawResponse()` remain available.
 
-### 6. Streaming Chat Responses
+## Embed and rerank
 
 ```typescript
-async function streamChat(message: string) {
-  const stream = await client.chatStream({
-    message,
-    model: "command-r-08-2024",
-  });
-
-  let fullText = "";
-  for await (const event of stream) {
-    if (event.eventType === "text-generation") {
-      process.stdout.write(event.text);
-      fullText += event.text;
-    } else if (event.eventType === "stream-end") {
-      console.log("\n--- Stream complete ---");
-      console.log("Token usage:", event.response?.meta?.tokens);
-    }
-  }
+await client.embed({
+  model: "embed-english-v3.0",
+  texts: ["Paris is the capital of France."],
+  inputType: "search_document",
+  embeddingTypes: ["float"],
+});
 
-  return fullText;
-}
+await client.rerank({
+  model: "rerank-v3.5",
+  query: "What is the capital of France?",
+  documents: ["Paris is the capital of France.", "Berlin is the capital of Germany."],
+  topN: 1,
+});
 ```
 
-## Traced Operations
+Embeddings use the `EMBEDDING` span kind; reranking uses `RERANKER`, including result indices and relevance scores. Chat uses `LLM`. The instrumentor reads the SDK's camelCase properties, including `chatHistory`, `toolCalls`, `inputTokens` and `relevanceScore`, and retains support for v1 payloads.
 
-### Chat API
+## Usage, provenance and streaming timing
 
-The instrumentation captures:
+The following numeric attributes are captured independently of input/output hiding:
 
-- Model name
-- Input messages and chat history
-- Preamble and connectors
-- Temperature and other generation parameters
-- Response text and metadata
-- Token usage (prompt and completion tokens)
+| Attribute | Meaning |
+| --- | --- |
+| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.total_tokens` | Actual tokens when supplied. For older responses without `tokens`, input/output billed units remain the fallback. |
+| `gen_ai.usage.cache_read_tokens` | Cohere's supplied `cachedTokens` (cached prompt tokens); not added to the total again. |
+| `cohere.usage.billed_units.input_tokens`, `cohere.usage.billed_units.output_tokens` | Separately supplied billable tokens, which can differ from actual tokens. |
+| `cohere.usage.billed_units.search_units`, `cohere.usage.billed_units.classifications` | Supplied billable operation units, not token counts. |
+| `cohere.usage.billed_units.images`, `cohere.usage.billed_units.image_tokens` | Supplied billable image counts and image tokens, respectively. |
+| `cohere.stream.time_to_first_token_ms` | Monotonic elapsed milliseconds from SDK request invocation until the first consumed nonempty generated text, reasoning, tool plan, or tool name/argument fragment. |
 
-### Embed API
+Missing usage is not synthesized. First-token timing includes request/headers latency and any delay before the consumer reads the first content event; it is not server-side inference timing. Metadata-only, empty, or cancelled-before-content streams have no timing value. A recorded value survives later cancellation or failure and is not replaced by subsequent chunks.
 
-The instrumentation captures:
+`gen_ai.response.id` retains the provider generation/response ID, including IDs delivered at stream start, even when content is hidden or the stream later fails or is cancelled.
 
-- Model name
-- Input texts
-- Input type
-- Truncation settings
-- Output embeddings (unless hidden)
-- Token usage
+With output capture enabled, v2 streamed citations are accumulated by index in `gen_ai.output.messages` and `raw.output`, including partial streams. Input hiding retains citation offsets, generated citation text and source IDs/types but removes source document/tool bodies. Output hiding omits citations along with the rest of the generated content. These projections never change the SDK events or responses delivered to your application.
 
-### Rerank API
+## Existing v1 applications
 
-The instrumentation captures:
+Keep using `CohereClient`, `CohereInstrumentation` and `manuallyInstrument` with the same setup. Calls through `CohereClient.v2` and `CohereClientV2` are also traced when available in your SDK. Disable/enable applies to subsequent calls, including already-bound v2 methods; in-flight calls finish their spans normally.
 
-- Model name
-- Query text
-- Documents to rerank
-- Top N parameter
-- Reranked results with relevance scores
+This integration covers `chat`, `chatStream`, `embed` and `rerank`, not every endpoint on the Cohere SDK. It does not infer a default model when no model was supplied.
 
-## Semantic Conventions
+## Troubleshooting
 
-This instrumentation follows OpenTelemetry semantic conventions and FutureAGI conventions for LLM observability:
+- **No v2 spans:** initialize instrumentation before constructing the client. V2 binds its methods in the constructor; recreate clients constructed before setup.
+- **Duplicate spans:** use one Cohere instrumentor per application and remove overlapping instrumentation.
+- **A stream span never finishes:** consume the stream, break/return from its iterator, or abort its controller before shutting down the provider.
+- **Missing content or vectors:** check your `traceConfig` and `FI_HIDE_*` environment settings. Input/output hiding also applies to Cohere-specific fields and raw payloads; vector hiding excludes the raw embedding response. Connector access tokens are always omitted from telemetry, regardless of content settings; requests to Cohere retain them.
 
-- Span names follow the pattern: `cohere.{operation}` (e.g., `cohere.chat`, `cohere.embed`, `cohere.rerank`)
-- Uses `LLM` span kind for chat operations
-- Uses `EMBEDDING` span kind for embed operations
-- Uses `RERANKER` span kind for rerank operations
+## Development
 
-## Supported Models
-
-### Chat Models
-
-- command
-- command-r
-- command-r-08-2024
-- command-light
-- command-nightly
-
-### Embedding Models
-
-- embed-english-v3.0
-- embed-multilingual-v3.0
-- embed-english-light-v3.0
-- embed-multilingual-light-v3.0
-
-### Rerank Models
-
-- rerank-english-v3.0
-- rerank-multilingual-v3.0
-- rerank-english-v2.0
-- rerank-multilingual-v2.0
-
-## Requirements
-
-- Node.js >= 18
-- cohere-ai SDK
-
-## Running Examples
-
-The `examples/` directory contains real-world examples:
+From the TypeScript workspace, build shared packages and the instrumentor before running its offline suite:
 
 ```bash
-cd examples
-cp .env.example .env
-# Edit .env with your API keys
-
-pnpm install
-pnpm run example
-```
-
-## E2E Testing
-
-Run E2E tests with real API keys:
-
-```bash
-COHERE_API_KEY=your_key pnpm test -- --testPathPattern=e2e
-```
-
-## Integration with TraceAI Platform
-
-```typescript
-import { CohereInstrumentation } from "@traceai/cohere";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { Resource } from "@opentelemetry/resources";
-
-const provider = new NodeTracerProvider({
-  resource: new Resource({
-    "service.name": "my-cohere-app",
-    "deployment.environment": "production",
-  }),
-});
-
-const exporter = new OTLPTraceExporter({
-  url: "https://api.traceai.com/v1/traces",
-  headers: {
-    Authorization: `Bearer ${process.env.TRACEAI_API_KEY}`,
-  },
-});
-
-provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
-provider.register();
-
-const instrumentation = new CohereInstrumentation();
-instrumentation.manuallyInstrument(require("cohere-ai"));
+pnpm --filter '@traceai/cohere...' --workspace-concurrency=1 run build
+pnpm --filter '@traceai/cohere' exec jest --runInBand
 ```
 
 ## License
 
 Apache-2.0
-
-## Related Packages
-
-- [@traceai/openai](../traceai_openai) - OpenAI instrumentation
-- [@traceai/anthropic](../traceai_anthropic) - Anthropic instrumentation
-- [@traceai/groq](../traceai_groq) - Groq instrumentation
-- [@traceai/mistral](../traceai_mistral) - Mistral instrumentation
-- [@traceai/google-genai](../traceai_google_genai) - Google GenAI instrumentation
-- [@traceai/fi-core](../fi-core) - Core tracing utilities

package/dist/esm/attributes.d.ts

@@ -0,0 +1,11 @@
+import { Attributes } from "@opentelemetry/api";
+import { TraceConfig } from "@traceai/fi-core";
+export type Operation = "chat" | "chatStream" | "embed" | "rerank";
+export type Data = Record<string, unknown>;
+export declare const object: (value: unknown) => Data;
+export declare const list: (value: unknown) => unknown[];
+export declare const hideInput: (config: TraceConfig) => boolean;
+export declare const hideOutput: (config: TraceConfig) => boolean;
+export declare function inputAttributes(operation: Operation, request: Data, config: TraceConfig): Attributes;
+export declare function outputAttributes(operation: Operation, response: Data, config: TraceConfig): Attributes;
+//# sourceMappingURL=attributes.d.ts.map

package/dist/esm/attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/attributes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAuB,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAC;AACnE,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3C,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,KAAG,IAAwE,CAAC;AACjH,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,OAAO,EAAuC,CAAC;AAGrF,eAAO,MAAM,SAAS,GAAI,QAAQ,WAAW,YAAoG,CAAC;AAClJ,eAAO,MAAM,UAAU,GAAI,QAAQ,WAAW,YAA6E,CAAC;AAgB5H,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,GAAG,UAAU,CA2DpG;AAyDD,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,GAAG,UAAU,CAkDtG"}