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 <laurisaarni@git.wordpress.org>
Co-authored-by: JasonTheAdams <jason_the_adams@git.wordpress.org>

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.

[JasonTheAdams]

I've requested @felixarntz to share his thoughts, but this makes sense to me and would help with debugging. There was recently a pretty significant refactor of the PromptBuilder as there's now a model resolver. Would you please update this PR to be rebased from that, @saarnilauri?

[saarnilauri]

@JasonTheAdams Thanks for the heads-up. I've rebased the PR onto the current trunk and adapted it to the new model resolver architecture.

Since the model selection logic (including the "No models found…" exception) moved from the PromptBuilder::getConfiguredModel() into ModelResolver::resolve(), the changes from this PR now live in ModelResolver:

• The new getNoSuitableModelsMessage() builds the error message there, distinguishing between no model supporting the capability at all vs. models supporting the capability but not the required options (naming the unmet options in the message).
• It preserves trunk's newer message variations, the $subject suffix ("for this prompt") and the empty-requirements fallback, which means EmbeddingBuilder gets the improved option-aware error messages for free, too.
• I also extended the docblock correction commit: ModelResolver::resolve() had the same stale claim that an explicitly set model is validated against the requirements, so that docblock is now corrected as well.