Spring AI

https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html
Admin
Spring AI provides a modular architecture to build custom or out-of-the-box Retrieval Augmented...
Tokens:12,324
Snippets:104
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### CompressionQueryTransformer example

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Compresses conversation history and a follow-up query into a standalone query. Useful when the conversation history is long and the follow-up query is related to the conversation context. The prompt can be customized via the `promptTemplate()` method in the builder.

```java
Query query = Query.builder()
        .text("And what is its second largest city?")
        .history(new UserMessage("What is the capital of Denmark?"),
                new AssistantMessage("Copenhagen is the capital of Denmark."))
        .build();

QueryTransformer queryTransformer = CompressionQueryTransformer.builder()
        .chatClientBuilder(chatClientBuilder)
        .build();

Query transformedQuery = queryTransformer.transform(query);
```

--------------------------------

### MultiQueryExpander example

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Expands a query into multiple semantically diverse variations to capture different perspectives. By default, the original query is included in the expanded list; disable with `includeOriginal(false)`. The prompt can be customized via the `promptTemplate()` method in the builder.

```java
MultiQueryExpander queryExpander = MultiQueryExpander.builder()
    .chatClientBuilder(chatClientBuilder)
    .numberOfQueries(3)
    .build();
List<Query> queries = queryExpander.expand(new Query("How to run a Spring Boot app?"));
```

--------------------------------

### Customize QuestionAnswerAdvisor prompt template

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Customizes the QuestionAnswerAdvisor's prompt template using a PromptTemplate with a custom renderer. The template must include 'query' and 'question_answer_context' placeholders. The example also shows using the advisor with a ChatClient.

```java
PromptTemplate customPromptTemplate = PromptTemplate.builder()
    .renderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
    .template("""
            <query>

            Context information is below.

			---------------------
			<question_answer_context>
			---------------------

			Given the context information and no prior knowledge, answer the query.

			Follow these rules:

			1. If the answer is not in the context, just say that you don't know.
			2. Avoid statements like "Based on the context..." or "The provided information...".
            """)
    .build();

    String question = "Where does the adventure of Anacletus and Birba take place?";

    QuestionAnswerAdvisor qaAdvisor = QuestionAnswerAdvisor.builder(vectorStore)
        .promptTemplate(customPromptTemplate)
        .build();

    String response = ChatClient.builder(chatModel).build()
        .prompt(question)
        .advisors(qaAdvisor)
        .call()
        .content();
```

--------------------------------

### RewriteQueryTransformer example

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Rewrites a user query to improve retrieval results when the query is verbose, ambiguous, or contains irrelevant information. The prompt can be customized via the `promptTemplate()` method in the builder.

```java
Query query = new Query("I'm studying machine learning. What is an LLM?");

QueryTransformer queryTransformer = RewriteQueryTransformer.builder()
        .chatClientBuilder(chatClientBuilder)
        .build();

Query transformedQuery = queryTransformer.transform(query);
```

--------------------------------

### TranslationQueryTransformer example

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Translates a query to a target language supported by the embedding model. If the query is already in the target language or its language is unknown, it is returned unchanged. The prompt can be customized via the `promptTemplate()` method in the builder.

```java
Query query = new Query("Hvad er Danmarks hovedstad?");

QueryTransformer queryTransformer = TranslationQueryTransformer.builder()
        .chatClientBuilder(chatClientBuilder)
        .targetLanguage("english")
        .build();

Query transformedQuery = queryTransformer.transform(query);
```

--------------------------------

### Implement adviseStream for a streaming advisor

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Shows the structure of a streaming advisor implementation. It uses Mono.just and publishOn(Schedulers.boundedElastic()) to allow blocking operations, then delegates to chain.nextStream(request) and processes the response. The comments indicate where to place advisor logic before and after the next section.

```java
@Override
public Flux<ChatClientResponse> adviseStream(ChatClientRequest chatClientRequest, StreamAdvisorChain chain) {

    return  Mono.just(chatClientRequest)
            .publishOn(Schedulers.boundedElastic())
            .map(request -> {
                // This can be executed by blocking and non-blocking Threads.
                // Advisor before next section
            })
            .flatMapMany(request -> chain.nextStream(request))
            .map(response -> {
                // Advisor after next section
            });
}

```

--------------------------------

### Configure ChatClient with default advisors and runtime parameters

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Configures a ChatClient with default advisors (MessageChatMemoryAdvisor and QuestionAnswerAdvisor) and sets the conversation ID parameter at runtime. Register advisors at build time using defaultAdvisors() and set advisor parameters via the advisors() method.

```java
ChatMemory chatMemory = ... // Initialize your chat memory store
VectorStore vectorStore = ... // Initialize your vector store

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        MessageChatMemoryAdvisor.builder(chatMemory).build(), // chat-memory advisor
        QuestionAnswerAdvisor.builder(vectorStore).build()    // RAG advisor
    )
    .build();

var conversationId = "678";

String response = this.chatClient.prompt()
    // Set advisor parameters at runtime
    .advisors(advisor -> advisor.param(ChatMemory.CONVERSATION_ID, conversationId))
    .user(userText)
    .call()
	.content();
```

--------------------------------

### Build ContextualQueryAugmenter with default settings

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Creates a ContextualQueryAugmenter with default settings. By default, the augmenter does not allow empty retrieved context and instructs the model not to answer the user query when the context is empty.

```java
QueryAugmenter queryAugmenter = ContextualQueryAugmenter.builder().build();
```

--------------------------------

### ContextualQueryAugmenter.builder().allowEmptyContext(true).build()

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Creates a ContextualQueryAugmenter with the allowEmptyContext option enabled, allowing the model to generate a response even when the retrieved context is empty.

```APIDOC
## ContextualQueryAugmenter with allowEmptyContext

### Description
Creates a ContextualQueryAugmenter with the allowEmptyContext option enabled, allowing the model to generate a response even when the retrieved context is empty.

### Method
builder().allowEmptyContext(true).build()

### Code Example
```java
QueryAugmenter queryAugmenter = ContextualQueryAugmenter.builder()
        .allowEmptyContext(true)
        .build();
```

### Builder Options
- **allowEmptyContext** (boolean) - Optional - When set to true, allows the model to generate a response even when the retrieved context is empty.
- **promptTemplate** - Optional - Customizes the prompt template used by the component.
- **emptyContextPromptTemplate** - Optional - Customizes the prompt template used when the context is empty.
```

--------------------------------

### ContextualQueryAugmenter.builder().build()

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Creates a default ContextualQueryAugmenter that does not allow empty context and instructs the model not to answer when context is empty.

```APIDOC
## ContextualQueryAugmenter

### Description
Creates a default ContextualQueryAugmenter that augments the user query with contextual data from the content of the provided documents. By default, it does not allow empty context and instructs the model not to answer when the retrieved context is empty.

### Method
builder().build()

### Code Example
```java
QueryAugmenter queryAugmenter = ContextualQueryAugmenter.builder().build();
```

### Builder Options
- **allowEmptyContext** (boolean) - Optional - When set to true, allows the model to generate a response even when the retrieved context is empty.
- **promptTemplate** - Optional - Customizes the prompt template used by the component.
- **emptyContextPromptTemplate** - Optional - Customizes the prompt template used when the context is empty.
```

--------------------------------

### Build ContextualQueryAugmenter with allowEmptyContext enabled

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Builds a ContextualQueryAugmenter with the allowEmptyContext option enabled, allowing the model to generate a response even when the retrieved context is empty. The prompts used by this component can be customized via the promptTemplate() and emptyContextPromptTemplate() builder methods.

```java
QueryAugmenter queryAugmenter = ContextualQueryAugmenter.builder()
        .allowEmptyContext(true)
        .build();
```

--------------------------------

### Naive RAG with RetrievalAugmentationAdvisor

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Build a RetrievalAugmentationAdvisor with a VectorStoreDocumentRetriever that uses a similarity threshold of 0.50. By default, empty retrieved context is not allowed; the model is instructed not to answer when no context is retrieved.

```java
Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .similarityThreshold(0.50)
                .vectorStore(vectorStore)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(retrievalAugmentationAdvisor)
        .user(question)
        .call()
        .content();
```

--------------------------------

### ReReadingAdvisor: Re2 Technique Advisor

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Implements BaseAdvisor to apply the Re-Reading (Re2) technique by augmenting the user's input query in the before method using a PromptTemplate. The after method returns the response unchanged. The order can be controlled via getOrder() and withOrder(); lower values execute first.

```java
public class ReReadingAdvisor implements BaseAdvisor {

	private static final String DEFAULT_RE2_ADVISE_TEMPLATE = """
			{re2_input_query}
			Read the question again: {re2_input_query}
			""";

	private final String re2AdviseTemplate;

	private int order = 0;

	public ReReadingAdvisor() {
		this(DEFAULT_RE2_ADVISE_TEMPLATE);
	}

	public ReReadingAdvisor(String re2AdviseTemplate) {
		this.re2AdviseTemplate = re2AdviseTemplate;
	}

	@Override
	public ChatClientRequest before(ChatClientRequest chatClientRequest, AdvisorChain advisorChain) { __**(1)**
		String augmentedUserText = PromptTemplate.builder()
			.template(this.re2AdviseTemplate)
			.variables(Map.of("re2_input_query", chatClientRequest.prompt().getUserMessage().getText()))
			.build()
			.render();

		return chatClientRequest.mutate()
			.prompt(chatClientRequest.prompt().augmentUserMessage(augmentedUserText))
			.build();
	}

	@Override
	public ChatClientResponse after(ChatClientResponse chatClientResponse, AdvisorChain advisorChain) {
		return chatClientResponse;
	}

	@Override
	public int getOrder() { __**(2)**
		return this.order;
	}

	public ReReadingAdvisor withOrder(int order) {
		this.order = order;
		return this;
	}

}
```

--------------------------------

### Configure QuestionAnswerAdvisor with SearchRequest threshold and topK

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Creates a QuestionAnswerAdvisor with a similarity threshold of 0.8 and returns the top 6 results. The filter expression can be configured here to apply to all ChatClient requests.

```java
var qaAdvisor = QuestionAnswerAdvisor.builder(vectorStore)
        .searchRequest(SearchRequest.builder().similarityThreshold(0.8d).topK(6).build())
        .build();
```

--------------------------------

### MultiQueryExpander with includeOriginal(false)

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Configures `MultiQueryExpander` to exclude the original query from the expanded list. The prompt can be customized via the `promptTemplate()` method in the builder.

```java
MultiQueryExpander queryExpander = MultiQueryExpander.builder()
    .chatClientBuilder(chatClientBuilder)
    .includeOriginal(false)
    .build();
```

--------------------------------

### Perform RAG with QuestionAnswerAdvisor in ChatClient

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Performs RAG by attaching a QuestionAnswerAdvisor to the ChatClient. The advisor queries the vector database for documents related to the user question and appends the response to the user text for context.

```java
ChatResponse response = ChatClient.builder(chatModel)
        .build().prompt()
        .advisors(QuestionAnswerAdvisor.builder(vectorStore).build())
        .user(userText)
        .call()
        .chatResponse();
```

--------------------------------

### VectorStoreDocumentRetriever.builder()

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Builds a VectorStoreDocumentRetriever to retrieve documents from a vector store based on semantic similarity. Supports filtering by metadata, similarity threshold, and top-k results.

```APIDOC
## VectorStoreDocumentRetriever.builder()

### Description
Builds a VectorStoreDocumentRetriever to retrieve documents from a vector store that are semantically similar to the input query. Supports filtering based on metadata, similarity threshold, and top-k results.

### Method
builder()

### Parameters
- **vectorStore** (VectorStore) - Required - The vector store to retrieve documents from.
- **similarityThreshold** (double) - Optional - The minimum similarity score for documents to be retrieved.
- **topK** (int) - Optional - The number of top results to return.
- **filterExpression** (FilterExpression or Supplier<FilterExpression>) - Optional - A static or dynamic filter expression to apply to the retrieval.

### Request Example
```java
DocumentRetriever retriever = VectorStoreDocumentRetriever.builder()
    .vectorStore(vectorStore)
    .similarityThreshold(0.73)
    .topK(5)
    .filterExpression(new FilterExpressionBuilder()
        .eq("genre", "fairytale")
        .build())
    .build();
List<Document> documents = retriever.retrieve(new Query("What is the main character of the story?"));
```

### Response
Returns a list of Document objects that are semantically similar to the query, filtered by the provided criteria.

### Notes
- The filter expression can be static or dynamic. For dynamic filter expressions, pass a Supplier.
- A request-specific filter expression can be provided via the Query API using the FILTER_EXPRESSION parameter. If both are provided, the request-specific filter expression takes precedence.
```

--------------------------------

### VectorStoreDocumentRetriever with dynamic filter expression

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Builds a VectorStoreDocumentRetriever with a dynamic filter expression using a Supplier. The filter is evaluated at retrieval time, allowing tenant-specific filtering.

```java
DocumentRetriever retriever = VectorStoreDocumentRetriever.builder()
    .vectorStore(vectorStore)
    .filterExpression(() -> new FilterExpressionBuilder()
        .eq("tenant", TenantContextHolder.getTenantIdentifier())
        .build())
    .build();
List<Document> documents = retriever.retrieve(new Query("What are the KPIs for the next semester?"));
```

--------------------------------

### VectorStoreDocumentRetriever with static filter expression

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Builds a VectorStoreDocumentRetriever with a static filter expression, similarity threshold, and top-k. Retrieves documents semantically similar to the query, filtered by metadata.

```java
DocumentRetriever retriever = VectorStoreDocumentRetriever.builder()
    .vectorStore(vectorStore)
    .similarityThreshold(0.73)
    .topK(5)
    .filterExpression(new FilterExpressionBuilder()
        .eq("genre", "fairytale")
        .build())
    .build();
List<Document> documents = retriever.retrieve(new Query("What is the main character of the story?"));
```

--------------------------------

### Allow empty context with ContextualQueryAugmenter

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Configure the RetrievalAugmentationAdvisor to allow empty context by setting allowEmptyContext(true) on the ContextualQueryAugmenter. This overrides the default behavior that instructs the model not to answer when no context is retrieved.

```java
Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .similarityThreshold(0.50)
                .vectorStore(vectorStore)
                .build())
        .queryAugmenter(ContextualQueryAugmenter.builder()
                .allowEmptyContext(true)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(retrievalAugmentationAdvisor)
        .user(question)
        .call()
        .content();
```

--------------------------------

### Ordered Interface

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

The Spring Ordered interface used to control advisor execution order.

```APIDOC
## Ordered Interface

### Description
The Spring `Ordered` interface defines the order value used to determine advisor execution priority. Lower values indicate higher precedence.

### Methods

#### getOrder()
- **Return Type**: int
- **Description**: Returns the order value of this object. Higher values are interpreted as lower priority. Same order values result in arbitrary sort positions.

### Constants
- **HIGHEST_PRECEDENCE** (int) - Integer.MIN_VALUE - Highest precedence value.
- **LOWEST_PRECEDENCE** (int) - Integer.MAX_VALUE - Lowest precedence value.

### Example
```java
public interface Ordered {
    int HIGHEST_PRECEDENCE = Integer.MIN_VALUE;
    int LOWEST_PRECEDENCE = Integer.MAX_VALUE;
    int getOrder();
}
```
```

--------------------------------

### Re2 Prompt Template

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

The Re-Reading (Re2) technique prompt template that augments the user's input query by repeating it with the instruction 'Read the question again'. This is the template used by the ReReadingAdvisor to improve reasoning in large language models.

```text
{Input_Query}
Read the question again: {Input_Query}
```

--------------------------------

### Add spring-ai-vector-store-advisor dependency

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Add this Maven dependency to your project to use the QuestionAnswerAdvisor or VectorStoreChatMemoryAdvisor from the Advisor API.

```xml
<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-vector-store-advisor</artifactId>
</dependency>
```

--------------------------------

### CallAdvisorChain

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Chain interface for synchronous advisors.

```APIDOC
## CallAdvisorChain Interface

### Description
Chain of call advisors that allows invoking the next advisor in the chain.

### Methods
- `ChatClientResponse nextCall(ChatClientRequest chatClientRequest)` - Invokes the next CallAdvisor in the chain with the given request.
- `List<CallAdvisor> getCallAdvisors()` - Returns the list of all CallAdvisor instances included in this chain at the time of its creation.
```

--------------------------------

### Advisor interface

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Base interface for all advisors. Extends Ordered to allow ordering of advisors in the chain. The getName() method returns the advisor's name.

```java
public interface Advisor extends Ordered {

	String getName();

}
```

--------------------------------

### StreamAdvisorChain

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Chain interface for reactive advisors.

```APIDOC
## StreamAdvisorChain Interface

### Description
Chain of stream advisors that allows invoking the next advisor in the chain.

### Methods
- `Flux<ChatClientResponse> nextStream(ChatClientRequest chatClientRequest)` - Invokes the next StreamAdvisor in the chain with the given request.
- `List<StreamAdvisor> getStreamAdvisors()` - Returns the list of all StreamAdvisor instances included in this chain at the time of its creation.
```

--------------------------------

### Dynamically filter RAG search with FILTER_EXPRESSION

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Shows how to update the SearchRequest filter expression at runtime using the FILTER_EXPRESSION advisor context parameter. The advisor is set as a default advisor, and the filter is applied per request.

```java
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore)
        .searchRequest(SearchRequest.builder().build())
        .build())
    .build();

// Update filter expression at runtime
String content = this.chatClient.prompt()
    .user("Please answer my question XYZ")
    .advisors(a -> a.param(QuestionAnswerAdvisor.FILTER_EXPRESSION, "type == 'Spring'"))
    .call()
    .content();
```

--------------------------------

### Add spring-ai-rag dependency

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Add the spring-ai-rag dependency to your project to use the RetrievalAugmentationAdvisor.

```xml
<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-rag</artifactId>
</dependency>
```

--------------------------------

### SimpleLoggerAdvisor: Logging Advisor for Call and Stream

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Implements both CallAdvisor and StreamAdvisor to log the ChatClientRequest before and the ChatClientResponse after the next advisor in the chain. The advisor only observes and does not modify the request/response. For streaming, it uses ChatClientMessageAggregator to aggregate the Flux responses into a single ChatClientResponse for logging; note that the aggregator is read-only and cannot alter the response.

```java
public class SimpleLoggerAdvisor implements CallAdvisor, StreamAdvisor {

	private static final Logger logger = LoggerFactory.getLogger(SimpleLoggerAdvisor.class);

	@Override
	public String getName() { __**(1)**
		return this.getClass().getSimpleName();
	}

	@Override
	public int getOrder() { __**(2)**
		return 0;
	}


	@Override
	public ChatClientResponse adviseCall(ChatClientRequest chatClientRequest, CallAdvisorChain callAdvisorChain) {
		logRequest(chatClientRequest);

		ChatClientResponse chatClientResponse = callAdvisorChain.nextCall(chatClientRequest);

		logResponse(chatClientResponse);

		return chatClientResponse;
	}

	@Override
	public Flux<ChatClientResponse> adviseStream(ChatClientRequest chatClientRequest,
			StreamAdvisorChain streamAdvisorChain) {
		logRequest(chatClientRequest);

		Flux<ChatClientResponse> chatClientResponses = streamAdvisorChain.nextStream(chatClientRequest);

		return new ChatClientMessageAggregator().aggregateChatClientResponse(chatClientResponses, this::logResponse); __**(3)**
	}

	private void logRequest(ChatClientRequest request) {
		logger.debug("request: {}", request);
	}

	private void logResponse(ChatClientResponse chatClientResponse) {
		logger.debug("response: {}", chatClientResponse);
	}

}
```

--------------------------------

### Advisor

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Base interface for all advisors, extending Ordered to allow ordering of advisors in a chain.

```APIDOC
## Advisor Interface

### Description
Base interface for all advisors, extending Ordered to allow ordering of advisors in a chain.

### Method
- `String getName()` - Returns the name of the advisor.

### Usage
Implement this interface to create a custom advisor.
```

--------------------------------

### CallAdvisorChain interface

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Chain interface for synchronous advisors. Provides nextCall to invoke the next advisor and getCallAdvisors to retrieve the list of advisors in the chain.

```java
public interface CallAdvisorChain extends AdvisorChain {

	/**
	 * Invokes the next {@link CallAdvisor} in the {@link CallAdvisorChain} with the given
	 * request.
	 */
	ChatClientResponse nextCall(ChatClientRequest chatClientRequest);

	/**
	 * Returns the list of all the {@link CallAdvisor} instances included in this chain at
	 * the time of its creation.
	 */
	List<CallAdvisor> getCallAdvisors();

}
```

--------------------------------

### SimpleLoggerAdvisor

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

A logging advisor that logs the ChatClientRequest before and the ChatClientResponse after the call to the next advisor. It implements both CallAdvisor and StreamAdvisor.

```APIDOC
## SimpleLoggerAdvisor

### Description
Logs the request and response of a chat client call. Implements both CallAdvisor and StreamAdvisor to support non-streaming and streaming scenarios.

### Methods

#### getName()
- Returns a unique name for the advisor.
- Returns: String - the simple class name.

#### getOrder()
- Returns the order of execution. Lower values execute first.
- Returns: int - the order value (default 0).

#### adviseCall(ChatClientRequest, CallAdvisorChain)
- Logs the request, calls the next advisor in the chain, logs the response, and returns the response.
- Parameters:
  - chatClientRequest (ChatClientRequest) - The request to process.
  - callAdvisorChain (CallAdvisorChain) - The chain to invoke the next advisor.
- Returns: ChatClientResponse - The response from the next advisor.

#### adviseStream(ChatClientRequest, StreamAdvisorChain)
- Logs the request, calls the next advisor in the chain, aggregates the streamed responses, and logs the aggregated response.
- Parameters:
  - chatClientRequest (ChatClientRequest) - The request to process.
  - streamAdvisorChain (StreamAdvisorChain) - The chain to invoke the next advisor.
- Returns: Flux<ChatClientResponse> - The stream of responses from the next advisor.

### Notes
- The advisor only observes the request and response and does not modify them.
- The MessageAggregator utility aggregates the Flux responses into a single ChatClientResponse for logging; it is read-only.
```

--------------------------------

### StreamAdvisorChain interface

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Chain interface for reactive advisors. Provides nextStream to invoke the next advisor and getStreamAdvisors to retrieve the list of advisors in the chain.

```java
public interface StreamAdvisorChain extends AdvisorChain {

	/**
	 * Invokes the next {@link StreamAdvisor} in the {@link StreamAdvisorChain} with the
	 * given request.
	 */
	Flux<ChatClientResponse> nextStream(ChatClientRequest chatClientRequest);

	/**
	 * Returns the list of all the {@link StreamAdvisor} instances included in this chain
	 * at the time of its creation.
	 */
	List<StreamAdvisor> getStreamAdvisors();

}
```

--------------------------------

### Advanced RAG with RewriteQueryTransformer

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Advanced RAG flow that adds a RewriteQueryTransformer to rewrite the query before retrieval. The transformer uses a mutated chat client builder.

```java
Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        .queryTransformers(RewriteQueryTransformer.builder()
                .chatClientBuilder(chatClientBuilder.build().mutate())
                .build())
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .similarityThreshold(0.50)
                .vectorStore(vectorStore)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(retrievalAugmentationAdvisor)
        .user(question)
        .call()
        .content();
```

--------------------------------

### StreamAdvisor

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Reactive advisor interface for intercepting streaming chat client calls.

```APIDOC
## StreamAdvisor Interface

### Description
Reactive advisor that can intercept and modify streaming chat client requests and responses.

### Method
- `Flux<ChatClientResponse> adviseStream(ChatClientRequest chatClientRequest, StreamAdvisorChain streamAdvisorChain)` - Processes the request and returns a reactive stream of responses, continuing the chain.
```

--------------------------------

### CallAdvisor interface

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Sub-interface for synchronous advisors. The adviseCall method takes a ChatClientRequest and a CallAdvisorChain, and returns a ChatClientResponse.

```java
public interface CallAdvisor extends Advisor {

	ChatClientResponse adviseCall(
		ChatClientRequest chatClientRequest, CallAdvisorChain callAdvisorChain);

}
```

--------------------------------

### VectorStoreDocumentRetriever.retrieve(Query)

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Retrieves documents from the vector store based on the given query. Supports request-specific filter expressions via the Query API.

```APIDOC
## VectorStoreDocumentRetriever.retrieve(Query)

### Description
Retrieves documents from the vector store that are semantically similar to the input query. Supports request-specific filter expressions via the Query API.

### Method
retrieve(Query)

### Parameters
- **query** (Query) - Required - The query object containing the text and optional context with filter expressions.

### Request Example
```java
Query query = Query.builder()
    .text("Who is Anacletus?")
    .context(Map.of(VectorStoreDocumentRetriever.FILTER_EXPRESSION, "location == 'Whispering Woods'"))
    .build();
List<Document> retrievedDocuments = documentRetriever.retrieve(query);
```

### Response
Returns a list of Document objects that match the query and filter criteria.

### Notes
- If both request-specific and retriever-specific filter expressions are provided, the request-specific filter expression takes precedence.
```

--------------------------------

### CallAdvisor

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Synchronous advisor interface for intercepting chat client calls.

```APIDOC
## CallAdvisor Interface

### Description
Synchronous advisor that can intercept and modify chat client requests and responses.

### Method
- `ChatClientResponse adviseCall(ChatClientRequest chatClientRequest, CallAdvisorChain callAdvisorChain)` - Processes the request and returns a response, continuing the chain.
```

--------------------------------

### Spring Ordered interface with precedence constants

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

The Spring Ordered interface defines precedence constants and the getOrder() method used to determine advisor execution order. Lower values indicate higher priority; equal values result in arbitrary ordering.

```java
public interface Ordered {

    /**
     * Constant for the highest precedence value.
     * @see java.lang.Integer#MIN_VALUE
     */
    int HIGHEST_PRECEDENCE = Integer.MIN_VALUE;

    /**
     * Constant for the lowest precedence value.
     * @see java.lang.Integer#MAX_VALUE
     */
    int LOWEST_PRECEDENCE = Integer.MAX_VALUE;

    /**
     * Get the order value of this object.
     * <p>Higher values are interpreted as lower priority. As a consequence,
     * the object with the lowest value has the highest priority (somewhat
     * analogous to Servlet {@code load-on-startup} values).
     * <p>Same order values will result in arbitrary sort positions for the
     * affected objects.
     * @return the order value
     * @see #HIGHEST_PRECEDENCE
     * @see #LOWEST_PRECEDENCE
     */
    int getOrder();
}
```

--------------------------------

### StreamAdvisor interface

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

Sub-interface for reactive advisors. The adviseStream method takes a ChatClientRequest and a StreamAdvisorChain, and returns a Flux<ChatClientResponse>.

```java
public interface StreamAdvisor extends Advisor {

	Flux<ChatClientResponse> adviseStream(
		ChatClientRequest chatClientRequest, StreamAdvisorChain streamAdvisorChain);

}
```

--------------------------------

### ConcatenationDocumentJoiner.join(Map<Query, List<List<Document>>>)

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Combines documents retrieved based on multiple queries and from multiple data sources by concatenating them into a single collection. Duplicate documents are removed, keeping the first occurrence.

```APIDOC
## ConcatenationDocumentJoiner.join(Map<Query, List<List<Document>>>)

### Description
Combines documents retrieved based on multiple queries and from multiple data sources by concatenating them into a single collection of documents. In case of duplicate documents, the first occurrence is kept. The score of each document is kept as is.

### Method
join(Map<Query, List<List<Document>>>)

### Parameters
- **documentsForQuery** (Map<Query, List<List<Document>>>) - Required - A map where each query maps to a list of lists of documents retrieved from different sources.

### Request Example
```java
Map<Query, List<List<Document>>> documentsForQuery = ...
DocumentJoiner documentJoiner = new ConcatenationDocumentJoiner();
List<Document> documents = documentJoiner.join(documentsForQuery);
```

### Response
Returns a single list of Document objects, with duplicates removed and scores preserved.
```

--------------------------------

### Filter with FILTER_EXPRESSION at runtime

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Filter search results by metadata using the FILTER_EXPRESSION advisor context parameter at runtime. The filter expression 'type == \'Spring\'' is passed per request.

```java
Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .similarityThreshold(0.50)
                .vectorStore(vectorStore)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(retrievalAugmentationAdvisor)
        .advisors(a -> a.param(VectorStoreDocumentRetriever.FILTER_EXPRESSION, "type == 'Spring'"))
        .user(question)
        .call()
        .content();
```

--------------------------------

### ReReadingAdvisor

Source: https://docs.spring.io/spring-ai/reference/api/advisors.html

An advisor that applies the Re-Reading (Re2) technique to augment the user's input query. It implements BaseAdvisor.

```APIDOC
## ReReadingAdvisor

### Description
Augments the user's input query using the Re-Reading (Re2) technique to improve reasoning in large language models.

### Constructors

#### ReReadingAdvisor()
- Creates an advisor with the default Re2 template.

#### ReReadingAdvisor(String re2AdviseTemplate)
- Creates an advisor with a custom Re2 template.
- Parameters:
  - re2AdviseTemplate (String) - The template to use for augmentation.

### Methods

#### before(ChatClientRequest, AdvisorChain)
- Augments the user's input query by applying the Re2 template and returns the modified request.
- Parameters:
  - chatClientRequest (ChatClientRequest) - The original request.
  - advisorChain (AdvisorChain) - The advisor chain (not used in this method).
- Returns: ChatClientRequest - The request with the augmented user message.

#### after(ChatClientResponse, AdvisorChain)
- Returns the response unchanged.
- Parameters:
  - chatClientResponse (ChatClientResponse) - The response from the chain.
  - advisorChain (AdvisorChain) - The advisor chain.
- Returns: ChatClientResponse - The unchanged response.

#### getOrder()
- Returns the order of execution. Lower values execute first.
- Returns: int - the order value.

#### withOrder(int order)
- Sets the order of execution and returns this advisor.
- Parameters:
  - order (int) - The order value.
- Returns: ReReadingAdvisor - This advisor instance.

### Notes
- The default template is: "{re2_input_query}\nRead the question again: {re2_input_query}".
```

--------------------------------

### Request-specific filter expression via Query API

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Provides a request-specific filter expression via the Query API using the FILTER_EXPRESSION parameter. This filter takes precedence over the retriever-specific filter if both are set.

```java
Query query = Query.builder()
    .text("Who is Anacletus?")
    .context(Map.of(VectorStoreDocumentRetriever.FILTER_EXPRESSION, "location == 'Whispering Woods'"))
    .build();
List<Document> retrievedDocuments = documentRetriever.retrieve(query);
```

--------------------------------

### ConcatenationDocumentJoiner to combine documents

Source: https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html

Uses ConcatenationDocumentJoiner to combine documents from multiple queries and sources. Duplicate documents are kept only on first occurrence, and scores are preserved.

```java
Map<Query, List<List<Document>>> documentsForQuery = ...
DocumentJoiner documentJoiner = new ConcatenationDocumentJoiner();
List<Document> documents = documentJoiner.join(documentsForQuery);
```
Tokens:
Raw