@khanglvm/ai-router 1.0.0

package/.env.test-suite.example

@@ -0,0 +1,15 @@
+AI_ROUTER_TEST_HOST=127.0.0.1
+AI_ROUTER_TEST_PORT=8787
+AI_ROUTER_TEST_TIMEOUT_MS=90000
+
+AI_ROUTER_TEST_PROVIDER_KEYS=EXAMPLE
+
+AI_ROUTER_TEST_EXAMPLE_PROVIDER_ID=example
+AI_ROUTER_TEST_EXAMPLE_NAME="Example Provider"
+AI_ROUTER_TEST_EXAMPLE_API_KEY=sk-...
+AI_ROUTER_TEST_EXAMPLE_OPENAI_BASE_URL=https://api.example.com/v1
+AI_ROUTER_TEST_EXAMPLE_CLAUDE_BASE_URL=https://api.example.com
+AI_ROUTER_TEST_EXAMPLE_MODELS=model-a,model-b
+AI_ROUTER_TEST_EXAMPLE_HEADERS_JSON={"X-Env":"local"}
+AI_ROUTER_TEST_EXAMPLE_OPENAI_HEADERS_JSON={"User-Agent":"Mozilla/5.0"}
+AI_ROUTER_TEST_EXAMPLE_CLAUDE_HEADERS_JSON={"x-foo":"bar"}

package/README.md

@@ -0,0 +1,268 @@
+# ai-router-proxy
+
+Generic API proxy for AI providers with:
+- Local runtime (`~/.ai-router.json`)
+- Cloudflare Worker runtime (`AI_ROUTER_CONFIG_JSON` secret)
+- Snap-based CLI + TUI setup/deploy flows
+- Unified + dual response endpoints:
+  - root/unified: `/`, `/v1`, `/v1/messages`, `/v1/chat/completions`
+  - `/anthropic` (Anthropic-compatible responses)
+  - `/openai` (OpenAI-compatible responses)
+- OS startup install/uninstall/status (macOS/Linux)
+- Auto-restart local server when config file changes
+
+## Install / Run
+
+```bash
+npm install
+```
+
+Global CLI (after `npm i -g`):
+- `ai-router` or `ai-router start` -> start local proxy
+- `ai-router setup` -> provider/model/master-key/startup manager (TUI by default)
+- `ai-router deploy` -> Cloudflare deploy helper (TUI by default)
+
+### Interactive setup (TUI)
+
+```bash
+npx ai-router-proxy setup
+# or globally:
+ai-router setup
+```
+
+This command:
+- asks for provider name/base URL/API key
+- requires a provider id (slug/camelCase, e.g. `openrouter` or `myProvider`)
+- probes the provider with live requests
+- auto-detects supported format(s): `openai` and/or `claude`
+- tries to discover model list
+- saves config to `~/.ai-router.json`
+
+### Non-interactive setup
+
+```bash
+npx ai-router-proxy setup \
+  --operation=upsert-provider \
+  --provider-id=openrouter \
+  --name=OpenRouter \
+  --base-url=https://openrouter.ai/api/v1 \
+  --api-key=sk-... \
+  --models=gpt-4o,claude-3-5-sonnet-latest \
+  --headers='{"User-Agent":"Mozilla/5.0"}'
+```
+
+### Start local proxy (default command)
+
+```bash
+ai-router
+# same as:
+ai-router start --port=8787
+```
+
+`ai-router start`:
+- starts local proxy on localhost
+- prints proxy URLs and provider/model summary
+- exits with guidance if config/providers are missing
+- watches `~/.ai-router.json` and auto-restarts on changes (default enabled)
+
+```bash
+ai-router start --port=8787 --watch-config=true
+```
+
+Secure local mode (require master key on every endpoint):
+
+```bash
+ai-router setup --operation=set-master-key --master-key=local_secret_key
+ai-router start --require-auth=true
+```
+
+Then call local endpoints with:
+- `Authorization: Bearer local_secret_key`
+- or `x-api-key: local_secret_key`
+
+Local mode reads `~/.ai-router.json` on each request. Auth is optional by default, and enforced when `--require-auth=true`.
+
+Endpoint bases:
+- Anthropic-compatible: `http://127.0.0.1:8787/anthropic`
+- OpenAI-compatible: `http://127.0.0.1:8787/openai`
+
+### Setup manager operations (CLI mode)
+
+```bash
+ai-router setup --operation=list
+ai-router setup --operation=remove-provider --provider-id=openrouter
+ai-router setup --operation=remove-model --provider-id=openrouter --model=gpt-4o
+ai-router setup --operation=set-master-key --master-key=your_master_key
+```
+
+### OS startup (start with OS)
+
+```bash
+ai-router setup --operation=startup-install
+ai-router setup --operation=startup-install --require-auth=true
+ai-router setup --operation=startup-status
+ai-router setup --operation=startup-uninstall
+```
+
+On macOS this installs a LaunchAgent, on Linux a `systemd --user` service. The startup service runs `ai-router start` with config-watch enabled.
+
+## Provider Smoke Test Suite (Real-Usage Simulation)
+
+This repo includes a CLI smoke test that simulates real local usage:
+- backs up `~/.ai-router.json` (if it exists)
+- removes the active file to start clean
+- runs `ai-router setup --operation=upsert-provider` for the provided providers/models
+- starts `ai-router`
+- sends live API requests for every configured provider/model
+- prints a terminal report
+- removes test config and restores the original `~/.ai-router.json` backup
+
+### Local secrets file (git-ignored)
+
+Use a local env file (already git-ignored by `.gitignore`) to store provider credentials and model lists:
+
+```bash
+cp .env.test-suite.example .env.test-suite
+```
+
+Fill in your provider details in `.env.test-suite`.
+
+Optional header fields per provider key:
+- `AI_ROUTER_TEST_<KEY>_HEADERS_JSON`
+- `AI_ROUTER_TEST_<KEY>_OPENAI_HEADERS_JSON`
+- `AI_ROUTER_TEST_<KEY>_CLAUDE_HEADERS_JSON`
+
+These must be JSON objects and are passed into `ai-router setup --headers=...`.
+
+### Run the smoke suite
+
+```bash
+npm run test:provider-smoke -- --env-file=.env.test-suite --provider-keys=RAMCLOUDS,ZAI
+```
+
+You can also pass provider specs directly via CLI JSON:
+
+```bash
+node scripts/provider-smoke-suite.mjs --providers-json='[{"id":"myprovider","name":"My Provider","apiKey":"sk-...","openaiBaseUrl":"https://api.example.com/v1","models":["model-a"]}]'
+```
+
+Notes:
+- If a provider exposes separate OpenAI and Anthropic base URLs, the suite creates endpoint-specific setup entries (e.g. `provider-openai`, `provider-claude`) so both paths are tested.
+- `--skip-probe=true` is the default for repeatable test runs. Set `--skip-probe=false` to include live setup probing.
+
+## Config File
+
+Default location: `~/.ai-router.json`
+
+```json
+{
+  "version": 1,
+  "masterKey": "your-worker-master-key",
+  "defaultModel": "openrouter/gpt-4o",
+  "providers": [
+    {
+      "id": "openrouter",
+      "name": "OpenRouter",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "apiKey": "sk-...",
+      "format": "openai",
+      "formats": ["openai"],
+      "auth": { "type": "bearer" },
+      "models": [{ "id": "gpt-4o" }, { "id": "claude-3-5-sonnet-latest" }]
+    }
+  ]
+}
+```
+
+Model names used by clients must follow:
+
+```txt
+${provider}/${model-name}
+```
+
+Examples:
+- `openrouter/gpt-4o`
+- `myProvider/claude-3-5-sonnet-latest`
+
+## Worker Deploy
+
+1) Export worker payload (requires `masterKey` and at least one provider):
+
+```bash
+ai-router deploy --export-only=true --out=.ai-router.worker.json
+```
+
+2) Upload payload as Worker secret:
+
+```bash
+wrangler secret put AI_ROUTER_CONFIG_JSON < .ai-router.worker.json
+```
+
+3) Deploy:
+
+```bash
+npm run deploy
+```
+
+Or one command (requires Wrangler installed/login):
+
+```bash
+ai-router deploy
+ai-router deploy --env=production
+```
+
+Quick master-key rotation on the Worker (runtime override secret, no full config re-export required):
+
+```bash
+ai-router worker-key --master-key=new_master_key
+ai-router worker-key --env=production --master-key=new_master_key
+# or reuse the local config's masterKey:
+ai-router worker-key --use-config-key=true
+```
+
+The Worker reads config from:
+- `AI_ROUTER_CONFIG_JSON` (primary)
+- `PROXY_CONFIG_JSON` or `AI_ROUTER_JSON` (aliases)
+- `AI_ROUTER_MASTER_KEY` (optional runtime override)
+
+## Endpoints
+
+- `GET /health`
+- `POST /` (unified, auto-detect request format)
+- `POST /v1` (unified, auto-detect request format)
+- `GET /anthropic/v1/models`
+- `GET /openai/v1/models`
+- `POST /anthropic/v1/messages` (Anthropic-compatible)
+- `POST /openai/v1/chat/completions` (OpenAI-compatible)
+
+Backward-compatible routes also work:
+- `GET /v1/models`
+- `POST /v1/messages`
+- `POST /v1/chat/completions`
+
+Worker auth note:
+- In Cloudflare Worker mode, all endpoints require the master key (including `GET /health`, `GET /`, and `GET /.../models`).
+- Send it as `Authorization: Bearer <masterKey>` (or `x-api-key: <masterKey>`).
+
+## Claude Code Example
+
+Point Claude Code at the Anthropic endpoint and use a qualified model id:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "their_master_key",
+    "ANTHROPIC_BASE_URL": "https://your-worker.example.workers.dev/anthropic"
+  },
+  "ANTHROPIC_DEFAULT_OPUS_MODEL": "provider-name/model-name"
+}
+```
+
+## Notes
+
+- Request translation currently supports:
+  - Claude request -> OpenAI provider
+  - OpenAI request -> Claude provider
+  - OpenAI stream/non-stream response -> Claude response
+- Claude stream/non-stream response -> OpenAI response
+- If a provider/model supports the endpoint format directly, the proxy bypasses the translator.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@khanglvm/ai-router",
+  "version": "1.0.0",
+  "description": "Generic AI Router Proxy (local + Cloudflare Worker)",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "ai-router": "./src/cli-entry.js",
+    "ai-router-proxy": "./src/cli-entry.js"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "tail": "wrangler tail",
+    "start": "node ./src/cli-entry.js start",
+    "setup": "node ./src/cli-entry.js setup",
+    "deploy:worker": "node ./src/cli-entry.js deploy",
+    "test:provider-smoke": "node ./scripts/provider-smoke-suite.mjs"
+  },
+  "dependencies": {
+    "@levu/snap": "^0.1.1"
+  },
+  "devDependencies": {
+    "wrangler": "^3.0.0"
+  }
+}