babelgate 0.0.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+babelgate
+Copyright 2025-2026 Dorrabb Khan

package/README.md

@@ -1 +1,467 @@
-# babelgate — name reserved; first release coming soon. https://github.com/dorrabbkhan/llm-proxy
+# babelgate
+
+A small proxy that sits in front of LLM APIs and translates between their
+request/response formats — streaming and tool calls included. Point your
+OpenAI client at it, and it can talk to Gemini, Ollama, or Anthropic behind
+the scenes — and vice versa. Point Claude Code at it, and it runs on any
+tool-capable model you can reach.
+
+Supported providers right now:
+
+- OpenAI (and OpenAI-compatible backends like OpenRouter)
+- Google Gemini
+- Ollama
+- Anthropic (Claude)
+
+<!-- OWNER: add docs/assets/demo.gif (from the OpenRouter gate run) before merge.
+![babelgate demo — Claude Code editing through the proxy](docs/assets/demo.gif)
+-->
+
+## Quick start: Claude Code on a local model
+
+```bash
+ollama pull qwen3-coder:30b
+OLLAMA_API_BASE_URL=http://localhost:11434 \
+  npx babelgate --preset claude-code --target ollama --model qwen3-coder:30b
+```
+
+babelgate prints the two lines Claude Code needs:
+
+```
+export ANTHROPIC_BASE_URL=http://localhost:3000
+export ANTHROPIC_AUTH_TOKEN=babelgate
+```
+
+Export them in your shell, then:
+
+```bash
+claude
+```
+
+Claude Code talks Anthropic format to babelgate; babelgate streams it to
+Ollama — tools included. Two honest caveats on this exact path: the release
+gate passed on hosted OpenRouter models, not on local `qwen3-coder:30b`, and
+small local models call tools unreliably — see
+[Known limitations](#known-limitations).
+
+### Claude Code on OpenRouter (or any OpenAI-compatible backend)
+
+```bash
+OPENAI_API_KEY=<your OpenRouter key> \
+  npx babelgate --preset claude-code --target openai \
+  --model qwen/qwen3-coder --base-url https://openrouter.ai/api
+```
+
+The base URL is `https://openrouter.ai/api` — babelgate appends
+`/v1/chat/completions` itself. If your OpenRouter key has a spend limit,
+cap Claude Code's output budget or requests can be rejected:
+
+```bash
+export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8000
+```
+
+Then the same two `export` lines and `claude`. Full walkthrough:
+[docs/recipes/claude-code.md](docs/recipes/claude-code.md).
+
+### Any OpenAI-SDK app on any backend
+
+```bash
+OLLAMA_API_BASE_URL=http://localhost:11434 \
+  npx babelgate --preset openai-apps --target ollama
+```
+
+prints:
+
+```
+export OPENAI_BASE_URL=http://localhost:3000/v1
+export OPENAI_API_KEY=babelgate
+```
+
+The app sends whatever model name it likes — it's forwarded to the target
+unchanged (send a name the target knows, like `qwen3-coder:30b`, or rename
+with `MODEL_MAP`). Recipe: [docs/recipes/openai-sdk.md](docs/recipes/openai-sdk.md).
+
+### Recommended tool-capable models
+
+- **Verified through the release gate** (Claude Code completed a real edit
+  task through babelgate): `qwen/qwen3-coder` and `poolside/laguna-s-2.1:free`
+  on OpenRouter.
+- **Local (Ollama):** `qwen3-coder:30b` is the intended launch model — it
+  needs serious RAM or a GPU. Smaller `qwen2.5-coder` sizes run on CPU but
+  are slow and call tools less reliably.
+
+## The `babelgate` CLI
+
+`npx babelgate` parses flags with `node:util`, sets environment defaults
+that **your own env always overrides** (a stderr line,
+`babelgate: your environment overrides <keys>`, tells you which preset
+values lost), starts the server, and prints the client `export` lines to
+paste. Upstream API keys come only from the environment — never from flags.
+
+```
+Usage: babelgate [--preset <claude-code|openai-apps>] [--target <provider>]
+                 [--model <name>] [--base-url <url>] [--port <n>] [--help]
+
+Upstream API keys come only from the environment
+(OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OLLAMA_API_KEY).
+```
+
+| Flag          | Effect                                                                        |
+| ------------- | ----------------------------------------------------------------------------- |
+| `--preset`    | `claude-code` (source `anthropic`) or `openai-apps` (source `openai`)           |
+| `--target`    | `ollama`, `openai`, `anthropic` or `gemini` — sets `TARGET_API`                 |
+| `--model`     | `claude-code` preset only: `MODEL_MAP=claude-*=<model>`                         |
+| `--base-url`  | Sets `{TARGET}_API_BASE_URL` (e.g. `https://openrouter.ai/api` for OpenRouter)  |
+| `--port`      | Listen port (default `3000`)                                                    |
+| `--help`      | Usage                                                                         |
+
+The `claude-code` preset also sets `TARGET_CONTEXT_WINDOW=32768` and, for
+`--target ollama`, `UPSTREAM_TIMEOUT_MS=600000` — local models are slow.
+Without `--model` it warns `babelgate: no --model given; claude-* model
+names are forwarded to the target unchanged` on stderr.
+
+Presets are just env values. Everything below works without them.
+
+## How it works
+
+The naive way to build this is a transformer per provider pair. That gets
+painful fast — four providers means twelve conversion functions in each
+direction, and every new provider adds another batch.
+
+Instead, every request goes through a **canonical format** in the middle:
+
+```
+OpenAI request ──► canonical ──► Gemini request
+Gemini response ──► canonical ──► OpenAI response
+```
+
+Each provider has an _adapter_ that knows how to convert its own format to and
+from canonical. Adding a provider costs you one adapter file — the rest of the
+pipeline doesn't care.
+
+The actual request flow:
+
+1. Request hits the Express app.
+2. If the path matches the configured source provider's API prefix
+   (e.g. `/v1/chat/completions` for OpenAI), the proxy takes it.
+   Otherwise it falls through to a 404.
+3. The body is converted to canonical, then from canonical to the target
+   format.
+4. It's forwarded upstream to `{TARGET}_API_BASE_URL` + the target's
+   endpoint, with the right auth headers.
+5. The response comes back through the same path in reverse.
+
+Endpoint kinds:
+
+- **Chat** — the request/response translation described above (OpenAI
+  `/v1/chat/completions`, Gemini `/v1beta/models/{m}:generateContent`,
+  Ollama `/api/chat`, Anthropic `/v1/messages`).
+- **Streaming chat** — `stream: true` (and Gemini's
+  `:streamGenerateContent?alt=sse`) flows chunk-by-chunk in each side's own
+  wire protocol: SSE for OpenAI, Anthropic and Gemini, NDJSON for Ollama.
+  A client disconnect aborts the upstream request; an upstream that dies
+  mid-stream produces an in-stream error in the client's dialect, and a
+  stream that stalls longer than `UPSTREAM_STREAM_IDLE_MS` is cut rather
+  than left hanging.
+- **Tools** — tool definitions, `tool_choice`, parallel calls, streamed
+  tool-call deltas and tool results map through canonical. Calls with
+  arguments that aren't valid JSON reach the model wrapped as
+  `{ "_invalid_arguments": "<raw>" }` instead of crashing the turn.
+- **Model list** — GET endpoints (`/v1/models`, `/v1beta/models`,
+  `/api/tags`) transform the upstream catalog into the source format,
+  so client SDKs and dropdowns work unchanged.
+- **`count_tokens`** (Anthropic source only) — answered locally as a
+  chars/4 estimate, marked by the `x-babelgate-token-estimate: true`
+  response header. Claude Code calls it constantly; the estimate keeps
+  it happy without a fake upstream.
+
+Every completed chat request logs token usage (`inputTokens`,
+`outputTokens`, `finishReason`, upstream latency) via pino — grep for
+`"Request completed"`. Model-list requests log `modelCount` instead
+(`"Models list completed"`).
+
+## Configuration
+
+Everything is environment variables. One instance serves one source→target
+pair; run multiple instances for more.
+
+| Variable                  | What it's for                                                                                |
+| ------------------------- | -------------------------------------------------------------------------------------------- |
+| `SOURCE_API`              | Format clients send to you — `openai`, `gemini`, `ollama`, or `anthropic`                    |
+| `TARGET_API`              | Format to translate to upstream — same options                                               |
+| `PORT`                    | Listen port (default `3000`)                                                                 |
+| `{PROVIDER}_API_BASE_URL` | Upstream base URL for the target provider, e.g. `OLLAMA_API_BASE_URL=http://localhost:11434` |
+| `{PROVIDER}_API_KEY`      | API key for the target provider (Ollama doesn't need one)                                    |
+| `UPSTREAM_TIMEOUT_MS`     | Per-request upstream timeout (default `30000`)                                               |
+| `UPSTREAM_RETRIES`        | Retries for transport failures / 429 / 503 (default `1`)                                     |
+| `UPSTREAM_STREAM_IDLE_MS` | Longest gap allowed between chunks mid-stream (default `300000`)                             |
+| `MAX_BODY_SIZE`           | JSON body limit (default `10mb` — base64 images need it)                                     |
+| `PROXY_API_KEY`           | Optional client auth — when set, callers send the key in their provider's native auth header (see Authentication) |
+| `MODEL_MAP`               | Ordered `glob=model` rules, comma-separated — e.g. `claude-*haiku*=qwen2.5-coder:7b,claude-*=qwen3-coder:30b`. First match wins; replies still carry the name the client asked for |
+| `TARGET_CONTEXT_WINDOW`   | Minimum context window the target should allocate (Ollama `options.num_ctx`)                  |
+
+Routing and upstream endpoints are conventions, not configuration: each
+provider's routes (`kind`, `method`, `pathPrefix`, `requestPath`) live in
+`PROVIDER_ROUTES` in `src/transformers/adapters/index.ts`.
+
+## Authentication
+
+Set `PROXY_API_KEY` and every proxied endpoint requires it, in whichever
+native auth style the client SDK already sends — any one match
+authenticates, and every comparison is timing-safe:
+
+- `Authorization: Bearer <key>` — OpenAI and Ollama SDKs, Anthropic's
+  `ANTHROPIC_AUTH_TOKEN` (the `Bearer` scheme is case-insensitive)
+- `x-api-key: <key>` — Anthropic SDK
+- `x-goog-api-key: <key>` — Gemini SDK
+- `?key=<key>` query parameter — Gemini's other auth style
+
+A wrong or missing key gets a `401` in the source provider's error format.
+The client key is never forwarded upstream — the upstream sees only the
+proxy's own `{TARGET}_API_KEY`. Leave `PROXY_API_KEY` unset to disable
+client auth (local dev — the CLI's printed `export …_TOKEN=babelgate`
+lines are placeholders in that mode), and note `/health` stays open either
+way.
+
+## Errors
+
+Errors on provider routes are rendered in the **source** provider's error
+format, so client SDKs raise their native exceptions:
+
+| Source | Error body |
+|---|---|
+| OpenAI | `{"error":{"message","type","param","code"}}` |
+| Anthropic | `{"type":"error","error":{"type","message"}}` |
+| Gemini | `{"error":{"code","message","status"}}` |
+| Ollama | `{"error":"<message>"}` |
+
+The same holds inside a stream: an upstream that fails mid-stream produces
+the source dialect's in-stream error event, never silence or half a JSON
+object.
+
+When the upstream provider itself fails, the status the client sees is:
+
+| Upstream | Client | Notes |
+|---|---|---|
+| 400, 422 | 400 | The upstream message passes through |
+| 404 | 404 | Almost always "model not found" — the client can fix it |
+| 413 | 413 | Request too large |
+| 429 | 429 | `Retry-After` passed through when present |
+| 401, 403 | 502 | `Upstream <provider> rejected the proxy's credentials (<status>)` — the *proxy's* upstream key failed, not the client's. Gemini's `400 API_KEY_INVALID` maps here too |
+| 503, 529 | 503 | Unavailable |
+| Other 5xx | 502 | Upstream failure |
+| Timeout | 504 | After `UPSTREAM_TIMEOUT_MS` |
+| Transport failure | 502 | Upstream unreachable |
+| Non-JSON 2xx body | 502 | `Upstream returned a non-JSON response (content-type: <type>)` |
+
+Error privacy in detail: proxy-generated messages contain no prompt text
+or API keys, and client credentials are redacted from request logs. An
+upstream 401/403 — including Gemini's `400 API_KEY_INVALID` — reaches
+neither the client nor the logs; every other upstream error message is
+passed through to the client and logged truncated to 200 characters.
+Outside production, an error's `details` may include the first 200
+characters of a non-JSON upstream body. Unknown paths and `/health` keep
+a small generic error shape rather than any provider's.
+
+## Running from source
+
+```bash
+npm ci
+cp .env.example .env
+```
+
+For a local Ollama target, `.env` needs three lines:
+
+```bash
+SOURCE_API=openai
+TARGET_API=ollama
+OLLAMA_API_BASE_URL=http://localhost:11434
+```
+
+Pull a small model and start the proxy:
+
+```bash
+ollama pull qwen2.5:0.5b
+npm run dev
+```
+
+Then send an OpenAI-style request at the proxy:
+
+```bash
+curl http://localhost:3000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model": "qwen2.5:0.5b", "messages": [{"role": "user", "content": "Hello"}]}'
+```
+
+That gets translated to an Ollama `/api/chat` call upstream (the proxy
+sends `stream: false` when you don't ask for a stream), and the response
+comes back in OpenAI `chat.completion` shape. Add `"stream": true` and the
+same call comes back as SSE.
+
+## Project structure
+
+```
+src/
+├── cli.ts                  npx babelgate — flags, presets, printed export lines
+├── app.ts                  Express app wiring (middleware → routes → errors)
+├── index.ts                Server startup
+├── config/env-config.ts    Env var config (lazy, validated)
+├── middleware/             pino request logging, error handler
+├── routes/proxy.ts         Thin HTTP adapter — writes streams, aborts on close
+├── services/
+│   ├── http-client.ts      Upstream transport: timeout, retry, logging, postStream
+│   ├── stream-pipeline.ts  Provider-agnostic stream plumbing (abort, idle timeout)
+│   ├── token-estimate.ts   chars/4 estimate behind count_tokens
+│   └── proxy.service.ts    Orchestration: validate → transform → forward
+├── transformers/
+│   ├── index.ts            transformRequest/transformResponse entry points
+│   └── adapters/           One file per provider (+ .stream.ts codecs) + PROVIDER_ROUTES
+├── types/
+│   ├── canonical.types.ts  The canonical format + CanonicalStreamEvent
+│   ├── canonical.schema.ts Zod schemas for runtime validation
+│   └── *.types.ts          Provider types (mostly SDK re-exports)
+└── utils/                  logger (pino), error classes, SSE/NDJSON parsers,
+                            ID generators, stream reassembly, MODEL_MAP
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+All fast, no network. Layers:
+
+- **Adapter unit tests** (`src/transformers/adapters/*.test.ts`) — each
+  adapter's to/from canonical functions.
+- **Contract tests** (`tests/contracts/`) — the interesting part. Every
+  adapter's canonical output is validated against Zod schemas, fixture-driven
+  golden tests cover realistic payloads, stream decoders are run against a
+  corpus of recorded wire bytes (and re-fed byte-by-byte at every split
+  point) and parsed back with the providers' own SDKs, and property tests
+  hammer the event-ordering rules.
+- **HTTP integration tests** (`tests/integration/`) — real requests against
+  the Express app via supertest, with upstream providers mocked by msw. No
+  actual network calls happen. `pairs.test.ts` generates end-to-end tests
+  per provider pair — chat and model list, so all 16 combinations get
+  exercised — `stream-pairs.test.ts` runs the streaming × tools matrix
+  over the launch pairs, and `errors.test.ts` runs every pair through the
+  upstream-error mapping table.
+
+The contract tests are what make the adapter approach hold up: you don't need
+N×N tests if every adapter produces schema-valid canonical data, because then
+any pair composes by construction.
+
+## Live tests
+
+`npm test` never touches the network, so it can't catch upstream-format
+drift. The opt-in live suite runs the real app against real upstreams:
+
+```bash
+npm run test:live
+```
+
+- **Ollama always runs**: `OLLAMA_API_BASE_URL` (default
+  `http://localhost:11434`) must be reachable or the suite fails loudly —
+  it never silently passes. Model from `LIVE_OLLAMA_MODEL` (default
+  `qwen2.5:0.5b`).
+- **Paid providers are opt-in**: OpenAI, Anthropic and Gemini cases run
+  only when `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` or `GEMINI_API_KEY` are
+  set, with cheap defaults `gpt-4o-mini`, `claude-haiku-5-5` and
+  `gemini-3.8-flash` respectively — `LIVE_<PROVIDER>_MODEL` overrides.
+  **OpenRouter** runs as an extra OpenAI-style target when
+  `OPENROUTER_API_KEY` is set (model `LIVE_OPENROUTER_MODEL`, default
+  `qwen/qwen3-coder`). Skipped targets are listed in the output.
+- Cases per available target, driven through every source format: a chat
+  round trip, the model list, an unknown model → 404 (400 on OpenRouter —
+  it answers bad model IDs differently), and a streamed chat asserted on
+  chunks, terminal event and usage — all on response *shape*, never on
+  generated text.
+
+A nightly GitHub Actions job (`.github/workflows/live.yml`) runs the
+suite against a fresh Ollama; paid-provider secrets are off until the
+owner adds them.
+
+**The release gate** — `scripts/gates/claude-code-edit.sh <ollama|openrouter>
+[model]` — is the end-to-end proof: it copies a fixture repo with a failing
+test, starts `babelgate --preset claude-code`, lets Claude Code fix the bug
+through the proxy (file edits and `npm test` only), then runs the test
+itself. Prints `GATE PASS`/`GATE FAIL`, the `claude --version`, model and
+duration. It makes real network calls.
+
+## Adding a provider
+
+Adding a provider means one adapter plus registration, env typing and
+fixtures/tests — see
+[CONTRIBUTING.md](CONTRIBUTING.md#adding-a-provider).
+
+## Known limitations
+
+- **Claude Code ↔ Ollama has not been gate-tested on a capable model.**
+  The release gate passed on OpenRouter (`qwen/qwen3-coder`,
+  `poolside/laguna-s-2.1:free`), proving Claude Code end to end through
+  babelgate; the Ollama adapter is live-tested nightly, but the combined
+  path on `qwen3-coder:30b` was never run (accepted launch risk — small
+  machines can't fit the model). Local models may call tools unreliably,
+  and on CPU-only machines a slow model can stall past
+  `UPSTREAM_STREAM_IDLE_MS` (default 300 s) and have its stream cut.
+- **Reasoning/thinking is not mapped.** `thinking` and
+  `redacted_thinking` blocks, thinking deltas, the `thinking` request
+  parameter and Ollama's `thinking` field are dropped (debug-logged by
+  type name only). `cache_control` and `metadata` are dropped too.
+  Reasoning mapping is planned for v1.4.
+- **`parallel_tool_calls` is ignored** — providers get their own default
+  parallel behaviour.
+- **Not every pair is equally verified.** Streaming and tools are
+  implemented in all four adapters, but the streaming × tools matrix only
+  gates the launch pairs: `anthropic → ollama`, `anthropic → openai`
+  (which is how OpenRouter is reached) and `openai → ollama`. The full
+  16-pair matrix is milestone 2 (v1.1.x). Gemini and Ollama **sources**
+  and the Gemini **target** have not had a clean live run yet.
+- **`count_tokens` is an estimate** (chars/4), marked by the
+  `x-babelgate-token-estimate: true` header — enough for Claude Code's
+  budgeting, not for billing.
+- **Ollama clients get a single JSON reply** when they omit `stream` —
+  unlike Ollama's own API, which streams NDJSON by default. Send
+  `"stream": false` explicitly to make that intent clear.
+- **Non-chat Gemini methods return 501** — `:countTokens`, `:embedContent`
+  and friends aren't translated.
+- Some provider-specific features (citations, extra usage fields) map to
+  canonical best-effort — the format only keeps what's expressible
+  across providers.
+- One source→target pair per instance. That's a deliberate simplification,
+  not an oversight.
+
+## Roadmap
+
+The version-by-version plan — the 16-pair matrix in v1.1.x, one endpoint
+for many providers in v1.2, and beyond — lives in
+[docs/roadmap.md](docs/roadmap.md).
+
+## Docker
+
+```bash
+docker build -t babelgate .
+docker run -p 3000:3000 --env-file .env babelgate
+```
+
+Release tags also publish `ghcr.io/dorrabbkhan/babelgate:<version>` and
+`:latest` via `.github/workflows/release.yml`.
+
+Multi-stage build: provider SDKs are `devDependencies` (type-only imports),
+so the runtime image ships `dist/` plus the top-level runtime
+dependencies from `package.json` — `dotenv`, `express`, `pino`,
+`pino-http` and `zod`.
+
+## Stack
+
+Express 5, TypeScript, pino (logging), zod (schema validation), vitest +
+msw + supertest (tests). Provider types come from the official SDKs wherever
+possible.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). Contributions
+are welcome: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup and checks,
+and first-time contributors sign the [CLA](CLA.md) once via the CLA
+Assistant bot on their first PR.