Distinguish unmet required options from unsupported capabilities in model selection errors

[saarnilauri]

Summary

When no model satisfies the prompt requirements, PromptBuilder always threw:

No models found that support text_generation for this prompt.

even when models supporting the capability exist and only a required option excluded them. Because every configured option becomes a hard requirement in ModelRequirements::fromPromptData(), a consumer doing something as ordinary as:

AiClient::prompt( 'Write a haiku.' )
    ->usingTemperature( 0.7 )
    ->generateTextResult();

against a provider whose models don't support temperature was told that text generation is unsupported, which is misleading and hard to debug. The capability is fine; the sampling parameter is the problem.

This is becoming more visible now that real models reject options they previously accepted: beginning with Claude Opus 4.7, the Anthropic API returns a 400 for any non-default temperature/top_p/top_k, so the Anthropic provider needs to stop advertising those options in its model metadata (see WordPress/ai-provider-for-anthropic#25). Accurate metadata is only half the story, the SDK should then also report option-based selection failures accurately.

How it works

When the candidate set is empty, PromptBuilder now re-checks the registry against the required capabilities alone:

• No model supports the capability → the existing messages are unchanged (byte-identical), including the provider-restricted variant.

• Models support the capability, but required options excluded them → the message names the options:

  No models found that support text_generation with the required options for this prompt. Models supporting text_generation are available, but none of them support the following required options: temperature.

• Each option is only individually supported (e.g. one model supports temperature, another topP, none both) → the message reflects that:

  … but no single model supports all of the following required options together: topP, temperature.

Supporting changes:

• New ModelRequirements::getUnmetRequiredOptions( ModelMetadata $metadata ): array returns the required options a model does not support (missing, or value not supported). areMetBy() is refactored to reuse it with no behavior change.
• The getConfiguredModel() docblock still claimed an explicitly set model is validated against the requirements; that validation was removed in ba25084, so the docblock now describes the actual behavior (explicit model is used as-is; unsupported parameters surface as errors from the provider's API).

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Fable 5
Used for: Investigating the model selection flow, drafting the implementation and tests. The final implementation was reviewed and edited by me.

Issue

Motivated by the discussion in WordPress/ai-provider-for-anthropic#25.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: saarnilauri <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.31%. Comparing base (052a468) to head (a7f87c9).

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk     #254      +/-   ##
============================================
+ Coverage     88.16%   88.31%   +0.15%     
- Complexity     1217     1228      +11     
============================================
  Files            61       61              
  Lines          3945     3989      +44     
============================================
+ Hits           3478     3523      +45     
+ Misses          467      466       -1     

Flag	Coverage Δ
unit	88.31% <100.00%> (+0.15%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[saarnilauri]

I will be on leave for some time. Will be officially back at 20th of July.