Add withProviderOptions() to storable files

[mohali-id]

Closes #716

Hi @pushpak1300

I re create this PR since #676 PR no progress.

This PR will fix #716

i cannot use vector store because of this harcorded purpose.

Azure OpenAI doesn't accept files with purpose = user_data for vector stores. It requires purpose = assistants. So it would be more flexible if the purpose in OpenAiFileGateway were configurable.

Before

Response Failed

After:

Response Success

Tested Using Azure OpenAI GPT 5.3 Codex

Thanks

[pushpak1300]

Thanks for digging into this @mohali-id, and for the clear before/after.

I went with a different approach here. purpose is specific to OpenAI (and Azure's OpenAI-compatible API). Other providers like Gemini and Anthropic have no concept of it, so adding a for() / purpose() method with a hardcoded OpenAI allow-list to the base File class would couple a provider-agnostic class to OpenAI's vocabulary.

Instead I reused the providerOptions() pattern we already have for agents, embeddings, and transcriptions. It's provider-agnostic and extends to any future per-provider upload option, not just purpose:

// override the purpose (or any other OpenAI file option)
Files::put(
    Document::fromPath('knowledge.txt')->withProviderOptions(['purpose' => 'fine-tune'])
);

// closure form, scoped per provider
Files::put(
    Document::fromPath('knowledge.txt')->withProviderOptions(fn (Lab $provider) => match ($provider) {
        Lab::OpenAI => ['purpose' => 'assistants'],
        default => [],
    })
);

Defaults still apply when nothing is passed (user_data for OpenAI, assistants for Azure), and your options win on top.

[mohali-id]

Thanks for digging into this @mohali-id, and for the clear before/after.

I went with a different approach here. purpose is specific to OpenAI (and Azure's OpenAI-compatible API). Other providers like Gemini and Anthropic have no concept of it, so adding a for() / purpose() method with a hardcoded OpenAI allow-list to the base File class would couple a provider-agnostic class to OpenAI's vocabulary.

Instead I reused the providerOptions() pattern we already have for agents, embeddings, and transcriptions. It's provider-agnostic and extends to any future per-provider upload option, not just purpose:

// override the purpose (or any other OpenAI file option)
Files::put(
    Document::fromPath('knowledge.txt')->withProviderOptions(['purpose' => 'fine-tune'])
);

// closure form, scoped per provider
Files::put(
    Document::fromPath('knowledge.txt')->withProviderOptions(fn (Lab $provider) => match ($provider) {
        Lab::OpenAI => ['purpose' => 'assistants'],
        default => [],
    })
);

Defaults still apply when nothing is passed (user_data for OpenAI, assistants for Azure), and your options win on top.

Thanks @pushpak1300 that's a better approach. I think we should add it to the laravel docs as well.

I will close this PR and issue.

[pushpak1300]

Hey @mohali-id i tried to make those changes in the same PR as well this is not supported at the moment.

[mohali-id]

Hey @mohali-id i tried to make those changes in the same PR as well this is not supported at the moment.

Oh I see, I thought it was already in merged PR #676

Thank you for taking the time to help resolve this issue!