Improve Message docs

Author: tzolov

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/functions/azure-open-ai-chat-functions.adoc

@@ -6,8 +6,6 @@ You can register custom Java functions with the `AzureOpenAiChatModel` and have
 This allows you to connect the LLM capabilities with external tools and APIs.
 The Azure models are trained to detect when a function should be called and to respond with JSON that adheres to the function signature.
 
-NOTE: Parallel function calling is only supported with gpt-35-turbo (1106) and gpt-4 (1106-preview) also known as GPT-4 Turbo Preview.
-
 The Azure OpenAI API does not call the function directly; instead, the model generates JSON that you can use to call the function in your code and return the result back to the model to complete the conversation.
 
 Spring AI provides flexible and user-friendly ways to register and call custom functions.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatmodel.adoc

@@ -74,35 +74,39 @@ public class Prompt implements ModelRequest<List<Message>> {
 
 ==== Message
 
-The `Message` interface encapsulates a textual message, a collection of attributes as a `Map`, and a categorization known as `MessageType`. The interface is defined as follows:
+The `Message` interface encapsulates a Prompt textual content and a collection of metadata attributes and a categorization known as `MessageType`.
 
-[source,java]
-----
-public interface Message extends Node<String> {
+The interface is defined as follows:
 
-   String getContent();
+```java
+public interface Content {
 
-   List<Media> getMedia();
+	String getContent();
 
-   MessageType getMessageType();
+	Map<String, Object> getMetadata();
 }
-----
 
+public interface Message extends Content {
+
+	MessageType getMessageType();
+}
+```
 
-and the Node interface is
+The multimodal message types implement also the `MediaContent` interface providing a list of `Media` content objects.
 
 ```java
+public interface MediaContent extends Content {
 
-public interface Node<T> {
-
-    T getContent();
+	Collection<Media> getMedia();
 
-    Map<String, Object> getMetadata();
 }
 ```
 
-The `Message` interface has various implementations that correspond to the categories of messages that an AI model can process.
-Some models, like OpenAI's chat completion endpoint, distinguish between message categories based on conversational roles, effectively mapped by the `MessageType`.
+The `Message` interface has various implementations that correspond to the categories of messages that an AI model can process:
+
+image::spring-ai-message-api.jpg[Spring AI Message API, width=800, align="center"]
+
+The chat completion endpoint, distinguish between message categories based on conversational roles, effectively mapped by the `MessageType`.
 
 For instance, OpenAI recognizes message categories for distinct conversational roles such as `system`,`user`, `function` or `assistant`.
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/prompt.adoc

@@ -44,55 +44,57 @@ public class Prompt implements ModelRequest<List<Message>> {
 
 === Message
 
-The `Message` interface encapsulates a textual message, a collection of attributes as a `Map`, a categorization known as `MessageType`, and a list of media objects for those models that are multimodal.
-The interface is defined as follows:
+The `Message` interface encapsulates a Prompt textual content and a collection of metadata attributes and a categorization known as `MessageType`.
 
-image::spring-ai-message-api.jpg[Spring AI Message API, width=800, align="center"]
+The interface is defined as follows:
 
 ```java
+public interface Content {
+
+	String getContent();
+
+	Map<String, Object> getMetadata();
+}
+
 public interface Message extends Content {
 
 	MessageType getMessageType();
-
 }
 ```
 
-and the Content interface is
+The multimodal message types implement also the `MediaContent` interface providing a list of `Media` content objects.
 
 ```java
+public interface MediaContent extends Content {
 
-public interface Content {
-
-	String getContent();
+	Collection<Media> getMedia();
 
-	Map<String, Object> getMetadata();
 }
 ```
 
-Various implementations of the `Message` interface correspond to different categories of messages that an AI model can process. Some models, like those from OpenAI, distinguish between message categories based on conversational roles. These roles are effectively mapped by the `MessageType`, as discussed below.
-
+Various implementations of the `Message` interface correspond to different categories of messages that an AI model can process. 
+The Models distinguish between message categories based on conversational roles. 
 
-== Roles
+image::spring-ai-message-api.jpg[Spring AI Message API, width=800, align="center"]
 
-The evolution of prompts in AI has transitioned from basic, straightforward text to more organized and complex formats with specific roles and structures.
+These roles are effectively mapped by the `MessageType`, as discussed below.
 
-Initially, prompts were simple strings – just lines of text.
-Over time, this evolved to include specific placeholders within these strings, like “USER:”, which the AI model could recognize and respond to accordingly.
-This was a step towards more structured prompts.
+==== Roles
 
-OpenAI then introduced an even more organized approach.
-In their model, prompts are not merely single strings but a series of messages.
-Each message, while still in text form, is assigned a specific role.
+Each message is assigned a specific role.
 These roles categorize the messages, clarifying the context and purpose of each segment of the prompt for the AI model.
 This structured approach enhances the nuance and effectiveness of communication with the AI, as each part of the prompt plays a distinct and defined role in the interaction.
 
-
 The primary roles are:
 
 * System Role: Guides the AI's behavior and response style, setting parameters or rules for how the AI interprets and replies to the input. It's akin to providing instructions to the AI before initiating a conversation.
 * User Role: Represents the user's input – their questions, commands, or statements to the AI. This role is fundamental as it forms the basis of the AI's response.
-* Assistant Role: The AI's response to the user's input. More than just an answer or reaction, it's crucial for maintaining the flow of the conversation. By tracking the AI's previous responses (its 'Assistant Role' messages), the system ensures coherent and contextually relevant interactions.
-* Function Role: This role deals with specific tasks or operations during the conversation. While the System Role sets the AI's overall behavior, the Function Role focuses on carrying out certain actions or commands the user asks for. It's like a special feature in the AI, used when needed to perform specific functions such as calculations, fetching data, or other tasks beyond just talking. This role allows the AI to offer practical help in addition to conversational responses.
+* Assistant Role: The AI's response to the user's input. 
+More than just an answer or reaction, it's crucial for maintaining the flow of the conversation. 
+By tracking the AI's previous responses (its 'Assistant Role' messages), the system ensures coherent and contextually relevant interactions.
+The Assistant message may contain Function Tool Call request information as well.
+It's like a special feature in the AI, used when needed to perform specific functions such as calculations, fetching data, or other tasks beyond just talking.
+* Tool/Function Role: The Too/Function Role focuses on returning additional information in response to Tool Call Aisstnat Messages.
 
 Roles are represented as an enumeration in Spring AI as shown below
 
@@ -107,25 +109,7 @@ public enum MessageType {
 
 	TOOL("tool");
 
-	private final String value;
-
-	MessageType(String value) {
-		this.value = value;
-	}
-
-	public String getValue() {
-		return value;
-	}
-
-	public static MessageType fromValue(String value) {
-		for (MessageType messageType : MessageType.values()) {
-			if (messageType.getValue().equals(value)) {
-				return messageType;
-			}
-		}
-		throw new IllegalArgumentException("Invalid MessageType value: " + value);
-	}
-
+    ...
 }
 ```