skalpel 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# Skalpel SDK
+
+Optimize your OpenAI and Anthropic API calls with Skalpel AI. The SDK transparently reroutes requests through the Skalpel proxy, adding cost optimization, caching, and intelligent model routing — without changing your existing code.
+
+## Installation
+
+```bash
+npm install skalpel
+```
+
+## Quick Start
+
+### Wrapper Pattern
+
+Wrap your existing client to route all calls through Skalpel with automatic fallback:
+
+```typescript
+import OpenAI from 'openai';
+import { createSkalpelClient } from 'skalpel';
+
+const openai = createSkalpelClient(new OpenAI(), {
+  apiKey: process.env.SKALPEL_API_KEY!,
+  workspace: 'my-workspace',
+});
+
+// Use exactly like the OpenAI client
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+```
+
+### URL Swap Pattern
+
+The simplest integration — one line change:
+
+```typescript
+import { createSkalpelOpenAI } from 'skalpel';
+
+const openai = await createSkalpelOpenAI({
+  apiKey: process.env.SKALPEL_API_KEY!,
+});
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+```
+
+## CLI Setup
+
+```bash
+npx skalpel init
+```
+
+Interactive wizard that detects your project type, AI SDKs, and generates the integration code.
+
+## API Reference
+
+### `createSkalpelClient<T>(client: T, options: SkalpelClientOptions): T`
+
+Wraps an existing OpenAI or Anthropic client instance. All API calls are transparently routed through the Skalpel proxy. Supports automatic fallback to the direct provider on errors.
+
+### `createSkalpelOpenAI(options): Promise<OpenAI>`
+
+Factory function that creates a pre-configured OpenAI client pointing at the Skalpel proxy.
+
+### `createSkalpelAnthropic(options): Promise<Anthropic>`
+
+Factory function that creates a pre-configured Anthropic client pointing at the Skalpel proxy.
+
+### `extractMetadata(headers): SkalpelMetadata | null`
+
+Extracts optimization metadata from Skalpel response headers (`x-skalpel-*`).
+
+## Error Handling
+
+The SDK provides typed error classes:
+
+- `SkalpelAuthError` (401) — authentication failed. Never falls back.
+- `SkalpelTimeoutError` — request timed out.
+- `SkalpelRateLimitError` (429) — rate limit exceeded, includes `retryAfter`.
+- `SkalpelUnavailableError` (5xx) — proxy unavailable.
+
+When `fallbackOnError: true` (default), the SDK retries with exponential backoff, then falls back to the direct provider. Auth errors always throw immediately.
+
+## Configuration
+
+```typescript
+interface SkalpelClientOptions {
+  apiKey: string;                  // Skalpel API key (sk-skalpel-*)
+  workspace?: string;              // Workspace ID
+  baseURL?: string;                // Proxy URL (default: https://api.skalpel.ai)
+  fallbackOnError?: boolean;       // Fall back to direct provider (default: true)
+  timeout?: number;                // Request timeout in ms (default: 30000)
+  retries?: number;                // Max retries (default: 2)
+  headers?: Record<string, string>;// Additional custom headers
+  verbose?: boolean;               // Log fallback events (default: false)
+  onFallback?: (error, provider) => void;  // Callback on fallback
+  onMetadata?: (metadata) => void;         // Callback with optimization info
+}
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and ships with full type declarations. All types are exported:
+
+```typescript
+import type {
+  SkalpelClientOptions,
+  SkalpelMetadata,
+  SkalpelConfig,
+  SupportedProvider,
+  InitConfig,
+} from 'skalpel';
+```