sync(bfmono): feat(gambit): add gambit.toml model aliases (+19 more) (bfmono@bdc68aae6)

This PR is an automated gambitmono sync of bfmono Gambit packages.

- Source: `packages/gambit/`
- Core: `packages/gambit-core/`
- bfmono rev: bdc68aae6

Changes:
- bdc68aae6 feat(gambit): add gambit.toml model aliases
- 8ed9e6d9c fix(gambit): include handler decks in model check
- 5e10ebb0f infra: add obsidian bft command and fix gambit check mocks
- 54a6bfc86 feat(gambit): add model availability check
- 951e6c678 feat(gambit): auto-pull missing ollama models
- ebc6ed21e feat(gambit): add ollama provider routing
- 3f7bf00e7 docs(gambit): document Gambit-first strategy shift
- 2cefee730 nits(simulator-ui): small tweaks
- 2ae91ed78 fix(simulator-ui): format json consistently
- f38dd2df8 feat(simulator-ui): refine tool call display
- e1c41537b feat(simulator-ui): refine calibrate summary cards
- af2191797 feat(simulator-ui): add status badge component
- 02e6d6819 chore(simulator-ui): add "+" to positive scores
- 17064a3ab fix(simulator-ui): normalize color tokens
- a8a0752ba feat(simulator-ui): make run header toggleable with icon cue
- 66bda7f6d docs(gambit): update simulator links for test/grade
- 1b7be82fd refactor(simulator-ui): remove session metadata display
- 26eb8d7d8 refactor(simulator-ui): simplify raw input details
- 642d14f7b refactor(simulator-ui): drop reference sample overlays
- 1940ad772 refactor(simulator-ui): drop copy ref button

Do not edit this repo directly; make changes in bfmono and re-run the sync.

Author: bft-codebot

docs/external/examples/ollama.md

@@ -23,3 +23,21 @@ Notes:
   Ollama, so the actual model name is `llama3.1`.
 - To point at a non-local instance, set `OLLAMA_BASE_URL` (defaults to
   `http://localhost:11434/v1`).
+
+## Model aliases
+
+Instead of hard-coding the `ollama/...` string in every deck, define an alias in
+`gambit.toml`:
+
+```toml
+[models.aliases.randall]
+model = "ollama/llama3.1"
+
+[models.aliases.randall.params]
+temperature = 0.2
+```
+
+Decks can now set `model = "randall"` inside `[modelParams]`. The CLI resolves
+the alias before calling Ollama, automatically merging the default params
+(`temperature = 0.2` above). CLI flags such as `--model randall` also use the
+alias, so swapping the target model only requires editing `gambit.toml`.

docs/internal/posts/2026-01-24-model-aliases.md

@@ -0,0 +1,40 @@
+++ area_owner = "engineering" authority = "status" lifecycle = "beta" scope =
+"Feature" ++
+
+# Model Aliases in `gambit.toml`
+
+**Published:** 2026-01-24
+
+## What changed
+
+- `gambit.toml` now supports `[models.aliases]` entries so teams can name models
+  (e.g., `randall`) once and reuse them across decks/CLI flags.
+- The CLI automatically resolves aliases, merges default params, and warns when
+  a deck references an undefined alias.
+- `gambit check` validates decks using the resolved models and fails fast if an
+  alias is missing.
+- Demo/init scaffolds include a starter alias plus docs describing how to route
+  Ollama/OpenRouter targets through the new layer.
+
+## Why
+
+- We needed a single source of truth for per-project model choices so swapping
+  providers (OpenRouter vs. Ollama) doesn't require editing every deck.
+- Bundling default params at the alias level keeps temperature/context-size
+  tuning consistent and auditable.
+- Resolving aliases inside `gambit check` prevents subtle drift between deck
+  references and provider availability.
+
+## Links
+
+- Code: `packages/gambit/src/project_config.ts`, `packages/gambit/src/cli.ts`,
+  `packages/gambit/src/commands/check.ts`
+- Docs: `packages/gambit/scaffolds/init/gambit.toml`,
+  `packages/gambit/docs/external/examples/ollama.md`
+
+## Next steps
+
+- Encourage repo owners to define aliases for their canonical models before
+  adding new decks.
+- Extend `gambit check` with richer reporting (e.g., list resolved aliases) if
+  teams need more visibility.

scaffolds/init/README.md

@@ -34,6 +34,6 @@ workspace with opinionated folders, ready for your own decks/actions/graders.
 - `tests/` – synthetic personas/test bots.
 - `schemas/` – Zod schemas shared across decks/tests.
 - `.gambit/` – local sessions/traces (safe to clear, usually ignored by git).
-- `gambit.toml` – workspace configuration for tools/automation.
+- `gambit.toml` – workspace configuration (folders + model aliases).
 
 Happy building!

scaffolds/init/gambit.toml

@@ -4,3 +4,10 @@ actions = "actions"
 graders = "graders"
 tests = "tests"
 schemas = "schemas"
+
+[models.aliases.default]
+model = "openrouter/openai/gpt-4o-mini"
+description = "Workspace default model alias."
+
+[models.aliases.default.params]
+temperature = 0.2

src/cli.ts

@@ -28,6 +28,10 @@ import {
   printShortUsage,
   printUsage,
 } from "./cli_args.ts";
+import {
+  createModelAliasResolver,
+  loadProjectConfig,
+} from "./project_config.ts";
 
 const logger = console;
 const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1";
@@ -232,6 +236,42 @@ async function main() {
       Deno.exit(1);
     }
 
+    const configHint = deckPath || args.graderPath || args.testDeckPath ||
+      args.exportDeckPath || Deno.cwd();
+    let projectConfig: Awaited<ReturnType<typeof loadProjectConfig>> = null;
+    try {
+      projectConfig = await loadProjectConfig(configHint);
+    } catch (err) {
+      logger.error(
+        `Failed to load gambit.toml: ${(err as Error).message}`,
+      );
+      Deno.exit(1);
+    }
+    const modelAliasResolver = createModelAliasResolver(
+      projectConfig?.config,
+    );
+    const warnedMissingAliases = new Set<string>();
+    const applyModelAlias = (
+      model?: string,
+      params?: Record<string, unknown>,
+    ): { model?: string; params?: Record<string, unknown> } => {
+      const resolution = modelAliasResolver(model);
+      if (
+        resolution.missingAlias &&
+        model &&
+        !warnedMissingAliases.has(model)
+      ) {
+        logger.warn(
+          `[gambit] Model alias "${model}" is not defined in gambit.toml; using literal value.`,
+        );
+        warnedMissingAliases.add(model);
+      }
+      const mergedParams = resolution.params
+        ? { ...resolution.params, ...(params ?? {}) }
+        : params;
+      return { model: resolution.model ?? model, params: mergedParams };
+    };
+
     if (args.cmd === "grade") {
       const graderPath = args.graderPath ?? deckPath;
       if (!graderPath) {
@@ -282,6 +322,7 @@ async function main() {
         openRouterBaseURL: Deno.env.get("OPENROUTER_BASE_URL") ?? undefined,
         ollamaApiKey: Deno.env.get("OLLAMA_API_KEY") ?? undefined,
         ollamaBaseURL: Deno.env.get("OLLAMA_BASE_URL") ?? undefined,
+        modelResolver: modelAliasResolver,
       });
       return;
     }
@@ -304,10 +345,12 @@ async function main() {
       baseURL: ollamaBaseURL,
     });
     const ollamaPrefix = "ollama/";
-    const ollamaModels = [
+    const flagModels = [
       args.model ?? undefined,
       args.modelForce ?? undefined,
-    ]
+    ].filter((model): model is string => Boolean(model));
+    const ollamaModels = flagModels
+      .map((model) => applyModelAlias(model).model)
       .filter((model): model is string => Boolean(model))
       .filter((model) => model.startsWith(ollamaPrefix))
       .map((model) => model.slice(ollamaPrefix.length));
@@ -322,16 +365,28 @@ async function main() {
           event: import("@bolt-foundry/gambit-core").ResponseEvent,
         ) => void;
       }) => {
-        if (input.request.model.startsWith(ollamaPrefix)) {
-          const trimmedModel = input.request.model.slice(ollamaPrefix.length);
+        const applied = applyModelAlias(
+          input.request.model,
+          input.request.params,
+        );
+        const request = {
+          ...input.request,
+          model: applied.model ?? input.request.model,
+          params: applied.params,
+        };
+        if (!request.model) {
+          throw new Error("Model is required.");
+        }
+        if (request.model.startsWith(ollamaPrefix)) {
+          const trimmedModel = request.model.slice(ollamaPrefix.length);
           const ollamaResponses = ollamaProvider.responses;
           if (!ollamaResponses) {
             throw new Error("Ollama responses are not configured.");
           }
           return await ollamaResponses({
             ...input,
             request: {
-              ...input.request,
+              ...request,
               model: trimmedModel,
             },
           });
@@ -341,7 +396,10 @@ async function main() {
             "OPENROUTER_API_KEY is required for non-ollama models.",
           );
         }
-        return await openRouterProvider.responses(input);
+        return await openRouterProvider.responses({
+          ...input,
+          request,
+        });
       },
       chat: async (input: {
         model: string;
@@ -352,16 +410,25 @@ async function main() {
         onStreamText?: (chunk: string) => void;
         params?: Record<string, unknown>;
       }) => {
-        if (input.model.startsWith(ollamaPrefix)) {
-          const model = input.model.slice(ollamaPrefix.length);
-          return await ollamaProvider.chat({ ...input, model });
+        const applied = applyModelAlias(input.model, input.params);
+        const request = {
+          ...input,
+          model: applied.model ?? input.model,
+          params: applied.params,
+        };
+        if (!request.model) {
+          throw new Error("Model is required.");
+        }
+        if (request.model.startsWith(ollamaPrefix)) {
+          const model = request.model.slice(ollamaPrefix.length);
+          return await ollamaProvider.chat({ ...request, model });
         }
         if (!openRouterProvider) {
           throw new Error(
             "OPENROUTER_API_KEY is required for non-ollama models.",
           );
         }
-        return await openRouterProvider.chat(input);
+        return await openRouterProvider.chat(request);
       },
     };
 

src/commands/check.test.ts

@@ -1,6 +1,7 @@
 import { assertRejects } from "@std/assert";
 import * as path from "@std/path";
 import { handleCheckCommand } from "./check.ts";
+import { createModelAliasResolver } from "../project_config.ts";
 
 async function writeDeck(dir: string, filename: string, contents: string) {
   const target = path.join(dir, filename);
@@ -200,3 +201,72 @@ Handler deck.`,
     globalThis.fetch = originalFetch;
   }
 });
+
+Deno.test("check resolves model aliases", async () => {
+  const dir = await Deno.makeTempDir();
+  const rootDeck = await writeDeck(
+    dir,
+    "root.deck.md",
+    `+++
+label = "root"
+[modelParams]
+model = "randall"
++++
+
+Root deck.`,
+  );
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (input: Request | URL | string) => {
+    const url = resolveUrl(input);
+    if (url.includes("ollama.test")) {
+      return Promise.resolve(
+        new Response(
+          JSON.stringify({ data: [{ id: "llama3" }] }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+      );
+    }
+    return Promise.resolve(new Response("not found", { status: 404 }));
+  };
+  try {
+    await handleCheckCommand({
+      deckPath: rootDeck,
+      ollamaBaseURL: "http://ollama.test/v1",
+      modelResolver: createModelAliasResolver({
+        models: {
+          aliases: {
+            randall: { model: "ollama/llama3" },
+          },
+        },
+      }),
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+Deno.test("check errors on missing aliases", async () => {
+  const dir = await Deno.makeTempDir();
+  const rootDeck = await writeDeck(
+    dir,
+    "root.deck.md",
+    `+++
+label = "root"
+[modelParams]
+model = "randall"
++++
+
+Root deck.`,
+  );
+  await assertRejects(
+    () =>
+      handleCheckCommand({
+        deckPath: rootDeck,
+        modelResolver: createModelAliasResolver({
+          models: { aliases: { other: { model: "openrouter/foo" } } },
+        }),
+      }),
+    Error,
+    "Unknown model aliases",
+  );
+});

src/commands/check.ts

@@ -1,5 +1,6 @@
 import * as path from "@std/path";
 import { loadDeck } from "@bolt-foundry/gambit-core";
+import type { ModelAliasResolver } from "../project_config.ts";
 
 const logger = console;
 const DEFAULT_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
@@ -109,10 +110,14 @@ function collectDeckRefs(deck: LoadedDeck): Array<string> {
   return refs;
 }
 
-async function collectDeckModels(rootDeckPath: string): Promise<Set<string>> {
+async function collectDeckModels(
+  rootDeckPath: string,
+  resolver?: ModelAliasResolver,
+): Promise<{ models: Set<string>; missingAliases: Set<string> }> {
   const resolvedRoot = path.resolve(rootDeckPath);
   const seenDecks = new Set<string>();
   const models = new Set<string>();
+  const missingAliases = new Set<string>();
   const queue: Array<string> = [resolvedRoot];
 
   while (queue.length > 0) {
@@ -122,7 +127,15 @@ async function collectDeckModels(rootDeckPath: string): Promise<Set<string>> {
     const deck = await loadDeck(deckPath);
     seenDecks.add(deck.path);
     if (deck.modelParams?.model) {
-      models.add(deck.modelParams.model);
+      const resolution = resolver
+        ? resolver(deck.modelParams.model)
+        : { model: deck.modelParams.model, applied: false };
+      if (resolution.missingAlias && deck.modelParams.model) {
+        missingAliases.add(deck.modelParams.model);
+      }
+      if (resolution.model) {
+        models.add(resolution.model);
+      }
     }
     const refs = collectDeckRefs(deck);
     for (const ref of refs) {
@@ -132,7 +145,7 @@ async function collectDeckModels(rootDeckPath: string): Promise<Set<string>> {
     }
   }
 
-  return models;
+  return { models, missingAliases };
 }
 
 async function fetchProviderModels(opts: {
@@ -182,14 +195,21 @@ export async function handleCheckCommand(opts: {
   openRouterBaseURL?: string;
   ollamaApiKey?: string;
   ollamaBaseURL?: string;
+  modelResolver?: ModelAliasResolver;
 }) {
-  const models = await collectDeckModels(opts.deckPath);
-  if (models.size === 0) {
+  const collected = await collectDeckModels(opts.deckPath, opts.modelResolver);
+  if (collected.missingAliases.size > 0) {
+    const missing = Array.from(collected.missingAliases).join(", ");
+    throw new Error(
+      `Unknown model aliases: ${missing}. Define them in gambit.toml or update the deck.`,
+    );
+  }
+  if (collected.models.size === 0) {
     logger.log("No explicit models found in deck tree.");
     return;
   }
 
-  const resolved = Array.from(models, resolveModelProvider);
+  const resolved = Array.from(collected.models, resolveModelProvider);
   const grouped = new Map<ModelProviderKey, Array<DeckModelInfo>>();
   for (const model of resolved) {
     const entry = grouped.get(model.provider) ?? [];