Task 158 follow-up: centralize LiteLLM provider metadata for UX hints

[spinje]

Context

Phase A now advertises LiteLLM's broader provider support, but provider-specific UX helpers still only know the core providers in a few places.

Problems

• _derive_env_var_for_model() currently maps Anthropic/OpenAI/Gemini, so non-core provider errors may suggest a generic or wrong env var.
• Provider/model detection logic is duplicated across llm_client.py, llm_reasoning_map.py, and exceptions.py.
• Docs mention providers such as OpenRouter, Ollama, Mistral, Bedrock, Azure, and Vertex, but error hints do not consistently reflect those names.

Scope

• Create a small provider metadata/helper layer for common LiteLLM provider prefixes.
• Use it for env-var suggestions and model-family predicates where appropriate.
• Keep the first pass boring: cover documented/common providers; fall back gracefully for unknown prefixes.

Candidate providers

OpenRouter, Mistral, Cohere, Bedrock/AWS, Azure OpenAI, Vertex/Gemini, Ollama/local providers.

[spinje]

Status update — substantially addressed by Task 158 §39 / §40

The duplication-elimination half of this issue is now done. src/pflow/core/llm_providers.py is the canonical provider metadata registry:

@dataclass(frozen=True)
class ProviderInfo:
    name: str
    provider_prefix: str
    bare_prefixes: tuple[str, ...]
    env_var: str

PROVIDERS: tuple[ProviderInfo, ...] = (
    ProviderInfo("anthropic", "anthropic/", ("claude-",), "ANTHROPIC_API_KEY"),
    ProviderInfo("openai", "openai/", ("gpt-", "o1", "o3", "o4"), "OPENAI_API_KEY"),
    ProviderInfo("gemini", "gemini/", ("gemini-",), "GEMINI_API_KEY"),
)

All three previously-duplicating sites now consume the registry:

• src/pflow/core/llm_client.py::_normalize_model_name and _is_anthropic use detect_provider.
• src/pflow/core/llm_reasoning_map.py::_detect_capabilities uses detect_provider + model_name_without_provider.
• src/pflow/core/exceptions.py::_derive_env_var_for_model uses detect_provider.

Adding a new provider/model family is now one registry-line plus any family-specific reasoning-capability decision in _detect_capabilities. The drift class that motivated this issue (e.g. the o4-* prefix existing in one place but not the other two) is structurally prevented.

Verified by:

• tests/test_core/test_llm_providers.py — registry contract tests.
• tests/test_core/test_llm_reasoning_map.py::test_openrouter_anthropic_path_is_not_anthropic — exact-prefix matching prevents the substring false-positive.
• tests/test_core/test_llm_client.py::TestNormalizeModelName — bare-name normalization across all current registry entries.
• The o4-* bug class explicitly fixed in .taskmaster/tasks/task_158/implementation/progress-log.md §40 issue 1.

What remains

The candidate-providers expansion half — extending the registry to OpenRouter, Mistral, Cohere, Bedrock/AWS, Azure OpenAI, Vertex/Gemini, Ollama/local providers — is gated on actual user demand for those provider integrations. Each addition is mechanical (one ProviderInfo(...) line + tests) but requires deciding the bare-prefix list and env-var name per provider. Best done when a real user need surfaces.

Recommendation

Re-scope this issue to "extend llm_providers.py registry to additional LiteLLM providers as user demand surfaces" — keeping it as a tracking ticket for future provider additions. The structural problem is resolved.