deadpipe 2.0.1 → 3.0.0

package/README.md

@@ -2,6 +2,8 @@
 
 LLM observability that answers one question: **"Is this prompt behaving the same as when it was last safe?"**
 
+**Supports:** OpenAI, Anthropic, Google AI (Gemini), Mistral, Cohere
+
 ## Installation
 
 ```bash
@@ -14,40 +16,147 @@ pnpm add deadpipe
 
 ## Quick Start
 
-### Option 1: Context Manager (Recommended)
+### Universal Wrapper (Recommended)
+
+The `wrap()` function auto-detects your provider and wraps appropriately:
+
+```typescript
+import { wrap } from 'deadpipe';
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+
+// Works with any supported provider
+const openai = wrap(new OpenAI(), { promptId: 'checkout_agent' });
+const anthropic = wrap(new Anthropic(), { promptId: 'support_agent' });
+
+// All calls automatically tracked with full input/output context
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Process refund for order 1938' }]
+});
+```
+
+### Provider-Specific Wrappers
+
+For explicit control, use provider-specific wrappers:
+
+```typescript
+import { wrapOpenAI, wrapAnthropic, wrapGoogleAI, wrapMistral, wrapCohere } from 'deadpipe';
+
+const openai = wrapOpenAI(new OpenAI(), { promptId: 'my_agent' });
+const anthropic = wrapAnthropic(new Anthropic(), { promptId: 'my_agent' });
+```
+
+### Manual Tracking
+
+For streaming, custom logic, or unsupported clients:
 
 ```typescript
 import { track } from 'deadpipe';
 import OpenAI from 'openai';
 
 const client = new OpenAI();
+const params = {
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Process refund for order 1938' }]
+};
 
 const response = await track('checkout_agent', async (t) => {
-  const response = await client.chat.completions.create({
-    model: 'gpt-4',
-    messages: [{ role: 'user', content: 'Process refund for order 1938' }]
-  });
-  t.record(response);
+  const response = await client.chat.completions.create(params);
+  t.record(response, undefined, params);  // Pass params to capture input
   return response;
 });
 ```
 
-### Option 2: Auto-Wrapping (Zero Code Changes)
+## Provider Examples
+
+### OpenAI
 
 ```typescript
-import { wrapOpenAI } from 'deadpipe';
+import { wrap } from 'deadpipe';
 import OpenAI from 'openai';
 
-const client = wrapOpenAI(new OpenAI(), { promptId: 'checkout_agent' });
+const client = wrap(new OpenAI(), { promptId: 'openai_agent' });
 
-// All calls automatically tracked
 const response = await client.chat.completions.create({
-  model: 'gpt-4',
-  messages: [{ role: 'user', content: 'Process refund for order 1938' }]
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+```
+
+### Anthropic
+
+```typescript
+import { wrap } from 'deadpipe';
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = wrap(new Anthropic(), { promptId: 'claude_agent' });
+
+const response = await client.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello, Claude!' }]
 });
 ```
 
-### Option 3: With Schema Validation (Zod)
+### Google AI (Gemini)
+
+```typescript
+import { wrap } from 'deadpipe';
+import { GoogleGenerativeAI } from '@google/generative-ai';
+
+const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
+const model = wrap(genAI, { promptId: 'gemini_agent' }).getGenerativeModel({ model: 'gemini-1.5-pro' });
+
+const result = await model.generateContent('Hello, Gemini!');
+```
+
+### Mistral
+
+```typescript
+import { wrap } from 'deadpipe';
+import { Mistral } from '@mistralai/mistralai';
+
+const client = wrap(new Mistral({ apiKey: process.env.MISTRAL_API_KEY }), { promptId: 'mistral_agent' });
+
+const response = await client.chat.complete({
+  model: 'mistral-large-latest',
+  messages: [{ role: 'user', content: 'Hello, Mistral!' }]
+});
+```
+
+### Cohere
+
+```typescript
+import { wrap } from 'deadpipe';
+import { CohereClient } from 'cohere-ai';
+
+const client = wrap(new CohereClient({ token: process.env.COHERE_API_KEY }), { promptId: 'cohere_agent' });
+
+const response = await client.chat({
+  model: 'command-r-plus',
+  message: 'Hello, Cohere!'
+});
+```
+
+## What Gets Tracked
+
+Every prompt execution captures:
+
+| Category | Metrics |
+|----------|---------|
+| **Identity** | prompt_id, model, provider, app_id, environment, version |
+| **Timing** | request_start, first_token_time, total_latency |
+| **Volume** | input_tokens, output_tokens, estimated_cost_usd |
+| **Reliability** | http_status, timeout, retry_count, error_message |
+| **Output Integrity** | output_length, empty_output, truncated, json_parse_success, schema_validation_pass |
+| **Behavioral Fingerprint** | output_hash, refusal_flag, tool_calls_count |
+| **Safety Proxies** | enum_out_of_range, numeric_out_of_bounds |
+| **Change Context** | prompt_hash, tool_schema_hash, system_prompt_hash |
+
+## Advanced Usage
+
+### Schema Validation (Zod)
 
 ```typescript
 import { track } from 'deadpipe';
@@ -82,35 +191,19 @@ const result = await track('checkout_agent', async (t) => {
     }
   }
 });
-// result is typed as RefundResponse | null
 ```
 
-## What Gets Tracked
-
-Every prompt execution captures:
-
-| Category | Metrics |
-|----------|---------|
-| **Identity** | prompt_id, model, provider, app_id, environment, version |
-| **Timing** | request_start, first_token_time, total_latency |
-| **Volume** | input_tokens, output_tokens, estimated_cost_usd |
-| **Reliability** | http_status, timeout, retry_count, error_message |
-| **Output Integrity** | output_length, empty_output, truncated, json_parse_success, schema_validation_pass |
-| **Behavioral Fingerprint** | output_hash, refusal_flag, tool_calls_count |
-| **Safety Proxies** | enum_out_of_range, numeric_out_of_bounds |
-| **Change Context** | prompt_hash, tool_schema_hash, system_prompt_hash |
-
-## Advanced Usage
-
 ### Track Streaming Responses
 
 ```typescript
+const params = {
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Tell me a story' }],
+  stream: true,
+};
+
 const response = await track('streaming_agent', async (t) => {
-  const stream = await client.chat.completions.create({
-    model: 'gpt-4',
-    messages: [{ role: 'user', content: 'Tell me a story' }],
-    stream: true,
-  });
+  const stream = await client.chat.completions.create(params);
 
   let fullContent = '';
   for await (const chunk of stream) {
@@ -120,12 +213,11 @@ const response = await track('streaming_agent', async (t) => {
     }
   }
 
-  // Record manually for streams
   t.record({ 
     model: 'gpt-4',
     choices: [{ message: { content: fullContent } }],
     usage: { prompt_tokens: 10, completion_tokens: 100, total_tokens: 110 }
-  });
+  }, undefined, params);
 
   return fullContent;
 });
@@ -148,25 +240,6 @@ const response = await track('checkout_agent', async (t) => {
 });
 ```
 
-### With Anthropic
-
-```typescript
-import { track } from 'deadpipe';
-import Anthropic from '@anthropic-ai/sdk';
-
-const client = new Anthropic();
-
-const response = await track('claude_agent', async (t) => {
-  const response = await client.messages.create({
-    model: 'claude-3-sonnet-20240229',
-    max_tokens: 1024,
-    messages: [{ role: 'user', content: 'Hello, Claude!' }]
-  });
-  t.record(response);
-  return response;
-}, { provider: 'anthropic' });
-```
-
 ### Environment-Based Configuration
 
 ```typescript
@@ -176,18 +249,18 @@ const response = await track('claude_agent', async (t) => {
 // DEADPIPE_ENVIRONMENT - e.g., 'production', 'staging'
 // DEADPIPE_VERSION or GIT_COMMIT - Version/commit hash
 
-import { track } from 'deadpipe';
+import { wrap } from 'deadpipe';
 
 // API key auto-loaded from DEADPIPE_API_KEY
-await track('my_prompt', async (t) => {
-  // ...
-});
+const client = wrap(new OpenAI(), { promptId: 'my_agent' });
 ```
 
 ### Full Options
 
 ```typescript
-await track('checkout_agent', fn, {
+const client = wrap(new OpenAI(), {
+  promptId: 'checkout_agent',
+  
   // Authentication
   apiKey: 'dp_...',
   baseUrl: 'https://www.deadpipe.com/api/v1',
@@ -197,62 +270,50 @@ await track('checkout_agent', fn, {
   appId: 'my-app',
   environment: 'production',
   version: '1.2.3',
-  provider: 'openai', // or 'anthropic'
 
   // Validation
   schema: { validate: (data) => ({ success: true, data }) },
   enumFields: { status: ['pending', 'approved', 'rejected'] },
   numericBounds: { amount: [0, 10000] },
-
-  // Context (for change detection)
-  messages: [...],
-  tools: [...],
-  systemPrompt: 'You are a helpful assistant...',
 });
 ```
 
-## Next.js API Routes
+## Framework Examples
+
+### Next.js API Routes
 
 ```typescript
-import { track } from 'deadpipe';
+import { wrap } from 'deadpipe';
 import OpenAI from 'openai';
 
-const client = new OpenAI();
+const client = wrap(new OpenAI(), { promptId: 'api_handler' });
 
 export async function POST(request: Request) {
   const { prompt } = await request.json();
 
-  const response = await track('api_handler', async (t) => {
-    const completion = await client.chat.completions.create({
-      model: 'gpt-4',
-      messages: [{ role: 'user', content: prompt }]
-    });
-    t.record(completion);
-    return completion;
+  const response = await client.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: prompt }]
   });
 
   return Response.json({ result: response.choices[0].message.content });
 }
 ```
 
-## Express.js
+### Express.js
 
 ```typescript
 import express from 'express';
-import { track } from 'deadpipe';
+import { wrap } from 'deadpipe';
 import OpenAI from 'openai';
 
 const app = express();
-const client = new OpenAI();
+const client = wrap(new OpenAI(), { promptId: 'express_endpoint' });
 
 app.post('/generate', async (req, res) => {
-  const response = await track('express_endpoint', async (t) => {
-    const completion = await client.chat.completions.create({
-      model: 'gpt-4',
-      messages: req.body.messages
-    });
-    t.record(completion);
-    return completion;
+  const response = await client.chat.completions.create({
+    model: 'gpt-4',
+    messages: req.body.messages
   });
 
   res.json(response);
@@ -261,42 +322,59 @@ app.post('/generate', async (req, res) => {
 
 ## API Reference
 
+### `wrap(client, options)`
+
+Universal wrapper that auto-detects provider.
+
+- `client`: Any supported LLM client
+- `options.promptId`: Unique identifier for prompts
+
+Returns: Wrapped client with identical API
+
+### Provider-Specific Wrappers
+
+- `wrapOpenAI(client, options)` - OpenAI client
+- `wrapAnthropic(client, options)` - Anthropic client
+- `wrapGoogleAI(client, options)` - Google AI client
+- `wrapMistral(client, options)` - Mistral client
+- `wrapCohere(client, options)` - Cohere client
+
 ### `track(promptId, fn, options?)`
 
 Track a prompt execution with full telemetry.
 
 - `promptId`: Unique identifier for this prompt
 - `fn`: Async function that receives a `PromptTracker`
-- `options`: Configuration options (see above)
+- `options`: Configuration options
 
 Returns: `Promise<T>` (result of fn)
 
-### `wrapOpenAI(client, options)`
-
-Wrap an OpenAI client to auto-track all completions.
-
-- `client`: OpenAI client instance
-- `options.promptId`: Unique identifier for prompts
-
-Returns: Wrapped client with identical API
-
 ### `PromptTracker`
 
 The tracker object passed to your function:
 
-- `record(response)` - Record the LLM response
+- `record(response, parsedOutput?, input?)` - Record the LLM response
 - `markFirstToken()` - Mark when first token received (streaming)
 - `markRetry()` - Mark a retry attempt
 - `recordError(error)` - Record an error
 - `getTelemetry()` - Get the telemetry object
 
-### `estimateCost(model, inputTokens, outputTokens)`
+### Utility Functions
 
-Estimate USD cost for a completion.
+- `estimateCost(model, inputTokens, outputTokens)` - Estimate USD cost
+- `detectRefusal(text)` - Detect if response is a refusal
+- `detectProvider(response)` - Detect provider from response
+- `detectClientProvider(client)` - Detect provider from client
 
-### `detectRefusal(text)`
+## Supported Models & Pricing
 
-Detect if response is a refusal/decline.
+| Provider | Models |
+|----------|--------|
+| **OpenAI** | gpt-4, gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo, o1, o1-mini, o1-pro |
+| **Anthropic** | claude-3-opus, claude-3-sonnet, claude-3-haiku, claude-3.5-sonnet, claude-sonnet-4, claude-opus-4 |
+| **Google AI** | gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash, gemini-2.0-pro |
+| **Mistral** | mistral-large, mistral-medium, mistral-small, mistral-nemo, codestral, pixtral |
+| **Cohere** | command-r-plus, command-r, command, command-light |
 
 ## Zero Dependencies
 

package/dist/index.d.mts

@@ -2,31 +2,35 @@
  * Deadpipe - LLM observability that answers one question:
  * "Is this prompt behaving the same as when it was last safe?"
  *
- * @example
- * import { track } from 'deadpipe';
+ * Supports: OpenAI, Anthropic, Google AI (Gemini), Mistral, Cohere
+ *
+ * @example Recommended: Universal wrapper (auto-detects provider)
+ * import { wrap } from 'deadpipe';
  * import OpenAI from 'openai';
+ * import Anthropic from '@anthropic-ai/sdk';
  *
- * const client = new OpenAI();
+ * // Works with any supported provider
+ * const openai = wrap(new OpenAI(), { promptId: 'checkout_agent' });
+ * const anthropic = wrap(new Anthropic(), { promptId: 'support_agent' });
  *
- * const { response, tracker } = await track('checkout_agent', async (t) => {
- *   const response = await client.chat.completions.create({
- *     model: 'gpt-4',
- *     messages: [{ role: 'user', content: 'Process refund for order 1938' }]
- *   });
- *   t.record(response);
- *   return response;
- * });
+ * @example Provider-specific wrappers
+ * import { wrapOpenAI, wrapAnthropic } from 'deadpipe';
  *
- * @example Auto-wrapping (zero code changes):
- * import { wrapOpenAI } from 'deadpipe';
- * import OpenAI from 'openai';
+ * const openai = wrapOpenAI(new OpenAI(), { promptId: 'my_agent' });
+ * const anthropic = wrapAnthropic(new Anthropic(), { promptId: 'my_agent' });
+ *
+ * @example Advanced: Manual tracking (for streaming, custom logic, etc.)
+ * import { track } from 'deadpipe';
  *
- * const client = wrapOpenAI(new OpenAI(), { promptId: 'checkout_agent' });
- * // All calls automatically tracked
- * const response = await client.chat.completions.create(...);
+ * const response = await track('checkout_agent', async (t) => {
+ *   const response = await client.chat.completions.create(params);
+ *   t.record(response, undefined, params);
+ *   return response;
+ * });
  */
-declare const VERSION = "2.0.0";
+declare const VERSION = "3.0.0";
 type StatusType = 'success' | 'error' | 'timeout' | 'empty' | 'schema_violation' | 'refusal';
+type ProviderType = 'openai' | 'anthropic' | 'google' | 'mistral' | 'cohere' | 'unknown';
 interface PromptTelemetry {
     prompt_id: string;
     model?: string;
@@ -77,17 +81,9 @@ interface TrackOptions {
     appId?: string;
     environment?: string;
     version?: string;
-    provider?: 'openai' | 'anthropic' | string;
     schema?: SchemaValidator;
     enumFields?: Record<string, unknown[]>;
     numericBounds?: Record<string, [number | null, number | null]>;
-    messages?: Array<{
-        role: string;
-        content: string;
-        [key: string]: unknown;
-    }>;
-    tools?: Array<Record<string, unknown>>;
-    systemPrompt?: string;
 }
 interface SchemaValidator {
     validate: (data: unknown) => {
@@ -96,13 +92,24 @@ interface SchemaValidator {
         errors?: string[];
     };
 }
-interface WrapOpenAIOptions extends Omit<TrackOptions, 'messages' | 'tools' | 'systemPrompt'> {
+interface WrapOptions extends TrackOptions {
     promptId: string;
 }
+type WrapOpenAIOptions = WrapOptions;
 declare function estimateCost(model: string, inputTokens: number, outputTokens: number): number | null;
 declare function detectRefusal(text: string): boolean;
 declare function validateEnumBounds(data: Record<string, unknown>, enumFields?: Record<string, unknown[]>): boolean;
 declare function validateNumericBounds(data: Record<string, unknown>, numericBounds?: Record<string, [number | null, number | null]>): boolean;
+/**
+ * Auto-detect provider from response object.
+ * Checks for provider-specific response structures.
+ */
+declare function detectProvider(response: any): ProviderType;
+/**
+ * Auto-detect provider from client object.
+ * Checks for provider-specific client structures.
+ */
+declare function detectClientProvider(client: any): ProviderType;
 interface ExtractedResponse {
     model: string;
     content: string;
@@ -118,6 +125,13 @@ interface ExtractedResponse {
 }
 declare function extractOpenAIResponse(response: any): ExtractedResponse;
 declare function extractAnthropicResponse(response: any): ExtractedResponse;
+declare function extractGoogleAIResponse(response: any): ExtractedResponse;
+declare function extractMistralResponse(response: any): ExtractedResponse;
+declare function extractCohereResponse(response: any): ExtractedResponse;
+/**
+ * Extract response data based on detected or specified provider.
+ */
+declare function extractResponse(response: any, provider?: ProviderType): ExtractedResponse;
 declare class PromptTracker {
     private promptId;
     private apiKey;
@@ -126,7 +140,6 @@ declare class PromptTracker {
     private appId;
     private environment;
     private versionStr;
-    private provider;
     private schema;
     private enumFields;
     private numericBounds;
@@ -145,23 +158,62 @@ declare class PromptTracker {
     start(): void;
     markFirstToken(): void;
     markRetry(): void;
-    record(response: any, parsedOutput?: unknown): unknown;
+    record(response: any, parsedOutput?: unknown, input?: any): unknown;
     recordError(error: Error): void;
     private send;
     isRecorded(): boolean;
     getTelemetry(): PromptTelemetry;
 }
 declare function track<T>(promptId: string, fn: (tracker: PromptTracker) => Promise<T>, options?: TrackOptions): Promise<T>;
-type OpenAIClient = any;
+type AnyClient = any;
 interface TrackedCompletions {
     create: (params: any) => Promise<any>;
 }
 interface TrackedChat {
     completions: TrackedCompletions;
 }
-interface TrackedOpenAIClient extends OpenAIClient {
+interface TrackedOpenAIClient extends AnyClient {
     chat: TrackedChat;
 }
-declare function wrapOpenAI(client: OpenAIClient, options: WrapOpenAIOptions): TrackedOpenAIClient;
+declare function wrapOpenAI(client: AnyClient, options: WrapOptions): TrackedOpenAIClient;
+interface TrackedMessages {
+    create: (params: any) => Promise<any>;
+}
+interface TrackedAnthropicClient extends AnyClient {
+    messages: TrackedMessages;
+}
+declare function wrapAnthropic(client: AnyClient, options: WrapOptions): TrackedAnthropicClient;
+interface TrackedGenerativeModel {
+    generateContent: (params: any) => Promise<any>;
+    startChat: (params?: any) => any;
+}
+interface TrackedGoogleAIClient extends AnyClient {
+    getGenerativeModel: (params: any) => TrackedGenerativeModel;
+}
+declare function wrapGoogleAI(client: AnyClient, options: WrapOptions): TrackedGoogleAIClient;
+interface TrackedMistralChat {
+    complete: (params: any) => Promise<any>;
+}
+interface TrackedMistralClient extends AnyClient {
+    chat: TrackedMistralChat;
+}
+declare function wrapMistral(client: AnyClient, options: WrapOptions): TrackedMistralClient;
+interface TrackedCohereClient extends AnyClient {
+    chat: (params: any) => Promise<any>;
+    generate?: (params: any) => Promise<any>;
+}
+declare function wrapCohere(client: AnyClient, options: WrapOptions): TrackedCohereClient;
+/**
+ * Universal wrapper that auto-detects the provider and wraps appropriately.
+ *
+ * @example
+ * import { wrap } from 'deadpipe';
+ * import OpenAI from 'openai';
+ * import Anthropic from '@anthropic-ai/sdk';
+ *
+ * const openai = wrap(new OpenAI(), { promptId: 'my_agent' });
+ * const anthropic = wrap(new Anthropic(), { promptId: 'my_agent' });
+ */
+declare function wrap(client: AnyClient, options: WrapOptions): AnyClient;
 
-export { type PromptTelemetry, PromptTracker, type SchemaValidator, type StatusType, type TrackOptions, VERSION, type WrapOpenAIOptions, detectRefusal, estimateCost, extractAnthropicResponse, extractOpenAIResponse, track, validateEnumBounds, validateNumericBounds, wrapOpenAI };
+export { type PromptTelemetry, PromptTracker, type ProviderType, type SchemaValidator, type StatusType, type TrackOptions, VERSION, type WrapOpenAIOptions, type WrapOptions, wrap as default, detectClientProvider, detectProvider, detectRefusal, estimateCost, extractAnthropicResponse, extractCohereResponse, extractGoogleAIResponse, extractMistralResponse, extractOpenAIResponse, extractResponse, track, validateEnumBounds, validateNumericBounds, wrap, wrapAnthropic, wrap as wrapClient, wrapCohere, wrapGoogleAI, wrapMistral, wrapOpenAI };