skalpel 1.1.2 → 1.3.0

package/README.md

@@ -1,196 +1,116 @@
-# Skalpel
+# Skalpel SDK
 
-Optimize Claude Code prompts to reduce credit usage. Skalpel sits between Claude Code and the Anthropic API, optimizing prompts before they reach the provider — saving you money without changing how you work.
+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.
 
-## How It Works
+## Installation
 
+```bash
+npm install skalpel
 ```
-Claude Code  -->  Skalpel Proxy (local)  -->  Skalpel Backend (AWS)  -->  Anthropic API
-                  Intercepts requests          Optimizes prompts           Returns response
-                  Adds tracking headers        Reduces token usage
-```
-
-1. A local proxy runs on your machine (port 18100)
-2. Claude Code is configured to send API requests to the proxy instead of `api.anthropic.com`
-3. The proxy forwards requests to the Skalpel backend, which optimizes prompts for lower token usage
-4. The optimized request is sent to Anthropic, and the response streams back to Claude Code
-
-Your Anthropic API key stays in the request chain — Skalpel never stores it.
 
 ## Quick Start
 
-One command to install, detect Claude Code, and start optimizing:
+### Wrapper Pattern
 
-```bash
-npx skalpel --api-key sk-skalpel-YOUR_KEY --auto
-```
+Wrap your existing client to route all calls through Skalpel with automatic fallback:
 
-This will:
-- Start the local proxy on ports 18100 (Anthropic) and 18101 (OpenAI)
-- Detect Claude Code on your machine
-- Configure `~/.claude/settings.json` with `ANTHROPIC_BASE_URL=http://localhost:18100`
-- Set shell environment variables in your `.bashrc`/`.zshrc`
-- Begin optimizing all Claude Code API traffic immediately
-
-### Interactive Setup
+```typescript
+import OpenAI from 'openai';
+import { createSkalpelClient } from 'skalpel';
 
-For a guided setup with prompts:
+const openai = createSkalpelClient(new OpenAI(), {
+  apiKey: process.env.SKALPEL_API_KEY!,
+  workspace: 'my-workspace',
+});
 
-```bash
-npx skalpel
+// Use exactly like the OpenAI client
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
 ```
 
-The wizard walks you through API key entry, agent detection, and proxy configuration.
-
-### Manual Setup
-
-```bash
-# 1. Start the proxy
-npx skalpel start
-
-# 2. Run the setup wizard to configure Claude Code
-npx skalpel setup
-
-# 3. Verify everything is working
-npx skalpel doctor
-```
+### URL Swap Pattern
 
-## What Gets Configured
+The simplest integration — one line change:
 
-### Claude Code (`~/.claude/settings.json`)
+```typescript
+import { createSkalpelOpenAI } from 'skalpel';
 
-Skalpel adds an environment override so Claude Code routes API calls through the local proxy:
+const openai = await createSkalpelOpenAI({
+  apiKey: process.env.SKALPEL_API_KEY!,
+});
 
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "http://localhost:18100"
-  }
-}
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
 ```
 
-### Shell Environment (`~/.bashrc`, `~/.zshrc`)
-
-Environment variables are added for tools that read them directly:
+## CLI Setup
 
 ```bash
-# BEGIN SKALPEL PROXY - do not edit manually
-export ANTHROPIC_BASE_URL="http://localhost:18100"
-export OPENAI_BASE_URL="http://localhost:18101"
-# END SKALPEL PROXY
-```
-
-### Proxy Config (`~/.skalpel/config.json`)
-
-```json
-{
-  "apiKey": "sk-skalpel-YOUR_KEY",
-  "remoteBaseUrl": "http://skalpel-production-554359744.us-west-2.elb.amazonaws.com",
-  "anthropicPort": 18100,
-  "openaiPort": 18101
-}
+npx skalpel init
 ```
 
-## CLI Commands
-
-| Command | Description |
-|---|---|
-| `npx skalpel` | Run the setup wizard |
-| `npx skalpel start` | Start the proxy |
-| `npx skalpel stop` | Stop the proxy |
-| `npx skalpel status` | Show proxy status and uptime |
-| `npx skalpel doctor` | Verify configuration and connectivity |
-| `npx skalpel logs` | View proxy logs |
-| `npx skalpel logs -f` | Follow proxy logs in real time |
-| `npx skalpel uninstall` | Remove proxy, configs, and shell modifications |
+Interactive wizard that detects your project type, AI SDKs, and generates the integration code.
 
-### Flags
-
-| Flag | Description |
-|---|---|
-| `--api-key <key>` | Provide Skalpel API key (skips interactive prompt) |
-| `--auto` | Non-interactive mode (requires `--api-key`) |
-
-## Streaming Support
-
-Skalpel fully supports Anthropic's SSE streaming protocol. When Claude Code sends a streaming request (`"stream": true`), the proxy:
-
-- Detects the streaming flag in the request body
-- Forwards to the backend with all original headers
-- Pipes SSE events (`message_start`, `content_block_delta`, `message_stop`) directly back to Claude Code
-- Preserves upstream headers like `anthropic-request-id`
-
-No buffering, no modification of the stream — chunks flow through in real time.
-
-## Headers
-
-The proxy adds these headers to every request forwarded to the Skalpel backend:
-
-| Header | Value | Purpose |
-|---|---|---|
-| `X-Skalpel-API-Key` | Your Skalpel key | Backend authentication |
-| `X-Skalpel-Source` | `claude-code` | Traffic source identification |
-| `X-Skalpel-Agent-Type` | `claude-code` | Agent type for optimization routing |
-| `X-Skalpel-SDK-Version` | `proxy-1.0.0` | SDK version tracking |
-
-The original `x-api-key` header (your Anthropic key) is forwarded as-is.
-
-## Codex Support
-
-Skalpel also supports OpenAI Codex on port 18101. The same `--auto` flow detects and configures both agents if present.
-
-## SDK Integration
+## API Reference
 
-For programmatic use in your own applications:
+### `createSkalpelClient<T>(client: T, options: SkalpelClientOptions): T`
 
-```typescript
-import { createSkalpelClient } from 'skalpel';
-import Anthropic from '@anthropic-ai/sdk';
+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.
 
-const client = createSkalpelClient(new Anthropic(), {
-  apiKey: process.env.SKALPEL_API_KEY!,
-});
+### `createSkalpelOpenAI(options): Promise<OpenAI>`
 
-const response = await client.messages.create({
-  model: 'claude-sonnet-4-20250514',
-  max_tokens: 1024,
-  messages: [{ role: 'user', content: 'Hello' }],
-});
-```
+Factory function that creates a pre-configured OpenAI client pointing at the Skalpel proxy.
 
-See the [API Reference](#api-reference) for all SDK options.
+### `createSkalpelAnthropic(options): Promise<Anthropic>`
 
-## API Reference
+Factory function that creates a pre-configured Anthropic client pointing at the Skalpel proxy.
 
-### `createSkalpelClient<T>(client: T, options: SkalpelClientOptions): T`
+### `extractMetadata(headers): SkalpelMetadata | null`
 
-Wraps an existing OpenAI or Anthropic client. All API calls route through the Skalpel proxy with automatic fallback on errors.
+Extracts optimization metadata from Skalpel response headers (`x-skalpel-*`).
 
-### `createSkalpelAnthropic(options): Promise<Anthropic>`
+## Error Handling
 
-Creates a pre-configured Anthropic client pointing at the Skalpel proxy.
+The SDK provides typed error classes:
 
-### `createSkalpelOpenAI(options): Promise<OpenAI>`
+- `SkalpelAuthError` (401) — authentication failed. Never falls back.
+- `SkalpelTimeoutError` — request timed out.
+- `SkalpelRateLimitError` (429) — rate limit exceeded, includes `retryAfter`.
+- `SkalpelUnavailableError` (5xx) — proxy unavailable.
 
-Creates a pre-configured OpenAI client pointing at the Skalpel proxy.
+When `fallbackOnError: true` (default), the SDK retries with exponential backoff, then falls back to the direct provider. Auth errors always throw immediately.
 
-### Configuration Options
+## Configuration
 
 ```typescript
 interface SkalpelClientOptions {
   apiKey: string;                  // Skalpel API key (sk-skalpel-*)
   workspace?: string;              // Workspace ID
-  baseURL?: string;                // Proxy URL (default: production ALB)
+  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
 }
 ```
 
-## Uninstall
+## TypeScript
 
-```bash
-npx skalpel uninstall
-```
+The SDK is written in TypeScript and ships with full type declarations. All types are exported:
 
-This removes the proxy, restores `~/.claude/settings.json` from backup, and cleans up shell environment variables.
+```typescript
+import type {
+  SkalpelClientOptions,
+  SkalpelMetadata,
+  SkalpelConfig,
+  SupportedProvider,
+  InitConfig,
+} from 'skalpel';
+```