Skip to content

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.

14.1 KB
Raw Blame
/**
 * 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 Object.hasOwn(MODEL_PROVIDERS, normalized)
    ? MODEL_PROVIDERS[normalized as ModelProviderId]
    : undefined;
}

/** 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 = Object.hasOwn(BOT_ENTRIES, botId)
    ? BOT_ENTRIES[botId]
    : undefined;
  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.
 *
 * Two kinds of OpenAI model, as OpenAI's own API answered on 2026-10-28:
 *
 * - `gpt-5.6-*` and every `gpt-6*` reject function tools on `/v1/chat/completions` ("To use
 *   function tools, use /v1/responses or set reasoning_effort to 'none'"), and `none` is itself
 *   refused by some of them (`gpt-6-astra`, `gpt-6.1-sol`), so the Responses API is the one way all
 *   of them take tools.
 * - The `-pro` models (`gpt-5-pro`, `gpt-5.5-pro`, `o3-pro`) and `gpt-5.3-codex` are not served on
 *   `/v1/chat/completions` at all.
 *
 * So a Bot that speaks chat completions by hand cannot use them, 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.
 *
 * A name a gateway publishes under its own namespace is the same model: LiteLLM and OpenRouter call
 * `gpt-5.6-terra` `openai/gpt-5.6-terra`, so only what follows the last slash is read.
 *
 * 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 {
  const name = model.trim().split("/").at(-1) ?? "";
  return /^gpt-5\.[6-9]|^gpt-[6-9]|^(?:gpt-[\d.]+|o\d+)-pro\b|^gpt-[\d.]+-codex\b/.test(
    name,
  );
}

/**
 * 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";
}