Start Here
- Inspect the current branch and worktree with
git status --short; preserve unrelated user changes. - Read
src/fractal/providers.py,src/fractal/onboarding.py,src/fractal/config.py,tests/test_providers.py,tests/test_cli_config.py, andREADME.md. - For model IDs, check current provider documentation or catalogs before editing. Do not rely on memory for active model names.
- Decide whether the task is only a model-menu update or a new provider/runtime behavior.
Provider Registry Pattern
Most provider changes live in src/fractal/providers.py.
- Add a provider id constant near the existing provider constants.
- Add the provider to
_PROVIDERSwith aProviderDefinition. - Use
default_modelfor the default menu selection. - Use
model_optionsfor curated alternatives only; do not duplicatedefault_model. - Use
restricted_modelsonly when Fractal must reject all other model IDs at runtime. - Set
model_prefixto the DSPy/LiteLLM provider prefix when runtime strings need normalization, such asopenai,anthropic, oropenrouter. - Keep
model_optionscurated. It is a setup menu, not an exhaustive provider catalog.
Provider behavior choices:
- API key plus LiteLLM-compatible string: reuse
ApiKeyStringLMBehavior. - OpenAI-compatible custom endpoint: follow
CustomOpenAICompatibleBehavior. - CLI/OAuth-backed provider: add a dedicated behavior class that validates shape, checks readiness without leaking secrets, and builds the runtime LM object.
Secrets must not be stored in Fractal config. Store references only: env var names, auth source names, or paths to external auth stores.
Model ID Rules
- OpenAI API options should be OpenAI model IDs without
openai/;_normalize_modeladds the prefix. - Anthropic options should be Claude API IDs without
anthropic/;_normalize_modeladds the prefix. - OpenRouter options should be OpenRouter catalog IDs like
openai/gpt-5.5oranthropic/claude-sonnet-4.6;_normalize_modeladdsopenrouter/. - Custom OpenAI-compatible endpoints cannot have a complete static model catalog. Keep a custom model entry in onboarding.
- If a provider has a dynamic catalog, do not hardcode the full live response into
model_options; pick stable, coding-relevant defaults and document that the list is curated.
Onboarding And Config
New providers appear in setup through list_providers(). Update onboarding only when the provider needs extra inputs beyond base URL and API-key env var.
- Provider/model menus use
model_choices(). - The line-mode fallback must keep working for non-TTY tests and automation.
- For any new config fields, update
ProviderConfig, redaction/rendering, schema validation, and tests. - Never add raw secret fields such as tokens, API keys, passwords, or credentials to config.
Tests
Add or update focused tests before broad tests:
tests/test_providers.py: registry membership,model_choices, model normalization, shape validation, credential readiness, and unsupported model errors.tests/test_cli_config.py: setup output/input flow, model selection, config writes, and secret redaction.- If config schema changes, update
tests/test_config.py. - If runtime behavior changes outside provider resolution, add narrow smoke/runtime coverage.
Validation commands:
.venv/bin/python -m pytest tests/test_providers.py tests/test_cli_config.py
.venv/bin/python -m pytest
Docs
Update README.md when a provider, auth source, default credential reference, or setup model menu changes. State when a menu is curated rather than exhaustive.
Commit And PR Workflow
Only commit when the user asks.
- Re-check
git status --shortand stage only files changed for this task. - Commit with a provider-scoped message, for example
Add <provider> provider supportorUpdate <provider> model options. - Push the current branch only when the user asks.
- Open a PR only when the user asks, using the repo's normal CLI if available, usually
gh pr create --fill. - In the PR body, include provider behavior, auth/secrets handling, model sources, and tests run.
If current branch ownership is unclear, ask before creating, switching, pushing, or opening a PR.