|
| 1 | +# Migration Guide: Updating Message Handling |
| 2 | + |
| 3 | +This guide outlines the necessary changes to migrate your code from the previous message handling structure (using the |
| 4 | +`Message` class) to the new structure introduced to support multi-modal content and |
| 5 | +tool calls, based on the abstract `ChatMessage` class. |
| 6 | + |
| 7 | +## Core Changes |
| 8 | + |
| 9 | +1. **Message Class Removed:** The old `Message` class has been removed. |
| 10 | +2. **ChatMessage Hierarchy:** A new abstract base class `ChatMessage` has been |
| 11 | + introduced. Specific message types now extend this class: |
| 12 | + - `SystemMessage` |
| 13 | + - `UserMessage` |
| 14 | + - `AssistantMessage` |
| 15 | + - `ToolMessage` |
| 16 | +3. **Multi-Modal Content:** Messages (primarily `UserMessage`, `AssistantMessage`, `ToolMessage`) now use a |
| 17 | + `List<ContentChunk>` for their `content` field to support text, images, etc. The |
| 18 | + `ContentChunk` interface has implementations like `TextChunk`, |
| 19 | + `ImageURLChunk`, etc. |
| 20 | + - `getTextContent()` helper methods were introduced to prevent having to loop over `ContentChunk`s to find `TextChunk`s |
| 21 | +4. **Tool Calls:** `AssistantMessage` now includes a `List<ToolCall> toolCalls` field, and a `ToolMessage` message type was introduced to support function calling/tools. |
| 22 | +5. **Streaming Deltas:** The `DeltaChoice` class (used in streaming responses via `MessageChunk`) now contains a |
| 23 | + `DeltaMessage` object (accessible via `getDelta()`). This `DeltaMessage` |
| 24 | + object, in turn, holds the partial delta fields: `role`, `content` (as `List<ContentChunk>`), and `toolCalls`. |
| 25 | + |
| 26 | +## Migration Steps |
| 27 | + |
| 28 | +### 1. Update `ChatCompletionRequest` Message List |
| 29 | + |
| 30 | +The `messages` field in `ChatCompletionRequest` now expects `List<ChatMessage>` instead of `List<Message>`. |
| 31 | + |
| 32 | +**Before:** |
| 33 | + |
| 34 | +```java |
| 35 | +import nl.dannyj.mistral.models.completion.Message; |
| 36 | + |
| 37 | +// ... |
| 38 | +List<Message> messages = ...; |
| 39 | + ChatCompletionRequest request = ChatCompletionRequest.builder() |
| 40 | + .messages(messages) |
| 41 | + // ... |
| 42 | + .build(); |
| 43 | +``` |
| 44 | + |
| 45 | +**After:** |
| 46 | + |
| 47 | +```java |
| 48 | +import nl.dannyj.mistral.models.completion.ChatMessage; |
| 49 | + |
| 50 | +// ... |
| 51 | +List<ChatMessage> messages = ...; // See MessageListBuilder changes below |
| 52 | + ChatCompletionRequest request = ChatCompletionRequest.builder() |
| 53 | + .messages(messages) |
| 54 | + // ... |
| 55 | + .build(); |
| 56 | +``` |
| 57 | + |
| 58 | +### 2. Update `MessageListBuilder` Usage |
| 59 | + |
| 60 | +The `MessageListBuilder` now works with `ChatMessage` and its subclasses. |
| 61 | + |
| 62 | +**Before:** |
| 63 | + |
| 64 | +```java |
| 65 | +import nl.dannyj.mistral.models.completion.Message; |
| 66 | +import nl.dannyj.mistral.builders.MessageListBuilder; |
| 67 | + |
| 68 | +// ... |
| 69 | +List<Message> messages = new MessageListBuilder() |
| 70 | + .system("System prompt") |
| 71 | + .user("User query") |
| 72 | + .assistant("Assistant response") |
| 73 | + .build(); |
| 74 | +``` |
| 75 | + |
| 76 | +**After:** |
| 77 | + |
| 78 | +```java |
| 79 | +import nl.dannyj.mistral.models.completion.ChatMessage; |
| 80 | +import nl.dannyj.mistral.builders.MessageListBuilder; |
| 81 | + |
| 82 | +// ... |
| 83 | +List<ChatMessage> messages = new MessageListBuilder() |
| 84 | + .system("System prompt") // Creates SystemMessage |
| 85 | + .user("User query") // Creates UserMessage |
| 86 | + .assistant("Assistant response") // Creates AssistantMessage (text only) |
| 87 | + // .assistant(listOfToolCalls) // Use this overload for tool calls |
| 88 | + // .tool("Tool result", "tool_call_id_123") // Creates ToolMessage |
| 89 | + .build(); |
| 90 | + |
| 91 | +// Alternatively, add pre-constructed messages: |
| 92 | +// messages = new MessageListBuilder() |
| 93 | +// .message(new SystemMessage("System prompt")) |
| 94 | +// .message(new UserMessage("User query")) |
| 95 | +// .message(AssistantMessage.fromText("Assistant response")) // Factory method |
| 96 | +// .build(); |
| 97 | +``` |
| 98 | + |
| 99 | +### 3. Update Handling of Non-Streaming Responses (`ChatCompletionResponse`) |
| 100 | + |
| 101 | +The `message` field within the `Choice` object (obtained from `ChatCompletionResponse.getChoices()`) is now specifically |
| 102 | +an `AssistantMessage`. |
| 103 | + |
| 104 | +**Before:** |
| 105 | + |
| 106 | +```java |
| 107 | +ChatCompletionResponse response = client.createChatCompletion(request); |
| 108 | +Message responseMsg = response.getChoices().get(0).getMessage(); |
| 109 | +String content = responseMsg.getContent(); |
| 110 | +System.out.println(content); |
| 111 | +``` |
| 112 | + |
| 113 | +**After:** |
| 114 | + |
| 115 | +```java |
| 116 | +import nl.dannyj.mistral.models.completion.message.AssistantMessage; |
| 117 | +import nl.dannyj.mistral.models.completion.content.ContentChunk; |
| 118 | +import nl.dannyj.mistral.models.completion.content.TextChunk; |
| 119 | + |
| 120 | +// ... |
| 121 | +ChatCompletionResponse response = client.createChatCompletion(request); |
| 122 | +AssistantMessage responseMsg = response.getChoices().get(0).getMessage(); |
| 123 | + |
| 124 | +// Extract text content (handle potential multi-modal content) |
| 125 | +String textContent = ""; |
| 126 | +if (responseMsg.getContent() != null) { |
| 127 | + for (ContentChunk chunk : responseMsg.getContent()) { |
| 128 | + if (chunk instanceof TextChunk textChunk) { |
| 129 | + textContent += textChunk.getText(); // Append text from TextChunks |
| 130 | + } |
| 131 | + // Handle other chunk types (ImageURLChunk, etc.) if necessary |
| 132 | + } |
| 133 | +} |
| 134 | +System.out.println(textContent); |
| 135 | + |
| 136 | +// Check for tool calls if applicable |
| 137 | +if (responseMsg.getToolCalls() != null) { |
| 138 | + // Process tool calls |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +### 4. Update Handling of Streaming Responses (`ChatCompletionChunkCallback`) |
| 143 | + |
| 144 | +The `onChunkReceived` method receives `MessageChunk`. The structure within `MessageChunk.getChoices().get(0)` (which is |
| 145 | +a `DeltaChoice`) has changed. Access `role`, `content`, and `toolCalls` directly from the `DeltaChoice` object. |
| 146 | + |
| 147 | +**Before:** |
| 148 | + |
| 149 | +```java |
| 150 | +client.createChatCompletionStream(request, new ChatCompletionChunkCallback() { |
| 151 | + @Override |
| 152 | + public void onChunkReceived(MessageChunk chunk) { |
| 153 | + // Old structure assumed delta was nested in a Message object |
| 154 | + String contentDelta = chunk.getChoices().get(0).getMessage().getContent(); |
| 155 | + if (contentDelta != null) { |
| 156 | + System.out.print(contentDelta); |
| 157 | + } |
| 158 | + } |
| 159 | + // ... onComplete, onError |
| 160 | +}); |
| 161 | +``` |
| 162 | + |
| 163 | +**After:** |
| 164 | + |
| 165 | +```java |
| 166 | +import nl.dannyj.mistral.models.completion.DeltaChoice; |
| 167 | +import nl.dannyj.mistral.models.completion.message.DeltaMessage; // <-- Add this import |
| 168 | +import nl.dannyj.mistral.models.completion.message.MessageChunk; // <-- Updated import path |
| 169 | +import nl.dannyj.mistral.models.completion.content.ContentChunk; |
| 170 | +import nl.dannyj.mistral.models.completion.content.TextChunk; |
| 171 | +// ... |
| 172 | +client.createChatCompletionStream(request, new ChatCompletionChunkCallback() { |
| 173 | + @Override |
| 174 | + public void onChunkReceived(MessageChunk chunk) { |
| 175 | + if (chunk.getChoices() == null || chunk.getChoices().isEmpty()) return; |
| 176 | + |
| 177 | + DeltaChoice deltaChoice = chunk.getChoices().get(0); |
| 178 | + DeltaMessage delta = deltaChoice.getDelta(); // <-- Get the DeltaMessage |
| 179 | + |
| 180 | + // Check for text content delta using the convenience method |
| 181 | + String textDelta = delta.getTextContent(); |
| 182 | + |
| 183 | + if (textDelta != null) { |
| 184 | + System.out.print(textDelta); |
| 185 | + } |
| 186 | + |
| 187 | + } |
| 188 | + // ... onComplete, onError |
| 189 | +}); |
| 190 | +``` |
| 191 | + |
| 192 | +### 5. Update Handling of `Choice` Object in `ChatCompletionResponse` |
| 193 | + |
| 194 | +The `Choice` class, which is part of the `ChatCompletionResponse.getChoices()`, has the following breaking changes: |
| 195 | + |
| 196 | +#### `finishReason` Type Change |
| 197 | +- The `finishReason` field is now of type `FinishReason` (an enum) instead of a raw `String`. |
| 198 | +- **Before:** `String finishReason = choice.getFinishReason();` |
| 199 | +- **After:** `FinishReason finishReason = choice.getFinishReason();` |
| 200 | +- To get the underlying string value (e.g., "stop", "length"), you can call `finishReason.getReason()`. |
| 201 | + |
| 202 | +#### Example: Handling `finishReason` (within the context of iterating choices from `ChatCompletionResponse`) |
| 203 | + |
| 204 | +**Before(inside loop processing `choice`):** |
| 205 | +```java |
| 206 | +String reason = choice.getFinishReason(); |
| 207 | + if ("stop".equals(reason)) { |
| 208 | + // ... |
| 209 | + } |
| 210 | +``` |
| 211 | + |
| 212 | +**After(inside loop processing `choice`):** |
| 213 | +```java |
| 214 | + import nl.dannyj.mistral.models.completion.FinishReason; // Ensure import |
| 215 | +// ... |
| 216 | +FinishReason reason = choice.getFinishReason(); |
| 217 | +if (reason == FinishReason.STOP) { |
| 218 | + // ... |
| 219 | +} |
| 220 | +// Or, to compare with the string value: |
| 221 | +// if ("stop".equals(reason.getReason())) { ... } |
| 222 | +``` |
| 223 | + |
| 224 | +#### `logProbs` Field Removal |
| 225 | +- The `logProbs` field (previously a `String`) has been removed from the `Choice` class as it is no longer returned by the API. |
0 commit comments