​

Model selection: per-step pins

Migrating from the tier API? Replace resolve_tier_model(pool, "standard") at a call site with a direct read of that step’s *_model pin (see the inventory below), and seed the pin in settings_defaults.py / 0000_baseline.seeds.sql. The cost_tier.*.model rows are deleted by migration 20260623_210500_drop_cost_tier_model_seeds.py.

​

Why this exists

​

Two decoupled axes — only one was removed

​

The contract: fail loud, no silent default

• Critical steps (writer, critic, the LLM-judge QA rails, hygiene-summary jobs) → notify_operator(critical=True) + raise. The pipeline halts loudly rather than degrade output quality silently.
• Non-critical enhancers (title regen, the media/video director stages, the image-gen prompt synthesiser) → log + soft-skip or return None, so a missing optional pin degrades that one enhancement without killing the post. Several still notify_operator(critical=False) so the gap is visible.

# Critical-step shape (e.g. the QA critic):
model = (site_config.get("pipeline_critic_model") or "").strip()
if not model:
    await notify_operator(
        "multi_model_qa: pipeline_critic_model is unset — QA critic cannot run",
        critical=True, site_config=site_config,
    )
    raise RuntimeError("no critic model configured — set pipeline_critic_model")
return model.removeprefix("ollama/")  # OllamaClient wants the bare name

​

Per-step pin inventory

​

What didn’t migrate (and why)

• Model-class detection — sites doing is_thinking_model(model) branch on whether a model emits <think>…</think> blocks (a capability test), not a model choice. Routed through services.llm_providers.thinking_models, which reads app_settings.thinking_model_substrings (a JSON array).
• Reference / canonical-default tables — cost_guard.py’s energy-per-1K-Wh table, each provider plugin’s default_model, and settings_defaults.py seed defaults. Already overridable per-row; not model-selection codepaths.

​

How operators tune the system

​

”I want the QA critic on a heavier local model”

UPDATE app_settings SET value = 'ollama/qwen2.5:72b' WHERE key = 'pipeline_critic_model';

​

”I want image-decision on a more accurate model"

UPDATE app_settings SET value = 'ollama/gemma3:27b' WHERE key = 'model_role_image_decision';

​

"I want a cloud model on a pin (e.g. premium QA for high-stakes critic calls)”

1. Point the pin at a paid model. cost_guard.py’s daily/monthly cap fires before the call, so you can’t accidentally blow the budget:
   UPDATE app_settings SET value = 'anthropic/claude-sonnet-4-6' WHERE key = 'pipeline_critic_model';
   
2. Authorise paid endpoints. The LiteLLM router default-denies any non-local model prefix (anthropic/, openai/, gemini/, …) or non-local api_base per feedback_no_paid_apis — so step 1 on its own raises LiteLLMProvider refuses paid model prefix …. Open the gate by flipping the flat operator key:
   poindexter settings set plugin.llm_provider.litellm.allow_paid_base_url true
   

   One effective key. allow_paid_base_url resolves from the flat plugin.llm_provider.<provider>.allow_paid_base_url row — what the seed, the refusal message, and poindexter settings set all reference. The dispatcher’s get_provider_config folds that row into the provider’s config, so you never have to hand-edit the nested JSON config blob. A value already inside that nested blob still wins if present (backcompat), but the flat row is the supported path. Swap litellm for openai_compat if that’s the provider configured for the tier.

​

”I want a cloud model on any pin” — full enablement checklist

1. Credential. Put the API key in the matching is_secret=true row — anthropic_api_key / openai_api_key / gemini_api_key. At startup the worker AND the Prefect flow subprocess run configure_cloud_api_keys (services/llm_providers/litellm_provider.py), which stamps the decrypted value into the *_API_KEY env var LiteLLM auto-discovers. Empty rows are the normal local-only state and stamp nothing.
2. Paid-endpoint gate. The provider refuses non-local model prefixes by default. Opt in on the plugin config row’s nested config object (the flat plugin.llm_provider.litellm.allow_paid_base_url row is seeded for discoverability, but the provider reads the JSON row):
   UPDATE app_settings
   SET value = jsonb_set(value::jsonb, '{config,allow_paid_base_url}', 'true')::text
   WHERE key = 'plugin.llm_provider.litellm';
   
3. Budget headroom. daily_spend_limit_usd / monthly_spend_limit_usd are enforced before every paid dispatch (fails closed). Size them for the expected traffic or the first over-cap call raises CostGuardExhausted.

​

”I want to see which model fired for which call”

​

Reasoning models and structured extraction

1. Separate model for structured extraction. resolve_structured_model() reads structured_extraction_model (default gemma3:27b, a JSON-reliable instruct model) instead of the writer pin, so a reasoning writer doesn’t break extraction:
   UPDATE app_settings SET value = 'ollama/gemma3:27b' WHERE key = 'structured_extraction_model';
   
2. Reasoning-content fallback in the provider. When LiteLLMProvider gets an empty content it recovers the payload from the response’s reasoning_content (stripping any <think> wrapper). Toggle via plugin.llm_provider.litellm.config.reasoning_content_fallback (default true). It triggers on the observed empty-content symptom, so it catches new reasoning models even before they’re added to thinking_model_substrings.

​

Related docs

• docs/reference/app-settings.md — every settings key, including the per-step *_model pins
• docs/architecture/services/litellm_provider.md — the provider that consumes the resolved model + tracks cost
• docs/architecture/anti-hallucination.md — the QA rails whose judge models are per-step pins