Models & Profiles

Profiles and Model Routing: Step-by-Step

This page teaches how to manage multiple provider profiles, set model aliases/fallbacks, and keep behavior predictable in scripts.

Step 1: Build one base profile

mosaic --project-state --profile default setup \
  --base-url https://api.openai.com \
  --api-key-env OPENAI_API_KEY \
  --model gpt-4o-mini

mosaic --project-state --profile default configure --show

Step 2: Inspect provider and model visibility

mosaic --project-state --profile default models list
mosaic --project-state --profile default models list --query gpt --limit 10
mosaic --project-state --profile default models status

Step 3: Resolve and set active model

mosaic --project-state --profile default models resolve
mosaic --project-state --profile default models resolve fast
mosaic --project-state --profile default models set gpt-4o-mini

Step 4: Use aliases to normalize call sites

mosaic --project-state --profile default models aliases set fast gpt-4o-mini
mosaic --project-state --profile default models aliases set deep gpt-4.1-mini
mosaic --project-state --profile default models aliases list
mosaic --project-state --profile default models aliases remove deep

Step 5: Configure fallback chain

mosaic --project-state --profile default models fallbacks add gpt-4.1-mini
mosaic --project-state --profile default models fallbacks add gpt-4o-mini
mosaic --project-state --profile default models fallbacks list
mosaic --project-state --profile default models fallbacks remove gpt-4.1-mini

Step 6: Patch configuration safely

mosaic --project-state --profile default configure keys
mosaic --project-state --profile default configure get provider.model
mosaic --project-state --profile default configure set agent.max_turns 10
mosaic --project-state --profile default configure unset agent.max_turns

mosaic --project-state --profile default configure patch --set provider.model=gpt-4o-mini --dry-run
mosaic --project-state --profile default configure preview --set provider.model=gpt-4o-mini
mosaic --project-state --profile default configure template --format toml --defaults

Step 7: Add a second profile (Azure example)

export AZURE_OPENAI_BASE_URL="https://<resource>.openai.azure.com/openai/v1"
export AZURE_OPENAI_API_KEY="<your_key>"

mosaic --project-state --profile az-openai setup \
  --base-url "$AZURE_OPENAI_BASE_URL" \
  --api-key-env AZURE_OPENAI_API_KEY \
  --model gpt-4o-mini

mosaic --project-state --profile az-openai models list

Step 8: JSON contract checks for automation

mosaic --project-state --profile default --json models list --query gpt --limit 5
mosaic --project-state --profile default --json models status
mosaic --project-state --profile default --json configure --show

Acceptance checklist

• At least two profiles can run models list independently.
• Aliases and fallbacks are visible and resolve as expected.
• configure patch/preview can be used without accidental destructive edits.
• JSON output is parseable by your CI pipeline.