Add Advisors documentation

Author: tzolov

spring-ai-docs/src/main/antora/modules/ROOT/images/advisors-api-classes.jpg

@@ -90,6 +90,7 @@
 *** xref:api/vectordbs/weaviate.adoc[]
 
 
+** xref:api/advisors.adoc[Advisors]
 ** xref:api/functions.adoc[Function Calling]
 ** xref:api/multimodality.adoc[Multimodality]
 ** xref:api/prompt.adoc[]

spring-ai-docs/src/main/antora/modules/ROOT/images/advisors-flow.jpg

@@ -0,0 +1,149 @@
+[[Advisors]]
+
+= Spring AI Advisors API
+
+== Overview
+
+The Spring AI Advisors API introduces a powerful component called `AroundAdvisor`. 
+This component dynamically intercepts chat-completion requests and responses, allowing for transformation or utilization of information within these interactions.
+
+The Advisors are important for a number of reasons:
+
+ - Encapsulation of Recurring Tasks: AroundAdvisors enable the packaging of common GenAI patterns into reusable units.
+ - Response Transformation: They facilitate the augmentation of data sent to Language Models (LLMs) and formatting of responses sent back to clients.
+ - Portability: As part of the Spring AI core specification, developers can create reusable transformation components that work across various models and use cases.
+
+The xref:api/chatclient.adoc#_advisor_configuration_in_chatclient[ChatClient API] provides a simple way to configure and use advisors. For example you can enable the built-in chat-memory and question-answer advisors like this:
+
+[source,java]
+----
+ChatClient.builder(chatModel)
+    .build()
+    .prompt()
+    .advisors(
+        new ChatMemoryAdvisor(chatMemory),
+        new QuestionAnswerAdvisor(vectorStore, SearchRequest.defaults())
+    )
+    .user(userText)
+    .call();
+----
+
+One cane use some of the Spring AI built-in advisors or implement custom advisors to meet your specific requirements.
+
+We'll outline the Advisors API, and describe how to implement customized advisors.
+Spring AI support adviser for streaming and non-streaming workloads.
+
+== Core Components
+
+The Advisor API is defined in the `org.springframework.ai.chat.client.advisor.api` package by the pair of `CallAroundAdvisor` and `CallAroundAdvisorChain` interfaces and the corresponding `StreamAroundAdvisor` and `StreamAroundAdvisorChain` pair for the streaming responses.
+
+image::advisors-api-classes.jpg[Advisors API Classes, width=400, align="center"]
+
+=== AdvisedRequest and AdvisedResponse
+
+* `AdvisedRequest`: Represents the unsealed Prompt request.
+* `AdvisedResponse`: Represents the Chat Completion response.
+* Both contain an `AdviserContext` object for sharing state across the advisor chain.
+
+=== Advisor Interfaces
+
+. For non-streaming workloads:
+** `CallAroundAdvisor`
+** `CallAroundAdvisorChain`
+
+. For streaming workloads:
+** `StreamAroundAdvisor`
+** `StreamAroundAdvisorChain`
+
+==== Key Methods
+
+. `nextAroundCall()` / `nextAroundStream()`: The core of the advisor logic, typically performing these actions:
+** Examining the unsealed Prompt data
+** Customizing and augmenting the Prompt data
+** Invoking the next entity in the advisor chain
+** Optionally blocking the request
+** Examining the chat completion response
+** Throwing exceptions to indicate processing errors
+
+. `getOrder()`: Determines the advisor's priority in the chain.
+. `getName()`: Provides a unique identifier for the advisor.
+
+=== Advisor Chain
+
+The advisor chain, provided by the Spring AI client, allows for the sequential invocation of multiple advisors. This chain is represented by `CallAroundAdvisorChain` for non-streaming and `StreamAroundAdvisorChain` for streaming scenarios.
+
+=== Usage Flow
+
+image::advisors-flow.jpg[Advisors API Flow, width=400, align="left"]
+
+. The Spring AI framework creates an `AdvisedRequest` from user's `Prompt` along with an empty `AdvisorContext` object.
+. Each advisor in the chain processes the request, potentially modifying it. Alternatively, it can choose to block the request by not making the call to invoke the next entity. In the latter case, the advisor is responsible for filling out the response.
+. The final advisor, provided by the framework, sends the request to the `Chat Model`.
+. The Chat Model's response is then passed back through the advisor chain and converted into `AdvisedResponse`. Later includes the shared `AdvisorContext` instance.
+. Each advisor can process or modify the response.
+. The final `AdvisedResponse` is returned to the client by extracting the `ChatCompletion`.
+
+== Implementing an Advisor
+
+To create an advisor, implement either `CallAroundAdvisor` or `StreamAroundAdvisor` (or both). The key method to implement is `nextAroundCall()` for non-streaming or `nextAroundStream()` for streaming advisors.
+
+=== Logging Advisor Example
+
+[source,java]
+----
+public class SimpleLoggerAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {
+
+	private static final Logger logger = LoggerFactory.getLogger(SimpleLoggerAdvisor.class);
+
+	@Override
+	public String getName() {
+		return this.getClass().getSimpleName();
+	}
+
+	@Override
+	public int getOrder() {
+		return 0;
+	}
+
+	@Override
+	public AdvisedResponse aroundCall(AdvisedRequest advisedRequest, CallAroundAdvisorChain chain) {
+
+		logger.debug("BEFORE: {}", advisedRequest);
+
+		AdvisedResponse advisedResponse = chain.nextAroundCall(advisedRequest);
+
+		logger.debug("AFTER: {}", advisedResponse);
+
+		return advisedResponse;
+	}
+
+	@Override
+	public Flux<AdvisedResponse> aroundStream(AdvisedRequest advisedRequest, StreamAroundAdvisorChain chain) {
+
+		logger.debug("BEFORE: {}", advisedRequest);
+
+		Flux<AdvisedResponse> advisedResponses = chain.nextAroundStream(advisedRequest);
+		
+        return new MessageAggregator().aggregateAdvisedResponse(advisedResponses, 
+                    advisedResponse -> logger.debug("AFTER: {}", advisedResponse));
+	}
+}
+----
+
+== Streaming vs Non-Streaming
+
+image::advisors-non-stream-vs-stream.jpg[Advisors Streaming vs Non-Streaming Flow, width=800, align="left"]
+
+* Non-streaming advisors work with complete requests and responses.
+* Streaming advisors handle requests and responses as continuous streams, using reactive programming concepts (e.g., Flux for responses).
+
+== Best Practices
+
+. Keep advisors focused on specific tasks for better modularity.
+. Use the `adviseContext` to share state between advisors when necessary.
+. Implement both streaming and non-streaming versions of your advisor for maximum flexibility.
+. Carefully consider the order of advisors in your chain to ensure proper data flow.
+
+== Conclusion
+
+The Spring AI Advisors API provides a flexible and powerful way to intercept, modify, and enhance AI-driven interactions in your Spring applications. By leveraging this API, developers can create more sophisticated, reusable, and maintainable AI components.