Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
feat: keep every Bot's provider defaults in one spec file (#649)
Hieu Dev 147537776206655
diff --git a/.env.example b/.env.exampleindex 114634b8..731118af 100644--- a/.env.example+++ b/.env.example@@ -222,6 +222,13 @@ OPENAI_API_KEY=# ANTHROPIC_API_KEY=# GOOGLE_API_KEY=+# A model sign-in in place of a key: the Anthropic token from `claude setup-token`, and the file a+# signed-in ChatGPT plan writes. The desktop app sets both when a provider is connected that way; a+# box you configure yourself sets them here. The API server reads them for built-in agents, and+# compose passes them to the picked harness. See docs/configuration.md.+# CLAUDE_CODE_OAUTH_TOKEN=+# CHATGPT_AUTH_FILE=+# Which model the framework Bot uses. Defaults per provider: gpt-5.5, claude-sonnet-4-5,# gemini-2.5-flash. A 5.6 tier works here: set one and the Responses API is switched on# automatically. It used to answer nothing at all on those models — RUN_STARTED, RUN_FINISHED, no@@ -365,8 +372,9 @@ MANAGED_AGENT_TOKEN=# proof of concept, and is reached the same way: point MANAGED_AGENT_AG_UI_URL at it, or add it as a# Bot of its own in the tenant package or at /agents.-# Which model the Bots use. BOT_MODEL is the framework Bot's: it runs gpt-5.6-terra and switches to-# the Responses API by itself, because 5.6 rejects function tools on /v1/chat/completions.+# Which model the Bots use. BOT_MODEL is the framework Bot's: it defaults to gpt-5.5 and switches+# to the Responses API by itself for a model that needs it — a 5.6 tier does, because 5.6 rejects+# function tools on /v1/chat/completions.## The proof-of-concept Bot has its own, AGENT_BOT_MODEL, defaulting to gpt-5.5, because it writes# that endpoint by hand and refuses to start on a model whose tools it cannot use. One variable fordiff --git a/CHANGELOG.md b/CHANGELOG.mdindex ff07b6cd..c8bc6066 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -217,6 +217,15 @@ gave up if the whole request had not arrived, and on Windows the accepted socketlistener's non-blocking mode, so a timeout did not apply. A good sign-in could be answered "Sign-indid not match". Both paths now read until the request line is complete, with a real timeout.+### The Bots agree on one set of provider defaults++The three TypeScript Bots now read a single shared list of provider facts instead of keeping their+own copies, which is what makes a default changeable in one place rather than in three. The Mastra+Bot also refuses a `BOT_PROVIDER` it does not recognize (such as `google`) instead of quietly+answering through OpenAI with a different model. The picked harness in Compose now receives+`GOOGLE_API_KEY` and `GOOGLE_GENERATIVE_AI_BASE_URL` as well, so a harness picked on+`BOT_PROVIDER=google` has the key it needs.+### Compose file lists separate correctly on WindowsThe separator between Compose files fell back to `:` everywhere, which is right on macOS and Linux@@ -225,6 +234,26 @@ reachable on every platform now that a port overlay is passed, where before it w## 0.0.14+### One spec file, in every language++`shared/model-providers.json` now holds the provider facts and every Bot's default provider and+model. The TypeScript Bots read it through `shared/model-providers.ts` and the ten Python Bots+through `shared/model_providers.py`, with `BOT_PROVIDER` and `BOT_MODEL` still winning over both+as they always have. Each Bot keeps its existing default, including Mastra's `gpt-4o-mini`.+Moving a Bot to a different model, or giving a Bot written in any other language its first one,+is editing one row in one file instead of one line per language.++Both loaders check the file against their own list of providers, in both directions, and refuse in+the same words. A wrong row in the file used to stop the three TypeScript Bots while the ten+Python Bots started clean and met it at their first model call instead; all thirteen stop at+startup now, naming the key that is wrong. Adding a provider is one row in the file and one entry+to `PROVIDER_IDS` in each loader.++Compose used to substitute `gpt-5.5` for `agent-langgraph` whenever `BOT_MODEL` was unset, whatever+`BOT_PROVIDER` named; it now passes the unset value through, so the Bot's row — or the moved+provider's default row — is what answers. An OpenAI deployment keeps the same `gpt-5.5` either way;+a Google or Anthropic one stops being handed a model its vendor has never heard of.+### A tool cannot be granted for an app this deployment has not addedGranting a Bot a connector's tool checked only that the person asking was an administrator, so adiff --git a/agent-adk/Dockerfile b/agent-adk/Dockerfileindex 635be013..fb990dbb 100644--- a/agent-adk/Dockerfile+++ b/agent-adk/Dockerfile@@ -9,6 +9,7 @@ COPY agent-adk/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-adk/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4208EXPOSE 4208diff --git a/agent-adk/src/main.py b/agent-adk/src/main.pyindex cf28e4f2..eeca9152 100644--- a/agent-adk/src/main.py+++ b/agent-adk/src/main.py@@ -5,6 +5,13 @@ reads LiteLLM model strings, and OpenBot writes the one it was told."""import os+import sys+from pathlib import Path++# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settingsfrom ag_ui_adk import ADKAgent, AGUIToolset, add_adk_fastapi_endpointfrom fastapi import FastAPI, Request@@ -53,8 +60,9 @@ def _model_id() -> str:and litellm then either routed to a provider nobody configured (`LLM Provider NOT provided`)or sent only the second half to the endpoint."""- provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()- model = (os.environ.get("BOT_MODEL") or "gpt-4o-mini").strip()+ settings = bot_settings("agent-adk")+ provider = settings.provider+ model = settings.modelreturn f"{provider}/{model}"diff --git a/agent-adk/tests/test_model_spec.py b/agent-adk/tests/test_model_spec.pynew file mode 100644index 00000000..0a54e5cc--- /dev/null+++ b/agent-adk/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-adk` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-adk"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-adk")' in sourcediff --git a/agent-ag2/Dockerfile b/agent-ag2/Dockerfileindex de95c3aa..df952e81 100644--- a/agent-ag2/Dockerfile+++ b/agent-ag2/Dockerfile@@ -9,6 +9,7 @@ COPY agent-ag2/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-ag2/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4210EXPOSE 4210diff --git a/agent-ag2/src/main.py b/agent-ag2/src/main.pyindex 796bc31b..0dcf1eb2 100644--- a/agent-ag2/src/main.py+++ b/agent-ag2/src/main.py@@ -1,6 +1,13 @@"""AG2 as a Bot. AG-UI is an extra in AG2's own package, so `ag2[ag-ui]` is the dependency."""import os+import sys+from pathlib import Path++# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settingsfrom ag2 import Agentfrom ag2.ag_ui import AGUIStream@@ -17,8 +24,9 @@ def _config() -> AnthropicConfig | OpenAIConfig:`BOT_PROVIDER` is `anthropic` for an Anthropic key and `openai` otherwise, an OpenAI-compatibleendpoint included. Each SDK reads its own key from the environment."""- provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()- model = (os.environ.get("BOT_MODEL") or "gpt-4o-mini").strip()+ settings = bot_settings("agent-ag2")+ provider = settings.provider+ model = settings.modelif provider == "anthropic":# Compose exports missing overrides as ""; the SDK only defaults an absent URL.base_url = (os.environ.get("ANTHROPIC_BASE_URL") or "").strip() or "https://api.anthropic.com"diff --git a/agent-ag2/tests/test_model_spec.py b/agent-ag2/tests/test_model_spec.pynew file mode 100644index 00000000..00aa3a0d--- /dev/null+++ b/agent-ag2/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-ag2` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-ag2"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-ag2")' in sourcediff --git a/agent-agno/Dockerfile b/agent-agno/Dockerfileindex 6a790e9a..9e97f434 100644--- a/agent-agno/Dockerfile+++ b/agent-agno/Dockerfile@@ -9,6 +9,7 @@ COPY agent-agno/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-agno/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4203EXPOSE 4203diff --git a/agent-agno/src/main.py b/agent-agno/src/main.pyindex ed8b6e10..3a545b04 100644--- a/agent-agno/src/main.py+++ b/agent-agno/src/main.py@@ -6,6 +6,13 @@ here, which is the rule."""import os+import sys+from pathlib import Path++# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settingsfrom agno.agent import Agentfrom agno.db.in_memory import InMemoryDb@@ -29,8 +36,9 @@ def _model_id() -> str:and litellm then either routed to a provider nobody configured (`LLM Provider NOT provided`)or sent only the second half to the endpoint."""- provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()- model = (os.environ.get("BOT_MODEL") or "gpt-5.5").strip()+ settings = bot_settings("agent-agno")+ provider = settings.provider+ model = settings.modelreturn f"{provider}/{model}"diff --git a/agent-agno/tests/test_model_spec.py b/agent-agno/tests/test_model_spec.pynew file mode 100644index 00000000..df4ce361--- /dev/null+++ b/agent-agno/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-agno` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-agno"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-5.5")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-5.5")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-agno")' in sourcediff --git a/agent-bot/src/index.ts b/agent-bot/src/index.tsindex b470ac93..4b22a868 100644--- a/agent-bot/src/index.ts+++ b/agent-bot/src/index.ts@@ -4,13 +4,13 @@ import { serve } from "bun";import OpenAI from "openai";import { hasManagedAgentToken } from "../../shared/agent-authorisation";import { listenPort } from "../../shared/listen-port";-import { toProviderMessages } from "./history";import {apiKeyOrPlaceholder,+ botSettings,keyIsRequired,- modelIsUnusable,- modelName,-} from "./model-key";+ requiresResponsesApi,+} from "../../shared/model-providers";+import { toProviderMessages } from "./history";/*** The built-in Bot is an AG-UI HTTP service registered the same way as any customer-provided Bot.@@ -39,24 +39,29 @@ if (!MANAGED_AGENT_TOKEN) {/*** Which model drives the Bot.*+ * This Bot speaks one provider's API by hand, so the provider is this file's and only the model is+ * configurable. What the default is, and which file every language in the box reads it from, is+ * `shared/model-providers.json`: this Bot's `bots.agent-bot` row, under `BOT_MODEL` when a+ * deployment sets one. The provider is pinned to `openai` rather than read from the environment —+ * this file has never read `BOT_PROVIDER`, and a Bot that answers on chat completions by hand+ * cannot start answering somewhere else because a variable changed.+ ** `gpt-5.5` works through `/v1/chat/completions`, which is the API this file uses.** `gpt-5.6-*` models require the Responses API for tool use and cannot be used by this* chat-completions streaming loop.*/-const MODEL = modelName(process.env.BOT_MODEL);+const MODEL = botSettings("agent-bot", process.env, "openai").model;/*- * Refuse a model this file cannot use, rather than discover it one tool call at a time.- *- * `gpt-5.6-*` rejects function tools on `/v1/chat/completions`: "To use function tools, use- * /v1/responses or set reasoning_effort to 'none'." The provider answers with an error, this Bot- * ends the run, and the person sees no reply and no reason. Silence is the worst failure available- * here, and it is what a single mistaken `BOT_MODEL` produced: every tool-using turn stopped dead- * while the Bot looked healthy.+ * Refuse a model this file cannot use, rather than discover it one tool call at a time — the+ * failure `requiresResponsesApi` names, asked as a question about this Bot rather than about the+ * model. The provider answers with an error, this Bot ends the run, and the person sees no reply+ * and no reason. Silence is the worst failure available here, and it is what a single mistaken+ * `BOT_MODEL` produced: every tool-using turn stopped dead while the Bot looked healthy.** Startup is where a deployment can act on it, which is the same posture as the token check above.*/-if (modelIsUnusable(MODEL)) {+if (requiresResponsesApi(MODEL)) {console.error(`BOT_MODEL=${MODEL} cannot be used by this Bot. It speaks /v1/chat/completions directly, and ` +"that endpoint refuses function tools for this model, so every tool call would fail with no " +@@ -97,7 +102,7 @@ const API_KEY = process.env.OPENAI_API_KEY?.trim();** The check still holds for plain OpenAI, which is the case it was written for.*/-if (!API_KEY && keyIsRequired(BASE_URL)) {+if (!API_KEY && keyIsRequired("openai", BASE_URL)) {console.error("OPENAI_API_KEY is not set, and no OPENAI_BASE_URL names an endpoint that needs no key. This Bot cannot answer without a model.",);diff --git a/agent-bot/src/model-key.ts b/agent-bot/src/model-key.tsdeleted file mode 100644index 9b219f56..00000000--- a/agent-bot/src/model-key.ts+++ /dev/null@@ -1,34 +0,0 @@-/**- * Whether this Bot needs a model key, checked before it starts.- *- * Its own module because `index.ts` serves at module scope, so importing it to reach one pure- * function binds a port.- */--/**- * A key is required unless an endpoint was named to answer instead.- *- * `OPENAI_BASE_URL` set means any endpoint speaking that API, and Ollama, vLLM, LM Studio and- * llama.cpp all serve it with no key. The setup window offers exactly those by name and accepts a- * blank key for them, so requiring one here exited this Bot on startup for every one of them.- */-export function keyIsRequired(baseUrl: string | undefined): boolean {- return !baseUrl?.trim();-}--/**- * What to hand the SDK, which insists on a string even when the endpoint ignores it.- *- * A placeholder rather than an empty string: empty is a client that cannot be constructed.- */-export function apiKeyOrPlaceholder(apiKey: string | undefined): string {- return apiKey?.trim() || "no-key-needed";-}--export function modelName(configured: string | undefined): string {- return configured?.trim() || "gpt-5.5";-}--export function modelIsUnusable(model: string): boolean {- return /^gpt-5\.[6-9]|^gpt-[6-9]/.test(model);-}diff --git a/agent-bot/tests/model-key.test.ts b/agent-bot/tests/model-key.test.tsdeleted file mode 100644index 3e0c43a7..00000000--- a/agent-bot/tests/model-key.test.ts+++ /dev/null@@ -1,56 +0,0 @@-import { describe, expect, test } from "bun:test";-import {- apiKeyOrPlaceholder,- keyIsRequired,- modelIsUnusable,- modelName,-} from "../src/model-key";--/**- * A named endpoint is a model, and its key belongs to it.- *- * The failure this pins: the setup window's "any OpenAI-compatible endpoint" row takes an address- * with no key, because Ollama and vLLM have none. This Bot then refused to start, saying- * OPENAI_API_KEY was not set, so the keyless half of that feature produced a dead container and a- * red line on the last screen about a key the person's own server does not have.- */-describe("whether a model key is required", () => {- test("plain OpenAI still needs its key", () => {- expect(keyIsRequired(undefined)).toBe(true);- expect(keyIsRequired("")).toBe(true);- expect(keyIsRequired(" ")).toBe(true);- });-- test("an endpoint named instead of OpenAI answers without one", () => {- expect(keyIsRequired("http://127.0.0.1:11434/v1")).toBe(false);- });-- test("the SDK is always handed a string", () => {- expect(apiKeyOrPlaceholder(undefined)).toBe("no-key-needed");- expect(apiKeyOrPlaceholder(" ")).toBe("no-key-needed");- expect(apiKeyOrPlaceholder("sk-real")).toBe("sk-real");- });-});--describe("which model this Bot was told to use", () => {- test("an unset or empty choice falls back", () => {- expect(modelName(undefined)).toBe("gpt-5.5");- expect(modelName("")).toBe("gpt-5.5");- expect(modelName(" ")).toBe("gpt-5.5");- });-- test("a padded name is the name", () => {- expect(modelName(" gpt-5.5 ")).toBe("gpt-5.5");- });-- test("the models this Bot cannot drive are refused", () => {- expect(modelIsUnusable("gpt-5.6-terra")).toBe(true);- expect(modelIsUnusable("gpt-6")).toBe(true);- expect(modelIsUnusable("gpt-5.5")).toBe(false);- });-- test("padding does not get one past the guard", () => {- expect(modelIsUnusable(modelName(" gpt-5.6-terra"))).toBe(true);- expect(modelIsUnusable(modelName("\tgpt-6 "))).toBe(true);- });-});diff --git a/agent-crewai/Dockerfile b/agent-crewai/Dockerfileindex df4a07d3..e2672f4f 100644--- a/agent-crewai/Dockerfile+++ b/agent-crewai/Dockerfile@@ -9,6 +9,7 @@ COPY agent-crewai/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-crewai/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4202EXPOSE 4202diff --git a/agent-crewai/src/main.py b/agent-crewai/src/main.pyindex ed62d700..1e31ff12 100644--- a/agent-crewai/src/main.py+++ b/agent-crewai/src/main.py@@ -10,10 +10,17 @@ serve AG-UI on a port, answer `/health`, and refuse anybody who does not carry t"""import os+import sysfrom collections.abc import Mappingfrom copy import deepcopy+from pathlib import Pathfrom typing import Any+# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settings+import ag_ui_crewai.endpoint as crewai_endpointfrom ag_ui.core import Message, Toolfrom ag_ui_crewai import add_crewai_flow_fastapi_endpoint@@ -46,8 +53,9 @@ def _model() -> str:and litellm then either routed to a provider nobody configured (`LLM Provider NOT provided`)or sent only the second half to the endpoint."""- provider = (os.environ.get("BOT_PROVIDER") or "").strip() or "openai"- model = (os.environ.get("BOT_MODEL") or "").strip() or "gpt-5.5"+ settings = bot_settings("agent-crewai")+ provider = settings.provider+ model = settings.modelreturn f"{provider}/{model}"diff --git a/agent-crewai/tests/test_model_spec.py b/agent-crewai/tests/test_model_spec.pynew file mode 100644index 00000000..74c43fe9--- /dev/null+++ b/agent-crewai/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-crewai` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-crewai"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-5.5")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-5.5")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-crewai")' in sourcediff --git a/agent-langgraph-agui/Dockerfile b/agent-langgraph-agui/Dockerfileindex 655796cd..989639ec 100644--- a/agent-langgraph-agui/Dockerfile+++ b/agent-langgraph-agui/Dockerfile@@ -9,6 +9,7 @@ COPY agent-langgraph-agui/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-langgraph-agui/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4206EXPOSE 4206diff --git a/agent-langgraph-agui/src/main.py b/agent-langgraph-agui/src/main.pyindex 7b38134a..349d46f7 100644--- a/agent-langgraph-agui/src/main.py+++ b/agent-langgraph-agui/src/main.py@@ -6,8 +6,14 @@ package the AG-UI project maintains, so the protocol stops being ours to keep wo"""import os+import sysfrom pathlib import Path+# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settings+from ag_ui_langgraph import add_langgraph_fastapi_endpointfrom fastapi import FastAPI, Requestfrom fastapi.responses import JSONResponse@@ -116,9 +122,12 @@ def _model():and the selected provider is passed separately, including when that ID contains a colon."""configured_model = os.environ.get("BOT_MODEL")- model = (configured_model or "gpt-4o-mini").strip()store = (os.environ.get("CHATGPT_AUTH_FILE") or "").strip()if store:+ # A signed-in ChatGPT plan ignores BOT_PROVIDER, retaining this Bot's file model unless+ # BOT_MODEL overrides it. Other providers use the fully resolved settings below.+ file_row = bot_settings("agent-langgraph-agui", {})+ model = (configured_model or "").strip() or file_row.modelstore_path = _chatgpt_auth_file(store)# Private and experimental, both deliberately. `langchain-openai` exports no public Codex# model and warns in the module that this one is unofficial. That is a maintenance cost we@@ -138,13 +147,15 @@ def _model():)_normalize_openai_base_url()- provider = (os.environ.get("BOT_PROVIDER") or "").strip() or "openai"- provider = _resolve_provider(provider)- if not configured_model:- model = {- "anthropic": "claude-sonnet-4-5",- "google_genai": "gemini-2.5-flash",- }.get(provider, model)+ settings = bot_settings("agent-langgraph-agui")+ if settings.provider == "google_genai":+ # LangChain's provider spelling is also an existing BOT_PROVIDER choice. Resolve its+ # defaults through the spec's Google row before mapping back to the SDK spelling.+ settings = bot_settings(+ "agent-langgraph-agui", {**os.environ, "BOT_PROVIDER": "google"}+ )+ provider = _resolve_provider(settings.provider)+ model = settings.modelprefix, separator, _ = model.partition(":")if separator and prefix in MODEL_PROVIDERS:return init_chat_model(model, **_google_genai_kwargs(prefix))diff --git a/agent-langgraph-agui/tests/test_model_spec.py b/agent-langgraph-agui/tests/test_model_spec.pynew file mode 100644index 00000000..a6e9d3c1--- /dev/null+++ b/agent-langgraph-agui/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-langgraph-agui` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-langgraph-agui"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-langgraph-agui")' in sourcediff --git a/agent-langgraph-agui/tests/test_provider_boundaries.py b/agent-langgraph-agui/tests/test_provider_boundaries.pyindex 5be6fcf8..a0a824f1 100644--- a/agent-langgraph-agui/tests/test_provider_boundaries.py+++ b/agent-langgraph-agui/tests/test_provider_boundaries.py@@ -16,6 +16,7 @@ import pytestsys.path.insert(0, str(Path(__file__).resolve().parents[1]))from src import main+from model_providers import SPEC_LOOPBACK_SOCKET_GUARD_INSTALLED = False@@ -344,6 +345,60 @@ async def test_anthropic_selection_reaches_anthropic_boundary_without_openai_key][email protected]("spec_source", ["bot", "provider"])+ ("configured_model", "request_model"),+ [+ (None, "claude-spec-model"),+ ("", "claude-spec-model"),+ (" ", "claude-spec-model"),+ (" claude-override ", "claude-override"),+ ("anthropic:claude-override", "claude-override"),+ ],+)+async def test_spec_model_reaches_anthropic_request(+ monkeypatch, spec_source, configured_model, request_model+):+ if spec_source == "bot":+ monkeypatch.setitem(+ SPEC["bots"],+ "agent-langgraph-agui",+ {"provider": "anthropic", "model": "claude-spec-model"},+ )+ else:+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setitem(+ SPEC["providers"]["anthropic"], "default_model", "claude-spec-model"+ )+ if configured_model is not None:+ monkeypatch.setenv("BOT_MODEL", configured_model)+ if configured_model and configured_model.startswith("anthropic:"):+ # A provider-qualified model still selects its provider independently of BOT_PROVIDER.+ monkeypatch.setenv("BOT_PROVIDER", "openai")+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-openbot-ci")+ monkeypatch.setenv("ANTHROPIC_BASE_URL", "http://127.0.0.1:4311")++ result, captured = await _run_answer_with_httpx2_capture(+ monkeypatch,+ {+ "id": "msg-openbot-ci",+ "type": "message",+ "role": "assistant",+ "model": request_model,+ "content": [{"type": "text", "text": "spec model proof"}],+ "stop_reason": "end_turn",+ "stop_sequence": None,+ "usage": {"input_tokens": 1, "output_tokens": 1},+ },+ )++ assert result["messages"][0].content == "spec model proof"+ assert len(captured) == 1+ assert captured[0]["url"] == "http://127.0.0.1:4311/v1/messages"+ assert captured[0]["body"]["model"] == request_model++# A conversation as the server sends it after somebody picked a skill: the coworker's standing role# at the head, and the skill's instruction as a system turn just ahead of the message it was picked# for. The turn stays in the thread's history, so every later run carries it too.@@ -463,6 +518,36 @@ async def test_google_provider_reaches_google_genai_boundary(][email protected]("provider", [None, "google", "google_genai"])+async def test_google_spec_model_reaches_google_request(+ monkeypatch, google_genai_endpoint, provider+):+ _install_loopback_socket_guard()+ base_url, captured = google_genai_endpoint+ monkeypatch.setenv("GOOGLE_API_KEY", "synthetic-google")+ monkeypatch.setenv("GOOGLE_GENERATIVE_AI_BASE_URL", base_url)+ if provider is None:+ monkeypatch.setitem(+ SPEC["bots"],+ "agent-langgraph-agui",+ {"provider": "google", "model": "gemini-spec-model"},+ )+ else:+ monkeypatch.setenv("BOT_PROVIDER", provider)+ monkeypatch.setitem(+ SPEC["providers"]["google"], "default_model", "gemini-spec-model"+ )++ result = await main.answer(+ {"messages": [{"role": "user", "content": "Say hello."}]}+ )++ assert result["messages"][0].content == "google loopback proof"+ assert len(captured) == 1+ assert captured[0]["path"] == "/v1beta/models/gemini-spec-model:generateContent"++def _write_synthetic_chatgpt_store(path: Path):from langchain_openai.chatgpt_oauth import _ChatGPTTokenfrom langchain_openai.chat_models.codex import _FileChatGPTOAuthTokenProviderdiff --git a/agent-langgraph-agui/tests/test_spec_validation.py b/agent-langgraph-agui/tests/test_spec_validation.pynew file mode 100644index 00000000..a0265b23--- /dev/null+++ b/agent-langgraph-agui/tests/test_spec_validation.py@@ -0,0 +1,99 @@+"""The spec file's validation, exercised the way the TypeScript loader exercises it.++`shared/model-providers.json` is one file, but `shared/model-providers.ts` and+`shared/model_providers.py` each keep their own list of the providers they have heard of and check+the file against their own list in both directions. This test is the Python half of that. Each case+imports the loader in a subprocess against a file written to `tmp_path`, so a refusal here cannot+leave a half-loaded module behind for the tests beside it, and the words asserted are the words the+TypeScript loader says for the same file.+"""++import json+import os+import subprocess+import sys+from pathlib import Path++import pytest++SHARED = Path(__file__).resolve().parents[2] / "shared"++sys.path.insert(0, str(SHARED))+from model_providers import PROVIDER_IDS++_PROVIDER_FIELDS = {+ "key_variable": "SOME_API_KEY",+ "base_url_variable": "SOME_BASE_URL",+ "default_model": "some-model",+}+++def _spec():+ """A file this module accepts, for a test to take one thing out of."""+ return {+ "providers": {+ provider_id: {**_PROVIDER_FIELDS, "label": provider_id.title()}+ for provider_id in PROVIDER_IDS+ },+ "bots": {"agent-x": {"provider": "openai", "model": "gpt-5.5"}},+ }+++def _import(spec, tmp_path, shipped=False):+ """Import the loader against `spec`, or against the file in the repository when `shipped`."""+ environment = dict(os.environ)+ environment.pop("BOT_SPEC_PATH", None)+ if not shipped:+ path = tmp_path / "model-providers.json"+ path.write_text(json.dumps(spec), encoding="utf-8")+ environment["BOT_SPEC_PATH"] = str(path)+ environment["PYTHONPATH"] = str(SHARED) + os.pathsep + environment.get("PYTHONPATH", "")+ return subprocess.run(+ [sys.executable, "-c", "import model_providers"],+ cwd=str(tmp_path),+ env=environment,+ text=True,+ capture_output=True,+ )+++def _refusal(spec, tmp_path):+ """The words the loader refused `spec` with."""+ result = _import(spec, tmp_path)+ assert result.returncode != 0, "the loader accepted a file it should have refused."+ return result.stderr+++def test_the_file_in_the_repository_is_one_this_module_accepts(tmp_path):+ result = _import(None, tmp_path, shipped=True)+ assert result.returncode == 0, result.stderr++ declared = json.loads(+ (SHARED / "model-providers.json").read_text(encoding="utf-8")+ )["providers"]+ assert set(declared) == set(PROVIDER_IDS)++[email protected]("missing", PROVIDER_IDS)+def test_a_provider_row_the_list_names_may_not_be_dropped(tmp_path, missing):+ spec = _spec()+ del spec["providers"][missing]+ assert f"providers is missing its {missing} row." in _refusal(spec, tmp_path)+++def test_a_provider_row_the_list_has_never_heard_of_is_refused(tmp_path):+ spec = _spec()+ spec["providers"]["mistral"] = {**_PROVIDER_FIELDS, "label": "Mistral"}+ assert (+ "providers has a mistral row this module has never heard of."+ in _refusal(spec, tmp_path)+ )+++def test_a_bot_naming_a_provider_the_list_has_never_heard_of_is_refused(tmp_path):+ spec = _spec()+ spec["bots"]["agent-x"]["provider"] = "mistral"+ assert (+ 'bots.agent-x.provider is "mistral", not one of openai, anthropic, google.'+ in _refusal(spec, tmp_path)+ )diff --git a/agent-langgraph/src/index.ts b/agent-langgraph/src/index.tsindex 7fb7d765..945cf977 100644--- a/agent-langgraph/src/index.ts+++ b/agent-langgraph/src/index.ts@@ -13,9 +13,16 @@ import { ChatOpenAI } from "@langchain/openai";import { serve } from "bun";import { hasManagedAgentToken } from "../../shared/agent-authorisation";import { listenPort } from "../../shared/listen-port";+import {+ apiKeyOrPlaceholder,+ baseUrlVariableFor,+ botSettings,+ keyIsRequired,+ keyVariableFor,+ requiresResponsesApi,+} from "../../shared/model-providers";import { toLangChainMessages } from "./history";import { readReasoningEffort } from "./model-options";-import { apiKeyOrPlaceholder, KEY_VARIABLE, keyIsRequired } from "./model-key";import { streamRun } from "./stream";import { toolAnswer } from "./tool-answer";@@ -65,47 +72,48 @@ if (!MANAGED_AGENT_TOKEN) {* Each provider reads its own key. A deployment that only runs Anthropic never needs an OpenAI key,* which is the point of making this configurable rather than assuming one vendor.*- * The default is unchanged so the two shipped Bots stay comparable out of the box.- */-const PROVIDER = (process.env.BOT_PROVIDER ?? "openai").toLowerCase();-/*- * An unset model and an empty one are the same thing.+ * The default comes from `shared/model-providers.json` — this Bot's `bots.agent-langgraph` row —+ * so the two shipped Bots stay comparable out of the box and every language in the box reads the+ * same decision. Which variable each provider's key and endpoint arrive in is read from the same+ * file's provider rows rather than repeated here.*- * `??` only catches undefined, and a compose file passing `BOT_MODEL: ${BOT_MODEL:-}` hands this an- * empty string, which is a value. The agent then asked its provider for a model named "" and the- * run died with "you must provide a model parameter", which reads as a broken Bot rather than as- * missing configuration.+ * Blank is OpenAI, the reading every other consumer of `BOT_PROVIDER` gives it: the desktop writes+ * an empty provider when switching back to OpenAI, and the server reads empty as OpenAI. An unset+ * environment falls through to the spec row, and when that says openai — as it does today — the+ * two readings are the same. Padded and differently-cased names are the same provider, because a+ * value typed into a setup window arrives with a space on it more often than not. A name nobody+ * has heard of is kept, so the check below can put it in its message. The lookup order is+ * environment over spec file over provider default; see `botSettings`.*/-const MODEL = process.env.BOT_MODEL?.trim() || defaultModelFor(PROVIDER);+const { provider: PROVIDER, model: MODEL } = botSettings("agent-langgraph");/*** OpenAI only. Its newer models require the Responses API, which the integration handles.** Inferred from the model rather than left to a separate switch. `gpt-5.6-*` rejects function tools* on `/v1/chat/completions`, so a deployment that set `BOT_MODEL` to one and did not also know about* this flag got a Bot that started, looked healthy, and failed on its first tool call. The switch is- * still honoured, so a model this list has not heard of can be told to use it.+ * still honoured, so a model the registry has not heard of can be told to use it.*/-const NEEDS_RESPONSES_API = /^gpt-5\.[6-9]|^gpt-[6-9]/.test(MODEL);+const NEEDS_RESPONSES_API = requiresResponsesApi(MODEL);const USE_RESPONSES_API =process.env.BOT_RESPONSES_API === "true" || NEEDS_RESPONSES_API;/**- * OpenAI only, and the same variable the API server reads for its built-in agents.+ * Read from the provider registry rather than spelled out here three times, under the names the+ * API server already reads. Sharing the names is the point: one line moves the built-in agents and+ * this Bot together, and a deployment cannot end up with half of itself pointed somewhere else.*- * Unset, `openai` means OpenAI. Set, it means any endpoint speaking that API: a gateway in front of- * several providers, a proxy, or a model on hardware you control. The integration owns the HTTP, so- * this is a base URL rather than another provider branch, and `BOT_MODEL` is sent verbatim because- * an endpoint names its own catalogue.- */-const OPENAI_BASE_URL = process.env.OPENAI_BASE_URL?.trim() || undefined;-/**- * The same idea for the other two providers, under the names the API server already reads.+ * Unset, this is that provider's own public endpoint. Set, it means any endpoint speaking that API:+ * a gateway in front of several providers, a proxy, or a model on hardware you control. The+ * integration owns the HTTP, so this is a base URL rather than another provider branch, and+ * `BOT_MODEL` is sent verbatim because an endpoint names its own catalogue.*- * Sharing the variable names is the point: one line moves the built-in agents and this Bot- * together, and a deployment cannot end up with half of itself pointed somewhere else.+ * Only the provider this Bot was configured for is read, and each branch of `buildModel` below+ * ever took its own and no other, so nothing that used to be visible has changed.*/-const ANTHROPIC_BASE_URL = process.env.ANTHROPIC_BASE_URL?.trim() || undefined;-const GOOGLE_BASE_URL =- process.env.GOOGLE_GENERATIVE_AI_BASE_URL?.trim() || undefined;+const baseUrlVariable = baseUrlVariableFor(PROVIDER);+const BASE_URL = baseUrlVariable+ ? process.env[baseUrlVariable]?.trim() || undefined+ : undefined;/*** OpenAI only, and Responses API only: how hard this Bot is allowed to think.@@ -141,12 +149,6 @@ if (REASONING_EFFORT && !USE_RESPONSES_API) {process.exit(1);}-function defaultModelFor(provider: string): string {- if (provider === "anthropic") return "claude-sonnet-4-5";- if (provider === "google") return "gemini-2.5-flash";- return "gpt-5.5";-}-/*** The key this provider needs, checked at startup rather than on the first run.*@@ -154,7 +156,7 @@ function defaultModelFor(provider: string): string {* a missing key should fail in front of whoever is deploying, not as a conversation that errors in* front of somebody trying to use it.*/-const keyVariable = KEY_VARIABLE[PROVIDER];+const keyVariable = keyVariableFor(PROVIDER);if (!keyVariable) {console.error(`BOT_PROVIDER=${PROVIDER} is not one this Bot knows. Use openai, anthropic or google.`,@@ -163,7 +165,7 @@ if (!keyVariable) {}const API_KEY = process.env[keyVariable]?.trim();// Unless an endpoint was named to answer instead: see `keyIsRequired`.-if (!API_KEY && keyIsRequired(PROVIDER, OPENAI_BASE_URL)) {+if (!API_KEY && keyIsRequired(PROVIDER, BASE_URL)) {console.error(`${keyVariable} is not set, and BOT_PROVIDER=${PROVIDER} needs it. This Bot cannot answer without a model.`,);@@ -199,7 +201,7 @@ function buildModel() {model: MODEL,apiKey: apiKeyOrPlaceholder(API_KEY),streaming: true,- ...(ANTHROPIC_BASE_URL ? { anthropicApiUrl: ANTHROPIC_BASE_URL } : {}),+ ...(BASE_URL ? { anthropicApiUrl: BASE_URL } : {}),});}if (PROVIDER === "google") {@@ -207,14 +209,14 @@ function buildModel() {model: MODEL,apiKey: apiKeyOrPlaceholder(API_KEY),streaming: true,- ...(GOOGLE_BASE_URL ? { baseUrl: GOOGLE_BASE_URL } : {}),+ ...(BASE_URL ? { baseUrl: BASE_URL } : {}),});}return new ChatOpenAI({model: MODEL,apiKey: apiKeyOrPlaceholder(API_KEY),streaming: true,- ...(OPENAI_BASE_URL ? { configuration: { baseURL: OPENAI_BASE_URL } } : {}),+ ...(BASE_URL ? { configuration: { baseURL: BASE_URL } } : {}),...(USE_RESPONSES_API ? { useResponsesApi: true } : {}),/** `reasoning.effort`, not the `reasoningEffort` convenience field: the integration deprecateddiff --git a/agent-langgraph/src/model-key.ts b/agent-langgraph/src/model-key.tsdeleted file mode 100644index 4bc6aa36..00000000--- a/agent-langgraph/src/model-key.ts+++ /dev/null@@ -1,42 +0,0 @@-/**- * Whether this Bot needs a model key, checked before it starts.- *- * Its own module for the reason `model-options.ts` is: `index.ts` calls `serve()` at module scope,- * so importing it to reach one pure function binds a port.- */--/** The environment variable each provider's key arrives in. */-export const KEY_VARIABLE: Record<string, string> = {- openai: "OPENAI_API_KEY",- anthropic: "ANTHROPIC_API_KEY",- google: "GOOGLE_API_KEY",-};--/**- * A key is required unless an endpoint was named to answer instead.- *- * `OPENAI_BASE_URL` set means any endpoint speaking that API, and Ollama, vLLM, LM Studio and- * llama.cpp all serve it with no key at all. The setup window offers exactly those by name and- * accepts a blank key for them, so requiring one here exited this Bot on startup for every one of- * them: the person filled in an address and got a dead container complaining about a key their- * server does not have. Two ends of one feature disagreeing.- *- * Only the OpenAI branch has a base URL to be named by, so nothing changes for the other two.- */-export function keyIsRequired(- provider: string,- baseUrl: string | undefined,-): boolean {- const named = provider === "openai" && Boolean(baseUrl?.trim());- return !named;-}--/**- * What to hand the SDK, which insists on a string even when the endpoint ignores it.- *- * A placeholder rather than an empty string: empty is a client that cannot be constructed, and the- * value is never sent anywhere that reads it.- */-export function apiKeyOrPlaceholder(apiKey: string | undefined): string {- return apiKey?.trim() || "no-key-needed";-}diff --git a/agent-langgraph/tests/model-key.test.ts b/agent-langgraph/tests/model-key.test.tsdeleted file mode 100644index cd6eff0f..00000000--- a/agent-langgraph/tests/model-key.test.ts+++ /dev/null@@ -1,34 +0,0 @@-import { describe, expect, test } from "bun:test";-import { apiKeyOrPlaceholder, keyIsRequired } from "../src/model-key";--/**- * A named endpoint is a model, and its key belongs to it.- *- * The failure this pins: the setup window's "any OpenAI-compatible endpoint" row takes an address- * with no key, because Ollama and vLLM have none. This Bot then refused to start, saying- * OPENAI_API_KEY was not set, so the whole keyless half of that feature produced a dead container.- */-describe("whether a model key is required", () => {- test("plain OpenAI still needs its key", () => {- expect(keyIsRequired("openai", undefined)).toBe(true);- expect(keyIsRequired("openai", "")).toBe(true);- expect(keyIsRequired("openai", " ")).toBe(true);- });-- test("an endpoint named instead of OpenAI answers without one", () => {- expect(keyIsRequired("openai", "http://127.0.0.1:11434/v1")).toBe(false);- });-- /** Neither of the other providers has a base URL to be named by, so neither changes. */- test("anthropic and google are unchanged", () => {- expect(keyIsRequired("anthropic", "http://127.0.0.1:11434/v1")).toBe(true);- expect(keyIsRequired("google", "http://127.0.0.1:11434/v1")).toBe(true);- });-- /** The SDK cannot be constructed with an empty string, so there is always something to pass. */- test("the SDK is always handed a string", () => {- expect(apiKeyOrPlaceholder(undefined)).toBe("no-key-needed");- expect(apiKeyOrPlaceholder(" ")).toBe("no-key-needed");- expect(apiKeyOrPlaceholder("sk-real")).toBe("sk-real");- });-});diff --git a/agent-langroid/Dockerfile b/agent-langroid/Dockerfileindex bfa27a1b..b34f1675 100644--- a/agent-langroid/Dockerfile+++ b/agent-langroid/Dockerfile@@ -9,6 +9,7 @@ COPY agent-langroid/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-langroid/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4209EXPOSE 4209diff --git a/agent-langroid/src/main.py b/agent-langroid/src/main.pyindex 58b59c2d..7dafb4ed 100644--- a/agent-langroid/src/main.py+++ b/agent-langroid/src/main.py@@ -1,6 +1,13 @@"""Langroid as a Bot, through `ag-ui-langroid`, which AG-UI maintains."""import os+import sys+from pathlib import Path++# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settingsfrom ag_ui_langroid import create_langroid_appfrom fastapi import Request@@ -19,8 +26,9 @@ def _model_id() -> str:`openai/gpt-4o-mini` is rejected by its OpenAI client as an invalid model id, so the prefix goeson only when the provider is somebody else."""- provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()- model = (os.environ.get("BOT_MODEL") or "gpt-4o-mini").strip()+ settings = bot_settings("agent-langroid")+ provider = settings.provider+ model = settings.modelif "/" in model or provider == "openai":return modelreturn f"litellm/{provider}/{model}"diff --git a/agent-langroid/tests/test_model_spec.py b/agent-langroid/tests/test_model_spec.pynew file mode 100644index 00000000..6a2d6ce1--- /dev/null+++ b/agent-langroid/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-langroid` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-langroid"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-langroid")' in sourcediff --git a/agent-llamaindex/Dockerfile b/agent-llamaindex/Dockerfileindex 84c2212f..7aca05b6 100644--- a/agent-llamaindex/Dockerfile+++ b/agent-llamaindex/Dockerfile@@ -9,6 +9,7 @@ COPY agent-llamaindex/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-llamaindex/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4204EXPOSE 4204diff --git a/agent-llamaindex/src/main.py b/agent-llamaindex/src/main.pyindex 4870bcd7..12478fc3 100644--- a/agent-llamaindex/src/main.py+++ b/agent-llamaindex/src/main.py@@ -5,6 +5,13 @@ FastAPI router. Mount it and stop."""import os+import sys+from pathlib import Path++# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settingsimport litellmfrom fastapi import FastAPI, Request@@ -26,8 +33,9 @@ def _model_id() -> str:and litellm then either routed to a provider nobody configured (`LLM Provider NOT provided`)or sent only the second half to the endpoint."""- provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()- model = (os.environ.get("BOT_MODEL") or "gpt-5.5").strip()+ settings = bot_settings("agent-llamaindex")+ provider = settings.provider+ model = settings.modelreturn f"{provider}/{model}"diff --git a/agent-llamaindex/tests/test_model_spec.py b/agent-llamaindex/tests/test_model_spec.pynew file mode 100644index 00000000..b3ecc171--- /dev/null+++ b/agent-llamaindex/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-llamaindex` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-llamaindex"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-5.5")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-5.5")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-llamaindex")' in sourcediff --git a/agent-mastra/Dockerfile b/agent-mastra/Dockerfileindex a2d21a45..52066367 100644--- a/agent-mastra/Dockerfile+++ b/agent-mastra/Dockerfile@@ -7,6 +7,8 @@ COPY agent-mastra/package.json ./RUN bun installCOPY shared/listen-port.ts /shared/listen-port.ts+COPY shared/model-providers.ts /shared/model-providers.ts+COPY shared/model-providers.json /shared/model-providers.jsonCOPY agent-mastra/src ./src# Built at image time, not at start: `mastra start` runs a bundle, and building on every containerdiff --git a/agent-mastra/src/mastra/index.test.ts b/agent-mastra/src/mastra/index.test.tsindex 5101787b..02016b48 100644--- a/agent-mastra/src/mastra/index.test.ts+++ b/agent-mastra/src/mastra/index.test.ts@@ -106,6 +106,41 @@ async function configuredPort(port: string | undefined) {};}+/**+ * How this Bot answers a provider it has no module for: refused at startup, before a model exists.+ *+ * The message is the result rather than an error to be thrown past the assertion, so the exit+ * status is returned the way the port probe returns it.+ */+async function providerStartup(botProvider: string) {+ const env: Record<string, string> = {+ PATH: process.env.PATH ?? "/opt/homebrew/bin:/usr/bin:/bin",+ MASTRA_TELEMETRY_DISABLED: "true",+ DO_NOT_TRACK: "1",+ NODE_ENV: "test",+ BOT_PROVIDER: botProvider,+ };++ const child = Bun.spawn(+ [+ Bun.argv[0],+ "-e",+ [+ 'const { mastra } = await import("./agent-mastra/src/mastra/index.ts");',+ 'const model = mastra.getAgent("openbot").model;',+ "console.log(JSON.stringify({ modelId: model.modelId }));",+ ].join("\n"),+ ],+ { env, stdout: "pipe", stderr: "pipe" },+ );++ const [stderr, exitCode] = await Promise.all([+ new Response(child.stderr).text(),+ child.exited,+ ]);+ return { exitCode, stderr };+}+describe("OpenBot Mastra receiver instructions", () => {test("delivers the learned catalog after the standing role and tool guidance", () => {expect(@@ -189,6 +224,26 @@ describe("OpenBot Mastra model configuration", () => {}});+/**+ * A provider this Bot cannot answer for is refused before it can fall into the OpenAI branch and+ * quietly answer with somebody else's model.+ */+describe("OpenBot Mastra provider configuration", () => {+ test("refuses a provider it loads no module for", async () => {+ const { exitCode, stderr } = await providerStartup("google");++ expect(exitCode).not.toBe(0);+ expect(stderr).toContain("loads no Google module");+ });++ test("refuses a provider the registry has not heard of", async () => {+ const { exitCode, stderr } = await providerStartup("mistral");++ expect(exitCode).not.toBe(0);+ expect(stderr).toContain("is not one this Bot knows");+ });+});+describe("OpenBot Mastra listen port configuration", () => {const validPortCases: PortCase[] = [{ name: "absent", expected: 4213 },diff --git a/agent-mastra/src/mastra/index.ts b/agent-mastra/src/mastra/index.tsindex adf5366e..e64c69b1 100644--- a/agent-mastra/src/mastra/index.ts+++ b/agent-mastra/src/mastra/index.ts@@ -16,19 +16,47 @@ import { Agent } from "@mastra/core/agent";import { Mastra } from "@mastra/core/mastra";import { registerApiRoute } from "@mastra/core/server";import { listenPort } from "../../../shared/listen-port";+import {+ apiKeyOrPlaceholder,+ botSettings,+ providerSpec,+} from "../../../shared/model-providers";-async function configuredModel() {- const provider = process.env.BOT_PROVIDER?.trim() || "openai";- const model =- process.env.BOT_MODEL?.trim() ||- (provider === "anthropic" ? "claude-sonnet-4-5" : "gpt-4o-mini");- const baseVariable =- provider === "anthropic" ? "ANTHROPIC_BASE_URL" : "OPENAI_BASE_URL";+/** The providers this Bot can drive: the ones whose SDK modules it loads below. */+const SUPPORTED_PROVIDERS = new Set(["openai", "anthropic"]);++/**+ * The model this Bot answers with, read from the spec file rather than remembered in this file.+ *+ * `shared/model-providers.json` holds this Bot's `bots.agent-mastra` row and the provider facts+ * around it; `BOT_PROVIDER` and `BOT_MODEL` still win over both, as they always have. The file+ * says which providers exist; this file still decides which of them it can drive, because only two+ * SDK modules are loaded here. Both halves refuse at startup: a provider the file has not heard of,+ * and one it has that this harness has no module for, used to fall through to the OpenAI branch+ * below and answer with a model the deployment never chose.+ */+async function buildModel() {+ const settings = botSettings("agent-mastra");+ const providerName = settings.provider;+ const spec = providerSpec(providerName);+ if (!spec) {+ // What to use is what this harness answers on, which is narrower than the registry.+ throw new Error(+ `BOT_PROVIDER=${providerName} is not one this Bot knows. Use ${[...SUPPORTED_PROVIDERS].join(" or ")}.`,+ );+ }+ if (!SUPPORTED_PROVIDERS.has(spec.id)) {+ throw new Error(+ `BOT_PROVIDER=${providerName} names ${spec.label}, and this Bot loads no ${spec.label} module. It answers on OpenAI and Anthropic only.`,+ );+ }+ const model = settings.model;+ const baseVariable = spec.baseUrlVariable;const baseURL = process.env[baseVariable]?.trim();// Provider modules create default clients at import, which reject Compose's empty overrides.if (!baseURL) delete process.env[baseVariable];- if (provider === "anthropic") {+ if (spec.id === "anthropic") {const { createAnthropic } = await import("@ai-sdk/anthropic");// Other harnesses accept an Anthropic origin; AI SDK expects the /v1 API prefix.const origin = (baseURL || "https://api.anthropic.com").replace(/\/+$/, "");@@ -43,7 +71,7 @@ async function configuredModel() {const openai = createOpenAI({baseURL: baseURL || "https://api.openai.com/v1",apiKey: compatible- ? process.env.OPENAI_API_KEY?.trim() || "no-key-needed"+ ? apiKeyOrPlaceholder(process.env[spec.keyVariable]): undefined,});// Compatible endpoints commonly expose Chat Completions; OpenAI keeps its Responses default.@@ -110,7 +138,7 @@ const openbot = new Agent({id: "openbot",name: "openbot",instructions: buildOpenBotInstructions,- model: await configuredModel(),+ model: await buildModel(),});/** The one header OpenBot's server sends, compared without leaking length through timing. */diff --git a/agent-microsoft/Dockerfile b/agent-microsoft/Dockerfileindex 2c4d71c3..a740f7c7 100644--- a/agent-microsoft/Dockerfile+++ b/agent-microsoft/Dockerfile@@ -9,6 +9,7 @@ COPY agent-microsoft/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-microsoft/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4211EXPOSE 4211diff --git a/agent-microsoft/src/main.py b/agent-microsoft/src/main.pyindex 53e7190e..9f387050 100644--- a/agent-microsoft/src/main.py+++ b/agent-microsoft/src/main.py@@ -1,6 +1,13 @@"""Microsoft Agent Framework as a Bot, through `agent-framework-ag-ui`, which Microsoft publishes."""import os+import sys+from pathlib import Path++# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settingsfrom agent_framework.anthropic import AnthropicClientfrom agent_framework.openai import OpenAIChatClient@@ -17,8 +24,9 @@ def _client() -> AnthropicClient | OpenAIChatClient:`BOT_PROVIDER` is `anthropic` for an Anthropic key and `openai` otherwise, an OpenAI-compatibleendpoint included. Each client reads its own key from the environment."""- provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()- model = (os.environ.get("BOT_MODEL") or "gpt-4o-mini").strip()+ settings = bot_settings("agent-microsoft")+ provider = settings.provider+ model = settings.modelif provider == "anthropic":# Compose exports missing overrides as ""; the SDK only defaults an absent URL.base_url = (os.environ.get("ANTHROPIC_BASE_URL") or "").strip() or "https://api.anthropic.com"diff --git a/agent-microsoft/tests/test_model_spec.py b/agent-microsoft/tests/test_model_spec.pynew file mode 100644index 00000000..2e775bc4--- /dev/null+++ b/agent-microsoft/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-microsoft` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-microsoft"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-microsoft")' in sourcediff --git a/agent-pydantic-ai/Dockerfile b/agent-pydantic-ai/Dockerfileindex 6894de47..7cf74864 100644--- a/agent-pydantic-ai/Dockerfile+++ b/agent-pydantic-ai/Dockerfile@@ -9,6 +9,7 @@ COPY agent-pydantic-ai/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-pydantic-ai/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4205EXPOSE 4205diff --git a/agent-pydantic-ai/src/main.py b/agent-pydantic-ai/src/main.pyindex e46fdc17..b83c93ea 100644--- a/agent-pydantic-ai/src/main.py+++ b/agent-pydantic-ai/src/main.py@@ -5,6 +5,13 @@ carries its own ASGI app and there is nothing to bridge."""import os+import sys+from pathlib import Path++# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settingsfrom fastapi import FastAPI, Requestfrom fastapi.responses import JSONResponse@@ -21,8 +28,9 @@ def _model_id() -> str:other colon is part of the model's name: Ollama tags every model with one, as in `llama3.1:8b`,and Pydantic AI read the part before it as a provider, refused an unknown one and started no Bot."""- provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()- model = (os.environ.get("BOT_MODEL") or "gpt-4o-mini").strip()+ settings = bot_settings("agent-pydantic-ai")+ provider = settings.provider+ model = settings.modelreturn model if model.startswith(f"{provider}:") else f"{provider}:{model}"diff --git a/agent-pydantic-ai/tests/test_model_spec.py b/agent-pydantic-ai/tests/test_model_spec.pynew file mode 100644index 00000000..5e6f161b--- /dev/null+++ b/agent-pydantic-ai/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-pydantic-ai` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-pydantic-ai"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-pydantic-ai")' in sourcediff --git a/agent-strands/Dockerfile b/agent-strands/Dockerfileindex b0c10668..27ac341d 100644--- a/agent-strands/Dockerfile+++ b/agent-strands/Dockerfile@@ -9,6 +9,7 @@ COPY agent-strands/requirements.txt ./RUN pip install --no-cache-dir -r requirements.txtCOPY agent-strands/src ./src+COPY shared/model_providers.py shared/model-providers.json /shared/ENV PORT=4207EXPOSE 4207diff --git a/agent-strands/src/main.py b/agent-strands/src/main.pyindex 46275c23..d1d2f9eb 100644--- a/agent-strands/src/main.py+++ b/agent-strands/src/main.py@@ -1,6 +1,13 @@"""AWS Strands as a Bot, through `ag_ui_strands`, which AG-UI maintains."""import os+import sys+from pathlib import Path++# The spec file every language in the box reads: one level above this Bot in the repository, and+# one level above /app/src in the image the Dockerfile builds.+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import bot_settingsfrom ag_ui_strands import StrandsAgent, add_strands_fastapi_endpointfrom fastapi import FastAPI, Request@@ -20,8 +27,9 @@ def _model_id() -> str:and litellm then either routed to a provider nobody configured (`LLM Provider NOT provided`)or sent only the second half to the endpoint."""- provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()- model = (os.environ.get("BOT_MODEL") or "gpt-4o-mini").strip()+ settings = bot_settings("agent-strands")+ provider = settings.provider+ model = settings.modelreturn f"{provider}/{model}"diff --git a/agent-strands/tests/test_model_spec.py b/agent-strands/tests/test_model_spec.pynew file mode 100644index 00000000..6961425f--- /dev/null+++ b/agent-strands/tests/test_model_spec.py@@ -0,0 +1,37 @@+"""The spec file this Bot reads, pinned to what this repository decided.++`shared/model-providers.json` is one file every language in the box reads; this test is the row+for `agent-strands` and the order the Python loader applies it in. If the file changes on purpose, this+test changes with it — the review point the file exists to create.+"""++import sys+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "shared"))+from model_providers import BotSettings, bot_settings++BOT_ID = "agent-strands"+++def test_the_row_this_bot_runs(monkeypatch):+ monkeypatch.delenv("BOT_PROVIDER", raising=False)+ monkeypatch.delenv("BOT_MODEL", raising=False)+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_environment_beats_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "anthropic")+ monkeypatch.setenv("BOT_MODEL", "claude-haiku")+ assert bot_settings(BOT_ID) == BotSettings(provider="anthropic", model="claude-haiku")+++def test_blank_environment_falls_through_to_the_file(monkeypatch):+ monkeypatch.setenv("BOT_PROVIDER", "")+ monkeypatch.setenv("BOT_MODEL", " ")+ assert bot_settings(BOT_ID) == BotSettings(provider="openai", model="gpt-4o-mini")+++def test_this_bots_source_reads_the_spec():+ source = (Path(__file__).resolve().parents[1] / "src" / "main.py").read_text(encoding="utf-8")+ assert f'bot_settings("agent-strands")' in sourcediff --git a/docker-compose.yml b/docker-compose.ymlindex 5cd73aac..735c08b1 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -321,6 +321,8 @@ services:OPENAI_BASE_URL: ${OPENAI_CONTAINER_BASE_URL:-${OPENAI_BASE_URL:-}}ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}ANTHROPIC_BASE_URL: ${ANTHROPIC_BASE_URL:-}+ GOOGLE_API_KEY: ${GOOGLE_API_KEY:-}+ GOOGLE_GENERATIVE_AI_BASE_URL: ${GOOGLE_GENERATIVE_AI_BASE_URL:-}BOT_PROVIDER: ${BOT_PROVIDER:-openai}CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}# A path into the mount below, set only when a ChatGPT plan was signed in to. The file is@@ -362,9 +364,13 @@ services:ANTHROPIC_BASE_URL: ${ANTHROPIC_BASE_URL:-}GOOGLE_API_KEY: ${GOOGLE_API_KEY:-}GOOGLE_GENERATIVE_AI_BASE_URL: ${GOOGLE_GENERATIVE_AI_BASE_URL:-}- # gpt-5.5, to stay comparable with agent-bot above rather than because 5.6 does not work:- # set BOT_MODEL to one and the Responses API is switched on for it automatically.- BOT_MODEL: ${BOT_MODEL:-gpt-5.5}+ # Unset, this Bot takes the spec file's row for its model rather than this line+ # substituting gpt-5.5 whatever BOT_PROVIDER named — a provider other than OpenAI was+ # handed that substitute and then failed at its own vendor on it. The file's OpenAI row is+ # the same gpt-5.5 as before, so an OpenAI deployment answers on the model it always did;+ # BOT_MODEL still wins when it is set, and a 5.6 tier named there switches the Responses+ # API on by itself below.+ BOT_MODEL: ${BOT_MODEL:-}BOT_RESPONSES_API: ${BOT_RESPONSES_API:-false}# How hard it thinks, on a model that reasons. Empty leaves the provider's own default.BOT_REASONING_EFFORT: ${BOT_REASONING_EFFORT:-}diff --git a/docs/configuration.md b/docs/configuration.mdindex 3d1df1ac..8aad6ec4 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -48,12 +48,12 @@ at `agent-langgraph` on a laptop.| `DEPLOYMENT_ID` | the tenant package's id | Names this deployment inside a shared Intelligence project. || `OPENAI_API_KEY` | unset | Default model key for built-in agents and both shipped Bots. || `OPENAI_BASE_URL` | unset | OpenAI-compatible endpoint that key is spent against. See below. |-| `BOT_PROVIDER` | `openai` | Provider for `agent-langgraph`: `openai`, `anthropic`, or `google`. |+| `BOT_PROVIDER` | `openai` | Provider the framework Bot (`agent-langgraph`) and the picked harness run on: `openai`, `anthropic`, or `google`. The Python Bots read it too; `agent-bot` does not, it is OpenAI only. || `ANTHROPIC_API_KEY` | unset | Anthropic key when `BOT_PROVIDER=anthropic`. || `ANTHROPIC_BASE_URL` | unset | Anthropic-compatible endpoint that key is spent against. || `GOOGLE_API_KEY` | unset | Google key when `BOT_PROVIDER=google`. || `GOOGLE_GENERATIVE_AI_BASE_URL` | unset | Google-compatible endpoint that key is spent against. |-| `BOT_MODEL` | provider default from Bot code/env | Model for the framework Bot (`agent-langgraph`). Provider defaults are `gpt-5.5`, `claude-sonnet-4-5`, and `gemini-2.5-flash`. |+| `BOT_MODEL` | the Bot's row in the spec file | Model for whichever Bot is starting. Unset, it comes from that Bot's row in [the provider spec file](#the-provider-spec-file); the provider fallbacks are `gpt-5.5`, `claude-sonnet-4-5`, and `gemini-2.5-flash`. || `AGENT_BOT_MODEL` | `gpt-5.5` | Model for the proof-of-concept Bot (`agent-bot`), kept separate because it speaks `/v1/chat/completions` directly and refuses a model it cannot use. || `BOT_RESPONSES_API` | `false` | Makes `agent-langgraph` use the OpenAI Responses API. || `BOT_REASONING_EFFORT` | unset (provider default) | OpenAI and the Responses API only: one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. `agent-langgraph` refuses to start on any other value, on a non-`openai` provider, or without the Responses API. |@@ -128,6 +128,63 @@ where the worker runs rather than a fact about the deployment `loadConfig` descrit at the server's own port on a laptop; the Helm chart's routines CronJob points it at the server'sin-cluster Service address.+## The provider spec file++`shared/model-providers.json` is one file, and every language in the box reads it: the TypeScript+Bots through `shared/model-providers.ts`, the Python Bots through `shared/model_providers.py`, and+any other implementation straight as JSON. It has two sections — the facts per provider, and the+provider and model each Bot runs:++```json+{+ "providers": {+ "openai": {+ "label": "OpenAI",+ "key_variable": "OPENAI_API_KEY",+ "base_url_variable": "OPENAI_BASE_URL",+ "default_model": "gpt-5.5"+ }+ },+ "bots": {+ "agent-langgraph": { "provider": "openai", "model": "gpt-5.5" },+ "agent-adk": { "provider": "openai", "model": "gpt-4o-mini" }+ }+}+```++The lookup order for `BOT_PROVIDER` and `BOT_MODEL` is unchanged, and the file sits in the middle+of it:++1. the environment — how a deployment overrides what the repository decided;+2. the Bot's row in this file — what the repository decided;+3. the provider's `default_model` — what is left when neither says.++Each Bot retains its existing default: for example, `agent-mastra` uses `gpt-4o-mini`, while+`agent-langgraph` uses `gpt-5.5`. Editing a Bot's row changes that Bot's default without changing+another Bot's choice. The Python LangGraph harness also accepts `BOT_PROVIDER=google_genai` as an+alias for the spec's `google` provider.++A blank value is read as unset, which is what a compose file passing `${BOT_MODEL:-}` hands a Bot+when nobody chose a model. API keys never appear in the file: they arrive in the environment+under the `key_variable` the provider row names.++Adding a Bot in any language is adding one `bots` entry — `"agent-java": { "provider":+"anthropic", "model": "claude-sonnet-4-5" }` — after which that Bot resolves its model the same+way everything else does. A row that names a provider no `providers` entry exists for, or leaves a+field empty, stops every Bot at startup with the path of the key that is wrong, rather than at the+first model call.++Adding a **provider** is three places rather than one: a row under `providers` here, one entry to+`PROVIDER_IDS` in `shared/model-providers.ts`, and one entry to `PROVIDER_IDS` in+`shared/model_providers.py`. Each loader checks this file against its own list in both+directions, so neither the Python Bots nor the TypeScript ones start against a provider row their+own loader has never heard of, nor against a provider their own loader names when the file has no+row for it. Either refusal names the key that is wrong, at startup rather than at the first model+call, in either language.++`agent-bot` is the one Bot that pins its provider: it speaks `/v1/chat/completions` directly and+has never read `BOT_PROVIDER`, and `bots.agent-bot` supplies only its model.+## OpenAI-compatible endpoints`OPENAI_BASE_URL` decides where an OpenAI-shaped request is answered. Unset, that is OpenAI. Set, it is any endpoint speaking the same API: a gateway in front of several providers, a proxy, or a model on hardware you control.diff --git a/shared/model-providers.json b/shared/model-providers.jsonnew file mode 100644index 00000000..58b2c678--- /dev/null+++ b/shared/model-providers.json@@ -0,0 +1,38 @@+{+ "_readme": "One file every language reads. providers = facts per provider (key variable, endpoint variable, default model). bots = which provider and model each Bot runs when its environment names none; API keys never live here. Environment beats this file: BOT_PROVIDER and BOT_MODEL still win. Adding a provider is one row here plus one entry to PROVIDER_IDS in each of shared/model-providers.ts and shared/model_providers.py: each loader checks this file against its own list in both directions, so a Bot never starts against a provider row its own loader has not heard of. See docs/configuration.md, 'The provider spec file'.",+ "providers": {+ "openai": {+ "label": "OpenAI",+ "key_variable": "OPENAI_API_KEY",+ "base_url_variable": "OPENAI_BASE_URL",+ "default_model": "gpt-5.5"+ },+ "anthropic": {+ "label": "Anthropic",+ "key_variable": "ANTHROPIC_API_KEY",+ "base_url_variable": "ANTHROPIC_BASE_URL",+ "default_model": "claude-sonnet-4-5"+ },+ "google": {+ "label": "Google",+ "key_variable": "GOOGLE_API_KEY",+ "base_url_variable": "GOOGLE_GENERATIVE_AI_BASE_URL",+ "default_model": "gemini-2.5-flash"+ }+ },+ "bots": {+ "agent-bot": { "provider": "openai", "model": "gpt-5.5" },+ "agent-langgraph": { "provider": "openai", "model": "gpt-5.5" },+ "agent-mastra": { "provider": "openai", "model": "gpt-4o-mini" },+ "agent-adk": { "provider": "openai", "model": "gpt-4o-mini" },+ "agent-ag2": { "provider": "openai", "model": "gpt-4o-mini" },+ "agent-agno": { "provider": "openai", "model": "gpt-5.5" },+ "agent-crewai": { "provider": "openai", "model": "gpt-5.5" },+ "agent-langgraph-agui": { "provider": "openai", "model": "gpt-4o-mini" },+ "agent-langroid": { "provider": "openai", "model": "gpt-4o-mini" },+ "agent-llamaindex": { "provider": "openai", "model": "gpt-5.5" },+ "agent-microsoft": { "provider": "openai", "model": "gpt-4o-mini" },+ "agent-pydantic-ai": { "provider": "openai", "model": "gpt-4o-mini" },+ "agent-strands": { "provider": "openai", "model": "gpt-4o-mini" }+ }+}diff --git a/shared/model-providers.test.ts b/shared/model-providers.test.tsnew file mode 100644index 00000000..6f42fde3--- /dev/null+++ b/shared/model-providers.test.ts@@ -0,0 +1,321 @@+import { describe, expect, test } from "bun:test";+import {+ MODEL_PROVIDERS,+ PROVIDER_IDS,+ apiKeyOrPlaceholder,+ baseUrlVariableFor,+ botSettings,+ configuredModel,+ defaultModelFor,+ keyIsRequired,+ keyVariableFor,+ providerSpec,+ requiresResponsesApi,+} from "./model-providers";++/**+ * The table is the contract, so its rows are written down.+ *+ * Every one of these values is read out of a `process.env` name or sent to a provider as a model+ * name; changing one silently retargets a running Bot. They are pinned here because they were the+ * thing that drifted — five files, five default OpenAI models — and a registry that can drift the+ * same way inside its own file has only moved the bug.+ */+describe("the provider registry", () => {+ test("each provider names the variable its key arrives in", () => {+ expect(MODEL_PROVIDERS.openai.keyVariable).toBe("OPENAI_API_KEY");+ expect(MODEL_PROVIDERS.anthropic.keyVariable).toBe("ANTHROPIC_API_KEY");+ expect(MODEL_PROVIDERS.google.keyVariable).toBe("GOOGLE_API_KEY");+ });++ test("each provider names the variable its endpoint override arrives in", () => {+ expect(MODEL_PROVIDERS.openai.baseUrlVariable).toBe("OPENAI_BASE_URL");+ expect(MODEL_PROVIDERS.anthropic.baseUrlVariable).toBe(+ "ANTHROPIC_BASE_URL",+ );+ expect(MODEL_PROVIDERS.google.baseUrlVariable).toBe(+ "GOOGLE_GENERATIVE_AI_BASE_URL",+ );+ });++ test("each provider has a model to run when none was configured", () => {+ expect(MODEL_PROVIDERS.openai.defaultModel).toBe("gpt-5.5");+ expect(MODEL_PROVIDERS.anthropic.defaultModel).toBe("claude-sonnet-4-5");+ expect(MODEL_PROVIDERS.google.defaultModel).toBe("gemini-2.5-flash");+ });++ test("each provider has a name to be refused by", () => {+ expect(MODEL_PROVIDERS.openai.label).toBe("OpenAI");+ expect(MODEL_PROVIDERS.anthropic.label).toBe("Anthropic");+ expect(MODEL_PROVIDERS.google.label).toBe("Google");+ });+});++/** Which provider was meant, and whether a name nobody has heard of is said out loud. */+describe("which provider was configured", () => {+ test("the three names the Bots accept resolve", () => {+ expect(providerSpec("openai")?.id).toBe("openai");+ expect(providerSpec("anthropic")?.id).toBe("anthropic");+ expect(providerSpec("google")?.id).toBe("google");+ });++ /**+ * Blank means OpenAI everywhere else that reads `BOT_PROVIDER`: the desktop writes an empty+ * provider when switching back to OpenAI, the server reads empty as OpenAI.+ */+ test("no provider named means OpenAI", () => {+ expect(providerSpec(undefined)?.id).toBe("openai");+ expect(providerSpec("")?.id).toBe("openai");+ expect(providerSpec(" ")?.id).toBe("openai");+ });++ /** Padded and differently-cased names are the same provider, the way `BOT_MODEL` is trimmed. */+ test("casing and padding are not a different provider", () => {+ expect(providerSpec(" OpenAI ")?.id).toBe("openai");+ expect(providerSpec("ANTHROPIC")?.id).toBe("anthropic");+ expect(providerSpec("Google")?.id).toBe("google");+ });++ /**+ * Answering "openai" for a name nobody has heard of is how a Bot silently falls into the OpenAI+ * branch; an unknown provider has to stay unknown so the Bot can name what went wrong.+ */+ test("a provider nobody has heard of does not become OpenAI", () => {+ expect(providerSpec("mistral")).toBeUndefined();+ expect(providerSpec("open-ai")).toBeUndefined();+ expect(keyVariableFor("mistral")).toBeUndefined();+ expect(baseUrlVariableFor("mistral")).toBeUndefined();+ });++ test("the key and endpoint variables come from the row", () => {+ expect(keyVariableFor("anthropic")).toBe("ANTHROPIC_API_KEY");+ expect(baseUrlVariableFor("google")).toBe("GOOGLE_GENERATIVE_AI_BASE_URL");+ expect(keyVariableFor(undefined)).toBe("OPENAI_API_KEY");+ });+});++/**+ * A named endpoint is a model, and its key belongs to it.+ *+ * The failure this pins: the setup window's "any OpenAI-compatible endpoint" row takes an address+ * with no key, because Ollama and vLLM have none. The Bots then refused to start, saying+ * OPENAI_API_KEY was not set, so the whole keyless half of that feature produced a dead container+ * and a red line on the last screen about a key the person's own server does not have.+ */+describe("whether a model key is required", () => {+ test("plain OpenAI still needs its key", () => {+ expect(keyIsRequired("openai", undefined)).toBe(true);+ expect(keyIsRequired("openai", "")).toBe(true);+ expect(keyIsRequired("openai", " ")).toBe(true);+ expect(keyIsRequired(undefined, undefined)).toBe(true);+ expect(keyIsRequired("", "")).toBe(true);+ });++ test("an endpoint named instead of OpenAI answers without one", () => {+ expect(keyIsRequired("openai", "http://127.0.0.1:11434/v1")).toBe(false);+ expect(keyIsRequired(undefined, "http://127.0.0.1:11434/v1")).toBe(false);+ });++ /** Neither of the other providers has a base URL to be named by, so neither changes. */+ test("anthropic and google are unchanged", () => {+ expect(keyIsRequired("anthropic", "http://127.0.0.1:11434/v1")).toBe(true);+ expect(keyIsRequired("google", "http://127.0.0.1:11434/v1")).toBe(true);+ });++ /** The SDK cannot be constructed with an empty string, so there is always something to pass. */+ test("the SDK is always handed a string", () => {+ expect(apiKeyOrPlaceholder(undefined)).toBe("no-key-needed");+ expect(apiKeyOrPlaceholder(" ")).toBe("no-key-needed");+ expect(apiKeyOrPlaceholder("sk-real")).toBe("sk-real");+ });+});++/**+ * Which model a Bot runs: what was configured, or its provider's default when it was not.+ *+ * Blank is not configured — a compose file passing `BOT_MODEL: ${BOT_MODEL:-}` hands an empty+ * string, and sending that on would ask a provider for a model named "".+ */+describe("which model this Bot was told to use", () => {+ test("an unset or empty choice falls back to the provider's default", () => {+ expect(configuredModel("openai", undefined)).toBe("gpt-5.5");+ expect(configuredModel("openai", "")).toBe("gpt-5.5");+ expect(configuredModel("openai", " ")).toBe("gpt-5.5");+ expect(configuredModel("anthropic", undefined)).toBe("claude-sonnet-4-5");+ expect(configuredModel("google", "")).toBe("gemini-2.5-flash");+ });++ /** An unknown provider has no default of its own; the Bot refuses it on its own a line later. */+ test("an unknown provider still has a model to be refused with", () => {+ expect(defaultModelFor("mistral")).toBe("gpt-5.5");+ expect(configuredModel("mistral", undefined)).toBe("gpt-5.5");+ });++ test("a padded name is the name", () => {+ expect(configuredModel("openai", " gpt-5.5 ")).toBe("gpt-5.5");+ expect(configuredModel("anthropic", "claude-sonnet-4-5")).toBe(+ "claude-sonnet-4-5",+ );+ });++ /** A configured model wins over the provider's default; that is the whole point of configuring. */+ test("a configured model is run, whatever the default says", () => {+ expect(configuredModel("openai", "gpt-4o-mini")).toBe("gpt-4o-mini");+ expect(configuredModel("anthropic", "claude-3-5-haiku")).toBe(+ "claude-3-5-haiku",+ );+ });+});++/**+ * The models that cannot be driven through chat completions, and the ones that can.+ *+ * `gpt-5.6-*` rejects function tools on `/v1/chat/completions`; which question a Bot asks of+ * this predicate — refuse the model, or turn on the Responses API — belongs to the Bot.+ */+describe("whether a model has to be driven through the Responses API", () => {+ test("the models that reject tools on chat completions are flagged", () => {+ expect(requiresResponsesApi("gpt-5.6-terra")).toBe(true);+ expect(requiresResponsesApi("gpt-6")).toBe(true);+ expect(requiresResponsesApi("gpt-5.5")).toBe(false);+ });++ test("padding does not get one past the guard", () => {+ expect(+ requiresResponsesApi(configuredModel("openai", " gpt-5.6-terra")),+ ).toBe(true);+ expect(requiresResponsesApi(configuredModel("openai", "\tgpt-6 "))).toBe(+ true,+ );+ });++ test("other providers' models are not OpenAI's problem", () => {+ expect(requiresResponsesApi("claude-sonnet-4-5")).toBe(false);+ expect(requiresResponsesApi("gemini-2.5-flash")).toBe(false);+ });+});++/**+ * The spec file, and the one lookup order it sits in.+ *+ * `shared/model-providers.json` is the file every language in the box reads; this module is its+ * TypeScript loader. These tests pin the order the loader applies — environment, then file, then+ * provider default — because that order is what `docs/configuration.md` promises and what a+ * developer in any other language is entitled to expect from their own loader too.+ */+describe("what a Bot runs from the spec file", () => {+ /** The shipped Bots, each at the row the file holds for it. */+ test("a Bot with an environment that names nothing runs its file row", () => {+ expect(botSettings("agent-bot", {})).toEqual({+ provider: "openai",+ model: "gpt-5.5",+ });+ expect(botSettings("agent-langgraph", {})).toEqual({+ provider: "openai",+ model: "gpt-5.5",+ });+ expect(botSettings("agent-mastra", {})).toEqual({+ provider: "openai",+ model: "gpt-4o-mini",+ });+ // A Bot the file pairs with a different model than the provider's own default:+ expect(botSettings("agent-adk", {})).toEqual({+ provider: "openai",+ model: "gpt-4o-mini",+ });+ expect(botSettings("agent-crewai", {})).toEqual({+ provider: "openai",+ model: "gpt-5.5",+ });+ });++ /** The environment is how a deployment overrides the repository; it wins over the file. */+ test("the environment beats the file", () => {+ expect(botSettings("agent-adk", { BOT_MODEL: "gpt-4.1" })).toEqual({+ provider: "openai",+ model: "gpt-4.1",+ });+ expect(+ botSettings("agent-adk", {+ BOT_PROVIDER: "anthropic",+ BOT_MODEL: "claude-haiku",+ }),+ ).toEqual({ provider: "anthropic", model: "claude-haiku" });+ expect(+ botSettings("agent-langgraph", { BOT_PROVIDER: " Google " }),+ ).toEqual({ provider: "google", model: "gemini-2.5-flash" });+ });++ /**+ * A blank variable is not a choice. Compose hands `BOT_MODEL: ${BOT_MODEL:-}` an empty string+ * when nobody picked a model, and the desktop writes an empty provider when switching back to+ * OpenAI; both mean "no opinion", and the file answers.+ */+ test("a blank environment value falls through to the file", () => {+ expect(+ botSettings("agent-adk", { BOT_PROVIDER: "", BOT_MODEL: "" }),+ ).toEqual({ provider: "openai", model: "gpt-4o-mini" });+ expect(botSettings("agent-adk", { BOT_MODEL: " " })).toEqual({+ provider: "openai",+ model: "gpt-4o-mini",+ });+ });++ /**+ * The file's model belongs to the file's provider.+ *+ * A deployment that moved this Bot to Anthropic gets Anthropic's default rather than the+ * OpenAI model the file pairs with the provider it left — sending `gpt-4o-mini` to Anthropic+ * would be a model name neither side chose.+ */+ test("a provider from the environment takes that provider's default", () => {+ expect(botSettings("agent-adk", { BOT_PROVIDER: "anthropic" })).toEqual({+ provider: "anthropic",+ model: "claude-sonnet-4-5",+ });+ });++ /**+ * A pinned provider is a Bot answering to one name only.+ *+ * `agent-bot` speaks chat completions by hand and has never read `BOT_PROVIDER`; pinning keeps+ * that true while the model still comes from the file.+ */+ test("a pinned Bot ignores the provider environment it never read", () => {+ expect(+ botSettings("agent-bot", { BOT_PROVIDER: "anthropic" }, "openai"),+ ).toEqual({ provider: "openai", model: "gpt-5.5" });+ expect(+ botSettings("agent-bot", { BOT_MODEL: " gpt-4.1 " }, "openai"),+ ).toEqual({ provider: "openai", model: "gpt-4.1" });+ });++ /** A name nobody has heard of is kept, so the Bot's own refusal can put it in the message. */+ test("an unknown provider stays unknown, with a model to be refused with", () => {+ expect(+ botSettings("agent-langgraph", { BOT_PROVIDER: " Mistral " }),+ ).toEqual({ provider: "mistral", model: "gpt-5.5" });+ });++ /** A Bot wired to the file without a row in it is a mistake made in this repository. */+ test("a Bot with no row in the file is refused at startup", () => {+ expect(() => botSettings("agent-java")).toThrow(+ /bots has no agent-java entry/,+ );+ });++ /**+ * The type and the file cannot drift apart.+ *+ * `PROVIDER_IDS` is what TypeScript believes; the file is what every other language reads.+ * Either missing the other stops the process here rather than in a language with no opinion.+ */+ test("the file carries a row for every provider the type names", () => {+ for (const id of PROVIDER_IDS) {+ expect(MODEL_PROVIDERS[id].id).toBe(id);+ }+ expect(Object.keys(MODEL_PROVIDERS).sort()).toEqual(+ [...PROVIDER_IDS].sort(),+ );+ });+});diff --git a/shared/model-providers.ts b/shared/model-providers.tsnew file mode 100644index 00000000..ab1ca34d--- /dev/null+++ b/shared/model-providers.ts@@ -0,0 +1,318 @@+/**+ * The facts every Bot shares about the model providers it may be pointed at.+ *+ * One entry per provider, rather than the same default model, key variable and base URL variable+ * written out in each Bot. They were written out in each Bot, and they drifted: five files, five+ * different default OpenAI models, the first time somebody changed one of them in one place only.+ * A provider is added here; the Bots that speak its SDK take their names from this table.+ *+ * THE VALUES LIVE IN `model-providers.json`, beside this file. That file is the contract every+ * language in the box reads — TypeScript and Python through the loaders beside it, any other+ * language straight as JSON — so a developer adding a Bot in Java adds one entry there and never+ * reads this module. What the two loaders add to the file is types and validation: in either+ * loader, a row missing a field, a provider row the file lacks, a provider row that loader's list+ * has never heard of, or a `bots` entry naming a provider outside that list, stops the process at+ * startup with the path of the offending key rather than at the first model call.+ *+ * ENVIRONMENT BEATS FILE. `BOT_PROVIDER` and `BOT_MODEL` still win, exactly as+ * `docs/configuration.md` has always described; the file supplies what they leave unset. API keys+ * never appear in the file — they arrive in the environment under the `key_variable` the provider+ * row names.+ *+ * Facts only. Which provider a Bot can DRIVE is that Bot's own decision, beside the code that+ * loads its SDK: this module knows Google exists and what its key is called, and `agent-mastra`+ * still refuses it because it loads no Google module. Keeping the two apart is what lets a new+ * provider be registered here without pretending every harness can answer for it. The `bots`+ * section records what a Bot runs by default, not what it is able to drive.+ *+ * Its own module for the reason `model-key.ts` had to be one: `agent-bot` and `agent-langgraph`+ * call `serve()` at module scope, so importing a pure function from an entry point binds a port.+ */++import specJson from "./model-providers.json";++/**+ * The providers this deployment knows the names of.+ *+ * Adding one is one entry here, one in `PROVIDER_IDS` in `shared/model_providers.py`, and one row+ * to the JSON file. Each loader checks the file against its own list in both directions, so a+ * provider row this list names and the file lacks, or a row in the file this list has never heard+ * of, stops this Bot at startup rather than at its first model call.+ */+export const PROVIDER_IDS = ["openai", "anthropic", "google"] as const;++export type ModelProviderId = (typeof PROVIDER_IDS)[number];++export type ProviderSpec = {+ readonly id: ModelProviderId;+ /** How the provider is named in an error message. */+ readonly label: string;+ /** The environment variable its API key arrives in. */+ readonly keyVariable: string;+ /** The environment variable an endpoint override for it arrives in. */+ readonly baseUrlVariable: string;+ /** What a Bot uses when it is told a provider and no model. */+ readonly defaultModel: string;+};++/** A row as `model-providers.json` writes it: snake_case, because every language reads it. */+type SpecProviderRow = {+ readonly label?: unknown;+ readonly key_variable?: unknown;+ readonly base_url_variable?: unknown;+ readonly default_model?: unknown;+};++/** What the file says a Bot runs when its environment names nothing. */+type SpecBotRow = {+ readonly provider?: unknown;+ readonly model?: unknown;+};++type SpecFile = {+ readonly providers?: Readonly<Record<string, SpecProviderRow | undefined>>;+ readonly bots?: Readonly<Record<string, SpecBotRow | undefined>>;+};++function fail(problem: string): never {+ throw new Error(`shared/model-providers.json: ${problem}`);+}++function requireText(value: unknown, where: string): string {+ if (typeof value !== "string" || !value.trim()) {+ fail(`${where} must be a non-empty string.`);+ }+ return value;+}++/**+ * The file, checked. Every read below is of a row this function has already seen.+ *+ * Checked once, at module load, because the failure it reports is a mistake in the repository+ * rather than in a deployment: a hand editing the JSON wrong should stop every Bot at startup+ * with the key they got wrong, not send one Bot to a model named by a typo.+ */+function readSpec(): {+ providers: Record<ModelProviderId, ProviderSpec>;+ bots: Record<string, { provider: ModelProviderId; model: string }>;+} {+ const spec = specJson as SpecFile;++ const providers = {} as Record<ModelProviderId, ProviderSpec>;+ for (const id of PROVIDER_IDS) {+ const row = spec.providers?.[id];+ if (!row) fail(`providers is missing its ${id} row.`);+ providers[id] = {+ id,+ label: requireText(row.label, `providers.${id}.label`),+ keyVariable: requireText(+ row.key_variable,+ `providers.${id}.key_variable`,+ ),+ baseUrlVariable: requireText(+ row.base_url_variable,+ `providers.${id}.base_url_variable`,+ ),+ defaultModel: requireText(+ row.default_model,+ `providers.${id}.default_model`,+ ),+ };+ }+ for (const id of Object.keys(spec.providers ?? {})) {+ if (!(PROVIDER_IDS as readonly string[]).includes(id)) {+ fail(`providers has a ${id} row this module has never heard of.`);+ }+ }++ const bots: Record<string, { provider: ModelProviderId; model: string }> = {};+ for (const [botId, entry] of Object.entries(spec.bots ?? {})) {+ if (!entry) fail(`bots.${botId} must be an object.`);+ const provider = requireText(entry.provider, `bots.${botId}.provider`);+ if (!(PROVIDER_IDS as readonly string[]).includes(provider)) {+ fail(+ `bots.${botId}.provider is ${JSON.stringify(provider)}, not one of ${PROVIDER_IDS.join(", ")}.`,+ );+ }+ bots[botId] = {+ provider: provider as ModelProviderId,+ model: requireText(entry.model, `bots.${botId}.model`),+ };+ }++ return { providers, bots };+}++const { providers: SPEC_PROVIDERS, bots: BOT_ENTRIES } = readSpec();++export const MODEL_PROVIDERS: Record<ModelProviderId, ProviderSpec> =+ SPEC_PROVIDERS;++/**+ * The provider somebody configured, or nothing if they named one nobody has heard of.+ *+ * Blank means OpenAI, because that is what every other reader of `BOT_PROVIDER` already decided:+ * the desktop writes an empty provider when switching back to OpenAI, the server reads empty as+ * OpenAI, and a compose file passing `${BOT_PROVIDER:-}` hands the variable an empty string rather+ * than no variable at all. A Bot that refused that would disagree with the screen that configured+ * it.+ *+ * Padded and differently-cased names are the same provider, for the same reason `BOT_MODEL` is+ * trimmed before it is used: a value somebody typed into a setup window arrives with a space on+ * it more often than not. A Bot that has to report which provider was named gets `undefined` here+ * and shows the raw value in its own message.+ */+export function providerSpec(+ provider: string | undefined,+): ProviderSpec | undefined {+ const normalized = provider?.trim().toLowerCase() || "openai";+ return MODEL_PROVIDERS[normalized as ModelProviderId];+}++/** The environment variable this provider's key arrives in, or nothing for a provider unknown. */+export function keyVariableFor(+ provider: string | undefined,+): string | undefined {+ return providerSpec(provider)?.keyVariable;+}++/** The environment variable an endpoint override for this provider arrives in. */+export function baseUrlVariableFor(+ provider: string | undefined,+): string | undefined {+ return providerSpec(provider)?.baseUrlVariable;+}++/**+ * What this Bot runs when it was told a provider and no usable model.+ *+ * An unknown provider falls back to the OpenAI default rather than refusing here, because the+ * Bots validate the provider themselves and their error message is the one that should name what+ * went wrong. This function is asked before that check runs.+ */+export function defaultModelFor(provider: string | undefined): string {+ return (+ providerSpec(provider)?.defaultModel ?? MODEL_PROVIDERS.openai.defaultModel+ );+}++/**+ * The model this Bot runs: what was configured, or the provider's default when it was not.+ *+ * Blank is not configured. A compose file passing `BOT_MODEL: ${BOT_MODEL:-}` hands this an empty+ * string, and a Bot that sent it on would ask its provider for a model named "" and die with+ * "you must provide a model parameter", which reads as a broken Bot rather than as missing+ * configuration.+ */+export function configuredModel(+ provider: string | undefined,+ configured: string | undefined,+): string {+ return configured?.trim() || defaultModelFor(provider);+}++/** What one Bot was decided to run: its provider, and the model on it. */+export type BotSettings = {+ /** The provider this Bot answers on. */+ readonly provider: string;+ /** The model it runs. */+ readonly model: string;+};++/**+ * This Bot's provider and model: environment over spec file over provider default.+ *+ * The lookup order is the whole contract, and it is the order `docs/configuration.md` already+ * documents for `BOT_PROVIDER` and `BOT_MODEL` — the environment is how a deployment overrides+ * what the repository decided, so it wins. What is new is the middle: `model-providers.json`'s+ * `bots` entry, the default this Bot had before this function existed, written down in one file+ * every language in the box reads instead of repeated in each Bot's source. What is unchanged is+ * the last: the provider's own default row, for a provider whose Bot entry the file pairs with+ * somebody else.+ *+ * `pinnedProvider` is for a Bot that drives exactly one provider's API and answers to no other+ * name — `agent-bot` speaks chat completions by hand and has never read `BOT_PROVIDER`. Pinning+ * keeps that Bot's behavior what it was while its model still comes from the file.+ *+ * A provider nobody has heard of is kept as typed, not rewritten to OpenAI, so the Bot's own+ * refusal can put the name in its message. Its model falls back to the OpenAI default for the+ * same reason `defaultModelFor` does it: the refusal is one line below and belongs to the Bot.+ *+ * A missing `bots` entry throws rather than defaults. The file is in this repository; a Bot wired+ * to it without a row is a mistake made while editing it, made at development time, and the+ * developer should meet it at startup rather than wonder why every deployment answers on+ * gpt-5.5.+ */+export function botSettings(+ botId: string,+ env: Readonly<Record<string, string | undefined>> = process.env,+ pinnedProvider?: string,+): BotSettings {+ const entry = BOT_ENTRIES[botId];+ if (!entry) {+ fail(+ `bots has no ${botId} entry. Add one before this Bot reads the spec file.`,+ );+ }++ const provider =+ pinnedProvider?.trim() ||+ (env.BOT_PROVIDER ?? "").trim().toLowerCase() ||+ entry.provider;++ // A model the environment names goes to whatever provider was resolved, because an endpoint+ // names its own catalogue. The file's model belongs to the file's provider, so a deployment+ // that moved this Bot to another provider gets that provider's default instead of a model+ // paired with the one it left.+ const model =+ env.BOT_MODEL?.trim() ||+ (provider === entry.provider ? entry.model : defaultModelFor(provider));++ return { provider, model };+}++/**+ * Whether this model has to be driven through the Responses API.+ *+ * `gpt-5.6-*` rejects function tools on `/v1/chat/completions` — "To use function tools, use+ * /v1/responses or set reasoning_effort to 'none'" — so a Bot that speaks chat completions by hand+ * cannot use it, and a Bot whose integration offers the Responses API has to turn it on. The same+ * predicate answers both questions; which question is asked belongs to the Bot.+ *+ * Named for the fact rather than for either consequence, because `agent-bot` uses it to refuse a+ * model and `agent-langgraph` uses it to select a flag, and neither name fits both.+ */+export function requiresResponsesApi(model: string): boolean {+ return /^gpt-5\.[6-9]|^gpt-[6-9]/.test(model);+}++/**+ * Whether this Bot must hold this provider's key before it can start.+ *+ * Not when an endpoint was named to answer instead. `OPENAI_BASE_URL` set means any endpoint+ * speaking that API, and Ollama, vLLM, LM Studio and llama.cpp all serve it with no key. The+ * setup window offers exactly those by name and accepts a blank key for them, so requiring one+ * refused the whole keyless half of that feature: somebody filled in an address, the app raised+ * the Bot, and it exited on startup complaining about a key their endpoint does not have.+ *+ * Only OpenAI has a base URL that means "somebody else's server"; Anthropic and Google are asked+ * with their own variable so the rule can grow without a second signature.+ */+export function keyIsRequired(+ provider: string | undefined,+ baseUrl: string | undefined,+): boolean {+ const named =+ providerSpec(provider)?.id === "openai" && Boolean(baseUrl?.trim());+ return !named;+}++/**+ * What to hand an SDK that insists on a string even when the endpoint ignores it.+ *+ * A placeholder rather than an empty string: empty is a client that cannot be constructed, and+ * the value is never sent anywhere that reads it when the endpoint needs no key.+ */+export function apiKeyOrPlaceholder(apiKey: string | undefined): string {+ return apiKey?.trim() || "no-key-needed";+}diff --git a/shared/model_providers.py b/shared/model_providers.pynew file mode 100644index 00000000..7345a0b5--- /dev/null+++ b/shared/model_providers.py@@ -0,0 +1,179 @@+"""The provider facts every Bot shares, read from `model-providers.json`.++The file beside this loader is the contract every language in the box reads: TypeScript reads it+through `shared/model-providers.ts`, this module reads it for the Python Bots, and any other+language reads it straight as JSON. A developer adding a Bot in Java adds one `bots` entry to the+file and never reads either loader.++ENVIRONMENT BEATS FILE, exactly as `docs/configuration.md` has always described: `BOT_PROVIDER`+and `BOT_MODEL` win, and the file supplies what they leave unset. API keys never appear in the+file — they arrive in the environment under the `key_variable` the provider row names.++A wrong or missing file stops the process at import with the path of the offending key, rather+than at the first model call: the mistakes this guards against are made in this repository, by a+hand editing the JSON, and the person who made it should meet it at startup.++The lookup here mirrors `botSettings` in `shared/model-providers.ts` line for line — same order,+same blank-is-unset reading, same refusal for a Bot with no row — because the two loaders answering+differently would put the languages of one box on different models, which is the drift this file+exists to end.++`PROVIDER_IDS` below is this module's copy of the list `shared/model-providers.ts` keeps for+itself, and each loader checks the file against its own list in both directions at import: a row+this module has never heard of, or a provider this module names that the file has no row for,+stops these Bots at startup rather than at their first model call. Adding a provider is one row in+the JSON file and one entry in each loader.+"""++from __future__ import annotations++import json+import os+from dataclasses import dataclass+from pathlib import Path+from typing import Any, Mapping++_WHERE = "shared/model_providers.py"++# The providers this deployment knows the names of. The same list `shared/model-providers.ts`+# keeps for itself, written out here rather than read from the file: each loader checking the file+# against its own list is what makes a provider added to the JSON alone stop these Bots too, where+# before this list existed only the TypeScript Bots were stopped by it. Adding a provider is one+# entry here, one in that module, and one row to the JSON file.+PROVIDER_IDS: tuple[str, ...] = ("openai", "anthropic", "google")+++def _spec_path() -> Path:+ """Where the file sits: beside this loader, unless the environment points elsewhere."""+ override = (os.environ.get("BOT_SPEC_PATH") or "").strip()+ if override:+ return Path(override)+ return Path(__file__).resolve().with_name("model-providers.json")+++def _require_text(row: Any, field: str, where: str) -> str:+ value = row.get(field) if isinstance(row, dict) else None+ if not isinstance(value, str) or not value.strip():+ raise RuntimeError(f"shared/model-providers.json: {where} must be a non-empty string.")+ return value+++def _load() -> dict[str, Any]:+ path = _spec_path()+ if not path.is_file():+ raise FileNotFoundError(+ f"shared/model-providers.json not found at {path}. The file sits beside this loader "+ "in shared/, or is named by BOT_SPEC_PATH; a Bot without it has no defaults to run."+ )+ try:+ spec = json.loads(path.read_text(encoding="utf-8"))+ except json.JSONDecodeError as error:+ raise RuntimeError(f"shared/model-providers.json at {path} is not JSON: {error}") from error+ if not isinstance(spec, dict):+ raise RuntimeError(f"shared/model-providers.json at {path} must hold an object.")++ providers = spec.get("providers")+ if not isinstance(providers, dict):+ raise RuntimeError("shared/model-providers.json: providers must be an object.")+ # The list's order rather than the file's, so the row an error names first is the row the list+ # named first — the same read the TypeScript loader makes.+ for provider_id in PROVIDER_IDS:+ row = providers.get(provider_id)+ if row is None:+ raise RuntimeError(+ f"shared/model-providers.json: providers is missing its {provider_id} row."+ )+ _require_text(row, "label", f"providers.{provider_id}.label")+ _require_text(row, "key_variable", f"providers.{provider_id}.key_variable")+ _require_text(row, "base_url_variable", f"providers.{provider_id}.base_url_variable")+ _require_text(row, "default_model", f"providers.{provider_id}.default_model")+ for provider_id in providers:+ if provider_id not in PROVIDER_IDS:+ raise RuntimeError(+ f"shared/model-providers.json: providers has a {provider_id} row this module "+ "has never heard of."+ )++ bots = spec.get("bots")+ if not isinstance(bots, dict):+ raise RuntimeError("shared/model-providers.json: bots must be an object.")+ for bot_id, entry in bots.items():+ if not isinstance(entry, dict):+ raise RuntimeError(f"shared/model-providers.json: bots.{bot_id} must be an object.")+ provider = _require_text(entry, "provider", f"bots.{bot_id}.provider")+ if provider not in PROVIDER_IDS:+ raise RuntimeError(+ f"shared/model-providers.json: bots.{bot_id}.provider is {json.dumps(provider)}, "+ f"not one of {', '.join(PROVIDER_IDS)}."+ )+ _require_text(entry, "model", f"bots.{bot_id}.model")++ return spec+++SPEC: dict[str, Any] = _load()+++@dataclass(frozen=True)+class BotSettings:+ """What one Bot was decided to run: its provider, and the model on it."""++ provider: str+ model: str+++def default_model_for(provider: str) -> str:+ """A provider's default row, or OpenAI's for a name nobody has heard of."""+ row = SPEC["providers"].get(provider)+ if row is None:+ row = SPEC["providers"]["openai"]+ return row["default_model"]+++def bot_settings(+ bot_id: str,+ env: Mapping[str, str] | None = None,+ pinned_provider: str | None = None,+) -> BotSettings:+ """This Bot's provider and model: environment over spec file over provider default.++ The lookup order is the whole contract, and it is the order `docs/configuration.md` already+ documents for `BOT_PROVIDER` and `BOT_MODEL` — the environment is how a deployment overrides+ what the repository decided, so it wins. What is new is the middle: the `bots` row this Bot+ had before, written down in one file every language reads instead of repeated in each Bot's+ source. A blank value is not a choice: compose hands `BOT_MODEL=` an empty string when nobody+ picked a model, and empty falls through to the file.++ A provider nobody has heard of is kept as typed, not rewritten to OpenAI, so the Bot's own+ refusal can put the name in its message. Its model falls back to the OpenAI default for the+ same reason the TypeScript loader does it: the refusal belongs to the Bot, one line below.++ A missing `bots` row throws rather than defaults. The file is in this repository; a Bot wired+ to it without a row is a mistake made while editing it, made at development time.+ """+ environ = os.environ if env is None else env++ entry = SPEC["bots"].get(bot_id)+ if entry is None:+ raise RuntimeError(+ f"shared/model-providers.json: bots has no {bot_id} entry. "+ "Add one before this Bot reads the spec file."+ )++ provider = (+ (pinned_provider or "").strip()+ or (environ.get("BOT_PROVIDER") or "").strip().lower()+ or entry["provider"]+ )++ # A model the environment names goes to whatever provider was resolved, because an endpoint+ # names its own catalogue. The file's model belongs to the file's provider, so a deployment+ # that moved this Bot to another provider gets that provider's default instead of a model+ # paired with the one it left.+ model = (environ.get("BOT_MODEL") or "").strip()+ if not model:+ model = (+ entry["model"] if provider == entry["provider"] else default_model_for(provider)+ )++ return BotSettings(provider=provider, model=model)diff --git a/tests/compose.test.ts b/tests/compose.test.tsindex 96064f9a..31403428 100644--- a/tests/compose.test.ts+++ b/tests/compose.test.ts@@ -334,13 +334,24 @@ for (const { name, environment, expected } of compatibleEndpointCases) {});}-test("preserves the framework Bot's other provider endpoints", () => {- const compose = composeFile();- for (const variable of [- "ANTHROPIC_BASE_URL",- "GOOGLE_GENERATIVE_AI_BASE_URL",- ]) {- expect(compose).toContain(`${variable}: \${${variable}:-}`);+test("passes every other provider's key and endpoint into the framework Bot and the picked harness", () => {+ const config = runComposeConfig({+ ANTHROPIC_API_KEY: "sk-ant-synthetic",+ ANTHROPIC_BASE_URL: "https://anthropic-gateway.example",+ GOOGLE_API_KEY: "synthetic-google",+ GOOGLE_GENERATIVE_AI_BASE_URL: "https://generativelanguage.example/v1beta",+ });++ // A service either receives the variable or it does not; reading the file's text cannot tell+ // the difference, because any one service declaring it would satisfy a raw `toContain`.+ for (const service of ["agent-langgraph", "agent-harness"]) {+ expect(config.services[service].environment).toMatchObject({+ ANTHROPIC_API_KEY: "sk-ant-synthetic",+ ANTHROPIC_BASE_URL: "https://anthropic-gateway.example",+ GOOGLE_API_KEY: "synthetic-google",+ GOOGLE_GENERATIVE_AI_BASE_URL:+ "https://generativelanguage.example/v1beta",+ });}});