@relayplane/proxy 0.1.9 → 0.2.0

package/README.md

@@ -1,319 +1,185 @@
 # @relayplane/proxy
 
-**100% Local. Zero Cloud. Full Control.**
+Intelligent AI model routing proxy for cost optimization and observability.
 
-Intelligent AI model routing that cuts costs by 50-80% while maintaining quality.
-
-[![CI](https://github.com/RelayPlane/proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/RelayPlane/proxy/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@relayplane/proxy)](https://www.npmjs.com/package/@relayplane/proxy)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Install
-
-```bash
-npm install @relayplane/proxy
-```
-
-Or run directly:
+## Installation
 
 ```bash
-npx @relayplane/proxy
-```
-
-## CLI Commands
-
-```bash
-# Start the proxy server
-npx @relayplane/proxy
-
-# Start on custom port
-npx @relayplane/proxy --port 8080
-
-# View routing statistics
-npx @relayplane/proxy stats
-
-# View stats for last 30 days
-npx @relayplane/proxy stats --days 30
-
-# Show help
-npx @relayplane/proxy --help
+npm install -g @relayplane/proxy
 ```
 
 ## Quick Start
 
-### 1. Set your API keys
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-export OPENAI_API_KEY="sk-..."
-# Optional: GEMINI_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY
-```
-
-### 2. Start the proxy
-
 ```bash
-npx @relayplane/proxy --port 3001
-```
+# Set your API keys
+export ANTHROPIC_API_KEY=your-key
+export OPENAI_API_KEY=your-key
 
-### 3. Point your tools to the proxy
+# Start the proxy
+relayplane-proxy
 
-```bash
+# Configure your tools to use the proxy
 export ANTHROPIC_BASE_URL=http://localhost:3001
 export OPENAI_BASE_URL=http://localhost:3001
 
-# Now run OpenClaw, Cursor, Aider, or any tool
-openclaw
+# Run your AI tools (Claude Code, Cursor, Aider, etc.)
 ```
 
-That's it. All API calls now route through RelayPlane for intelligent model selection.
+## Features
 
-## How It Works
+- **Intelligent Routing**: Routes requests to the optimal model based on task type
+- **Cost Tracking**: Tracks and reports API costs across all providers
+- **Provider Agnostic**: Works with Anthropic, OpenAI, Gemini, xAI, and more
+- **Local Learning**: Learns from your usage patterns to improve routing
+- **Privacy First**: Never sees your prompts or responses
 
-```
-Your Tool (OpenClaw, Cursor, etc.)
-         │
-         ▼
-    RelayPlane Proxy
-    ├── Infers task type (code_review, analysis, etc.)
-    ├── Checks routing rules
-    ├── Selects optimal model (Haiku for simple, Opus for complex)
-    ├── Tracks outcomes (success/failure/latency)
-    └── Learns patterns → improves over time
-         │
-         ▼
-    Provider (Anthropic, OpenAI, etc.)
-```
-
-## Learning & Adaptation
-
-RelayPlane doesn't just route — it **learns from every request**:
-
-- **Outcome Tracking** — Records success/failure for each route decision
-- **Pattern Detection** — Identifies what works for your specific codebase
-- **Continuous Improvement** — Routing gets smarter the more you use it
-- **Local Intelligence** — All learning happens in your local SQLite DB
+## CLI Options
 
 ```bash
-# View your routing stats (last 7 days)
-npx @relayplane/proxy stats
+relayplane-proxy [command] [options]
 
-# View last 30 days
-npx @relayplane/proxy stats --days 30
+Commands:
+  (default)              Start the proxy server
+  telemetry [on|off|status]  Manage telemetry settings
+  stats                  Show usage statistics
+  config                 Show configuration
 
-# Query the raw data directly
-sqlite3 ~/.relayplane/data.db "SELECT model, task_type, COUNT(*) FROM runs GROUP BY model, task_type"
+Options:
+  --port <number>    Port to listen on (default: 3001)
+  --host <string>    Host to bind to (default: 127.0.0.1)
+  --offline          Disable all network calls except LLM endpoints
+  --audit            Show telemetry payloads before sending
+  -v, --verbose      Enable verbose logging
+  -h, --help         Show this help message
+  --version          Show version
 ```
 
-Unlike static routing rules, RelayPlane adapts to **your** usage patterns.
+## Telemetry
 
-## Supported Providers
+RelayPlane collects anonymous telemetry to improve model routing. This data helps us understand usage patterns and optimize routing decisions.
 
-| Provider | Models | Streaming | Tools |
-|----------|--------|-----------|-------|
-| **Anthropic** | Claude 4.5 (Opus, Sonnet, Haiku) | ✓ | ✓ |
-| **OpenAI** | GPT-5.2, GPT-5.2-Codex, o1, o3 | ✓ | ✓ |
-| **Google** | Gemini 2.0 Flash, 2.0 Pro | ✓ | ✓ |
-| **xAI** | Grok-3, Grok-3-mini | ✓ | ✓ |
-| **Moonshot** | v1-8k, v1-32k, v1-128k | ✓ | ✓ |
+### What We Collect (Exact Schema)
 
-## Routing Modes
-
-| Model | Description |
-|-------|-------------|
-| `relayplane:auto` | Infers task type, routes to optimal model |
-| `relayplane:cost` | Prioritizes cheapest models (maximum savings) |
-| `relayplane:quality` | Uses best available model |
-
-Or pass through explicit models: `claude-3-5-sonnet-latest`, `gpt-4o`, etc.
-
-## Why RelayPlane?
-
-| Without RelayPlane | With RelayPlane |
-|-------------------|-----------------|
-| Pay Opus token rates for simple tasks | Route simple tasks to Haiku (1/10 the cost) |
-| Static model selection | Learns from outcomes over time |
-| Manual optimization | Automatic cost-quality balance |
-| No visibility into spend | Built-in savings tracking |
+```json
+{
+  "device_id": "anon_8f3a...",
+  "task_type": "code_review",
+  "model": "claude-3-5-haiku",
+  "tokens_in": 1847,
+  "tokens_out": 423,
+  "latency_ms": 2341,
+  "success": true,
+  "cost_usd": 0.02
+}
+```
 
-## Key Features
+### Field Descriptions
 
-- **100% Local** — All data in SQLite (`~/.relayplane/data.db`)
-- **Zero Friction** — Set 2 env vars, done
-- **Learning** — Improves routing based on outcomes
-- **Full Streaming** — SSE support for all providers
-- **Tool Calls** — Function calling across providers
+| Field | Type | Description |
+|-------|------|-------------|
+| `device_id` | string | Anonymous random ID (not fingerprintable) |
+| `task_type` | string | Inferred from token patterns, NOT prompt content |
+| `model` | string | The model that handled the request |
+| `tokens_in` | number | Input token count |
+| `tokens_out` | number | Output token count |
+| `latency_ms` | number | Request latency in milliseconds |
+| `success` | boolean | Whether the request succeeded |
+| `cost_usd` | number | Estimated cost in USD |
 
-## Programmatic Usage
+### Task Types
 
-```typescript
-import { startProxy, RelayPlane, calculateSavings } from '@relayplane/proxy';
+Task types are inferred from request characteristics (token counts, ratios, etc.) - never from prompt content:
 
-// Start the proxy
-await startProxy({ port: 3001, verbose: true });
+- `quick_task` - Short input/output (< 500 tokens each)
+- `code_review` - Medium-long input, medium output
+- `generation` - High output/input ratio
+- `classification` - Low output/input ratio, short output
+- `long_context` - Input > 10,000 tokens
+- `content_generation` - Output > 1,000 tokens
+- `tool_use` - Request includes tool calls
+- `general` - Default classification
 
-// Or use RelayPlane directly
-const relay = new RelayPlane({});
-const result = await relay.run({ prompt: 'Review this code...' });
-console.log(result.taskType); // 'code_review'
-console.log(result.model);    // 'anthropic:claude-3-5-haiku-latest'
+### What We NEVER Collect
 
-// Check savings
-const savings = calculateSavings(relay.store, 30);
-console.log(`Saved ${savings.savingsPercent}% this month`);
+- ❌ Your prompts
+- ❌ Model responses
+- ❌ File paths or contents
+- ❌ Anything that could identify you or your project
 
-relay.close();
-```
+### Verification
 
-## CLI Options
+You can verify exactly what data is collected:
 
 ```bash
-npx @relayplane/proxy [options]
+# See telemetry payloads before they're sent
+relayplane-proxy --audit
 
-Options:
-  --port <number>    Port to listen on (default: 3001)
-  --host <string>    Host to bind to (default: 127.0.0.1)
-  -v, --verbose      Enable verbose logging
-  -h, --help         Show help
-```
+# Disable all telemetry transmission
+relayplane-proxy --offline
 
-## REST API
-
-The proxy exposes endpoints for stats and monitoring:
+# View the source code
+# https://github.com/RelayPlane/proxy
+```
 
-### `GET /health`
+### Opt-Out
 
-Server health and version info.
+To disable telemetry completely:
 
 ```bash
-curl http://localhost:3001/health
-```
-
-```json
-{
-  "status": "ok",
-  "version": "0.1.7",
-  "uptime": "2h 15m 30s",
-  "providers": { "anthropic": true, "openai": true, "google": false },
-  "totalRuns": 142
-}
+relayplane-proxy telemetry off
 ```
 
-### `GET /stats`
-
-Aggregated statistics and cost savings.
+To re-enable:
 
 ```bash
-curl http://localhost:3001/stats
-```
-
-```json
-{
-  "totalRuns": 142,
-  "savings": {
-    "estimatedSavingsPercent": "73.2%",
-    "actualCostUsd": "0.0234",
-    "baselineCostUsd": "0.0873",
-    "savedUsd": "0.0639"
-  },
-  "modelDistribution": {
-    "anthropic/claude-3-5-haiku-latest": { "count": 98, "percentage": "69.0%" },
-    "anthropic/claude-sonnet-4-20250514": { "count": 44, "percentage": "31.0%" }
-  }
-}
+relayplane-proxy telemetry on
 ```
 
-### `GET /runs`
-
-Recent routing decisions.
+Check current status:
 
 ```bash
-curl "http://localhost:3001/runs?limit=10"
-```
-
-```json
-{
-  "runs": [
-    {
-      "runId": "abc123",
-      "timestamp": "2026-02-03T13:26:03Z",
-      "model": "anthropic/claude-3-5-haiku-latest",
-      "taskType": "code_generation",
-      "confidence": 0.92,
-      "mode": "auto",
-      "durationMs": 1203,
-      "promptPreview": "Write a function that..."
-    }
-  ],
-  "total": 142
-}
+relayplane-proxy telemetry status
 ```
 
 ## Configuration
 
-RelayPlane creates a config file on first run at `~/.relayplane/config.json`:
-
-```json
-{
-  "strategies": {
-    "code_review": { "model": "anthropic:claude-sonnet-4-20250514" },
-    "code_generation": { "model": "anthropic:claude-3-5-haiku-latest" },
-    "analysis": { "model": "anthropic:claude-sonnet-4-20250514" },
-    "summarization": { "model": "anthropic:claude-3-5-haiku-latest" },
-    "creative_writing": { "model": "anthropic:claude-sonnet-4-20250514" },
-    "data_extraction": { "model": "anthropic:claude-3-5-haiku-latest" },
-    "translation": { "model": "anthropic:claude-3-5-haiku-latest" },
-    "question_answering": { "model": "anthropic:claude-3-5-haiku-latest" },
-    "general": { "model": "anthropic:claude-3-5-haiku-latest" }
-  },
-  "defaults": {
-    "qualityModel": "claude-sonnet-4-20250514",
-    "costModel": "claude-3-5-haiku-latest"
-  }
-}
-```
-
-**Edit and save — changes apply instantly** (hot-reload, no restart needed).
+Configuration is stored in `~/.relayplane/config.json`.
 
-### Strategy Options
+### Set API Key (Pro Features)
 
-| Field | Description |
-|-------|-------------|
-| `model` | Provider and model in format `provider:model` |
-| `minConfidence` | Optional. Only use this strategy if confidence >= threshold |
-| `fallback` | Optional. Fallback model if primary fails |
-
-### Examples
-
-Route all analysis tasks to GPT-4o:
-```json
-"analysis": { "model": "openai:gpt-4o" }
+```bash
+relayplane-proxy config set-key your-api-key
 ```
 
-Use Opus for code review with fallback:
-```json
-"code_review": { 
-  "model": "anthropic:claude-opus-4-5-20250514",
-  "fallback": "anthropic:claude-sonnet-4-20250514"
-}
+### View Configuration
+
+```bash
+relayplane-proxy config
 ```
 
-## Data Storage
+## Usage Statistics
 
-All data stored locally at `~/.relayplane/data.db` (SQLite).
+View your usage statistics:
 
 ```bash
-# View recent runs
-sqlite3 ~/.relayplane/data.db "SELECT * FROM runs ORDER BY created_at DESC LIMIT 10"
-
-# Check routing rules
-sqlite3 ~/.relayplane/data.db "SELECT * FROM routing_rules"
+relayplane-proxy stats
 ```
 
-## Links
+This shows:
+- Total requests and cost
+- Success rate
+- Breakdown by model
+- Breakdown by task type
+
+## Environment Variables
 
-- [Documentation](https://relayplane.com/integrations/openclaw)
-- [GitHub](https://github.com/RelayPlane/proxy)
-- [RelayPlane SDK](https://github.com/RelayPlane/sdk)
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `GEMINI_API_KEY` | Google Gemini API key |
+| `XAI_API_KEY` | xAI/Grok API key |
+| `MOONSHOT_API_KEY` | Moonshot API key |
 
 ## License