- Split model autoconfigurations based on the model
- Change the autoconfiguration class into model specific autoconfigurations - chat, embedding, image etc.,
- Update/add tests based on this change
- Make sure the conditional logic to enable the model auto configuration is at the class level so that the configuration properties as well as the models are not enabled when the model is explicitly disabled. By default, the condition will allow enabling the beans if not explicitly overridden.
- Remove spring-ai-spring-boot-autoconfigure as a dedicated auto-configuration module
Signed-off-by: Ilayaperumal Gopinathan <ilayaperumal.gopinathan@broadcom.com>
- Introduce top level properties to support conditional logic
- The properties will have the format like "spring.ai.vectorstore.type=<vectorstore provider>" to enable specific vectore store implementation
- By default, these will be enabled when no specific properties are set. To disable, set any value other than the provider name for example, none"
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
- Conditionally enable invidividual models within the provider
- Introduce top level properties to support conditional logic
- The properties will have the format like "spring.ai.model.<chat/embedding/image etc.,>=<provider>" to enable specific chat/embedding/image/audio/moderation models by the provider. By default, these will be enabled when no specific properties are set. To disable, set any value other than the provider name for example, "none"
- For the auto configurations where the provider has multiple models, split the autoconfiguration into per model auto-configuration classes. This will enable the isolated auto-configurations for each provider and its model.
- This PR addresses this for OpenAI and others will follow in subsequent PRs
Signed-off-by: Ilayaperumal Gopinathan <ilayaperumal.gopinathan@broadcom.com>
Move vector store auto-configuration classes to dedicated modules under auto-configurations/vector-stores/:
- Creates separate modules for Milvus, Pinecone, Qdrant, and Typesense vector stores
- Moves CommonVectorStoreProperties to spring-ai-core for better reusability
- Updates pom.xml dependencies to maintain proper relationships between modules
- Name the artifacts based on the pattern spring-ai-autoconfigure-vector-store-<implementation>.
For example - spring-ai-autoconfigure-vectore-store-milvus
- Package names follow the pattern org.springframework.ai.vectorstore.<implementation>.autoconfigure
- Naming the correspondinbg starter modules accordingly (spring-ai-starter-vector-store-milvus for example).
This change improves modularity by allowing each vector store implementation to be
independently versioned and maintained, continuing the migration pattern established
with previous vector stores.
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
Fixes: #938
Issue link: https://github.com/spring-projects/spring-ai/issues/938
This commit integrates Couchbase as a vector store option in Spring AI, providing:
- CouchbaseSearchVectorStore implementation with vector similarity search capabilities
- Support for metadata filtering with SQL++ expression conversion
- Spring Boot auto-configuration and starter module for easy integration
- Comprehensive documentation covering setup, configuration, and usage examples
- Integration tests using TestContainers with Couchbase 7.6
The implementation supports configuring dimensions, similarity functions (dot_product/l2_norm),
and optimization strategies (recall/latency). Schema initialization is now opt-in via
the initializeSchema property. Documentation includes both auto-configuration and
manual configuration instructions, along with property configuration details.
Signed-off-by: Abhiraj <abhiraj.official15@gmail.com>
co-authored-by: Laurent Doguin <laurent.doguin@gmail.com>
This change ensures that @Tool annotated methods can be properly discovered even when the tool objects are wrapped
in Spring AOP proxies, which is common when using aspects or other proxy-based features.
- Enhance MethodToolCallbackProvider to properly handle AOP proxied tool objects by detecting proxies
and retrieving their target classes when scanning for @Tool annotated methods.
- Add test suite in MethodToolCallbackProviderAopTests.java to verify AOP proxy handling
Resolves#2356
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Fix Embedding equals() using Arrays.equals() for embedding array comparison
- Fix Embedding hashCode() using Arrays.hashCode() for proper array hashing
- Add final modifiers to fields in Embedding classes
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
- Remove deprecations from models, vector stores and usage
- Deprecations from FunctionCallback and ObservationContext/Convention will be in a separate PR
Models updates
- Remove AbstractToolCallSupport from the models which use ToolCallingManager
- Remove deprecated constructors and their usage
- Remove FunctionCallbackResolver and FunctionCallbacks usage in the models
- Add back deprecations for VectorStoreChatMemoryAdvisor until builder is fixed
- Update OpenAiPaymentTransactionIT to use ToolCallbackResolver in config
Signed-off-by: Ilayaperumal Gopinathan <ilayaperumal.gopinathan@broadcom.com>
When using the RetrievalAugmentationAdvisor with the VectorStoreDocumentRetriever, it’s now possible to provide a filter expression at request-time as an advisor context variable with key VectorStoreDocumentRetriever.FILTER_EXPRESSION.
Fixes gh-1776
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Updated `SearchRequest.java` to make the class non-final.
- Added `MilvusSearchRequest` with specific Milvus parameters such as `nativeExpression` and `searchParamsJson`.
- Modified `doSimilaritySearch` method in `MilvusVectorStore` to handle these new fields from `MilvusSearchRequest`.
Add unit tests for MilvusVectorStore and MilvusSearchRequest
Introduce comprehensive unit tests to validate the functionality of MilvusVectorStore and MilvusSearchRequest, including scenarios for native and filter expressions. Refactor MilvusVectorStore to improve filter expression handling by introducing a helper method for converted expressions.
Add detailed documentation for MilvusSearchRequest usage
Introduced sections explaining MilvusSearchRequest's parameters, `nativeExpression`, and `searchParamsJson`, with examples for enhanced clarity. This update provides guidance on leveraging Milvus-specific features for precise filtering and optimal search performance.
Signed-off-by: waileong <wai_leong1015@hotmail.com>
This enhancement adds a documentFormatter parameter to ContextualQueryAugmenter,
allowing users to customize how documents are formatted in the context.
If not specified, the original document formatting logic is preserved.
Signed-off-by: magicgone <magic4gone@gmail.com>
Changes the validation logic in MethodToolCallback to check if a ToolContext is required by the method but not provided,
rather than checking if a ToolContext is provided but not supported by the method.
This ensures methods that expect a ToolContext parameter receive one.
Updates tests cases to reflect the new validation logic
Resolves#2337
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Extends the ToolCallingAutoConfiguration to support both FunctionCallback and ToolCallback types.
- The toolCallbackResolver bean now handles both callback types through ObjectProvider injection.
- Added comprehensive tests to verify the resolution of multiple function and tool callbacks.
- Introduce new StaticToolCallbackProvider implementation
- Update ToolCallbackProvider to return FunctionCallback[]
- Migrate from List to ToolCallbackProvider in configurations
- Update tests to use new provider pattern
- Enhance tool callback providers to support multiple clients
- Refactor AsyncMcpToolCallbackProvider and SyncMcpToolCallbackProvider to handle multiple MCP clients
- Add ToolCallbackProvider support to ChatClient API
- Deprecate direct tool callback list methods in favor of providers
- Fix typos in Closeable class names
- Update MCP documentation with new examples and usage patterns
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Update AnthropicChatModel to use the new ToolCallingManager API, while ensuring full API backward compatibility.
- Introduce Builder to instantiate a new AnthropicChatModel since the number of overloaded constructors is growing too big.
- Update documentation about tool calling and Anthropic support for that.
Part of the #2207 epic
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Each ModelObservationContext takes both a request object (e.g. Prompt) and an options object (e.g. ChatOptions). However, the options are already included in the request object. This PR deprecates the additional field, which will be removed in a subsequent release.
The reason why the extra field was there in the first place was due to the model implementations not handling request options correctly, requiring a dedicated setter. We started fixing the model implementations now, so we are deprecating te extra field, and we'll remove it in the next release, once we have completed the implementation of a fix for all model implementations.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Migrate from function calling to tool calling API
- Add support for Gemini 2.0 models (flash, flash-lite)
- Implement JSON schema to OpenAPI schema conversion
- Add builder pattern for improved configuration
- Deprecate legacy function calling constructors and methods
- Update default model to GEMINI_2_0_FLASH
- Add comprehensive test coverage for tool calling
- Upgrade victools dependency to 4.37.0
- Update the Vertex Tool calling docs
Part of the #2207 epic
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Additiona fixes: API key validation and tool calling backward compatibility
- Fix API key validation in OpenAiApi builder
- Standardize API key validation using Assert.notNull
- Add backward compatibility support for FunctionCallback in tool calling
- Update integration tests to use LegacyToolCallingManager
Co-authored-by:Christian Tzolov <christian.tzolov@broadcom.com>
Signed-off-by: Ricken Bazolo <ricken.bazolo@gmail.com>
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Update OpenAiChatModel to use the new ToolCallingManager API, while ensuring full API backward compatibility.
- Introduce Builder to instantiate a new OpenAiChatModel since the number of overloaded constructors is growing too big.
- Update documentation about tool calling and OpenAI support for that.
- Add extra validation to ensure the uniqueness of tool names when aggregated from different sources.
- Ensure consistent merging of options, following Spring Boot strategy.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Change VectorStore.delete() and related implementations to return void instead of Optional<Boolean>
- Remove unnecessary boolean return values and success status checks across all vector store implementations
- Clean up tests by removing redundant assertions
- Implementations continue using runtime exceptions for error signaling
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
When fields in OllamaOptions are marked as ignored in Jackson, they require explicit merge of runtime and default options.
Added tests to validate the different merge combinations for all tool-related options.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Adds comprehensive Model Context Protocol (MCP) integration to Spring AI, including:
Core Features:
- MCP client implementation with Spring AI tool calling capabilities
- Spring-friendly abstractions for MCP clients and servers
- Both synchronous and asynchronous MCP server operation modes
- Add MCP client autoconfiguration with support for STDIO, WebMVC and WebFlux transports
- Auto-configuration for MCP server components
- Spring Boot starter (spring-ai-starter-mcp) with WebFlux and WebMVC support
- MCP dependency management with BOM
- Add close() method to McpToolCallback for proper resource cleanup
- Add initialize flag to control MCP client initialization
- Add comprehensive integration tests and documentation for MCP client configuration
Technical Improvements:
- Split WebMvc and WebFlux configurations into separate auto-configuration classes
- Server type configurable via 'spring.ai.mcp.server.type' property (SYNC/ASYNC)
- Comprehensive test coverage including McpServerAutoConfigurationIT
- Utility classes for converting between Spring AI tools and MCP tools
- MCP SDK version management in parent pom
Reorganize MCP tool utilities and client configuration
- Rename ToolUtils to McpToolUtils for better MCP-specific naming
- Rename McpToolCallbackProvider to SyncMcpToolCallbackProvider
- Add utility methods for handling tool callbacks in McpToolUtils
- Extract client configuration logic into new McpClientDefinitions class
- Add tool callback support to ChatClient interface and implementations
- Remove redundant integration test
Introduce MCP client customization support
- Add McpSyncClientCustomizer interface for customizing MCP sync clients
- Replace McpClientDefinitions with McpSyncClientConfigurer
- Refactor MCP client initialization to support customization
- Remove redundant close() method from McpToolCallback
- Fix conditional class dependencies in WebMvc/Flux configurations
Add MCP AOT hints
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Introduces a new API key interface that allows users to customize how
API keys are provided and managed in their Spring AI applications. This
change improves security and flexibility by:
- Adding core ApiKey interface and SimpleApiKey implementation
- Adding builder pattern for OpenAiApi creation
- Deprecating public constructors in favor of builder API (since 1.0.0.M6)
- Added docs
The new system enables users to implement their own key management
strategies while maintaining backward compatibility with property-based
configuration.
Introduce a utility class `LoggingMarkers` providing an SLF4J marker for tagging log entries with Personally Identifiable Information (PII). Update `BeanOutputConverter` to use the `PII_MARKER` in error logs for invalid JSON conversions. Enhance tests to verify PII marker usage in logging.
- Set Java version dynamically and configure Kotlin compiler
- Updated Maven configurations to dynamically reference the Java version using `${java.version}`. Added Kotlin compiler settings, including `jvmTarget` alignment with Java version and enabling `javaParameters`. This ensures consistency and better compatibility across builds.
- Fix log assertion in BeanOutputConverterTest to use Java 17
- Updated the test to assert log size explicitly before accessing the first log entry. This ensures the test is more robust and avoids potential issues with accessing logs unexpectedly.
- Use placeholders in logger.error to prevent string concatenation.
- Replaced string concatenation with a placeholder in the logger.error call to improve performance and maintain consistency with logging best practices. This helps avoid unnecessary overhead when logging is disabled.
- Update logging markers and improve data classification
- Replaced `PII_MARKER` with `SENSITIVE_DATA_MARKER`. Introduced `RESTRICTED_DATA_MARKER`, `REGULATED_DATA_MARKER` and `PUBLIC_DATA_MARKER`
- Updated associated logging logic and tests to reflect these changes.
- Fix punctuation in Javadoc comments for LoggingMarkers.
- Added missing periods to improve consistency and clarity in the Javadoc comments. This change ensures proper formatting and adheres to standard writing conventions.
Signed-off-by: Konstantin Pavlov <{ID}+{username}@users.noreply.github.com>
* Completed new documentation for Tool Calling
* Added deprecation notes and migration guide to documentation
* Made “call” methods explicit in ToolCallback API
* Consolidated naming: ToolCallExceptionConverter -> ToolExecutionExceptionProcessor
* Consolidated naming: ToolCallResultConvert.apply() -> ToolCallResultConvert.convert()
* Redraw diagrams for consistency
Relates to gh-2049
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
* Introduced new ToolParam annotation for defining a description for tool parameters and marking them as (non)required.
* Improved the JSON Schema generation for tools, solving inconsistencies between methods and functions, and ensuring a predictable outcome.
* Added support for returning tool results directly to the user instead of passing them back to the model. Introduced new ToolExecutionResult API to propagate this information.
* Consolidated naming of tool-related options in ToolCallingChatOptions.
* Fixed varargs issue in ChatClient when passing ToolCallback[].
* Introduced new documentation for the tool calling capabilities in Spring AI, and deprecated the old one.
* Bumped jsonschema dependency to 4.37.0.
Relates to gh-2049
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Adds getNativeClient API to VectorStore interface allowing access to the underlying native client implementation.
This change:
- Adds getNativeClient() default method to VectorStore interface returning Optional<T>
- Implements getNativeClient() in all vector store implementations exposing their respective native clients
- Adds integration tests verifying native client access for all implementations
Fixes: #2137
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
* Adopted new tool calling logic in OllamaChatModel, while maintaining full API backward compatibility thanks to the LegacyToolCallingManager.
* Improved efficiency and robustness of merging options in prompts for Ollama.
* Update Ollama Autoconfiguration to use the new ToolCallingManager.
* Improved troubleshooting for new tool calling APIs and finalised changes for full backward compatibility.
* Updated Ollama Testcontainers dependency to 0.5.7.
Relates to gh-2049
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Refactors the test codebase to use tools instead of functions.
- Rename FunctionCallback to FunctionToolCallback
- Rename FunctionCallingOptions to ToolCallingChatOptions
- Update API methods from functions() to tools()
- Deprecate function-related methods in favor of tool alternatives
- Refactor MethodToolCallback implementation with improved builder pattern
- Update all tests to use new tool-based APIs
- Add funcs to tools migration guide
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
* Introduced ToolCallingManager to manage the tool calling activities for resolving and executing tools. A default implementation is provided. It can be used to handle explicit tool execution on the client-side, superseding the previous FunctionCallingHelper class. It’s ready to be instrumented via Micrometer, and support exception handling when tool calls fail.
* Introduced ToolCallExceptionConverter to handle exceptions in tool calling, and provided a default implementation propagating the error message to the chat morel.
* Introduced ToolCallbackResolver to resolve ToolCallback instances. A default implementation is provided (DelegatingToolCallbackResolver), capable of delegating the resolution to a series of resolvers, including static resolution (StaticToolCallbackResolver) and dynamic resolution from the Spring context (SpringBeanToolCallbackResolver).
* Improved configuration in ToolCallingChatOptions to enable/disable the tool execution within a ChatModel (superseding the previous proxyToolCalls option).
* Added unit and integration tests to cover all the new use cases and existing functionality which was not covered by autotests (tool resolution from Spring context).
* Deprecated FunctionCallbackResolver, AbstractToolCallSupport, and FunctionCallingHelper.
Relates to gh-2049
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Remove model specific Usage implementations
- Add `Object getNativeUsage()` to Usage interface
- This will allow the model specific Usage data to be returned
- At the client side, client needs to cast the return type of `getNativeUsage` into the corresponding Usage returned by the model API
- Rename `generationTokens` to `completionTokens`
- Since `completion` token name is more common among the models, renaming generation tokens into completion tokens
- Maintain JSON deserialization compatibility for legacy `generationTokens` field
- Remove deprecated Long-based constructors to avoid API ambiguity
- Change the prompt, completion and total token return types from Long to Integer
- This is a breaking change that requires updating all constructor calls
- Integer is sufficient for token counts and aligns better with most model APIs
- Use DefaultUsage for most of the model specific usage handling
- When initializing set the native usage to the model specific usage type
- Ensure immutability by making all fields final and removing setters
- Add comprehensive test coverage for all functionality including edge cases
Resolves#1407
* Enhanced support for functions as tools via FunctionToolCallback (deprecating the existing FunctionInvokingFunctionCallback).
* Aligned JSON Schema generation and parsing logic between function-based and method-based tools.
* Deprecated previous client-side function calling APIs.
* Included AOT configuration for Tool-annotated methods in Spring beans.
Relates to gh-2049
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Add string-based filter deletion alongside the Filter.Expression-based deletion
for vector stores. This provides a more convenient API for simple filter cases
while maintaining the full flexibility of expression-based filtering.
Key changes:
- Add delete(Filter.Expression) and delete(String) methods to VectorStore
- Add default string filter implementation in VectorStore interface
- Implement filter deletion in Chroma/Elasticsearch/PgVector stores
- Add integration tests for both filter APIs across implementations
This extends vector store deletion capabilities while maintaining consistent
behavior across implementations.
