clasp-ai 0.0.1 → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 jedarden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,59 +1,516 @@
-# CLASP
+# CLASP - Claude Language Agent Super Proxy
 
-**C**laude **L**anguage **A**gent **S**uper **P**roxy
+A high-performance Go proxy that translates Claude/Anthropic API calls to OpenAI-compatible endpoints, enabling Claude Code to work with any LLM provider.
 
-Run Claude Code with any LLM provider - OpenAI, Azure, OpenRouter, and more.
+## Features
+
+- **Multi-Provider Support**: OpenAI, Azure OpenAI, OpenRouter (200+ models), and custom endpoints (Ollama, vLLM, LM Studio)
+- **Full Protocol Translation**: Anthropic Messages API ↔ OpenAI Chat Completions API
+- **SSE Streaming**: Real-time token streaming with state machine processing
+- **Tool Calls**: Complete translation of tool_use/tool_result between formats
+- **Connection Pooling**: Optimized HTTP transport with persistent connections
+- **Retry Logic**: Exponential backoff for transient failures
+- **Metrics Endpoint**: Request statistics and performance monitoring
+- **API Key Authentication**: Secure the proxy with optional API key validation
 
 ## Installation
 
+### Via npm (recommended)
+
 ```bash
+# Install globally
 npm install -g clasp-ai
+
+# Or run directly with npx
+npx clasp-ai
 ```
 
-## Features (Coming Soon)
+### Via Go
 
-- **Multi-Provider Support**: OpenAI, Azure OpenAI, OpenRouter, Anthropic, custom endpoints
-- **Zero Configuration**: Auto-detects provider from environment variables
-- **Interactive Setup**: Guided configuration for any provider
-- **Model Selection**: Dynamic model fetching from provider APIs
-- **Profile System**: Save and switch between provider configurations
-- **Auto-Update**: Built-in update mechanism
+```bash
+go install github.com/jedarden/clasp/cmd/clasp@latest
+```
 
-## Supported Providers
+### From Source
 
-| Provider | Models | Status |
-|----------|--------|--------|
-| OpenRouter | 200+ models | Coming Soon |
-| OpenAI | GPT-4o, o1, o3 | Coming Soon |
-| Azure OpenAI | Enterprise deployments | Coming Soon |
-| Anthropic | Claude (passthrough) | Coming Soon |
-| Custom | Ollama, vLLM, LM Studio | Coming Soon |
+```bash
+git clone https://github.com/jedarden/CLASP.git
+cd CLASP
+make build
+```
 
-## Usage (Preview)
+### Via Docker
 
 ```bash
-# With OpenRouter (default)
-export OPENROUTER_API_KEY=sk-or-...
-clasp
+# Run with Docker
+docker run -d -p 8080:8080 \
+  -e OPENAI_API_KEY=sk-... \
+  ghcr.io/jedarden/clasp-ai:latest
+
+# Or with docker-compose
+docker-compose up -d
+```
+
+## Quick Start
 
-# With OpenAI
-export PROVIDER=openai
+### Using with OpenAI
+
+```bash
+# Set your API key
 export OPENAI_API_KEY=sk-...
-clasp --model gpt-4o
 
-# With Azure
-export PROVIDER=azure
-export AZURE_API_KEY=...
-export AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com
+# Start the proxy
+clasp -model gpt-4o
+
+# In another terminal, use Claude Code
+ANTHROPIC_BASE_URL=http://localhost:8080 claude
+```
+
+### Using with Azure OpenAI
+
+```bash
+export AZURE_API_KEY=your-key
+export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
 export AZURE_DEPLOYMENT_NAME=gpt-4
-clasp
 
-# With local Ollama
-export PROVIDER=custom
+clasp -provider azure
+```
+
+### Using with OpenRouter
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+
+clasp -provider openrouter -model anthropic/claude-3-sonnet
+```
+
+### Using with Local Models (Ollama)
+
+```bash
 export CUSTOM_BASE_URL=http://localhost:11434/v1
-clasp --model llama3.1:70b
+
+clasp -provider custom -model llama3.1
+```
+
+## Configuration
+
+### Command Line Options
+
+```
+clasp [options]
+
+Options:
+  -port <port>           Port to listen on (default: 8080)
+  -provider <name>       LLM provider: openai, azure, openrouter, custom
+  -model <model>         Default model to use for all requests
+  -debug                 Enable debug logging (full request/response)
+  -rate-limit            Enable rate limiting
+  -cache                 Enable response caching
+  -cache-max-size <n>    Maximum cache entries (default: 1000)
+  -cache-ttl <n>         Cache TTL in seconds (default: 3600)
+  -multi-provider        Enable multi-provider tier routing
+  -fallback              Enable fallback routing for auto-failover
+  -auth                  Enable API key authentication
+  -auth-api-key <key>    API key for authentication (required with -auth)
+  -version               Show version information
+  -help                  Show help message
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PROVIDER` | LLM provider type | `openai` |
+| `CLASP_PORT` | Proxy server port | `8080` |
+| `CLASP_MODEL` | Default model | - |
+| `CLASP_MODEL_OPUS` | Model for Opus tier | - |
+| `CLASP_MODEL_SONNET` | Model for Sonnet tier | - |
+| `CLASP_MODEL_HAIKU` | Model for Haiku tier | - |
+| `OPENAI_API_KEY` | OpenAI API key | - |
+| `OPENAI_BASE_URL` | Custom OpenAI base URL | `https://api.openai.com/v1` |
+| `AZURE_API_KEY` | Azure OpenAI API key | - |
+| `AZURE_OPENAI_ENDPOINT` | Azure endpoint URL | - |
+| `AZURE_DEPLOYMENT_NAME` | Azure deployment name | - |
+| `AZURE_API_VERSION` | Azure API version | `2024-02-15-preview` |
+| `OPENROUTER_API_KEY` | OpenRouter API key | - |
+| `CUSTOM_BASE_URL` | Custom endpoint base URL | - |
+| `CUSTOM_API_KEY` | Custom endpoint API key | - |
+| `CLASP_DEBUG` | Enable all debug logging | `false` |
+| `CLASP_DEBUG_REQUESTS` | Log requests only | `false` |
+| `CLASP_DEBUG_RESPONSES` | Log responses only | `false` |
+| `CLASP_RATE_LIMIT` | Enable rate limiting | `false` |
+| `CLASP_RATE_LIMIT_REQUESTS` | Requests per window | `60` |
+| `CLASP_RATE_LIMIT_WINDOW` | Window in seconds | `60` |
+| `CLASP_RATE_LIMIT_BURST` | Burst allowance | `10` |
+| `CLASP_CACHE` | Enable response caching | `false` |
+| `CLASP_CACHE_MAX_SIZE` | Maximum cache entries | `1000` |
+| `CLASP_CACHE_TTL` | Cache TTL in seconds | `3600` |
+| `CLASP_MULTI_PROVIDER` | Enable multi-provider routing | `false` |
+| `CLASP_FALLBACK` | Enable fallback routing | `false` |
+| `CLASP_AUTH` | Enable API key authentication | `false` |
+| `CLASP_AUTH_API_KEY` | Required API key for access | - |
+| `CLASP_AUTH_ALLOW_ANONYMOUS_HEALTH` | Allow /health without auth | `true` |
+| `CLASP_AUTH_ALLOW_ANONYMOUS_METRICS` | Allow /metrics without auth | `false` |
+
+### Model Mapping
+
+CLASP can automatically map Claude model tiers to your provider's models:
+
+```bash
+# Map Claude tiers to specific models
+export CLASP_MODEL_OPUS=gpt-4o
+export CLASP_MODEL_SONNET=gpt-4o-mini
+export CLASP_MODEL_HAIKU=gpt-3.5-turbo
+```
+
+### Multi-Provider Routing
+
+Route different Claude model tiers to different LLM providers for cost optimization:
+
+```bash
+# Enable multi-provider routing
+export CLASP_MULTI_PROVIDER=true
+
+# Route Opus tier to OpenAI (premium)
+export CLASP_OPUS_PROVIDER=openai
+export CLASP_OPUS_MODEL=gpt-4o
+export CLASP_OPUS_API_KEY=sk-...  # Optional, inherits from OPENAI_API_KEY
+
+# Route Sonnet tier to OpenRouter (cost-effective)
+export CLASP_SONNET_PROVIDER=openrouter
+export CLASP_SONNET_MODEL=anthropic/claude-3-sonnet
+export CLASP_SONNET_API_KEY=sk-or-...  # Optional, inherits from OPENROUTER_API_KEY
+
+# Route Haiku tier to local Ollama (free)
+export CLASP_HAIKU_PROVIDER=custom
+export CLASP_HAIKU_MODEL=llama3.1
+export CLASP_HAIKU_BASE_URL=http://localhost:11434/v1
+
+clasp -multi-provider
+```
+
+**Multi-Provider Environment Variables:**
+
+| Variable | Description |
+|----------|-------------|
+| `CLASP_MULTI_PROVIDER` | Enable multi-provider routing (`true`/`1`) |
+| `CLASP_{TIER}_PROVIDER` | Provider for tier: `openai`, `openrouter`, `custom` |
+| `CLASP_{TIER}_MODEL` | Model name for the tier |
+| `CLASP_{TIER}_API_KEY` | API key (optional, inherits from main config) |
+| `CLASP_{TIER}_BASE_URL` | Base URL (optional, uses provider default) |
+
+Where `{TIER}` is `OPUS`, `SONNET`, or `HAIKU`.
+
+**Benefits:**
+- **Cost Optimization**: Use expensive providers only for complex tasks
+- **Latency Reduction**: Route simple requests to faster local models
+- **Redundancy**: Mix cloud and local providers for reliability
+- **A/B Testing**: Compare different models across tiers
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /v1/messages` | Anthropic Messages API (translated) |
+| `GET /health` | Health check |
+| `GET /metrics` | Request statistics (JSON) |
+| `GET /metrics/prometheus` | Prometheus metrics |
+| `GET /` | Server info |
+
+## Example Usage
+
+### With curl
+
+```bash
+curl http://localhost:8080/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: any-key" \
+  -d '{
+    "model": "claude-3-5-sonnet-20241022",
+    "max_tokens": 1024,
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+### Streaming
+
+```bash
+curl http://localhost:8080/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: any-key" \
+  -d '{
+    "model": "claude-3-5-sonnet-20241022",
+    "max_tokens": 1024,
+    "stream": true,
+    "messages": [
+      {"role": "user", "content": "Count to 5"}
+    ]
+  }'
+```
+
+## Response Caching
+
+CLASP can cache responses to reduce API costs and improve latency for repeated requests:
+
+```bash
+# Enable caching with defaults (1000 entries, 1 hour TTL)
+clasp -cache
+
+# Custom cache settings
+clasp -cache -cache-max-size 500 -cache-ttl 1800
+
+# Via environment
+CLASP_CACHE=true CLASP_CACHE_MAX_SIZE=500 clasp
+```
+
+**Caching behavior:**
+- Only non-streaming requests are cached
+- Requests with `temperature > 0` are not cached (non-deterministic)
+- Cache uses LRU (Least Recently Used) eviction when full
+- Cache entries expire after TTL (time-to-live)
+- Response headers include `X-CLASP-Cache: HIT` or `X-CLASP-Cache: MISS`
+
+## Metrics
+
+Access `/metrics` for request statistics:
+
+```json
+{
+  "requests": {
+    "total": 100,
+    "successful": 98,
+    "errors": 2,
+    "streaming": 75,
+    "tool_calls": 15,
+    "success_rate": "98.00%"
+  },
+  "performance": {
+    "avg_latency_ms": "523.50",
+    "requests_per_sec": "2.34"
+  },
+  "cache": {
+    "enabled": true,
+    "size": 42,
+    "max_size": 1000,
+    "hits": 156,
+    "misses": 44,
+    "hit_rate": "78.00%"
+  },
+  "uptime": "5m30s"
+}
+```
+
+## Docker
+
+### Build and Run
+
+```bash
+# Build Docker image
+make docker
+
+# Run container
+make docker-run
+
+# Stop container
+make docker-stop
+```
+
+### Docker Compose
+
+Create a `.env` file with your configuration:
+
+```bash
+PROVIDER=openai
+OPENAI_API_KEY=sk-...
+CLASP_DEFAULT_MODEL=gpt-4o
+```
+
+Then start the service:
+
+```bash
+docker-compose up -d
+```
+
+### Docker Environment Variables
+
+All configuration is done through environment variables. See the Environment Variables section above.
+
+## Development
+
+```bash
+# Build
+make build
+
+# Run tests
+make test
+
+# Build for all platforms
+make build-all
+
+# Build Docker image
+make docker
+
+# Format code
+make fmt
+```
+
+## Debugging
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+# Via CLI flag
+clasp -debug
+
+# Via environment variable
+CLASP_DEBUG=true clasp
+
+# Log only requests or responses
+CLASP_DEBUG_REQUESTS=true clasp
+CLASP_DEBUG_RESPONSES=true clasp
+```
+
+Debug output includes:
+- Incoming Anthropic requests
+- Outgoing OpenAI requests
+- Raw OpenAI responses
+- Transformed Anthropic responses
+
+## Authentication
+
+Secure your CLASP proxy with API key authentication to control access:
+
+```bash
+# Enable authentication with CLI flags
+clasp -auth -auth-api-key "my-secret-key"
+
+# Or via environment variables
+CLASP_AUTH=true CLASP_AUTH_API_KEY="my-secret-key" clasp
+```
+
+### Providing the API Key
+
+Clients can provide the API key in two ways:
+
+```bash
+# Via x-api-key header
+curl http://localhost:8080/v1/messages \
+  -H "x-api-key: my-secret-key" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "claude-3-5-sonnet-20241022", ...}'
+
+# Via Authorization header (Bearer token)
+curl http://localhost:8080/v1/messages \
+  -H "Authorization: Bearer my-secret-key" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "claude-3-5-sonnet-20241022", ...}'
+```
+
+### Authentication Options
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLASP_AUTH` | Enable authentication | `false` |
+| `CLASP_AUTH_API_KEY` | Required API key | - |
+| `CLASP_AUTH_ALLOW_ANONYMOUS_HEALTH` | Allow /health without auth | `true` |
+| `CLASP_AUTH_ALLOW_ANONYMOUS_METRICS` | Allow /metrics without auth | `false` |
+
+### Endpoint Access with Authentication Enabled
+
+| Endpoint | Default Access |
+|----------|----------------|
+| `/` | Always accessible |
+| `/health` | Anonymous by default |
+| `/metrics` | Requires auth by default |
+| `/metrics/prometheus` | Requires auth by default |
+| `/v1/messages` | Requires auth |
+
+### Using with Claude Code
+
+When authentication is enabled, set both the base URL and API key:
+
+```bash
+# Start CLASP with auth
+OPENAI_API_KEY=sk-... clasp -auth -auth-api-key "proxy-key"
+
+# Use with Claude Code (the proxy key is passed as the Anthropic key)
+ANTHROPIC_BASE_URL=http://localhost:8080 ANTHROPIC_API_KEY=proxy-key claude
+```
+
+## Request Queuing
+
+Queue requests during provider outages for automatic retry:
+
+```bash
+# Enable request queuing
+clasp -queue
+
+# Custom queue settings
+clasp -queue -queue-max-size 200 -queue-max-wait 60
+
+# Via environment
+CLASP_QUEUE=true CLASP_QUEUE_MAX_SIZE=200 clasp
+```
+
+### Queue Options
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLASP_QUEUE` | Enable request queuing | `false` |
+| `CLASP_QUEUE_MAX_SIZE` | Maximum queued requests | `100` |
+| `CLASP_QUEUE_MAX_WAIT` | Queue timeout in seconds | `30` |
+| `CLASP_QUEUE_RETRY_DELAY` | Retry delay in milliseconds | `1000` |
+| `CLASP_QUEUE_MAX_RETRIES` | Maximum retries per request | `3` |
+
+## Circuit Breaker
+
+Prevent cascade failures with circuit breaker pattern:
+
+```bash
+# Enable circuit breaker
+clasp -circuit-breaker
+
+# Custom circuit breaker settings
+clasp -circuit-breaker -cb-threshold 10 -cb-recovery 3 -cb-timeout 60
+
+# Via environment
+CLASP_CIRCUIT_BREAKER=true clasp
+```
+
+### Circuit Breaker Options
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLASP_CIRCUIT_BREAKER` | Enable circuit breaker | `false` |
+| `CLASP_CIRCUIT_BREAKER_THRESHOLD` | Failures before opening circuit | `5` |
+| `CLASP_CIRCUIT_BREAKER_RECOVERY` | Successes to close circuit | `2` |
+| `CLASP_CIRCUIT_BREAKER_TIMEOUT` | Timeout in seconds before retry | `30` |
+
+### Circuit Breaker States
+
+- **Closed**: Normal operation, requests pass through
+- **Open**: Circuit tripped, requests fail fast with 503
+- **Half-Open**: Testing if service recovered, limited requests allowed
+
+### Maximum Resilience Configuration
+
+For production deployments requiring maximum resilience:
+
+```bash
+# Enable queue + circuit breaker + fallback
+OPENAI_API_KEY=sk-xxx OPENROUTER_API_KEY=sk-or-xxx \
+  clasp -queue -circuit-breaker -fallback \
+    -queue-max-size 200 \
+    -cb-threshold 5 \
+    -cb-timeout 30
 ```
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/jedarden/CLASP).

package/bin/clasp-wrapper.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+/**
+ * CLASP Wrapper Script
+ * Executes the Go binary with all passed arguments
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const BINARY_NAME = os.platform() === 'win32' ? 'clasp.exe' : 'clasp';
+const binaryPath = path.join(__dirname, BINARY_NAME);
+
+// Check if binary exists
+if (!fs.existsSync(binaryPath)) {
+  console.error('[CLASP] Binary not found. Running install script...');
+  require('../scripts/install.js');
+}
+
+// Spawn the Go binary with all arguments
+const args = process.argv.slice(2);
+const child = spawn(binaryPath, args, {
+  stdio: 'inherit',
+  env: process.env
+});
+
+child.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('[CLASP] Binary not found. Please run: npm run postinstall');
+  } else {
+    console.error(`[CLASP] Error: ${err.message}`);
+  }
+  process.exit(1);
+});
+
+child.on('close', (code) => {
+  process.exit(code || 0);
+});

package/package.json

@@ -1,38 +1,53 @@
 {
   "name": "clasp-ai",
-  "version": "0.0.1",
-  "description": "CLASP - Claude Language Agent Super Proxy. Run Claude Code with any LLM provider - OpenAI, Azure, OpenRouter, and more.",
-  "bin": {
-    "clasp": "./bin/clasp"
+  "version": "0.7.1",
+  "description": "Claude Language Agent Super Proxy - Translate Claude/Anthropic API calls to OpenAI-compatible endpoints",
+  "author": "jedarden",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jedarden/CLASP.git"
   },
-  "scripts": {
-    "postinstall": "node postinstall.js || true"
+  "bugs": {
+    "url": "https://github.com/jedarden/CLASP/issues"
   },
+  "homepage": "https://github.com/jedarden/CLASP#readme",
   "keywords": [
     "claude",
-    "claude-code",
-    "openai",
-    "openrouter",
-    "azure",
     "anthropic",
-    "llm",
+    "openai",
     "proxy",
+    "llm",
     "ai",
-    "clasp",
-    "gpt",
-    "gemini",
-    "grok"
+    "api",
+    "translation",
+    "openrouter",
+    "azure"
   ],
-  "author": "",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/yourname/clasp-ai"
+  "bin": {
+    "clasp": "./bin/clasp-wrapper.js"
   },
-  "homepage": "https://github.com/yourname/clasp-ai#readme",
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "start": "node bin/clasp-wrapper.js",
+    "prepack": "node scripts/prepack.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=16.0.0"
   },
-  "os": ["darwin", "linux", "win32"],
-  "cpu": ["x64", "arm64"]
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
 }