Forward attachment provider options to OpenAI text generation requests

Merged
MR
4mo ago
+171-8

I noticed that since #717 / #753, provider options on files are honored when uploading via Files::put(), but silently dropped when the same file is attached to a text prompt — MapsAttachments never reads them. This PR closes that gap for the OpenAI and Azure OpenAI text gateways:

$response = $agent->prompt(
    'What is in this image?',
    attachments: [
        (new LocalImage($path))->withProviderOptions(['detail' => 'low']),
    ],
);

Previously the detail option never reached the request body. Now it's merged into the attachment's content part (input_image / input_file).

This matters because detail directly controls vision token billing. Same 1536×1024 image, measured against the live API:

modeldetail: lowdetail: high
gpt-4o-mini2,849 tokens36,851 tokens (13×)
gpt-5.185 tokens925 tokens (11×)

Before this change every request went out as auto no matter what the user configured.

The implementation follows the existing mapTools pattern: Provider is threaded down to mapAttachments, and the options are merged into the wire part with user options winning on conflicts. Closures work the same way they do on the upload path — fn (Lab $provider) => match ($provider) { ... } — which is also how you scope options in multi-provider or failover setups. Azure gets the feature automatically through the shared concerns, with Lab::Azure as the closure key. Heads-up: mapMessagesToInput() / mapUserMessage() are protected trait methods and gained a required Provider parameter.

One pre-existing limitation worth noting: provider options don't survive conversation persistence (File::toArray() doesn't round-trip them) — happy to address that in a follow-up.

I started with OpenAI as the reference implementation; the same pattern applies to the other attachment mappers (Anthropic cache_control, Gemini video_metadata, chat-completions detail). Happy to follow up with those too.

Includes five feature tests in the existing MessageMappingTest style: array options on image and document parts, closure options, a no-options regression, and an Azure test pinning Lab::Azure as the closure key.