[[upgrade-notes]]
= Upgrading Notes

== Upgrading to 1.0.0.M2

* The configuration prefix for the Chroma Vector Store has been changes from `spring.ai.vectorstore.chroma.store` to `spring.ai.vectorstore.chroma` in order to align with the naming conventions of other vector stores.

* The default value of the `initialize-schema` property on vector stores capable of initializing a schema is now set to `false`.
This implies that the applications now need to explicitly opt-in for schema initialization on supported vector stores, if the schema is expected to be created at application startup.
Not all vector stores support this property.
See the corresponding vector store documentation for more details.
The following are the vector stores that currently don't support the `initialize-schema` property.

1. Hana
2. Pinecone
3. Weaviate

== Upgrading to 1.0.0.M1

On our march to release 1.0.0 M1 we have made several breaking changes.  Apologies, it is for the best!

=== ChatClient changes

A major change was made that took the 'old' `ChatClient` and moved the functionality into `ChatModel`.  The 'new' `ChatClient` now takes an instance of `ChatModel`. This was done do support a fluent API for creating and executing prompts in a style similar to other client classes in the Spring ecosystem, such as `RestClient`, `WebClient`, and `JdbcClient`.  Refer to the [JavaDoc](https://docs.spring.io/spring-ai/docs/1.0.0-SNAPSHOT/api/) for more information on the Fluent API, proper reference documentation is coming shortly.

We renamed the 'old' `ModelClient` to `Model` and renamed implementing classes, for example `ImageClient` was renamed to `ImageModel`.  The `Model` implementation represent the portability layer that converts between the Spring AI API and the underlying AI Model API.

### Adapting to the changes

NOTE: The `ChatClient` class is now in the package `org.springframework.ai.chat.client`

#### Approach 1

Now, instead of getting an Autoconfigured `ChatClient` instance, you will get a `ChatModel` instance.  The `call` method signatures after renaming remain the same.
To adapt your code should refactor you code to change use of the type `ChatClient` to `ChatModel`
Here is an example of existing code before the change

```java
@RestController
public class OldSimpleAiController {

    private final ChatClient chatClient;

    public OldSimpleAiController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/ai/simple")
    Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", chatClient.call(message));
    }
}
```

Now after the changes this will be

```java
@RestController
public class SimpleAiController {

    private final ChatModel chatModel;

    public SimpleAiController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/simple")
    Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", chatModel.call(message));
    }
}
```

NOTE: The renaming also applies to the classes
* `StreamingChatClient` -> `StreamingChatModel`
* `EmbeddingClient` -> `EmbeddingModel`
* `ImageClient` -> `ImageModel`
* `SpeechClient` -> `SpeechModel`
* and similar for other `<XYZ>Client` classes

#### Approach 2

In this approach you will use the new fluent API available on the 'new' `ChatClient`

Here is an example of existing code before the change

```java
@RestController
class OldSimpleAiController {

    ChatClient chatClient;

    OldSimpleAiController(ChatClient chatClient) {
        this.chatClient = chatClient;
	}

	@GetMapping("/ai/simple")
	Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
		return Map.of(
                "generation",
                chatClient.call(message)
        );
	}
}
```

Now after the changes this will be

```java
@RestController
class SimpleAiController {

    private final ChatClient chatClient;

    SimpleAiController(ChatClient.Builder builder) {
      this.chatClient = builder.build();
    }

    @GetMapping("/ai/simple")
    Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of(
                "generation",
                chatClient.prompt().user(message).call().content()
        );
    }
}
```


NOTE: The `ChatModel` instance is made available to you through autoconfiguration.

#### Approach 3

There is a tag in the GitHub repository called [v1.0.0-SNAPSHOT-before-chatclient-changes](https://github.com/spring-projects/spring-ai/tree/v1.0.0-SNAPSHOT-before-chatclient-changes) that you can checkout and do a local build to avoid updating any of your code until you are ready to migrate your code base.

```bash
git checkout tags/v1.0.0-SNAPSHOT-before-chatclient-changes

./mvnw clean install -DskipTests
```


=== Artifact name changes

Renamed POM artifact names:
- spring-ai-qdrant -> spring-ai-qdrant-store
- spring-ai-cassandra -> spring-ai-cassandra-store
- spring-ai-pinecone -> spring-ai-pinecone-store
- spring-ai-redis -> spring-ai-redis-store
- spring-ai-qdrant -> spring-ai-qdrant-store
- spring-ai-gemfire -> spring-ai-gemfire-store
- spring-ai-azure-vector-store-spring-boot-starter -> spring-ai-azure-store-spring-boot-starter
- spring-ai-redis-spring-boot-starter -> spring-ai-redis-store-spring-boot-starter

== Upgrading to 0.8.1

Former `spring-ai-vertex-ai` has been renamed to `spring-ai-vertex-ai-palm2` and `spring-ai-vertex-ai-spring-boot-starter` has been renamed to `spring-ai-vertex-ai-palm2-spring-boot-starter`.

So, you need to change the dependency from

[source,xml]
----
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai</artifactId>
</dependency>
----

To

[source,xml]
----
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-palm2</artifactId>
</dependency>
----

and the related Boot starter for the Palm2 model has changed from

[source,xml]
----
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-spring-boot-starter</artifactId>
</dependency>
----

to

[source,xml]
----
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-palm2-spring-boot-starter</artifactId>
</dependency>
----

* Renamed Classes (01.03.2024)

** VertexAiApi -> VertexAiPalm2Api
** VertexAiClientChat -> VertexAiPalm2ChatClient
** VertexAiEmbeddingClient -> VertexAiPalm2EmbeddingClient
** VertexAiChatOptions -> VertexAiPalm2ChatOptions

== Upgrading to 0.8.0

=== January 24, 2024 Update

* Moving the `prompt` and `messages` and `metadata` packages to subpackages of `org.sf.ai.chat`
* New functionality is *text to image* clients. Classes are `OpenAiImageModel` and `StabilityAiImageModel`. See the integration tests for usage, docs are coming soon.
* A new package `model` that contains interfaces and base classes to support creating AI Model Clients for any input/output data type combination. At the moment the chat and image model packages implement this. We will be updating the embedding package to this new model soon.
* A new "portable options" design pattern. We wanted to provide as much portability in the `ModelCall` as possible across different chat based AI Models. There is a common set of generation options and then those that are specific to a model provider. A sort of "duck typing" approach is used. `ModelOptions` in the model package is a marker interface indicating implementations of this class will provide the options for a model. See `ImageOptions`, a subinterface that defines portable options across all text->image `ImageModel` implementations. Then `StabilityAiImageOptions` and `OpenAiImageOptions` provide the options specific to each model provider. All options classes are created via a fluent API builder all can be passed into the portable `ImageModel` API. These option data types are using in autoconfiguration/configuration properties for the `ImageModel` implementations.

=== January 13, 2024 Update

The following OpenAi Autoconfiguration chat properties has changed

* from `spring.ai.openai.model` to `spring.ai.openai.chat.options.model`.
* from `spring.ai.openai.temperature` to `spring.ai.openai.chat.options.temperature`.

Find updated documentation about the OpenAi properties: https://docs.spring.io/spring-ai/reference/api/chat/openai-chat.html

=== December 27, 2023 Update

Merge SimplePersistentVectorStore and InMemoryVectorStore into SimpleVectorStore
* Replace InMemoryVectorStore with SimpleVectorStore

=== December 20, 2023 Update

Refactor the Ollama client and related classes and package names

* Replace the org.springframework.ai.ollama.client.OllamaClient by org.springframework.ai.ollama.OllamaModelCall.
* The OllamaChatClient method signatures have changed.
* Rename the org.springframework.ai.autoconfigure.ollama.OllamaProperties into org.springframework.ai.autoconfigure.ollama.OllamaChatProperties and change the suffix to: `spring.ai.ollama.chat`. Some of the properties have changed as well.

=== December 19, 2023 Update

Renaming of AiClient and related classes and package names

* Rename AiClient to ChatClient
* Rename AiResponse to ChatResponse
* Rename AiStreamClient to StreamingChatClient
* Rename package org.sf.ai.client to org.sf.ai.chat

Rename artifact ID of

* `transformers-embedding` to `spring-ai-transformers`

Moved Maven modules from top-level directory and `embedding-clients` subdirectory to all be under a single `models` directory.

[WARNING]

=== December 1, 2023

We are transitioning the project's Group ID:

* *FROM*: `org.springframework.experimental.ai`
* *TO*: `org.springframework.ai`

Artifacts will still be hosted in the snapshot repository as shown below.

The main branch will move to the version `0.8.0-SNAPSHOT`.
It will be unstable for a week or two.
Please use the 0.7.1-SNAPSHOT if you don't want to be on the bleeding edge.

You can access `0.7.1-SNAPSHOT` artifacts as before and still access https://markpollack.github.io/spring-ai-0.7.1/[0.7.1-SNAPSHOT Documentation].

=== 0.7.1-SNAPSHOT Dependencies

* Azure OpenAI
+
[source,xml]
----
<dependency>
    <groupId>org.springframework.experimental.ai</groupId>
    <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
    <version>0.7.1-SNAPSHOT</version>
</dependency>
----

* OpenAI
+
[source,xml]
----
<dependency>
    <groupId>org.springframework.experimental.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>0.7.1-SNAPSHOT</version>
</dependency>
----

