- Deprecate existing ChatOptionsBuilder and its inner class DefaultChatOptions
- Create a new builder interface ChatOptions.Builder for building the Chat options
- Create an explicit DefaultChatOptions
- Create DefaultChatOptionBuilder which can create DefaultChatOptions
- Add javadoc for the deprecated Builder
Resolves#1875
- Fix OpenAI ChatModel's call() operation
- When toolcalling is used, calculate cumulative usage from the preceding ChatResponses
- Fix OpenAI ChatModel's stream() operation
- Make sure that cumulative usage is calculated from the ChatResponse which has a valid usage
- Use overlapping buffer to check and store the usage from the response that holds the usage.
- Add tests for both call() and stream()
The Document class previously allowed multiple media entries while also having a
text field, leading to ambiguity in content handling. This change enforces a
clear separation between text and media documents to prevent content type
confusion and simplify document processing.
A Document now must contain either text content or a single media entry, but
never both. This aligns with the class's primary use in ETL pipelines where
clear content type boundaries are essential for proper embedding generation and
vector database storage.
Additional architectural changes:
- Document now implements a cleaner API by removing deprecated methods
- Removed MediaContent interface implementation from Document class
- Document.getMedia() now returns a single Media object instead of Collection
- Removed EMPTY_TEXT constant in favor of proper null handling
- Constructor signatures simplified and streamlined
- Builder pattern improved to enforce single content type constraint
The breaking changes include:
- Media is now a single entry instead of a collection
- Content field renamed to text for clarity
- Removed support for mixed content types
- Simplified builder API to prevent ambiguous construction
Prefer using text-related methods over deprecated content methods to
better reflect the actual content type being handled and improve API clarity.
- Add BedrockMediaFormat class to handle media format conversions for documents, images and videos
- Enhance Media class with builder pattern and comprehensive format constants
- Refactor BedrockProxyChatModel to support multimodal content handling
- Add integration tests for PDF, image and video processing
- Add unit tests for Media and BedrockMediaFormat classes
- Upgrade AWS SDK version from 2.26.7 to 2.29.29
- Remove redundant aws.sdk.version property in favor of awssdk.version
Documentation updates for Bedrock Converse API
- Added multimodal support documentation (images, video, documents)
- Added deprecation notices for existing Bedrock model implementations
- Updated feature comparison table
- Added warning notes about transitioning to Converse API
- Implement streaming tool call support in OllamaApi and OllamaChatModel
- Add OllamaApiHelper to manage merging of streaming chat response chunks
- Remove @Disabled annotations for streaming function call tests
- Update documentation to reflect new streaming function call capabilities
- Add a new default constructor for ChatResponse
- Update Ollama chat documentation to clarify streaming support requirements
- Deprecated withContent(), withImages(), and withToolCalls() methods
- Replaced with content(), images(), and toolCalls() methods
Add token and duration aggregation for Ollama chat responses
- Modify OllamaChatModel to support accumulating tokens and durations across multiple responses
- Update ChatResponse metadata generation to aggregate usage and duration metrics
- Add tests to verify metadata aggregation behavior
Refactor Ollama duration fields and tests
- Replace Duration fields in OllamaApi.ChatResponse with Long to represent durations in nanoseconds, ensuring precision and compatibility.
- Update methods to convert Long nanoseconds to Duration objects (getTotalDuration, getLoadDuration, getEvalDuration, getPromptEvalDuration).
- Adjust merge logic in OllamaApiHelper to sum Long values for duration fields.
- Modify test cases in OllamaChatModelTests to align with Long duration representation and Duration.ofNanos conversions.
- Add new test class OllamaDurationFieldsTests to validate JSON deserialization and Duration conversion for duration fields.
Resolves#1847
Related to #1800Resolves#1796
Related to #1307
test: Update OllamaWithOpenAiChatModelIT integration tests
- Remove @Disabled annotation for streamFunctionCallTest
- Add inputType for function callback in stream function call test
This refactoring introduces a consistent builder pattern across vector store
implementations to standardize configuration and initialization, while also
moving ChromaVectorStore to a dedicated chroma package.
Key changes:
- Add VectorStore.Builder interface and AbstractVectorStoreBuilder to establish
a common builder hierarchy
- Move ChromaVectorStore and related classes from vectorstore to
org.springframework.ai.chroma.vectorstore package
- Migrate ChromaVectorStore to builder pattern as the first implementation
- Add null-safety annotations and parameter validation
- Deprecate direct constructors in favor of builder API
- Update all tests and documentation to reflect new structure
The builder pattern provides several benefits:
- Consistent configuration across all vector store implementations
- Better validation of required parameters
- More flexible initialization order
- Clearer separation of concerns between configuration and usage
- Improved discoverability of options through method chaining
- Since the Document object's reference to the `embedding` is deprecated and will be removed, the VectorStore implementations require a way to store the embedding of the corresponding Document objects
- One way to fix this is, to have the EmbeddingModel#embed to return the embeddings in the same order as that of the Documents passed to it.
- Since both the Document and embedding collections use the List object, their iteration operation will make sure to keep them in line with the same order.
- A fix is required to preserve the order when batching strategy is applied.
- Updated the Javadoc for BatchingStrategy
- Fixed the Document List order in TokenCountBatchingStrategy
- Refactored the vector store implementations to update this change
Resolves #GH-1826
Document
* Introduced “score” attribute in Document API. It stores the similarity score.
* Consolidate “distance” metadata for Documents. It stores the distance measurement.
* Adopted prefix-less naming convention in Document.Builder and deprecated old methods.
* Deprecated the many overloaded Document constructors in favour of Document.Builder.
Vector Stores
* Every vector store implementation now configures a “score” attribute with the similarity score of the Document embedding. It also includes the “distance” metadata with the distance measurement.
* Fixed error in Elasticsearch where distance and similarity were mixed up.
* Added missing integration tests for SimpleVectorStore.
* The Azure Vector Store and HanaDB Vector Store do not include those measurements because the product documentation do not include information about how the similarity score is returned, and without access to the cloud products I could not verify that via debugging.
* Improved tests to actually assert the result of the similarity search based on the returned score.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Introduced new options for audio output modalities in ChatCompletionRequest
- Added AudioParameters configuration for voice and audio format selection
- Enhanced OpenAiChatModel to handle audio generation and embedding
- Updated AssistantMessage and Media classes to support audio media
- Added integration tests for audio output functionality
- Implemented support for text and audio multi-modal responses
- Updated Spring AI's chat model comparison table to clarify OpenAI's input/output modalities
- Added new configuration properties for audio output:
* spring.ai.openai.chat.options.output-modalities
* spring.ai.openai.chat.options.output-audio
- Extended documentation to explain audio output generation with the gpt-4o-audio-preview model
- Updated Spring Boot configuration metadata to support new audio-related properties
- Included auto-configuration integration test for chat model with audio response generation
Resolves#1841
Extracts shared function callback builder functionality into DefaultCommonCallbackInvokingSpec
base class, reducing code duplication across builder implementations.
Makes FunctionInvokingSpec and MethodInvokingSpec extend CommonCallbackInvokingSpec for better
code organization. Also fixes function/description builder order in Anthropic tests.
- Introduced a common base class for function callback builders to centralize shared logic
- Standardized the order of method chaining for function and description in multiple AI model test classes
- Refactored test cases across various AI model integrations
- Corrected builder method order from .description().function() to .function().description()
and .description().method() to .method().description()
- Updated multiple test files to consistently use .function() before .description()
- Updated documentation examples to reflect new builder method order
- Modified DefaultFunctionCallbackResolver to maintain new builder method order
- Updated DefaultChatClient and ChatClient test classes to reflect new builder pattern
- Simplified callback specification by removing parent spec reference
- Removed cascading getter logic for description, schema type, and other properties
- Minor adjustments to function callback builder and invoking specs
- Updated `org.springframework.boot.autoconfigure.AutoConfiguration.imports` to include MariaDB vector store auto-configuration
- Created MariaDB Vector Store autoconfiguration integration tests (`MariaDbStoreAutoConfigurationIT`)
- Added MariaDB store properties configuration and tests (`MariaDbStorePropertiesTests`)
- Introduced new Maven modules:
- `spring-ai-mariadb-store`: Core MariaDB vector store implementation
- `spring-ai-starter-mariadb-store`: Spring Boot starter for MariaDB vector store
- Added `MariaDBFilterExpressionConverter` to support JSON-based metadata filtering in MariaDB
- Implemented filter expression conversion for MariaDB vector store queries
- Added README.md with documentation link for MariaDB Vector Store
- Updated project dependencies to include MariaDB JDBC driver and test containers
- Configured integration testing with TestContainers for MariaDB
- Added observability support for MariaDB vector store operations
- Added support for audio input and output in OpenAI Chat Completion API
- Introduced new audio-related parameters, enums, and record types
- Updated ChatCompletionMessage, ChatCompletionChunk, and related classes
- Added new AudioParameters, AudioOutput, and InputAudio record types
- Implemented method to handle audio media content conversion
- Included new model enum for GPT-4o audio preview
- Extended existing API classes to accommodate audio modalities
- Modified usage tracking and metadata classes to handle audio-specific token details
- Improved ModelOptionsUtils with additional JSON utility methods
Tests:
- Updated test classes to validate audio input and output functionality
- Added integration tests for multimodal audio input with streaming and non-streaming methods
- Created parameterized tests for audio-enabled models
- Enhanced OpenAI API integration tests to cover audio-related scenarios
Docs:
- Updated documentation in spring-ai-docs to explain audio multimodality support
Resolves#1560
- Introduces a new FunctionCallbackResolver interface to define the strategy for
resolving FunctionCallback instances.
- Renames FunctionCallbackContext to DefaultFunctionCallbackResolver to better reflect its
implementation role. Updates all related components to use the new interface.
- Update the affected AI model implementations
- Replaces FunctionCallbackContext parameter with FunctionCallbackResolver in all
model constructors
- Updates builder patterns to use functionCallbackResolver() method instead of
withFunctionCallbackContext()
- Deprecates old withFunctionCallbackContext() methods in builders to guide
migration
- Updates integration tests to use DefaultFunctionCallbackResolver
- Improves documentation to clarify the resolver's role in function callbacks
- Moves SchemaType enum from FunctionCallbackContext to FunctionCallback
Resolves#758
- ChatGenerationMetadata provides Map for additional metadata
- Add Builder interface and DefaultChatGenerationMetadataBuilder
- Add DefaultChatGenerationMetadata implementation
- Update all AI model implementations to use the new builder pattern
- Deprecate ChatGenerationMetadata.from() factory method
- Remove commented out legacy code from ChatGenerationMetadata interface
- Make metadata and content filter collections immutable via Collections.unmodifiableSet()
- Add null validation in DefaultChatGenerationMetadata constructor
- Improve toString() method with more informative output
- Remove SimpleVectorStore's dependency on deprecated embeddings from Document object
- Create a custom Content object that represents the SimpleVectorStore's contents and embedding
- Add tests
Pre-Retrieval:
* Consolidated naming and documentation
Retrieval:
* Consolidated naming and documentation
* Introduced DocumentJoiner sub-module and CompositionDocumentJoiner operator
Post-Retrieval:
* Introduced main interfaces for sub-modules. Implementation waiting for missing features in Document APIs
Orchestration:
* Introduced QueryRouter sub-module and AllDocumentRetrieversQueryRouter operator
Generation:
* Consolidated naming and documentation
Advisor:
* Introduced BaseAdvisor to reduce boilerplate when implementing Advisors
* Extended RetrievalAugmentationAdvisor to include the new sub-modules
Relates to #gh-1603
- Replace hardcoded "tool_use" with StopReason enum value
- Add tests for token usage aggregation with tool calls
- Add handling for null response metadata
Add AI_OPERATION_TYPE and AI_PROVIDER as low cardinality key names to advisor observations.
The advisor AI_OPERATION_TYPE is set to 'framework' and the AI_PROVIDER to 'spring_ai'.
Resolves#1660
- Add TOOL_CALL_HISTORY constant to store tool call history
- Extend ToolContext with getToolConversationHistory method
- Include tool call history in tool context during function execution
- Add test coverage for tool call history verification
Resolves#1202
Add support for no-argument Supplier and single-argument Consumer function
callbacks in the Spring AI core module. This enhancement allows:
- Registration of Supplier<O> callbacks with no input (Void) type
- Registration of Consumer<I> callbacks with no output (Void) type
- Support for Kotlin Function0 (equivalent to Java Supplier)
- Handle empty properties for Void input types in schema generation
- Enhance FunctionCallback builder to support Supplier/Consumer patterns
Additional changes:
- Add test coverage for both Supplier and Consumer callbacks in various scenarios
- Enhance TypeResolverHelper to support Consumer input type resolution
- Support lambda-style function declarations for improved ergonomics
- Add test cases for void input/output handling in OpenAI chat model
- Include examples of function calls without return values
- Add support for parameterless functions through Supplier interface
Add comprehensive documentation for the FunctionCallback API:
- Overview of the interface and its key methods
- Builder pattern usage with function and method invocation approaches
- Examples for different function types (Function, BiFunction, Supplier, Consumer)
- Best practices and common pitfalls
- Schema generation and customization options
Resolves#1718 , #1277 , #1118, #860
Improves function calling documentation with clearer organization and examples:
- Reorganizes content into server-side and client-side registration sections
- Adds detailed examples for both function-invoking and method-invoking approaches
- Enhances tool context documentation with diagrams and usage examples
- Updates function-calling diagrams to reflect current implementation
- Update deprecated annotation messages to correctly reference functions() instead of function()
- Add detailed documentation for FunctionCallback.Builder hierarchy
- Deprecate FunctionCallbackWrapper class in favor of Builder pattern
- Fix typos and improve code documentation
Introduces a simplified, type-safe builder pattern for function callbacks to
improve developer experience and code reliability. The new hierarchical API
separates concerns between direct function invocation and method reflection,
while providing better compile-time safety.
This change deprecates the older FunctionCallbackWrapper in favor of a more
intuitive FunctionCallback.Builder that better handles generic types via
ParameterizedTypeReference. It also adds automatic function description
generation as a fallback when none is provided, though explicit descriptions
are still recommended.
The update standardizes function callback handling across all AI model
implementations (OpenAI, Ollama, Minimax, etc.) and improves response
handling with configurable converters.
Core API Enhancements:
- New Builder Interface: Replaced FunctionCallbackWrapper.builder() with
FunctionCallback.builder(), introducing a hierarchical approach that improves
customization and type safety.
- Specialized Builders: Introduced FunctionInvokerBuilder for direct Function/BiFunction
implementations and MethodInvokerBuilder for reflection-based invocations.
- Generic Type Support: Added ParameterizedTypeReference for better handling of generic parameters.
- Unified Method Definition: Merged method() and argumentTypes() into a single method() call
for simplicity and type safety.
- Automatic Descriptions: Implemented auto-generation of function descriptions, with warnings
to encourage explicit descriptions.
- Configurable Response Converters: Enhanced response handling with support for custom
converters, reducing unnecessary JSON conversions.
Architecture Improvements:
- Established common Builder interface for shared properties
- Separated function object handling from constructor
- Added method-specific configuration (name, arg types, target)
- Added JSON schema generation support for ResolvableType
- Moved to standardized schema types across AI providers
- Set OPEN_API_SCHEMA as default for Vertex AI Gemini
Builder Pattern Standardization:
- Standardized builder method ordering across implementations
- Moved function() call after description() for consistency
- Improved function callback configuration with unified patterns
- Enhanced error handling and validation in DefaultFunctionCallbackBuilder
Deprecations:
- FunctionCallbackWrapper.Builder replaced by DefaultFunctionCallbackBuilder
- Removed CustomizedTypeReference in favor of ParameterizedTypeReference
- Deprecated older ChatClient API methods for function handling
Testing & Documentation:
- Updated all AI model implementations (OpenAI, Ollama, Minimax, Moonshot, ZhiPuAI)
- Added comprehensive integration tests for static/instance methods
- Added integration tests for auto-generated descriptions
- Updated documentation to reflect new builder pattern usage
- Added Kotlin extension for inputType() support
Co-authored-by: Sébastien Deleuze <sebastien.deleuze@broadcom.com>
- Remove deprecated types,methods and references
- Remove usage of "Generation(String text)" and replace with
"Generation(AssistantMessage)"
- Remove MiniMaxApi,MootShotApi,OpenAiApi,ZhiPuAiApi
ChatCompletionFinishReason's FUNCTION_CALL
- Remove OllamaApi's deprecated types
- Remove deprecated constructors from PostgresMlEmbeddingModel
- Remove deprecated constructor from Media
- Remove tokenNames usage from antlr4 FiltersLexer and FiltersParser
- Remove deprecated methods from CassandraVectorStoreProperties
- Remove deprecated constructor and static config class from QdrantVectorStore
- Minor cleanups on removing deprecated models and versions
- Remove old name for mixtral models
Resolves#1599
- Adviser name is moved from hight to low cardinality key values.
- Updated tests in to reflect these changes, ensuring the new low cardinality key is correctly captured.
Resolves#1716
Query Analysis
* Introduce Query Analysis Module
* Define QueryTransformer API and TranslationQueryTransformer implementation
* Define QueryExpander API and MultiQueryExpander implementation
* Support QueryTransformer in RetrievalAugmentationAdvisor (support for QueryExpander will be in the next PR together with the needed DocumentFuser API).
Improvements
* Refine Retrieval and Augmentation Modules for increased robustness
* Expand test coverage for both modules
* Define clone() method for ChatClient.Builder
Tests
* Introduce “spring-ai-integration-tests” for full-fledged integration tests
* Add integration tests for RAG modules
* Add integration tests for RAG advisor
Query Analysis
* Introduce Query Analysis Module
* Define QueryTransformer API and TranslationQueryTransformer implementation
* Define QueryExpander API and MultiQueryExpander implementation
* Support QueryTransformer in RetrievalAugmentationAdvisor (support for QueryExpander will be in the next PR together with the needed DocumentFuser API).
Improvements
* Refine Retrieval and Augmentation Modules for increased robustness
* Expand test coverage for both modules
* Define clone() method for ChatClient.Builder
Tests
* Introduce “spring-ai-integration-tests” for full-fledged integration tests
* Add integration tests for RAG modules
* Add integration tests for RAG advisor
Relates to #gh-1603
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
This change enables more flexible integration between Spring AI and LLM function
calling capabilities while maintaining type safety and ease of use.
- Add new MethodFunctionCallback class to support method invocation via reflection
- Supports both static and non-static method calls
- Handles multiple parameter types including primitives, objects, collections
- Supports empty parameters and empty response
- Auto-generates JSON schema from method parameters
- Special handling for ToolContext parameters
- Builder pattern for easy configuration
- Add comprehensive unit tests for MethodFunctionCallback
- Add integration tests for MethodFunctionCallback with both Anthropic and OpenAI clients
- Add jackson-module-jsonSchema dependency
- Modify FunctionCallback to check for empty tool context
Testing coverage includes:
- Static method invocation scenarios
- Non-static method calls with various parameter types
- Void return type methods
- Complex parameter types (enums, records, lists)
- Tool context handling
- Error cases and validation
Add MethodFunctionCallback reference docs
- Add support for proper Kotlin functions handling by adapting
`kotlin.jvm.functions.Function1` to `java.util.function.Function` and
`kotlin.jvm.functions.Function2` to `java.util.function.BiFunction`.
- Removes the dependency on Spring Cloud Function and
`net.jodah:typetools` which are replaced by leveraging
Spring Framework `ResolvableType` capabilities.
- Add a Kotlin extension function for
`FunctionCallbackWrapper.Builder.withInputType` allowing to
specify `withInputType<T>()` instead of `withInputType(T::class.java)`.
- Add Kotlin documentation.
