Switch to Responses API for OpenAI

[tpaulshippy]

What this does

As explained here there are numerous reasons to use the newer Responses API instead of the Chat Completions API. Features we get by switching include:

1. Mixing web search with custom tools
2. Conversations with images in and out
3. Certain models like o4-mini-deep-research
4. MCP support through OpenAI

There is one feature not yet available - audio inputs are not supported by the Responses API. So, the library will detect any audio inputs and fall back to the Chat Completions API if they exist.

Type of change

• New feature

Scope check

• I read the Contributing Guide
• This aligns with RubyLLM's focus on LLM communication
• This isn't application-specific logic that belongs in user code
• This benefits most users, not just my specific use case

Quality check

• I ran overcommit --install and all hooks pass
• I tested my changes thoroughly
• I updated documentation if needed
• I didn't modify auto-generated files manually (models.json, aliases.json)

API changes

• No API changes

Related issues

Replaces #290
Should enable resolution of #213

[crmne]

Hey Paul,

thanks for your work so far! Just to be totally transparent:

This is a big change. I feel like this needs a bit more time in the oven and I want to think thoroughly how to have one provider that has two different APIs as RubyLLM was not designed with that in mind.

Responses API not supporting audio is a big no-no. Backwards compatibility is king. Not using a new shiny model that's only supported on the responses API is a lot less inconvenient than suddenly pulling the rug under audio support.

I'll take a look at this when it hurts.

[tpaulshippy]

This change would be backward compatible as it falls back to the chat completion API when you provide audio.

[jaryl]

Just some heads up, support for audio in the Responses API might be coming:

Multimodal from the ground up. Text, images, audio, function calls—all first-class citizens. We didn’t bolt modalities onto a text API; we designed the house with enough bedrooms from day one.
Source: https://developers.openai.com/blog/responses-api/

Don't see it in the docs yet.

[rikkiprince]

I'm interested in Responses API support so we can more easily connect to remote MCP servers.

[radanskoric]

While there seem to be very few technical reasons to switch to the Responses API, it looks like OpenAI is set on pushing it hard. Ignoring the reasons why they're doing this (this is not the place to discuss that) I'm worried that they will start to release new features only on ResponsesAPI in order to force people to switch. I doubt they will deprecate the Completions API but I wouldn't be surprised if they decide to "leave it behind". In that case it would be good to have RubyLLM support ResponsesAPI at least as an optional non-default.

I realise it's a problem due to RubyLLM not being designed to have multiple APIs per provider but is that a direction with less friction? Perhaps "OpenAIResponses" could be introduced as a new separate provider, with OpenAI provider still defaulting to Completions. I know that has some potential for confusion but at least it would make it very explicit that you need to intentionally switch to the Responses API.