proxitor 0.9.0-beta.1 → 0.9.0-beta.11

package/README.md

@@ -1,90 +1,70 @@
 # proxitor
 
 <p align="center">
-  <strong>A transparent proxy between your AI CLI tools and OpenRouter.</strong><br/>
-  Route by provider. Control costs. Keep streaming. Zero config changes in Claude Code.
+  <strong>A friendly proxy between your AI CLI tools and OpenRouter.</strong><br/>
+  Route requests to the provider you want. Keep prompt caching alive. Cut costs.<br/>
+  Your tools don't even notice.
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/proxitor"><img src="https://img.shields.io/npm/v/proxitor?color=6366f1&labelColor=1e2327&label=npm" alt="npm version"></a>
-  <a href="https://github.com/neiromaster/proxitor/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?labelColor=1e2327" alt="MIT License"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?labelColor=1e2327" alt="MIT License"></a>
   <img src="https://img.shields.io/badge/node-%3E%3D22-3b82f6?labelColor=1e2327" alt="Node.js ≥ 22">
-  <img src="https://img.shields.io/badge/built_with-TypeScript-3178c6?labelColor=1e2327" alt="TypeScript">
 </p>
 
----
+🌍 **English** · [Русский](./docs/README.ru.md)
 
-```
-  Claude Code / Codex
-        │
-        │  ANTHROPIC_BASE_URL=http://localhost:8828/v1
-        ▼
-  ┌───────────────┐
-  │   proxitor    │  ← injects provider routing
-  │  :8828        │  ← streams SSE back unchanged
-  └───────────────┘
-        │
-        │  + X-OpenRouter-* headers
-        ▼
-     OpenRouter
-   ┌──────┬──────┐
-  Anthropic  DeepInfra  Azure  ...
-```
+<p align="center"><img src="./docs/assets/proxitor-wizard.gif" alt="proxitor setup wizard" width="640"></p>
 
 ---
 
-## Why
+Proxitor sits between Claude Code (or Codex, or any Anthropic/OpenAI-compatible CLI) and [OpenRouter](https://openrouter.ai). One API key, every model — but **you** decide which provider serves each request, and you make prompt caching actually work.
 
-### The prompt cache problem
+```
+your AI CLI  →  proxitor  →  OpenRouter  →  the provider you picked
+```
 
-OpenRouter is convenient — one key, every model. But by default it load-balances across multiple provider instances for the same model. Each request can land on a different provider, and **prompt caching is provider-scoped**: a cache entry built on Anthropic's infrastructure doesn't help when the next request goes to DeepInfra.
+## Why you'd want this
 
-Claude Code sends a large system prompt on every single request. Without a pinned provider, you pay full token price every time. With proxitor locking `claude-*` to `anthropic`, that system prompt gets cached after the first hit and subsequent requests cost a fraction.
+OpenRouter is convenient — one key, every model. But it load-balances across providers, and **prompt caching is provider-scoped**: a cache built on Anthropic doesn't help when the next request lands on DeepInfra. Claude Code sends a big system prompt on every request, so without a pinned provider you pay full price every time.
 
-```yaml
-# pin all Claude models to Anthropic — prompt cache works reliably
-modelOverrides:
-  "claude-*":
-    provider:
-      only: "anthropic"
-```
+Pin `claude-*` to `anthropic`, and that system prompt gets cached after the first hit. Subsequent requests cost a fraction.
 
-### Other reasons to use it
+A few other things it's good for:
 
-- **Cost control** — route specific models to cheaper providers when caching isn't the priority
-- **Automatic fallbacks** — if Anthropic is degraded, fall back to DeepInfra without touching your tools
-- **Mixed routing** — `claude-*` on Anthropic, `gpt-*` on Azure, different rules per model
-- **Data privacy** — enforce `dataCollection: deny` or ZDR across all requests
+- **Cost control** — route specific models to cheaper providers when caching isn't the priority.
+- **Automatic fallbacks** — Anthropic down? Fall back to DeepInfra without touching your tools.
+- **Mixed routing** — `claude-*` on Anthropic, `gpt-*` on Azure, different rules per model.
+- **Privacy** — enforce `dataCollection: deny` or zero-data-retention across everything.
 
-Proxitor sits between your CLI tools and OpenRouter, injecting all of this transparently. Your tools don't know anything changed.
-
----
+> Proxitor injects all of this transparently. Your tools see a normal API. Nothing on their side changes.
 
 ## Install
 
+Requires **Node.js 22+**.
+
 ```sh
-# npm
 npm install -g proxitor
-
-# bun
-bun install -g proxitor
-
-# no install needed
-npx proxitor
+# or:  bun install -g proxitor
+# or run it once, no install:  npx proxitor
 ```
 
----
+## Quick start
+
+**1. Set it up** — the wizard asks a few questions and writes your config:
 
-## Quick Start
+```sh
+proxitor config wizard
+```
 
-**1. Start the proxy**
+**2. Run it**
 
 ```sh
-OPENROUTER_API_KEY=sk-or-... proxitor
+proxitor
 # Listening on http://0.0.0.0:8828
 ```
 
-**2. Point your tools at it**
+**3. Point your tool at it**
 
 ```sh
 # Claude Code
@@ -94,368 +74,59 @@ ANTHROPIC_BASE_URL=http://localhost:8828/v1 claude
 OPENAI_BASE_URL=http://localhost:8828/v1 codex
 ```
 
-That's it. Requests flow through proxitor to OpenRouter, SSE streams pass through unchanged.
-
----
-
-## Configuration
-
-Proxitor looks for a config file in this order:
-
-```
-proxitor.config.yaml  →  proxitor.config.yml  →  proxitor.config.json
-.proxitor.yaml        →  .proxitor.yml         →  .proxitor.json
-```
-
-**Priority:** CLI flags > config file > environment variables > defaults
-
-All defaults are derived from a single Zod schema (`DEFAULTS`) — no hardcoded constants scattered across modules. Config values are validated through Zod on load, including the final merged result.
-
-See [`proxitor.config.example.yaml`](./proxitor.config.example.yaml) for the complete reference.
-
-### Authentication type
-
-By default, proxitor sends the API key as a `Bearer` token (`Authorization: Bearer sk-...`). If you're using a custom proxy provider that expects an `OAuth` header instead, set `authType` to `oauth`:
-
-```yaml
-authType: oauth    # "bearer" (default) or "oauth"
-```
-
-This changes the header to `Authorization: OAuth sk-...`.
-
-### Custom API URL and data fallback
-
-When using a custom `openrouterBaseUrl` that points to a third-party service, that service may not support OpenRouter-specific endpoints like `/providers` or `/models/{author}/{slug}/endpoints`. Proxitor handles this automatically:
-
-- **Automatic fallback** — if the custom API returns an error (4xx/5xx) or an unexpected response format for data endpoints, proxitor falls back to `https://openrouter.ai/api` (no API key needed — these endpoints are public)
-- **`openrouterDataUrl`** — set this explicitly to control the primary URL for data fetching, independent of `openrouterBaseUrl` (which is used for proxying requests)
-
-```yaml
-# Proxy requests go to custom service, data fetching falls back to OpenRouter
-# NOTE: do NOT include /v1 in the base URL — request paths like /v1/chat/completions
-# are forwarded as-is, so /v1 would be duplicated if included here
-openrouterBaseUrl: 'https://custom-service.example.com/api'
-
-# Explicitly set the primary data URL (optional, defaults to openrouterBaseUrl)
-# openrouterDataUrl: 'https://openrouter.ai/api'
-```
-
-When a fallback occurs, proxitor logs a warning: `Custom API did not return providers, using OpenRouter data as fallback`.
-
-### Provider routing
-
-Control which provider handles your requests. All three options accept a string or an array:
-
-```yaml
-# Strict lock — only this provider, no fallbacks
-provider:
-  only: "anthropic"
-
-# Restricted pool — load balance between these providers only
-provider:
-  only:
-    - "anthropic"
-    - "deepinfra"
-
-# Priority order — try Anthropic first, fall back to others if unavailable
-provider:
-  order: "anthropic"
-  allowFallbacks: true
-
-# Strict order — try in sequence, no fallbacks outside the list
-provider:
-  order:
-    - "anthropic"
-    - "deepinfra"
-  allowFallbacks: false
-
-# Blacklist — never use these providers
-provider:
-  ignore: "azure"
-```
-
-| Option | Behavior |
-|---|---|
-| `only` | Restrict to the listed provider(s). Load balances by price within the list. Never routes outside it — if all are unavailable, the request fails. |
-| `order` | Try providers in the specified priority order. If none work, falls back to other available providers (unless `allowFallbacks: false`). |
-| `ignore` | Never route to the listed provider(s). |
-
-Without `provider` set, requests are forwarded unchanged.
-
-See [OpenRouter's provider routing docs](https://openrouter.ai/docs/guides/routing/provider-selection) for the full list of supported providers and options.
-
-### Per-model overrides
-
-Route different models differently. Keys are exact names or prefix wildcards. More specific matches win.
-
-```yaml
-provider:
-  order: "deepinfra"   # global default
-
-modelOverrides:
-  # Exact match — force this model to Anthropic
-  "claude-sonnet-4-6":
-    provider:
-      only: "anthropic"
-
-  # Wildcard — all claude-* models prefer Anthropic with fallback
-  "claude-*":
-    provider:
-      order:
-        - "anthropic"
-        - "deepinfra"
-
-  # GPT models to OpenAI/Azure, plus a custom header
-  "gpt-*":
-    provider:
-      only:
-        - "openai"
-        - "azure"
-    headers:
-      X-Model-Family: "gpt"
-```
-
-**Match priority:** exact name > longer prefix > shorter prefix.
+That's the whole setup. Requests flow through proxitor; streaming responses pass through untouched.
 
-### Custom headers
+## Configuring it
 
-Add headers to all proxied requests, or per-model (merged on top of global):
-
-```yaml
-headers:
-  X-Custom-Header: "my-value"
-  X-Environment: "production"
-
-modelOverrides:
-  "claude-*":
-    headers:
-      X-Custom-Header: "claude-override"  # overrides the global value
-      X-Extra: "only-for-claude"          # added only for this model
-```
-
-### Advanced provider options
-
-```yaml
-provider:
-  sort: "throughput"          # sort by: price | throughput | latency
-  quantizations:
-    - "fp8"                   # filter by quantization level
-  maxPrice:
-    prompt: 1                 # $/M tokens
-    completion: 2
-  requireParameters: true     # only use providers that support all request params
-  dataCollection: "deny"      # "allow" | "deny"
-  zdr: true                   # Zero Data Retention enforcement
-  preferredMinThroughput:
-    p90: 50                   # tokens/sec (soft threshold)
-  preferredMaxLatency:
-    p90: 3                    # seconds (soft threshold)
-```
-
-### Prompt caching
-
-By default, OpenRouter doesn't enable prompt caching — every request pays full token price. Proxitor can inject `cache_control` and `session_id` to make caching work automatically.
-
-**`cacheControl`** — injects `cache_control: { "type": "ephemeral" }` into the request body. OpenRouter uses this to set cache breakpoints and advance them as conversations grow.
-
-**`cacheControlTtl`** — controls the cache time-to-live. Anthropic's default TTL is 5 minutes (300s). Set to `1h` for a 1-hour cache at higher write cost (2× vs 1.25×). Only applies to Anthropic models — other providers don't support TTL.
-
-**`sessionId`** — injects `session_id` for provider sticky routing. Without it, OpenRouter only pins to a provider after detecting a cache hit. With it, routing sticks from the **first request** — critical for OpenAI models where delayed caching means 0 cached tokens on the first 1-2 requests.
-
-Both `cacheControl` and `sessionId` support `auto` / `always` / `never` modes:
-
-| Mode | `cacheControl` | `sessionId` |
-| --- | --- | --- |
-| `auto` (default) | Anthropic models on `/v1/chat/completions`; all models on `/v1/messages` and `/v1/responses` | Use `X-Claude-Code-Session-Id` header if present; otherwise generate proxy UUID |
-| `always` | All models, all endpoints | Generate a proxy UUID for sticky routing |
-| `never` | Disabled | Disabled |
-
-`cacheControlTtl` values:
-
-| Value | TTL | Write cost | Use when |
-| --- | --- | --- | --- |
-| _(not set)_ | 5 min (Anthropic default) | 1.25× | High-frequency requests (>1 per 5 min) |
-| `5m` | 5 minutes | 1.25× | Explicit short cache |
-| `1h` | 1 hour | 2.0× | Low-frequency or long-running sessions |
-
-```yaml
-cacheControl: auto    # safe default — Anthropic and safe endpoints only
-sessionId: auto       # always ensures sticky routing (client header or proxy UUID)
-
-# Use 1-hour cache for all Anthropic models (higher write cost, longer TTL)
-cacheControlTtl: 1h
-
-# Force caching for all models (may cause 400 on non-Anthropic /v1/chat/completions)
-# cacheControl: always
-
-# Per-model overrides — TTL supports '5m', '1h', or 'default' (cancel global TTL)
-modelOverrides:
-  "gpt-*":
-    cacheControl: never       # OpenAI caches automatically, no injection needed
-    sessionId: always          # but sticky routing still helps
-  "claude-opus-*":
-    cacheControlTtl: default   # cancel global 1h TTL for Opus — use Anthropic's 5 min default
-```
-
-**Why all three matter:**
-
-- **Anthropic models** — `cache_control` activates caching, `cacheControlTtl` extends it beyond 5 min, `session_id` prevents provider flip-flopping that would invalidate it
-- **OpenAI models** — caching is automatic (no `cache_control` needed), but `session_id` ensures sticky routing from request #1 instead of waiting for a cache hit
-- **All models** — `session_id` prevents the provider switch that silently resets cache
-
-### Health check
+The friendly way: an interactive menu — no YAML required.
 
 ```sh
-curl http://localhost:8828/health
+proxitor config         # open the menu
+proxitor config wizard  # (re)run guided setup
 ```
 
-### Cache usage logging
+From the menu you can set your API key and connection, pick routing per model (with live provider pricing), tune caching, and add or edit model overrides. It pulls live data from OpenRouter, so you browse real models and providers with up-to-date prices.
 
-Proxitor automatically logs cache token usage from upstream responses — both non-streaming JSON and streaming SSE. No configuration needed.
+Prefer to edit a file? The full **[configuration reference](./docs/configuration.md)** covers provider routing, per-model overrides, headers, caching modes, and every option. [`proxitor.config.example.yaml`](./proxitor.config.example.yaml) is a commented template.
 
-```
-[abc123] Cache read: 50000, write: 25000 tokens
-[def456] Cache: no cached tokens
-```
-
-Supports both provider formats:
-
-| Provider format | Fields |
-|---|---|
-| Anthropic | `usage.cache_read_input_tokens` / `usage.cache_creation_input_tokens` |
-| OpenAI / OpenRouter | `usage.prompt_tokens_details.cached_tokens` / `cache_write_tokens` |
-
-When both formats are present (e.g., OpenRouter relaying an Anthropic response), Anthropic fields take priority.
-
----
+## Adding a model override
 
-## Interactive Config Manager
+Pin a model — or a wildcard like `claude-*` — to specific providers, straight from the menu. It pulls live pricing and latency for every provider of that model.
 
-Proxitor includes an interactive CLI for managing model overrides — search models, pick providers, and write to config without editing YAML by hand.
+<p align="center"><img src="./docs/assets/proxitor-add.gif" alt="proxitor: add a model override" width="640"></p>
 
-### Setup wizard
-
-Run the wizard to create or update your config interactively. If no config exists, any command will offer to launch it automatically.
+## When something's off
 
 ```sh
-proxitor config wizard
+proxitor doctor   # checks environment, config, key, network, port, version
 ```
 
-The wizard asks for:
+It prints a clear report and exits non-zero if anything fails — handy from CI too (`--json`, `--offline`, `--timeout`).
 
-- **OpenRouter API key** — stored in config or set as `OPENROUTER_API_KEY` env var
-- **Port** — default `8828` (avoids conflicts with common dev servers on 8080)
-- **API base URL** — default `https://openrouter.ai/api`; change for self-hosted or custom endpoints
-- **Data URL** — separate URL for provider/model data fetching; falls back to OpenRouter automatically if the custom API doesn't support these endpoints
-- **Authentication type** — `bearer` (default) or `oauth`; use `oauth` for custom proxy providers that pass tokens in the `Authorization: OAuth ...` header
-- **Host** — all interfaces (`0.0.0.0`) or localhost only (`127.0.0.1`)
-- **Save location** — project directory, `~/.config/proxitor/`, or `$XDG_CONFIG_HOME/proxitor/`
+While proxitor runs, it logs cache usage from upstream so you can see whether caching is actually helping:
 
-If a config already exists, the wizard shows its location and asks whether to reconfigure. Existing `modelOverrides`, `provider`, and other fields are preserved — only the wizard fields are updated.
-
-```sh
-proxitor config menu           # interactive menu
-proxitor config add            # add a model override
-proxitor config edit           # edit existing override
-proxitor config remove         # remove override(s)
-proxitor config list           # show current overrides
-proxitor config browse         # explore models with pricing info
-proxitor config wizard         # interactive setup wizard
-proxitor config validate       # validate config file
 ```
-
-### Add override walkthrough
-
-```sh
-$ proxitor config add
-
-┌──────────────────────────────────┐
-│   Add Model Override             │
-╰──────────────────────────────────╯
-
-◇ Search for a model
-│ claude
-  (23 matches)
-  ● anthropic/claude-sonnet-4-6 · $3.00/$15.00 · 200k
-  ○ anthropic/claude-opus-4-8   · $15.00/$75.00 · 200k
-  ...
-
-◇ Configure provider routing
-│ ○ Use specific providers only
-  ○ Set provider priority order
-  ○ Ignore specific providers
-  ○ Skip provider routing
+[abc123] Cache read: 50000, write: 25000 tokens (99.6% hit)
 ```
 
-**"Use specific providers only" / "Ignore specific providers"** — multiselect, pick all that apply:
-
-```text
-◇ Select providers
-  ◼ anthropic (anthropic)     · 1.0s · 40 t/s
-  ◻ google-vertex/global      · 1.1s · 39 t/s
-  ◻ amazon-bedrock            · 1.2s · 40 t/s
-```
-
-**"Set provider priority order"** — pick providers one at a time, then select **✓ Done** at the bottom to finish:
-
-```text
-◇ Select provider #1 (or cancel to finish)
-│ ● anthropic (anthropic)     · 1.0s · 40 t/s
-  ○ google-vertex/global      · 1.1s · 39 t/s
-  ○ amazon-bedrock            · 1.2s · 40 t/s
-  ○ ✓ Done
-
-◇ Select provider #2 (or cancel to finish)
-│ ● google-vertex/global      · 1.1s · 39 t/s
-  ○ amazon-bedrock            · 1.2s · 40 t/s
-  ○ ✓ Done
-
-◇ Select provider #3 (or cancel to finish)
-│ ● ✓ Done
+Quick health poke: `curl http://localhost:8828/health`.
 
-◇ Allow fallbacks to other providers? Yes
+## Commands at a glance
 
-◇ Save to config? Yes
-
-╭──────────────────────────────────╮
-│ ✓ Model override saved           │
-╰──────────────────────────────────╯
+```sh
+proxitor                 # start the proxy (the default command)
+proxitor config          # interactive config menu
+proxitor config wizard   # guided setup
+proxitor config browse   # explore models + pricing
+proxitor doctor          # diagnose everything
+proxitor --help          # the rest of the flags
 ```
 
-The interface uses live data from the OpenRouter API — model search with type-ahead, real provider availability and pricing for each model.
-
----
-
-## CLI Options
-
-| Flag | Default | Description |
-|---|---|---|
-| `-p, --port <port>` | `8828` | Server port |
-| `-h, --host <host>` | `0.0.0.0` | Server host |
-| `-c, --config <path>` | auto-discovered | Path to config file |
-| `--openrouter-key <key>` | `$OPENROUTER_API_KEY` | OpenRouter API key |
-| `--verbose` | `false` | Enable verbose logging |
-| `--no-config` | | Skip config file discovery |
-| `-v, --version` | | Print version |
-| `--help` | | Print help |
+Common flags: `--port`, `--host`, `--config <path>`, `--openrouter-key <key>`. Run `proxitor --help` and `proxitor config --help` for the full list.
 
----
-
-## Development
-
-```sh
-pnpm install          # install dependencies
-pnpm dev              # build + watch
-pnpm test             # run tests
-pnpm test:e2e         # end-to-end tests
-pnpm typecheck        # TypeScript check
-pnpm check:biome      # lint + format check
-pnpm lint:fix         # auto-fix lint issues
-pnpm build            # production build
-pnpm check            # typecheck + biome + test (full CI)
-```
+## Contributing
 
----
+PRs welcome — see **[CONTRIBUTING.md](./CONTRIBUTING.md)** for setup, tests, commits, and changesets.
 
 ## License