Spring/spring-ai
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update upgrade notes

Browse Source
This commit is contained in:
Mark Pollack
2025-04-10 13:49:13 -04:00
parent 352c0d83be
commit d4a3f7a774
1 changed files with 206 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

349
spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc
View File

@@ -4,38 +4,165 @@
[[upgrading-to-1-0-0-snapshot]]
== Upgrading to 1.0.0-SNAPSHOT
== Part 1
You can upgrade to 1.0.0-SNAPSHOT either by following the manual steps outlined below or by using an automated approach with the Claude Code CLI tool and a provided prompt.
=== Overview
The 1.0.0-SNAPSHOT version includes significant changes to artifact IDs, package names, and module structure. This section provides guidance specific to using the SNAPSHOT version.
The automated approach can save time and reduce errors when upgrading multiple projects or complex codebases.
For details on the automated approach, see the xref:upgrade-notes.adoc#automating-upgrading-using-ai[Automating upgrading using AI] section.
=== Add Snapshot Repositories
=== Manual Upgrade
==== Add Snapshot Repositories
To use the 1.0.0-SNAPSHOT version, you need to add the snapshot repositories to your build file.
To use the 1.0.0-SNAPSHOT version, you need to add the snapshot repositories to your build file.
For detailed instructions, refer to the xref:getting-started.adoc#snapshots-add-snapshot-repositories[Snapshots - Add Snapshot Repositories] section in the Getting Started guide.
==== Update Dependency Management
=== Update Dependency Management
Update your Spring AI BOM version to `1.0.0-SNAPSHOT` in your build configuration.
Update your Spring AI BOM version to `1.0.0-SNAPSHOT` in your build configuration.
For detailed instructions on configuring dependency management, refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section in the Getting Started guide.
==== Changes to Spring AI Artifact IDs
=== Artifact ID, Package, and Module Changes
The 1.0.0-SNAPSHOT includes changes to artifact IDs, package names, and module structure.
The naming pattern for Spring AI starter artifacts has changed in 1.0.0-SNAPSHOT.
For details, refer to:
- xref:upgrade-notes.adoc#common-artifact-id-changes[Common Artifact ID Changes]
- xref:upgrade-notes.adoc#common-package-changes[Common Package Changes]
- xref:upgrade-notes.adoc#common-module-structure[Common Module Structure]
[[automating-upgrading-using-ai]]
=== Automating upgrading using AI
You can automate the upgrade process to 1.0.0-SNAPSHOT using the Claude Code CLI tool with a provided prompt. The prompt will guide the AI to perform the following tasks:
1. Update the Spring AI BOM version to 1.0.0-SNAPSHOT
2. Ensure all required repositories exist in your build configuration
3. Update Spring AI artifact IDs according to the new naming patterns
To use this automation:
1. Download the https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview[Claude Code CLI tool]
2. Copy the prompt from the https://github.com/spring-projects/spring-ai/blob/main/src/prompts/update-to-snapshot.txt[update-to-snapshot.txt] file
3. Paste the prompt into the Claude Code CLI
4. The AI will analyze your project and make the necessary changes
This approach can save time and reduce the chance of errors when upgrading multiple projects or complex codebases.
[[upgrading-to-1-0-0-m7]]
== Upgrading to 1.0.0-M7
=== Overview of Changes
Spring AI 1.0.0-M7 is the last milestone release before the RC1 and GA releases. It introduces several important changes to artifact IDs, package names, and module structure that will be maintained in the final release.
=== Artifact ID, Package, and Module Changes
The 1.0.0-M7 includes the same structural changes as 1.0.0-SNAPSHOT.
For details, refer to:
- xref:upgrade-notes.adoc#common-artifact-id-changes[Common Artifact ID Changes]
- xref:upgrade-notes.adoc#common-package-changes[Common Package Changes]
- xref:upgrade-notes.adoc#common-module-structure[Common Module Structure]
=== MCP Java SDK Upgrade to 0.9.0
Spring AI 1.0.0-M7 now uses MCP Java SDK version 0.9.0, which includes significant changes from previous versions. If you're using MCP in your applications, you'll need to update your code to accommodate these changes.
Key changes include:
==== Interface Renaming
* `ClientMcpTransport` → `McpClientTransport`
* `ServerMcpTransport` → `McpServerTransport`
* `DefaultMcpSession` → `McpClientSession` or `McpServerSession`
* All `*Registration` classes → `*Specification` classes
==== Server Creation Changes
* Use `McpServerTransportProvider` instead of `ServerMcpTransport`
[source,java]
----
// Before
ServerMcpTransport transport = new WebFluxSseServerTransport(objectMapper, "/mcp/message");
var server = McpServer.sync(transport)
.serverInfo("my-server", "1.0.0")
.build();
// After
McpServerTransportProvider transportProvider = new WebFluxSseServerTransportProvider(objectMapper, "/mcp/message");
var server = McpServer.sync(transportProvider)
.serverInfo("my-server", "1.0.0")
.build();
----
==== Handler Signature Changes
All handlers now receive an `exchange` parameter as their first argument:
[source,java]
----
// Before
.tool(calculatorTool, args -> new CallToolResult("Result: " + calculate(args)))
// After
.tool(calculatorTool, (exchange, args) -> new CallToolResult("Result: " + calculate(args)))
----
==== Client Interaction via Exchange
Methods previously available on the server are now accessed through the exchange object:
[source,java]
----
// Before
ClientCapabilities capabilities = server.getClientCapabilities();
CreateMessageResult result = server.createMessage(new CreateMessageRequest(...));
// After
ClientCapabilities capabilities = exchange.getClientCapabilities();
CreateMessageResult result = exchange.createMessage(new CreateMessageRequest(...));
----
==== Roots Change Handlers
[source,java]
----
// Before
.rootsChangeConsumers(List.of(
roots -> System.out.println("Roots changed: " + roots)
))
// After
.rootsChangeHandlers(List.of(
(exchange, roots) -> System.out.println("Roots changed: " + roots)
))
----
For a complete guide to migrating MCP code, refer to the https://github.com/spring-projects/spring-ai/blob/main/spring-ai-docs/src/main/antora/modules/ROOT/pages/mcp-migration.adoc[MCP Migration Guide].
=== Automating upgrading using AI
You can automate the upgrade process to 1.0.0-M7 using the Claude Code CLI tool with a provided prompt:
1. Download the https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview[Claude Code CLI tool]
2. Copy the prompt from the https://github.com/spring-projects/spring-ai/blob/main/src/prompts/update-to-m7.txt[update-to-m7.txt] file
3. Paste the prompt into the Claude Code CLI
4. The AI will analyze your project and make the necessary changes
NOTE: The automated upgrade prompt currently handles artifact ID changes, package relocations, and module structure changes, but does not yet include automatic changes for upgrading to MCP 0.9.0. If you're using MCP, you'll need to manually update your code following the guidance in the xref:upgrade-notes.adoc#mcp-java-sdk-upgrade-to-0-9-0[MCP Java SDK Upgrade] section.
[[common-sections]]
== Common Changes Across Versions
[[common-artifact-id-changes]]
=== Artifact ID Changes
The naming pattern for Spring AI starter artifacts has changed.
You'll need to update your dependencies according to the following patterns:
* Model starters: `spring-ai-\{model\}-spring-boot-starter` → `spring-ai-starter-model-\{model\}`
* Vector Store starters: `spring-ai-\{store\}-store-spring-boot-starter` → `spring-ai-starter-vector-store-\{store\}`
* MCP starters: `spring-ai-mcp-\{type\}-spring-boot-starter` → `spring-ai-starter-mcp-\{type\}`
===== Examples
==== Examples
[tabs]
======
Maven::
Maven::
+
[source,xml,indent=0,subs="verbatim,quotes"]
----
@@ -52,7 +179,7 @@ Maven::
</dependency>
----
Gradle::
Gradle::
+
[source,groovy,indent=0,subs="verbatim,quotes"]
----
@@ -68,8 +195,8 @@ implementation 'org.springframework.ai:spring-ai-starter-vector-store-redis'
==== Changes to Spring AI Autoconfiguration Artifacts
The Spring AI autoconfiguration has changed from a single monolithic artifact to individual autoconfiguration artifacts per model, vector store, and other components.
This change was made to minimize the impact of different versions of dependent libraries conflicting, such as Google Protocol Buffers, Google RPC, and others.
The Spring AI autoconfiguration has changed from a single monolithic artifact to individual autoconfiguration artifacts per model, vector store, and other components.
This change was made to minimize the impact of different versions of dependent libraries conflicting, such as Google Protocol Buffers, Google RPC, and others.
By separating autoconfiguration into component-specific artifacts, you can avoid pulling in unnecessary dependencies and reduce the risk of version conflicts in your application.
The original monolithic artifact is no longer available:
@@ -90,11 +217,11 @@ Instead, each component now has its own autoconfiguration artifact following the
* Vector Store autoconfiguration: `spring-ai-autoconfigure-vector-store-\{store\}`
* MCP autoconfiguration: `spring-ai-autoconfigure-mcp-\{type\}`
===== Examples of New Autoconfiguration Artifacts
==== Examples of New Autoconfiguration Artifacts
[tabs]
======
Models::
Models::
+
[source,xml,indent=0,subs="verbatim,quotes"]
----
@@ -114,7 +241,7 @@ Models::
</dependency>
----
Vector Stores::
Vector Stores::
+
[source,xml,indent=0,subs="verbatim,quotes"]
----
@@ -134,7 +261,7 @@ Vector Stores::
</dependency>
----
MCP::
MCP::
+
[source,xml,indent=0,subs="verbatim,quotes"]
----
@@ -150,107 +277,77 @@ MCP::
----
======
NOTE: In most cases, you won't need to explicitly add these autoconfiguration dependencies.
NOTE: In most cases, you won't need to explicitly add these autoconfiguration dependencies.
They are included transitively when using the corresponding starter dependencies.
[[automating-upgrading-using-ai]]
=== Automating upgrading using AI
You can automate the upgrade process to 1.0.0-SNAPSHOT using the Claude Code CLI tool with a provided prompt. The prompt will guide the AI to perform the following tasks:
1. Update the Spring AI BOM version to 1.0.0-SNAPSHOT
2. Ensure all required repositories exist in your build configuration
3. Update Spring AI artifact IDs according to the new naming patterns
To use this automation:
1. Download the https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview[Claude Code CLI tool]
2. Copy the prompt from the https://github.com/spring-projects/spring-ai/blob/main/src/prompts/update-to-snapshot.txt[update-to-snapshot.txt] file
3. Paste the prompt into the Claude Code CLI
4. The AI will analyze your project and make the necessary changes
This approach can save time and reduce the chance of errors when upgrading multiple projects or complex codebases.
== Part 2
As of April 4, the main branch now has changes to module/artifact structure of the project.
Since the start of the Spring AI project, there has been one central artifact where the main interfaces are defined, the `spring-ai-core` module.
Over time, this has grown to contain multiple specialized domains and we wanted to separate these domain out into their own modules.
For example, to use the `ChatClient` functionality, there does not need to be any classes related to Vector Stores in your application.
The `spring-ai-core` module had a clean Dependency Structure Matrix, so most of the work to break up this module was simply cut and pasting code.
However, there were a few cases where the package names of classes have been changed.
=== Changes to package names
[[common-package-changes]]
=== Package Name Changes
Your IDE should assist with refactoring to the new package locations.
`KeywordMetadataEnricher` and SummaryMetadataEnricher` have moved from `org.springframework.ai.transformer` to `org.springframework.ai.chat.transformer`.
* `KeywordMetadataEnricher` and `SummaryMetadataEnricher` have moved from `org.springframework.ai.transformer` to `org.springframework.ai.chat.transformer`.
* `Content`, `MediaContent`, and `Media` have moved from `org.springframework.ai.model` to `org.springframework.ai.content`.
`Content`, `MediaContent`, and `Media` have moved from `org.springframework.ai.model` to `org.springframework.ai.content`.
[[common-module-structure]]
=== Module Structure
The project has undergone significant changes to its module and artifact structure. Previously, `spring-ai-core` contained all central interfaces, but this has now been split into specialized domain modules to reduce unnecessary dependencies in your applications.
=== New Modules Overview
image::spring-ai-dependencies.png[Spring AI Dependencies, width=1000, align="center"]
image::spring-ai-dependencies.png[Spring AI Dependnecies, width=1000, align="center"]
==== spring-ai-commons
==== `spring-ai-commons`
Base module with no dependencies on other Spring AI modules. Contains:
- Core domain models (`Document`, `TextSplitter`)
- JSON utilities and resource handling
- Structured logging and observability support
This is a base module with no dependencies on other Spring AI modules.
It defines core domain models (`Document`, `TextSplitter`, etc.), JSON utilities, resource handling, and structured logging.
Supports document processing, tokenization, embedding optimization, and observability via operation metadata and metrics.
==== spring-ai-model
==== `spring-ai-model`
Provides AI capability abstractions:
- Interfaces like `ChatModel`, `EmbeddingModel`, and `ImageModel`
- Message types and prompt templates
- Function-calling framework (`ToolDefinition`, `ToolCallback`)
- Content filtering and observation support
Provides abstractions for AI capabilities via interfaces like `ChatModel`, `EmbeddingModel`, and `ImageModel`.
Includes message types, prompt templates, response structures, and a full function-calling framework (`ToolDefinition`, `ToolCallback`, annotations).
Supports observation, content filtering, and consistent builder/strategy patterns across AI providers.
==== spring-ai-vector-store
==== `spring-ai-vector-store`
Unified vector database abstraction:
- `VectorStore` interface for similarity search
- Advanced filtering with SQL-like expressions
- `SimpleVectorStore` for in-memory usage
- Batching support for embeddings
Defines a unified abstraction (`VectorStore`) for vector databases and similarity search.
Includes advanced filtering via SQL-like expressions, `SearchRequest`, and `Filter.Expression.`
Offers `SimpleVectorStore` (in-memory) and observability integration.
Emphasizes type safety, extensibility, and batching support for embeddings.
==== spring-ai-client-chat
==== `spring-ai-client-chat`
High-level conversational AI APIs:
- `ChatClient` interface
- Conversation persistence via `ChatMemory`
- Response conversion with `OutputConverter`
- Advisor-based interception
- Synchronous and reactive streaming support
This module provides high-level APIs for conversational AI via the `ChatClient` interface.
Includes conversation persistence (`ChatMemory`), response conversion (`OutputConverter`), and advisor-based interception.
Supports synchronous and streaming (Project Reactor) interactions with observability via Micrometer.
==== spring-ai-advisors-vector-store
This client layer abstracts away the complexities of different AI model implementations, providing application developers with a uniform way to incorporate conversational AI capabilities while handling common concerns like conversation state management, response transformation, and instrumentation in a consistent manner.
Bridges chat with vector stores for RAG:
- `QuestionAnswerAdvisor`: injects context into prompts
- `VectorStoreChatMemoryAdvisor`: stores/retrieves conversation history
==== `spring-ai-advisors-vector-store`
==== spring-ai-model-chat-memory-cassandra
Bridges chat with vector stores for RAG and persistent memory.
Apache Cassandra persistence for `ChatMemory`:
- `CassandraChatMemory` implementation
- Type-safe CQL with Cassandra's QueryBuilder
==== spring-ai-model-chat-memory-neo4j
`QuestionAnswerAdvisor`: injects context into prompts using similarity search.
Neo4j graph database persistence for chat conversations.
`VectorStoreChatMemoryAdvisor`: stores/retrieves conversation history in vector stores, with filtering and session continuity.
==== spring-ai-rag
This component is essential for implementing sophisticated conversational applications that require both context retrieval and memory persistence within the Spring AI ecosystem.
==== `spring-ai-model-chat-memory-cassandra`
This module adds Apache Cassandra persistence for `ChatMemory` (via `CassandraChatMemory`).
Extracted from the Cassandra vector store module to provide a standalone, production-ready solution.
Uses immutable config records and Cassandra's QueryBuilder for type-safe CQL.
==== `spring-ai-model-chat-memory-neo4j`
This module provides Neo4j graph database persistence for chat conversations.
This functionality was previously located in the Neo4j vector store implementation module, but has been extracted to create a dedicated chat memory solution.
==== `spring-ai-rag`
This module provides a comprehensive framework for implementing Retrieval Augmented Generation (RAG)
pipelines based on a modular architecture inspired by academic research.
It offers a structured approach to the entire RAG workflow through well-defined interfaces for each stage of the process.
The central `RetrievalAugmentationAdvisor` serves as the main entry point, orchestrating the entire RAG workflow.
The design follows functional programming principles with composable components, enabling customization of each pipeline stage while maintaining a consistent programming model aligned with Spring's conventions.
Comprehensive framework for Retrieval Augmented Generation:
- Modular architecture for RAG pipelines
- `RetrievalAugmentationAdvisor` as main entry point
- Functional programming principles with composable components
=== Dependency Structure
@@ -262,54 +359,20 @@ The dependency hierarchy can be summarized as:
* `spring-ai-advisors-vector-store` and `spring-ai-rag` (depend on both client-chat and vector-store)
* `spring-ai-model-chat-memory-*` modules (depend on client-chat)
The details are:
[[common-toolcontext-changes]]
=== ToolContext Changes
=== Module Dependencies
The `ToolContext` class has been enhanced to support both explicit and implicit tool resolution. Tools can now be:
[cols="1,3,3", options="header"]
|===
| Module
| Depends On
| Description
1. **Explicitly Included**: Tools that are explicitly requested in the prompt and included in the call to the model.
2. **Implicitly Available**: Tools that are made available for runtime dynamic resolution, but never included in any call to the model unless explicitly requested.
| `spring-ai-commons`
| _None_
| Base module with no dependencies on other Spring AI modules. Used by many other modules.
Starting with 1.0.0-M7, tools are only included in the call to the model if they are explicitly requested in the prompt or explicitly included in the call.
| `spring-ai-model`
| `spring-ai-commons`
| Provides core model interfaces and abstractions.
Additionally, the `ToolContext` class has now been marked as final and cannot be extended anymore. It was never supposed to be subclassed. You can add all the contextual data you need when instantiating a `ToolContext`, in the form of a `Map<String, Object>`. For more information, check the [documentation](https://docs.spring.io/spring-ai/reference/api/tools.html#_tool_context).
| `spring-ai-vector-store`
| `spring-ai-model` → `spring-ai-commons`
| Provides vector database abstractions.
| `spring-ai-client-chat`
| `spring-ai-model` → `spring-ai-commons`
| High-level client API for chat interactions.
| `spring-ai-advisors-vector-store`
| `spring-ai-client-chat`, `spring-ai-vector-store`
| Bridges chat capabilities with vector stores.
| `spring-ai-model-chat-memory-cassandra`
| `spring-ai-client-chat`
| Provides Cassandra implementation for chat memory.
| `spring-ai-model-chat-memory-neo4j`
| `spring-ai-client-chat`
| Provides Neo4j implementation for chat memory.
| `spring-ai-rag`
| `spring-ai-client-chat`, `spring-ai-vector-store`
| Provides RAG framework implementation.
|===
=== ToolContext changes
* The `ToolContext` class has now been marked as final and cannot be extended anymore. It was never supposed to be subclassed. You can add all the contextual data you need when instantiating a `ToolContext`, in the form of a `Map<String, Object>`. For more information, check the [documentation](https://docs.spring.io/spring-ai/reference/api/tools.html#_tool_context).
== Upgrading to 1.0.0.M6
[[upgrading-to-1-0-0-m6]]
== Upgrading to 1.0.0-M6
=== Changes to Usage Interface and DefaultUsage Implementation