Configure TemplateRenderer in ChatClient

- Extend the ChatClient with a new templateRenderer() method to pass a custom TemplateRenderer object used to render user and system templates.
- Evolve the QuestionAnswerAdvisor to accept a PromptTemplate for customising the RAG prompt and templating logic while maintaining backward compatibility.
- Introduce integration tests for the QuestionAnswerAdvisor.
- Document the TemplateRenderer API and how to use it to build PromptTemplate with custom templating logic.
- Document how to customise the templating logic used internally by the ChatClient via the TemplateRendererAPI.

Add validation tests and improve PromptTemplate resource handling

Enhance robustness and reliability of the PromptTemplate class with better
resource handling and comprehensive input validation:

- Add dedicated validation tests for builder methods with null/invalid inputs
- Improve renderResource method to gracefully handle edge cases:
  - Null resources return empty string
  - ByteArrayResource handling with proper charset (UTF-8)
  - Empty resources check with proper existence test
  - Better error handling with logging instead of exception propagation
- Add input validation assertions to all Builder methods
- Fix typo in deprecated annotation comment ("fahvor" → "favor")

Update documentation to clarify template rendering in different contexts:
- Add clear notes about TemplateRenderer usage in ChatClient vs Advisors
- Document how advisor template customization differs from ChatClient template rendering
- Add comprehensive API upgrade notes for template-related deprecations
- Include detailed migration examples for PromptTemplate and QuestionAnswerAdvisor

Fixes gh-355, gh-1687, gh-2448, gh-1849, gh-1428

Signed-off-by: Thomas Vitale <[email protected]>

Author: ThomasVitale

advisors/spring-ai-advisors-vector-store/src/main/java/org/springframework/ai/chat/client/advisor/vectorstore/QuestionAnswerAdvisor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -39,6 +39,7 @@
 import org.springframework.ai.vectorstore.VectorStore;
 import org.springframework.ai.vectorstore.filter.Filter;
 import org.springframework.ai.vectorstore.filter.FilterExpressionTextParser;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
@@ -49,6 +50,7 @@
  * @author Christian Tzolov
  * @author Timo Salm
  * @author Ilayaperumal Gopinathan
+ * @author Thomas Vitale
  * @since 1.0.0
  */
 public class QuestionAnswerAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {
@@ -57,7 +59,7 @@ public class QuestionAnswerAdvisor implements CallAroundAdvisor, StreamAroundAdv
 
 	public static final String FILTER_EXPRESSION = "qa_filter_expression";
 
-	private static final String DEFAULT_USER_TEXT_ADVISE = """
+	private static final PromptTemplate DEFAULT_PROMPT_TEMPLATE = new PromptTemplate("""
 
 			Context information is below, surrounded by ---------------------
 
@@ -68,13 +70,13 @@ public class QuestionAnswerAdvisor implements CallAroundAdvisor, StreamAroundAdv
 			Given the context and provided history information and not prior knowledge,
 			reply to the user comment. If the answer is not in the context, inform
 			the user that you can't answer the question.
-			""";
+			""");
 
 	private static final int DEFAULT_ORDER = 0;
 
 	private final VectorStore vectorStore;
 
-	private final String userTextAdvise;
+	private final PromptTemplate promptTemplate;
 
 	private final SearchRequest searchRequest;
 
@@ -88,7 +90,7 @@ public class QuestionAnswerAdvisor implements CallAroundAdvisor, StreamAroundAdv
 	 * @param vectorStore The vector store to use
 	 */
 	public QuestionAnswerAdvisor(VectorStore vectorStore) {
-		this(vectorStore, SearchRequest.builder().build(), DEFAULT_USER_TEXT_ADVISE);
+		this(vectorStore, SearchRequest.builder().build(), DEFAULT_PROMPT_TEMPLATE, true, DEFAULT_ORDER);
 	}
 
 	/**
@@ -97,9 +99,11 @@ public QuestionAnswerAdvisor(VectorStore vectorStore) {
 	 * @param vectorStore The vector store to use
 	 * @param searchRequest The search request defined using the portable filter
 	 * expression syntax
+	 * @deprecated in favor of the builder: {@link #builder(VectorStore)}
 	 */
+	@Deprecated
 	public QuestionAnswerAdvisor(VectorStore vectorStore, SearchRequest searchRequest) {
-		this(vectorStore, searchRequest, DEFAULT_USER_TEXT_ADVISE);
+		this(vectorStore, searchRequest, DEFAULT_PROMPT_TEMPLATE, true, DEFAULT_ORDER);
 	}
 
 	/**
@@ -110,9 +114,12 @@ public QuestionAnswerAdvisor(VectorStore vectorStore, SearchRequest searchReques
 	 * expression syntax
 	 * @param userTextAdvise The user text to append to the existing user prompt. The text
 	 * should contain a placeholder named "question_answer_context".
+	 * @deprecated in favor of the builder: {@link #builder(VectorStore)}
 	 */
+	@Deprecated
 	public QuestionAnswerAdvisor(VectorStore vectorStore, SearchRequest searchRequest, String userTextAdvise) {
-		this(vectorStore, searchRequest, userTextAdvise, true);
+		this(vectorStore, searchRequest, PromptTemplate.builder().template(userTextAdvise).build(), true,
+				DEFAULT_ORDER);
 	}
 
 	/**
@@ -127,10 +134,13 @@ public QuestionAnswerAdvisor(VectorStore vectorStore, SearchRequest searchReques
 	 * blocking threads. If false the advisor will not protect the execution from blocking
 	 * threads. This is useful when the advisor is used in a non-blocking environment. It
 	 * is true by default.
+	 * @deprecated in favor of the builder: {@link #builder(VectorStore)}
 	 */
+	@Deprecated
 	public QuestionAnswerAdvisor(VectorStore vectorStore, SearchRequest searchRequest, String userTextAdvise,
 			boolean protectFromBlocking) {
-		this(vectorStore, searchRequest, userTextAdvise, protectFromBlocking, DEFAULT_ORDER);
+		this(vectorStore, searchRequest, PromptTemplate.builder().template(userTextAdvise).build(), protectFromBlocking,
+				DEFAULT_ORDER);
 	}
 
 	/**
@@ -146,17 +156,23 @@ public QuestionAnswerAdvisor(VectorStore vectorStore, SearchRequest searchReques
 	 * threads. This is useful when the advisor is used in a non-blocking environment. It
 	 * is true by default.
 	 * @param order The order of the advisor.
+	 * @deprecated in favor of the builder: {@link #builder(VectorStore)}
 	 */
+	@Deprecated
 	public QuestionAnswerAdvisor(VectorStore vectorStore, SearchRequest searchRequest, String userTextAdvise,
 			boolean protectFromBlocking, int order) {
+		this(vectorStore, searchRequest, PromptTemplate.builder().template(userTextAdvise).build(), protectFromBlocking,
+				order);
+	}
 
-		Assert.notNull(vectorStore, "The vectorStore must not be null!");
-		Assert.notNull(searchRequest, "The searchRequest must not be null!");
-		Assert.hasText(userTextAdvise, "The userTextAdvise must not be empty!");
+	QuestionAnswerAdvisor(VectorStore vectorStore, SearchRequest searchRequest, @Nullable PromptTemplate promptTemplate,
+			boolean protectFromBlocking, int order) {
+		Assert.notNull(vectorStore, "vectorStore cannot be null");
+		Assert.notNull(searchRequest, "searchRequest cannot be null");
 
 		this.vectorStore = vectorStore;
 		this.searchRequest = searchRequest;
-		this.userTextAdvise = userTextAdvise;
+		this.promptTemplate = promptTemplate != null ? promptTemplate : DEFAULT_PROMPT_TEMPLATE;
 		this.protectFromBlocking = protectFromBlocking;
 		this.order = order;
 	}
@@ -212,32 +228,30 @@ private AdvisedRequest before(AdvisedRequest request) {
 
 		var context = new HashMap<>(request.adviseContext());
 
-		// 1. Advise the system text.
-		String advisedUserText = request.userText() + System.lineSeparator() + this.userTextAdvise;
-
-		// 2. Search for similar documents in the vector store.
-		String query = new PromptTemplate(request.userText(), request.userParams()).render();
+		// 1. Search for similar documents in the vector store.
 		var searchRequestToUse = SearchRequest.from(this.searchRequest)
-			.query(query)
+			.query(request.userText())
 			.filterExpression(doGetFilterExpression(context))
 			.build();
 
 		List<Document> documents = this.vectorStore.similaritySearch(searchRequestToUse);
 
-		// 3. Create the context from the documents.
+		// 2. Create the context from the documents.
 		context.put(RETRIEVED_DOCUMENTS, documents);
 
 		String documentContext = documents.stream()
 			.map(Document::getText)
 			.collect(Collectors.joining(System.lineSeparator()));
 
-		// 4. Advise the user parameters.
-		Map<String, Object> advisedUserParams = new HashMap<>(request.userParams());
-		advisedUserParams.put("question_answer_context", documentContext);
+		// 3. Augment the user prompt with the document context.
+		String augmentedUserText = this.promptTemplate.mutate()
+			.template(request.userText() + System.lineSeparator() + this.promptTemplate.getTemplate())
+			.variables(Map.of("question_answer_context", documentContext))
+			.build()
+			.render();
 
 		AdvisedRequest advisedRequest = AdvisedRequest.from(request)
-			.userText(advisedUserText)
-			.userParams(advisedUserParams)
+			.userText(augmentedUserText)
 			.adviseContext(context)
 			.build();
 
@@ -266,7 +280,7 @@ public static final class Builder {
 
 		private SearchRequest searchRequest = SearchRequest.builder().build();
 
-		private String userTextAdvise = DEFAULT_USER_TEXT_ADVISE;
+		private PromptTemplate promptTemplate;
 
 		private boolean protectFromBlocking = true;
 
@@ -277,15 +291,25 @@ private Builder(VectorStore vectorStore) {
 			this.vectorStore = vectorStore;
 		}
 
+		public Builder promptTemplate(PromptTemplate promptTemplate) {
+			Assert.notNull(promptTemplate, "promptTemplate cannot be null");
+			this.promptTemplate = promptTemplate;
+			return this;
+		}
+
 		public Builder searchRequest(SearchRequest searchRequest) {
 			Assert.notNull(searchRequest, "The searchRequest must not be null!");
 			this.searchRequest = searchRequest;
 			return this;
 		}
 
+		/**
+		 * @deprecated in favour of {@link #promptTemplate(PromptTemplate)}
+		 */
+		@Deprecated
 		public Builder userTextAdvise(String userTextAdvise) {
 			Assert.hasText(userTextAdvise, "The userTextAdvise must not be empty!");
-			this.userTextAdvise = userTextAdvise;
+			this.promptTemplate = PromptTemplate.builder().template(userTextAdvise).build();
 			return this;
 		}
 
@@ -300,7 +324,7 @@ public Builder order(int order) {
 		}
 
 		public QuestionAnswerAdvisor build() {
-			return new QuestionAnswerAdvisor(this.vectorStore, this.searchRequest, this.userTextAdvise,
+			return new QuestionAnswerAdvisor(this.vectorStore, this.searchRequest, this.promptTemplate,
 					this.protectFromBlocking, this.order);
 		}
 

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/client/OpenAiChatClientIT.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,6 +43,7 @@
 import org.springframework.ai.openai.api.OpenAiApi.ChatCompletionRequest.AudioParameters;
 import org.springframework.ai.openai.api.tool.MockWeatherService;
 import org.springframework.ai.openai.testutils.AbstractIT;
+import org.springframework.ai.template.st.StTemplateRenderer;
 import org.springframework.ai.test.CurlyBracketEscaper;
 import org.springframework.ai.tool.function.FunctionToolCallback;
 import org.springframework.beans.factory.annotation.Value;
@@ -378,6 +379,124 @@ void multiModalityAudioResponse() {
 		logger.info("Response: " + response);
 	}
 
+	@Test
+	void customTemplateRendererWithCall() {
+		BeanOutputConverter<ActorsFilms> outputConverter = new BeanOutputConverter<>(ActorsFilms.class);
+
+		// @formatter:off
+		String result = ChatClient.create(this.chatModel).prompt()
+				.user(u -> u
+						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
+								+ "<format>")
+						.param("format", outputConverter.getFormat()))
+				.templateRenderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
+				.call()
+				.content();
+		// @formatter:on
+
+		assertThat(result).isNotEmpty();
+		ActorsFilms actorsFilms = outputConverter.convert(result);
+
+		logger.info("" + actorsFilms);
+		assertThat(actorsFilms.actor()).isEqualTo("Tom Hanks");
+		assertThat(actorsFilms.movies()).hasSize(5);
+	}
+
+	@Test
+	void customTemplateRendererWithCallAndAdvisor() {
+		BeanOutputConverter<ActorsFilms> outputConverter = new BeanOutputConverter<>(ActorsFilms.class);
+
+		// @formatter:off
+		String result = ChatClient.create(this.chatModel).prompt()
+				.advisors(new SimpleLoggerAdvisor())
+				.user(u -> u
+						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
+								+ "<format>")
+						.param("format", outputConverter.getFormat()))
+				.templateRenderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
+				.call()
+				.content();
+		// @formatter:on
+
+		assertThat(result).isNotEmpty();
+		ActorsFilms actorsFilms = outputConverter.convert(result);
+
+		logger.info("" + actorsFilms);
+		assertThat(actorsFilms.actor()).isEqualTo("Tom Hanks");
+		assertThat(actorsFilms.movies()).hasSize(5);
+	}
+
+	@Test
+	void customTemplateRendererWithStream() {
+		BeanOutputConverter<ActorsFilms> outputConverter = new BeanOutputConverter<>(ActorsFilms.class);
+
+		// @formatter:off
+		Flux<ChatResponse> chatResponse = ChatClient.create(this.chatModel)
+				.prompt()
+				.options(OpenAiChatOptions.builder().streamUsage(true).build())
+				.user(u -> u
+						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
+								+ "<format>")
+						.param("format", outputConverter.getFormat()))
+				.templateRenderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
+				.stream()
+				.chatResponse();
+
+		List<ChatResponse> chatResponses = chatResponse.collectList()
+				.block()
+				.stream()
+				.toList();
+
+		String generationTextFromStream = chatResponses
+				.stream()
+				.filter(cr -> cr.getResult() != null)
+				.map(cr -> cr.getResult().getOutput().getText())
+				.collect(Collectors.joining());
+		// @formatter:on
+
+		ActorsFilms actorsFilms = outputConverter.convert(generationTextFromStream);
+
+		logger.info("" + actorsFilms);
+		assertThat(actorsFilms.actor()).isEqualTo("Tom Hanks");
+		assertThat(actorsFilms.movies()).hasSize(5);
+	}
+
+	@Test
+	void customTemplateRendererWithStreamAndAdvisor() {
+		BeanOutputConverter<ActorsFilms> outputConverter = new BeanOutputConverter<>(ActorsFilms.class);
+
+		// @formatter:off
+		Flux<ChatResponse> chatResponse = ChatClient.create(this.chatModel)
+				.prompt()
+				.options(OpenAiChatOptions.builder().streamUsage(true).build())
+				.advisors(new SimpleLoggerAdvisor())
+				.user(u -> u
+						.text("Generate the filmography of 5 movies for Tom Hanks. " + System.lineSeparator()
+								+ "<format>")
+						.param("format", outputConverter.getFormat()))
+				.templateRenderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
+				.stream()
+				.chatResponse();
+
+		List<ChatResponse> chatResponses = chatResponse.collectList()
+				.block()
+				.stream()
+				.toList();
+
+		String generationTextFromStream = chatResponses
+				.stream()
+				.filter(cr -> cr.getResult() != null)
+				.map(cr -> cr.getResult().getOutput().getText())
+				.collect(Collectors.joining());
+		// @formatter:on
+
+		ActorsFilms actorsFilms = outputConverter.convert(generationTextFromStream);
+
+		logger.info("" + actorsFilms);
+		assertThat(actorsFilms.actor()).isEqualTo("Tom Hanks");
+		assertThat(actorsFilms.movies()).hasSize(5);
+	}
+
 	record ActorsFilms(String actor, List<String> movies) {
 
 	}

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/ChatClient.java

@@ -34,6 +34,7 @@
 import org.springframework.ai.chat.prompt.Prompt;
 import org.springframework.ai.content.Media;
 import org.springframework.ai.converter.StructuredOutputConverter;
+import org.springframework.ai.template.TemplateRenderer;
 import org.springframework.ai.tool.ToolCallback;
 import org.springframework.ai.tool.ToolCallbackProvider;
 import org.springframework.core.ParameterizedTypeReference;
@@ -247,6 +248,8 @@ interface ChatClientRequestSpec {
 
 		ChatClientRequestSpec user(Consumer<PromptUserSpec> consumer);
 
+		ChatClientRequestSpec templateRenderer(TemplateRenderer templateRenderer);
+
 		CallResponseSpec call();
 
 		StreamResponseSpec stream();
@@ -282,6 +285,8 @@ interface Builder {
 
 		Builder defaultSystem(Consumer<PromptSystemSpec> systemSpecConsumer);
 
+		Builder defaultTemplateRenderer(TemplateRenderer templateRenderer);
+
 		Builder defaultTools(String... toolNames);
 
 		Builder defaultTools(ToolCallback... toolCallbacks);