Support for Extensible API Parameters in Chat Clients

[mejiwef]

Issue: Support for Extensible API Parameters in Chat Clients

Problem Description

Currently, when integrating with AI providers that are partially compatible with OpenAI but have additional or slightly different parameters, the Spring AI framework lacks extensibility. The existing ChatClient implementations only expose a limited set of parameters defined in their respective ChatOptions classes.

For example, when using Grok's API which supports web search functionality, the required parameter is:

{
    "search_parameters": {
        "mode": "auto"
    }
}

Whereas OpenAI uses web_search_options with different key structures. The current implementation doesn't allow passing these vendor-specific parameters without copying and modifying the entire spring-ai-starter-model-openai implementation.

Proposed Solution

I suggest adding extensibility mechanisms to allow users to pass additional vendor-specific parameters without breaking the existing API. Here are some possible approaches:

1. Extensible Options Classes: Add a Map<String, Object> extraParams field to base option classes like OpenAiChatOptions that gets merged into the final request.

2. Custom Parameter Interceptor: Support a pluggable interceptor mechanism that allows modifying requests before they're sent.

3. Vendor-Specific Option Extensions: Create extension points for vendor-specific option classes while maintaining the core interface.

Example Usage

If implemented, users could easily add custom parameters:

// Approach 1: Using extra parameters map
OpenAiChatOptions options = OpenAiChatOptions.builder()
    .withModel("grok-4")
    .withExtraParam("search_parameters", Map.of("mode", "auto"))
    .build();

// Approach 2: Using vendor-specific options  
GrokChatOptions options = GrokChatOptions.builder()
    .withModel("grok-4")
    .withSearchParameters(Map.of("mode", "auto"))
    .build();

Benefits

• Backward Compatible: Existing code continues to work unchanged
• Flexible: Supports any current and future vendor-specific parameters
• Clean Architecture: Avoids the need for users to copy-paste-modify entire implementations
• Type Safety: Could be implemented with both type-safe and dynamic approaches

Workarounds Currently Required

Currently, users have to:

1. Copy the entire OpenAiChatClient implementation
2. Modify the request creation logic
3. Maintain this fork separately

This is cumbersome and defeats the purpose of using a framework.

Additional Context

• Spring AI Version: [Your Spring AI version]
• Affected Modules: spring-ai-starter-model-openai, potentially other model starters
• Related APIs: Any AI provider with OpenAI-compatible but extended APIs (Grok, Claude, etc.)

[quaff]

Map<String, Object> extraBody is introduced to OpenAiChatOptions currently, it should be generalized to all models.