- Remove deprecated ChatMemory.get(String conversationId, int lastN) method
- Replace AbstractChatMemoryAdvisor with BaseChatMemoryAdvisor interface in api package
- Make constructors private in all memory advisor implementations to enforce builder usage
- Rename CHAT_MEMORY_CONVERSATION_ID_KEY to CONVERSATION_ID and move to ChatMemory interface
- In VectorStoreChatMemoryAdvisor:
- Rename DEFAULT_CHAT_MEMORY_RESPONSE_SIZE (100) to DEFAULT_TOP_K (20)
- Rename builder method chatMemoryRetrieveSize() to topK()
- Remove systemTextAdvise() builder method
- In PromptChatMemoryAdvisor:
- Remove systemTextAdvise() builder method
- Fix bug where only the last user message was stored from prompts with multiple messages
- Enhance logging in memory advisors to aid in debugging
- Add comprehensive tests for all advisor implementations:
- Unit tests for builder behavior
- Integration tests for the various chat memory advisors
Signed-off-by: Mark Pollack <mark.pollack@broadcom.com>
Remove circular dependencies:
Move utility classes from various packages to dedicated support packages:
- Move ToolCallbacks from ai.tool to ai.support
- Move UsageUtils to UsageCalculator in ai.support
- Move tool.util to tool.support
- Create new ToolDefinitions utility class
Support packages for the classes in question is more idomatic in spring than util packages.
Signed-off-by: Mark Pollack <mark.pollack@broadcom.com>
The built-in advisors that perform prompt augmentation have been updated to use self-contained templates. The goal is for each advisor to be able to perform templating operations without affecting nor being affected by templating and prompt decisions in other advisors.
* QuestionAnswerAdvisor
* PromptChatMemoryAdvisor
* VectorStoreChatMemoryAdvisor
Documentation and upgrade notes have been updated accordingly
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
The DocumentPostProcessor is one of the modular RAG components introduce in M8. You can now use this API from within the RetrievalAugmentationAdvisor to post-process the retrieved documents before passing them to the model. For example, you can use such an interface to perform re-ranking of the retrieved documents based on their relevance to the query, remove irrelevant or redundant documents, or compress the content of each document to reduce noise and redundancy.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Output format instructions should not be included until the very last advisor runs, otherwise there's a risk of templating failure if more than one advisor tries to render the prompt template. This change guarantees the output format instructions are always included right before calling the chat model, without the risk of previous advisors interfering with it.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Move evaluation core classes (Request, Response, Evaluator) to spring-ai-commons.
- Move chat-specific evaluators (FactChecking, Relevancy) to spring-ai-client-chat#evaluation package.
- Move OutputConverter implementations and related classes to spring-ai-model#converter package.
- Move MetadataEnricher transformer classes to spring-ai-model#transformer package.
- Move PromptAssert utility to spring-ai-rag#util package.
- Update relevant pom.xml files and adjust imports in affected classes.
- Document class movements in upgrade-notes.adoc for M8 release.
This refactoring improves module organization and separation of concerns.
Signed-off-by: Mark Pollack <mark.pollack@broadcom.com>
Renames the ambiguous overloaded `tools` methods in `ChatClient.PromptRequestSpec`
to `toolNames` and `toolCallbacks` respectively. This improves clarity
and prevents potential issues with method dispatching based on argument types.
Updates relevant code examples and adds documentation to upgrade notes.
Signed-off-by: Mark Pollack <mark.pollack@broadcom.com>
- Extend the ChatClient with a new templateRenderer() method to pass a custom TemplateRenderer object used to render user and system templates.
- Evolve the QuestionAnswerAdvisor to accept a PromptTemplate for customising the RAG prompt and templating logic while maintaining backward compatibility.
- Introduce integration tests for the QuestionAnswerAdvisor.
- Document the TemplateRenderer API and how to use it to build PromptTemplate with custom templating logic.
- Document how to customise the templating logic used internally by the ChatClient via the TemplateRendererAPI.
Add validation tests and improve PromptTemplate resource handling
Enhance robustness and reliability of the PromptTemplate class with better
resource handling and comprehensive input validation:
- Add dedicated validation tests for builder methods with null/invalid inputs
- Improve renderResource method to gracefully handle edge cases:
- Null resources return empty string
- ByteArrayResource handling with proper charset (UTF-8)
- Empty resources check with proper existence test
- Better error handling with logging instead of exception propagation
- Add input validation assertions to all Builder methods
- Fix typo in deprecated annotation comment ("fahvor" → "favor")
Update documentation to clarify template rendering in different contexts:
- Add clear notes about TemplateRenderer usage in ChatClient vs Advisors
- Document how advisor template customization differs from ChatClient template rendering
- Add comprehensive API upgrade notes for template-related deprecations
- Include detailed migration examples for PromptTemplate and QuestionAnswerAdvisor
Fixes gh-355, gh-1687, gh-2448, gh-1849, gh-1428
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
* ChatClient observations now include the full prompt content instead of just the userText and systemText. Furthermore, they include consistent telemetry for the tools passed via the ChatClient and a first-class conversation ID when using memory advisors. Incomplete or unsafe attributes have been deprecated.
* Adopted the new robust Advisor APIs for BaseAdvisor and RetrievalAugmentationAdvisor.
* Improved the prompt augmentation facilities in ChatClientRequest and Prompt for performance and immutability.
* Fixed integration test racing condition.
* Updated the documentation for ChatClient and Observability accordingly.
* Documented changes in upgrade notes.
* Introduced `prompt.augmentUserMessage(String text)` to directly replace the user message content.
* Added `prompt.augmentUserMessage(Function<UserMessage, UserMessage> augmenter)` for more granular updates using the `userMessage.mutate()` pattern, allowing modification of text, media, and metadata.
Relates to gh-2655
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Avoid overlapping package names
Changed in spring-ai-commons package from org.sf.ai.model to org.sf.ai.content
Refactor advisor module name to be spring-ai-advisors-vector-store
Moved advisors into org.springframework.ai.chat.client.advisor.vectorstore
- Created top level memory directory
- Create new module spring-ai-model-chat-memory-neo4j and moved neo4j memory classes out of the vectorstore module
Updated neo4j autoconfiguation
- 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>
- 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>
This commit introduces the `JsoupDocumentReader` and `JsoupDocumentReaderConfig` classes, which provide functionality to read and parse HTML documents using the JSoup library.
The reader supports:
- Extracting text from specific HTML elements using CSS selectors.
- Extracting all text from the body of the document.
- Grouping text by element.
- Extracting metadata, including the document title, meta tags, and link URLs.
- Reading from various resource types (files, URLs, byte arrays).
- Configurable character encoding, selector, separator, and metadata extraction.
This new reader enhances Spring AI's ability to process web content and other HTML-based data sources.
Signed-off-by: Alexandros Pappas <apappascs@gmail.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>
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>
* 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>
* Defined new APIs consolidating the “tool” naming as opposed to the current “function”, aligning with the industry and solving the confusion between “function tool” and “Java Function”: ToolCallback and ToolCallingChatOptions. They extend the current ones to ensure backward compatibility, but FunctionCallback and FunctionCallingOptions can be considered deprecated.
* Enhanced support for methods as tools, introducing support for declarative Tool-annotated methods via MethodToolCallback and MethodToolCallbackProvider (deprecating the existing MethodInvokingFunctionCallback).
* Improved tool execution logic with granular support for returning the result directly to the client and exception handling.
* Improved JSON Schema generation and parsing logic, consolidating the usage of the victools/jsonschema-generator library and dropping the non-maintained Jackson JSON Schema Module. This makes it possible to use tools with input lists/arrays, which the latter library was not supporting.
* Extended ChatClient API with new methods tools() and toolCallbacks(). The existing functions() methods can be considered deprecated.
Relates to gh-2049
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
* Extend Query with conversation history in RetrievalAugmentationAdvisor
* Add integration tests for query compression and rewrite
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
* Remove use of Document.getContext method from spring-ai-core, use getText
* Remove deprecated ChatOptionsBuilder class
* Remove deprecated FunctionCallingOptionsBuilder class
* Introduce CompressionQueryTransformer and RewriteQueryTransformer in the Pre-Retrieval Module.
* Extend Query with conversation history and context.
* Remove QueryRouter sub-module. New design will be considered in the next milestone.
* Update RetrievalAugmentationAdvisor accordingly.
* Add initial documentation for Modular RAG, and establish dedicated page for RAG content.
Fixes gh-1850
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Move PgVectorStore and related classes to org.springframework.ai.pg.vectorstore package
- Update builder pattern to use more idiomatic method names (e.g. withSchemaName -> schemaName)
- Deprecate existing constructors and old Builder class in favor of new static builder() method
- Update tests to reflect the new builder style usage
- Update docs
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.
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>
