babelgate 1.1.2 → 1.2.0

package/README.md

@@ -13,9 +13,8 @@ Supported providers right now:
 - 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)
--->
+![Claude Code fixing a failing test through babelgate on a free OpenRouter model](docs/assets/demo.gif)
+*Recorded with [scripts/demo](scripts/demo/); the model's thinking time is cut.*
 
 ## Quick start: Claude Code on a local model
 
@@ -90,6 +89,89 @@ with `MODEL_MAP`). Recipe: [docs/recipes/openai-sdk.md](docs/recipes/openai-sdk.
   needs serious RAM or a GPU. Smaller `qwen2.5-coder` sizes run on CPU but
   are slow and call tools less reliably.
 
+## One endpoint, many providers
+
+Everything above is one target behind one port. With a `babelgate.yaml`
+the same port serves **every client format at once** — OpenAI, Anthropic,
+Gemini and Ollama SDKs all work against it — and routes each request to
+one of several providers by model name, with aliases, a long-context
+condition, and fallbacks before the first byte:
+
+The npm package doesn't ship `examples/` — fetch the file first (saving
+it as `babelgate.yaml` also works, since `./babelgate.yaml` is
+auto-discovered):
+
+```bash
+curl -fsSLo claude-code-hybrid.yaml \
+  https://raw.githubusercontent.com/dorrabbkhan/babelgate/main/examples/claude-code-hybrid.yaml
+OPENROUTER_API_KEY=<your key> \
+  npx babelgate --config claude-code-hybrid.yaml --preset claude-code
+```
+
+[examples/claude-code-hybrid.yaml](examples/claude-code-hybrid.yaml)
+keeps Claude Code's cheap background calls on a small local model, runs
+routine turns on local `qwen3-coder:30b`, sends ≥ 60 000-token contexts
+to OpenRouter, and falls back to OpenRouter when Ollama is down:
+
+```yaml
+routes:
+  - match: claude-*haiku*
+    to: ollama/qwen2.5-coder:7b
+  - match: claude-*
+    when:
+      min_input_tokens: 60000
+    to: openrouter/qwen/qwen3-coder
+  - match: claude-*
+    to: ollama/qwen3-coder:30b
+    fallback:
+      - openrouter/qwen/qwen3-coder
+```
+
+Model resolution, in order: an explicit `<provider>/<model>` in the
+request, then aliases, then routes in file order, then the `default`
+provider with the model unchanged. Replies always keep the name the
+client asked for. Walkthrough:
+[docs/recipes/claude-code-hybrid.md](docs/recipes/claude-code-hybrid.md);
+a second example with three providers and aliases lives at
+[examples/multi-provider.yaml](examples/multi-provider.yaml) — fetch it
+the same way.
+
+Started without `--preset`, babelgate prints a client-facing endpoint
+per dialect — each is the **base URL the SDK expects**, which differs
+from the raw request paths:
+
+```
+OpenAI     http://localhost:3000/v1
+Anthropic  http://localhost:3000
+Gemini     http://localhost:3000
+Ollama     http://localhost:3000
+```
+
+```python
+# OpenAI SDK (Python) — base_url includes /v1
+OpenAI(base_url="http://localhost:3000/v1", api_key="babelgate")
+
+# google-genai (Python) — http_options.base_url excludes it; the SDK
+# appends /v1beta itself (a /v1beta base URL double-appends and 404s)
+genai.Client(api_key="babelgate",
+             http_options={"base_url": "http://localhost:3000"})
+```
+
+```ts
+// @google/genai (JS) — same, via httpOptions.baseUrl
+new GoogleGenAI({ apiKey: "babelgate",
+                  httpOptions: { baseUrl: "http://localhost:3000" } })
+```
+
+Raw-HTTP callers use the real paths instead: `/v1/chat/completions`,
+`/v1/messages`, `/v1beta/models/<model>:generateContent`, `/api/chat`.
+Every proxied reply carries `x-babelgate-provider`, `x-babelgate-model`
+and `x-babelgate-attempts`, and `GET …/models` returns one merged list
+across all providers. Any OpenAI-compatible backend (Groq, DeepSeek,
+Together, LM Studio, vLLM, llama.cpp…) is a `type: openai` provider —
+base URLs and key handling are in
+[docs/recipes/openai-compatible-providers.md](docs/recipes/openai-compatible-providers.md).
+
 ## The `babelgate` CLI
 
 `npx babelgate` parses flags with `node:util`, sets environment defaults
@@ -100,18 +182,21 @@ 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]
+                 [--model <name>] [--base-url <url>] [--port <n>]
+                 [--config <path>] [--help]
 
-Upstream API keys come only from the environment
+Config file discovery: --config, then BABELGATE_CONFIG,
+then ./babelgate.yaml. 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`                 |
+| `--preset`    | `claude-code` or `openai-apps` — picks which `export` lines to print; with no config file it also sets the v1.1 env routing |
+| `--target`    | `ollama`, `openai`, `anthropic` or `gemini` — sets `TARGET_API` (env-only mode) |
 | `--model`     | `claude-code` preset only: `MODEL_MAP=claude-*=<model>`                         |
 | `--base-url`  | Sets `{TARGET}_API_BASE_URL` (e.g. `https://openrouter.ai/api` for OpenRouter)  |
+| `--config`    | Path to a `babelgate.yaml` — `--target`, `--model` and `--base-url` are then defined by the file |
 | `--port`      | Listen port (default `3000`)                                                    |
 | `--help`      | Usage                                                                         |
 
@@ -142,12 +227,14 @@ 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
+2. The request path decides the client's format (`/v1/chat/completions`
+   is OpenAI, `/v1/messages` Anthropic, `/v1beta/models` Gemini,
+   `/api/chat` Ollama); the route table picks it up. Unknown paths fall
+   through to a 404.
+3. The body is converted to canonical, routed to a provider (config
+   file, or the single `TARGET_API` in env-only mode), then encoded in
+   the target's format.
+4. It's forwarded upstream to the provider's `base_url` + the target's
    endpoint, with the right auth headers.
 5. The response comes back through the same path in reverse.
 
@@ -182,23 +269,27 @@ Every completed chat request logs token usage (`inputTokens`,
 
 ## Configuration
 
-Everything is environment variables. One instance serves one source→target
-pair; run multiple instances for more.
+Two modes. A **`babelgate.yaml`** (found via `--config`, `BABELGATE_CONFIG`
+or `./babelgate.yaml`) defines ≥ 1 providers, aliases and ordered routes —
+see the section above and [examples/](examples/). With no file,
+**env-only mode** is exactly the v1.1 setup: one provider named after
+`TARGET_API`, `MODEL_MAP` entries become its routes.
 
 | 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                                               |
+| `BABELGATE_CONFIG`        | Path to a `babelgate.yaml` (same as `--config`)                                               |
+| `SOURCE_API`              | **Deprecated** — ignored in 1.2 (the request path decides the client format); removed in 2.0  |
+| `TARGET_API`              | Format to translate to upstream — same options (env-only mode; ignored when a YAML file is loaded) |
 | `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)                                    |
+| `{PROVIDER}_API_BASE_URL` | Upstream base URL for the target provider, e.g. `OLLAMA_API_BASE_URL=http://localhost:11434` (env-only; YAML providers use `base_url`) |
+| `{PROVIDER}_API_KEY`      | API key for the target provider (Ollama doesn't need one). With YAML, keys are whichever env vars `api_key_env` names |
 | `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`)                  |
+| `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 (env-only; YAML has `routes`) |
+| `TARGET_CONTEXT_WINDOW`   | Minimum context window the target should allocate (Ollama `options.num_ctx`; env-only — YAML has per-provider `context_window`) |
 
 Routing and upstream endpoints are conventions, not configuration: each
 provider's routes (`kind`, `method`, `pathPrefix`, `requestPath`) live in
@@ -270,10 +361,9 @@ npm ci
 cp .env.example .env
 ```
 
-For a local Ollama target, `.env` needs three lines:
+For a local Ollama target, `.env` needs two lines:
 
 ```bash
-SOURCE_API=openai
 TARGET_API=ollama
 OLLAMA_API_BASE_URL=http://localhost:11434
 ```
@@ -426,8 +516,9 @@ fixtures/tests — see
 - 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.
+- **No config hot reload and no overall request deadline** — a
+  `babelgate.yaml` change needs a restart, and worst-case latency is the
+  sum of per-attempt timeouts across a fallback chain.
 
 ## Roadmap
 

package/dist/app.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.app = void 0;
 const express_1 = __importDefault(require("express"));
 const request_logger_1 = require("./middleware/request-logger");
-const resolve_source_1 = require("./middleware/resolve-source");
+const detect_source_1 = require("./middleware/detect-source");
 const error_handler_1 = require("./middleware/error-handler");
 const require_api_key_1 = require("./middleware/require-api-key");
 const proxy_1 = require("./routes/proxy");
@@ -14,10 +14,10 @@ const app = (0, express_1.default)();
 exports.app = app;
 // 1. Request logger - logs every incoming request
 app.use(request_logger_1.requestLogger);
-// 1a. Source resolver - records res.locals.sourceApi on provider paths so
-// the error handler renders errors (auth, body-parser, upstream) in the
-// client's own dialect.
-app.use((0, resolve_source_1.resolveSource)());
+// 1a. Source detection - records the request's own format on
+// res.locals.sourceApi so the error handler renders errors (auth,
+// body-parser, upstream) in the client's dialect (spec §3.2).
+app.use((0, detect_source_1.detectSourceMiddleware)());
 // 2. Body parser - parses application/json. LLM payloads (base64
 // images, long context) routinely exceed the 100kb default.
 app.use(express_1.default.json({ limit: process.env.MAX_BODY_SIZE || "10mb" }));

package/dist/cli.js

@@ -5,9 +5,12 @@ exports.parseCliArgs = parseCliArgs;
 exports.presetEnv = presetEnv;
 exports.overriddenKeys = overriddenKeys;
 exports.clientInstructions = clientInstructions;
+exports.endpointLines = endpointLines;
 exports.main = main;
 const node_util_1 = require("node:util");
 const env_config_1 = require("./config/env-config");
+const yaml_config_1 = require("./config/yaml-config");
+const table_1 = require("./routing/table");
 const index_1 = require("./index");
 const PRESETS = ["claude-code", "openai-apps"];
 const PROVIDERS = ["openai", "gemini", "ollama", "anthropic"];
@@ -24,6 +27,7 @@ function parseCliArgs(argv) {
             target: { type: "string" },
             model: { type: "string" },
             "base-url": { type: "string" },
+            config: { type: "string" },
             port: { type: "string" },
             help: { type: "boolean" },
         },
@@ -45,6 +49,14 @@ function parseCliArgs(argv) {
         args.model = values.model;
     if (values["base-url"] !== undefined)
         args.baseUrl = values["base-url"];
+    if (values.config !== undefined)
+        args.config = values.config;
+    if (args.config !== undefined &&
+        (args.target !== undefined ||
+            args.model !== undefined ||
+            args.baseUrl !== undefined)) {
+        throw new Error("--target, --model and --base-url are defined by the config file");
+    }
     if (values.port !== undefined) {
         const port = Number(values.port);
         if (!Number.isInteger(port) || port <= 0 || port > 65535) {
@@ -73,32 +85,31 @@ function effectiveTarget(args, env) {
  * applied. `env` is still consulted to resolve the effective target for
  * --base-url and the ollama timeout.
  */
-function wantedEnv(args, env) {
+function wantedEnv(args, env, configMode = false) {
     const wanted = {};
-    if (args.preset === "claude-code") {
-        wanted.SOURCE_API = "anthropic";
-    }
-    else if (args.preset === "openai-apps") {
-        wanted.SOURCE_API = "openai";
-    }
-    if (args.target !== undefined) {
-        wanted.TARGET_API = args.target;
-    }
-    if (args.preset === "claude-code") {
-        if (args.model !== undefined) {
-            wanted.MODEL_MAP = `claude-*=${args.model}`;
+    // With a config file loaded, routing is defined by the file (spec §3.7):
+    // no flag or preset may set TARGET_API, MODEL_MAP, *_API_BASE_URL or
+    // TARGET_CONTEXT_WINDOW — only PORT still applies (§3.5).
+    if (!configMode) {
+        if (args.target !== undefined) {
+            wanted.TARGET_API = args.target;
         }
-        wanted.TARGET_CONTEXT_WINDOW = "32768";
-        if (effectiveTarget(args, env) === "ollama") {
-            wanted.UPSTREAM_TIMEOUT_MS = "600000";
+        if (args.preset === "claude-code") {
+            if (args.model !== undefined) {
+                wanted.MODEL_MAP = `claude-*=${args.model}`;
+            }
+            wanted.TARGET_CONTEXT_WINDOW = "32768";
+            if (effectiveTarget(args, env) === "ollama") {
+                wanted.UPSTREAM_TIMEOUT_MS = "600000";
+            }
         }
-    }
-    if (args.baseUrl !== undefined) {
-        const target = effectiveTarget(args, env);
-        if (target === undefined) {
-            throw new Error("--base-url requires --target or TARGET_API in the environment");
+        if (args.baseUrl !== undefined) {
+            const target = effectiveTarget(args, env);
+            if (target === undefined) {
+                throw new Error("--base-url requires --target or TARGET_API in the environment");
+            }
+            wanted[`${target.toUpperCase()}_API_BASE_URL`] = args.baseUrl;
         }
-        wanted[`${target.toUpperCase()}_API_BASE_URL`] = args.baseUrl;
     }
     if (args.port !== undefined) {
         wanted.PORT = String(args.port);
@@ -109,18 +120,20 @@ function wantedEnv(args, env) {
  * Environment values implied by the flags. Keys the user's own env already
  * sets (a non-empty value) are not returned — user env always wins and
  * presets are only ever env values, never changes to config defaults.
+ * `configMode` (a config file was resolved) suppresses every routing env
+ * var; only `--port` still maps to PORT.
  */
-function presetEnv(args, env) {
-    return Object.fromEntries(Object.entries(wantedEnv(args, env)).filter(([key]) => !env[key]));
+function presetEnv(args, env, configMode = false) {
+    return Object.fromEntries(Object.entries(wantedEnv(args, env, configMode)).filter(([key]) => !env[key]));
 }
 /**
  * Names of the preset/flag env keys that lost to values already set in
  * `env` — everything the flags/preset wanted that presetEnv(args, env)
  * dropped. Names only, never values.
  */
-function overriddenKeys(args, env) {
-    const applied = presetEnv(args, env);
-    return Object.keys(wantedEnv(args, env)).filter((key) => !(key in applied));
+function overriddenKeys(args, env, configMode = false) {
+    const applied = presetEnv(args, env, configMode);
+    return Object.keys(wantedEnv(args, env, configMode)).filter((key) => !(key in applied));
 }
 /**
  * The `export …` lines the user pastes into their shell to point the client
@@ -143,23 +156,29 @@ function clientInstructions(args, port, proxyApiKey) {
     }
     return [];
 }
+/**
+ * The endpoints block printed at startup when no preset is given
+ * (spec §3.7): one URL per client dialect, column-aligned.
+ */
+function endpointLines(port) {
+    return [
+        `OpenAI     http://localhost:${port}/v1`,
+        `Anthropic  http://localhost:${port}`,
+        `Gemini     http://localhost:${port}`,
+        `Ollama     http://localhost:${port}`,
+    ];
+}
 function usageLines() {
     return [
         "Usage: babelgate [--preset <claude-code|openai-apps>] [--target <provider>]",
-        "                 [--model <name>] [--base-url <url>] [--port <n>] [--help]",
+        "                 [--model <name>] [--base-url <url>] [--port <n>]",
+        "                 [--config <path>] [--help]",
         "",
-        "Upstream API keys come only from the environment",
+        "Config file discovery: --config, then BABELGATE_CONFIG,",
+        "then ./babelgate.yaml. Upstream API keys come only from the environment",
         "(OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OLLAMA_API_KEY).",
     ];
 }
-/** The preset whose export lines match a resolved source API. */
-function presetForSource(sourceApi) {
-    if (sourceApi === "anthropic")
-        return "claude-code";
-    if (sourceApi === "openai")
-        return "openai-apps";
-    return undefined;
-}
 async function main(argv) {
     try {
         const args = parseCliArgs(argv);
@@ -168,8 +187,20 @@ async function main(argv) {
                 console.log(line);
             return;
         }
-        const envValues = presetEnv(args, process.env);
-        const overridden = overriddenKeys(args, process.env);
+        // A config file resolves via --config, BABELGATE_CONFIG or
+        // ./babelgate.yaml (spec §3.5); with one loaded, the routing flags
+        // are errors (spec §3.7) — the parseCliArgs check only covers an
+        // explicit --config.
+        const configPath = (0, yaml_config_1.resolveConfigPath)(args.config, process.env, process.cwd());
+        const configMode = configPath !== undefined;
+        if (configMode &&
+            (args.target !== undefined ||
+                args.model !== undefined ||
+                args.baseUrl !== undefined)) {
+            throw new Error("--target, --model and --base-url are defined by the config file");
+        }
+        const envValues = presetEnv(args, process.env, configMode);
+        const overridden = overriddenKeys(args, process.env, configMode);
         for (const [key, value] of Object.entries(envValues)) {
             process.env[key] = value;
         }
@@ -177,21 +208,31 @@ async function main(argv) {
             console.error(`babelgate: your environment overrides ${overridden.join(", ")} ` +
                 "(flags and presets never replace values you set)");
         }
-        if (args.preset === "claude-code" &&
+        if (!configMode &&
+            args.preset === "claude-code" &&
             args.model === undefined &&
             !process.env.MODEL_MAP) {
             console.error("babelgate: no --model given; claude-* model names are forwarded " +
                 "to the target unchanged");
         }
+        (0, env_config_1.setConfigPath)(args.config);
         await (0, index_1.startServer)();
         const config = (0, env_config_1.getConfig)();
         if (args.preset !== undefined) {
-            // The export lines must match the server that actually started: the
-            // user's env may have overridden the preset's SOURCE_API.
-            for (const line of clientInstructions({ ...args, preset: presetForSource(config.sourceApi) }, config.port, config.proxyApiKey)) {
+            // The export lines come from the requested preset — there is no
+            // configured source format; the request path decides the dialect.
+            for (const line of clientInstructions(args, config.port, config.proxyApiKey)) {
                 console.log(line);
             }
         }
+        else {
+            for (const line of endpointLines(config.port)) {
+                console.log(line);
+            }
+        }
+        for (const line of (0, table_1.formatRoutingTable)(config)) {
+            console.log(line);
+        }
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));

package/dist/config/env-config.js

@@ -4,11 +4,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = loadConfig;
+exports.setConfigPath = setConfigPath;
 exports.getConfig = getConfig;
 exports.resetConfig = resetConfig;
 const dotenv_1 = __importDefault(require("dotenv"));
 const model_map_1 = require("../utils/model-map");
+const registry_1 = require("../routing/registry");
+const yaml_config_1 = require("./yaml-config");
 const errors_1 = require("../utils/errors");
+const logger_1 = require("../utils/logger");
 dotenv_1.default.config({ quiet: true });
 const VALID_PROVIDERS = ["openai", "gemini", "ollama", "anthropic"];
 function isValidProvider(value) {
@@ -21,14 +25,10 @@ function normalizeProvider(value) {
  * Loads configuration from environment variables
  */
 function loadConfig() {
-    if (!process.env.SOURCE_API || !process.env.TARGET_API) {
-        throw new Error("SOURCE_API and TARGET_API environment variables are required");
+    if (!process.env.TARGET_API) {
+        throw new Error("TARGET_API environment variable is required");
     }
-    const sourceApi = process.env.SOURCE_API;
     const targetApi = process.env.TARGET_API;
-    if (!isValidProvider(sourceApi)) {
-        throw new Error(`SOURCE_API must be one of: ${VALID_PROVIDERS.join(", ")}`);
-    }
     if (!isValidProvider(targetApi)) {
         throw new Error(`TARGET_API must be one of: ${VALID_PROVIDERS.join(", ")}`);
     }
@@ -51,8 +51,32 @@ function loadConfig() {
     if (!targetBaseUrl) {
         throw new Error(`${baseUrlEnvVar} environment variable is required for target API ${targetApi}`);
     }
+    const modelMap = (0, model_map_1.parseModelMap)(process.env.MODEL_MAP);
+    const targetContextWindow = parseTargetContextWindow();
+    // Env-only mode (spec §3.5): one provider named after TARGET_API,
+    // itself the default; MODEL_MAP entries become ordered routes to it.
+    const registry = (0, registry_1.createRegistry)([
+        {
+            name: normalizedTarget,
+            type: normalizedTarget,
+            baseUrl: targetBaseUrl.replace(/\/$/, ""),
+            apiKey: targetApiKey,
+            apiKeyEnv: targetApiKey !== undefined
+                ? apiKeyEnvVars[normalizedTarget]
+                : undefined,
+            contextWindow: targetContextWindow,
+        },
+    ]);
+    const routing = {
+        defaultProvider: normalizedTarget,
+        aliases: {},
+        rules: modelMap.map((rule) => ({
+            match: rule.pattern,
+            to: { provider: normalizedTarget, model: rule.model },
+            fallback: [],
+        })),
+    };
     return {
-        sourceApi: normalizeProvider(sourceApi),
         targetApi: normalizedTarget,
         port: process.env.PORT ? parseInt(process.env.PORT, 10) : 3000,
         targetApiKey,
@@ -67,8 +91,11 @@ function loadConfig() {
             ? parseInt(process.env.UPSTREAM_STREAM_IDLE_MS, 10)
             : 300_000,
         proxyApiKey: process.env.PROXY_API_KEY || undefined,
-        modelMap: (0, model_map_1.parseModelMap)(process.env.MODEL_MAP),
-        targetContextWindow: parseTargetContextWindow(),
+        modelMap,
+        targetContextWindow,
+        registry,
+        routing,
+        deprecatedEnv: process.env.SOURCE_API !== undefined ? ["SOURCE_API"] : [],
     };
 }
 function parseTargetContextWindow() {
@@ -85,9 +112,32 @@ function parseTargetContextWindow() {
  * Get the current configuration (lazy-loaded)
  */
 let _config = null;
+let _configPath;
+/**
+ * Explicit config-file path for getConfig()'s discovery — set by the
+ * CLI's --config before getConfig() runs (spec §3.5). Cleared by
+ * resetConfig().
+ */
+function setConfigPath(path) {
+    _configPath = path;
+}
 function getConfig() {
     if (!_config) {
-        _config = loadConfig();
+        const yamlPath = (0, yaml_config_1.resolveConfigPath)(_configPath, process.env, process.cwd());
+        if (yamlPath !== undefined) {
+            _config = (0, yaml_config_1.loadYamlConfig)(yamlPath, process.env);
+            const ignored = (0, yaml_config_1.ignoredEnvKeys)(process.env);
+            if (ignored.length > 0) {
+                logger_1.logger.warn(`Ignoring env vars set but defined by the config file: ${ignored.join(", ")}`);
+            }
+        }
+        else {
+            const envConfig = loadConfig();
+            if (envConfig.deprecatedEnv.length > 0) {
+                logger_1.logger.warn("SOURCE_API is deprecated and ignored: the request path decides the client format. It will be removed in 2.0.");
+            }
+            _config = envConfig;
+        }
     }
     return _config;
 }
@@ -96,4 +146,5 @@ function getConfig() {
  */
 function resetConfig() {
     _config = null;
+    _configPath = undefined;
 }

package/dist/config/gateway.schema.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatewayFileSchema = void 0;
+const zod_1 = require("zod");
+const PROVIDER_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+const providerEntrySchema = zod_1.z
+    .strictObject({
+    type: zod_1.z.enum(["openai", "anthropic", "gemini", "ollama"]),
+    base_url: zod_1.z.string().min(1),
+    api_key_env: zod_1.z.string().optional(),
+    context_window: zod_1.z.number().int().positive().optional(),
+    timeout_ms: zod_1.z.number().int().positive().optional(),
+    stream_idle_ms: zod_1.z.number().int().positive().optional(),
+})
+    .superRefine((entry, ctx) => {
+    if (entry.type !== "ollama" && entry.api_key_env === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["api_key_env"],
+            message: 'required unless type is "ollama"',
+        });
+    }
+});
+/**
+ * babelgate.yaml schema (spec §3.5): strict objects at every level, so
+ * unknown keys are startup errors. Semantic checks (default is a
+ * provider, targets resolve, key env vars are set) happen in
+ * loadYamlConfig — they need the registry and the environment.
+ */
+exports.gatewayFileSchema = zod_1.z.strictObject({
+    default: zod_1.z.string(),
+    providers: zod_1.z
+        .record(zod_1.z.string().regex(PROVIDER_NAME), providerEntrySchema)
+        .refine((map) => Object.keys(map).length >= 1, {
+        message: "at least one provider is required",
+    }),
+    aliases: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    routes: zod_1.z
+        .array(zod_1.z.strictObject({
+        match: zod_1.z.string().min(1),
+        when: zod_1.z
+            .strictObject({
+            min_input_tokens: zod_1.z.number().int().positive().optional(),
+        })
+            .optional(),
+        to: zod_1.z.string(),
+        fallback: zod_1.z.array(zod_1.z.string()).optional(),
+    }))
+        .optional(),
+});