Introduce TemplateRenderer for prompt templating

- Introduce new TemplateRenderer API providing the logic for rendering an input template.
- Update the PromptTemplate API to accept a TemplateRenderer object at construction time.
- Move ST logic to StTemplateRenderer implementation, used by default in PromptTemplate.
- Extend ChatClient API to support passing a custom TemplateRenderer.

- Add integration tests showing how to customize prompts in QuestionAnswerAdvisor and RetrievalAugmentationAdvisor.
- Support PromptTemplate instead of String in QuestionAnswerAdvisor.

Relates to spring-projectsgh-2655

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.
@@ -21,6 +21,7 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
+import org.springframework.lang.Nullable;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 import reactor.core.scheduler.Schedulers;
@@ -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,10 +228,7 @@ 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.
+		// 1. Search for similar documents in the vector store.
 		String query = new PromptTemplate(request.userText(), request.userParams()).render();
 		var searchRequestToUse = SearchRequest.from(this.searchRequest)
 			.query(query)
@@ -224,20 +237,21 @@ private AdvisedRequest before(AdvisedRequest request) {
 
 		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())
+			.build()
+			.render(Map.of("question_answer_context", documentContext));
 
 		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;
 
@@ -283,9 +297,15 @@ public Builder searchRequest(SearchRequest searchRequest) {
 			return this;
 		}
 
+		public Builder promptTemplate(PromptTemplate promptTemplate) {
+			Assert.notNull(promptTemplate, "promptTemplate cannot be null");
+			this.promptTemplate = promptTemplate;
+			return this;
+		}
+
 		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 +320,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);
 		}
 

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

@@ -32,6 +32,7 @@
 import org.springframework.ai.chat.model.ChatResponse;
 import org.springframework.ai.chat.prompt.ChatOptions;
 import org.springframework.ai.chat.prompt.Prompt;
+import org.springframework.ai.chat.prompt.template.TemplateRenderer;
 import org.springframework.ai.content.Media;
 import org.springframework.ai.converter.StructuredOutputConverter;
 import org.springframework.ai.model.function.FunctionCallback;
@@ -254,6 +255,8 @@ interface ChatClientRequestSpec {
 
 		ChatClientRequestSpec user(Consumer<PromptUserSpec> consumer);
 
+		ChatClientRequestSpec promptTemplateRenderer(TemplateRenderer templateRenderer);
+
 		CallResponseSpec call();
 
 		StreamResponseSpec stream();
@@ -313,6 +316,8 @@ interface Builder {
 
 		Builder defaultToolContext(Map<String, Object> toolContext);
 
+		Builder defaultPromptTemplateRenderer(TemplateRenderer templateRenderer);
+
 		Builder clone();
 
 		ChatClient build();

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

@@ -59,6 +59,8 @@
 import org.springframework.ai.chat.model.StreamingChatModel;
 import org.springframework.ai.chat.prompt.ChatOptions;
 import org.springframework.ai.chat.prompt.Prompt;
+import org.springframework.ai.chat.prompt.template.TemplateRenderer;
+import org.springframework.ai.chat.prompt.template.st.StTemplateRenderer;
 import org.springframework.ai.content.Media;
 import org.springframework.ai.converter.BeanOutputConverter;
 import org.springframework.ai.converter.StructuredOutputConverter;
@@ -88,6 +90,8 @@ public class DefaultChatClient implements ChatClient {
 
 	private static final ChatClientObservationConvention DEFAULT_CHAT_CLIENT_OBSERVATION_CONVENTION = new DefaultChatClientObservationConvention();
 
+	private static final TemplateRenderer DEFAULT_PROMPT_TEMPLATE_RENDERER = StTemplateRenderer.builder().build();
+
 	private final DefaultChatClientRequestSpec defaultChatClientRequest;
 
 	public DefaultChatClient(DefaultChatClientRequestSpec defaultChatClientRequest) {
@@ -138,7 +142,7 @@ public static DefaultChatClientRequestSpec toDefaultChatClientRequestSpec(Advise
 				advisedRequest.functionCallbacks(), advisedRequest.messages(), advisedRequest.functionNames(),
 				advisedRequest.media(), advisedRequest.chatOptions(), advisedRequest.advisors(),
 				advisedRequest.advisorParams(), observationRegistry, customObservationConvention,
-				advisedRequest.toolContext());
+				advisedRequest.toolContext(), null);
 	}
 
 	@Override
@@ -666,6 +670,8 @@ public static class DefaultChatClientRequestSpec implements ChatClientRequestSpe
 
 		private final Map<String, Object> toolContext = new HashMap<>();
 
+		private TemplateRenderer promptTemplateRenderer;
+
 		@Nullable
 		private String userText;
 
@@ -679,15 +685,16 @@ public static class DefaultChatClientRequestSpec implements ChatClientRequestSpe
 		DefaultChatClientRequestSpec(DefaultChatClientRequestSpec ccr) {
 			this(ccr.chatModel, ccr.userText, ccr.userParams, ccr.systemText, ccr.systemParams, ccr.toolCallbacks,
 					ccr.messages, ccr.toolNames, ccr.media, ccr.chatOptions, ccr.advisors, ccr.advisorParams,
-					ccr.observationRegistry, ccr.observationConvention, ccr.toolContext);
+					ccr.observationRegistry, ccr.observationConvention, ccr.toolContext, ccr.promptTemplateRenderer);
 		}
 
 		public DefaultChatClientRequestSpec(ChatModel chatModel, @Nullable String userText,
 				Map<String, Object> userParams, @Nullable String systemText, Map<String, Object> systemParams,
 				List<FunctionCallback> toolCallbacks, List<Message> messages, List<String> toolNames, List<Media> media,
 				@Nullable ChatOptions chatOptions, List<Advisor> advisors, Map<String, Object> advisorParams,
 				ObservationRegistry observationRegistry,
-				@Nullable ChatClientObservationConvention observationConvention, Map<String, Object> toolContext) {
+				@Nullable ChatClientObservationConvention observationConvention, Map<String, Object> toolContext,
+				@Nullable TemplateRenderer promptTemplateRenderer) {
 
 			Assert.notNull(chatModel, "chatModel cannot be null");
 			Assert.notNull(userParams, "userParams cannot be null");
@@ -720,6 +727,8 @@ public DefaultChatClientRequestSpec(ChatModel chatModel, @Nullable String userTe
 			this.observationConvention = observationConvention != null ? observationConvention
 					: DEFAULT_CHAT_CLIENT_OBSERVATION_CONVENTION;
 			this.toolContext.putAll(toolContext);
+			this.promptTemplateRenderer = promptTemplateRenderer != null ? promptTemplateRenderer
+					: DEFAULT_PROMPT_TEMPLATE_RENDERER;
 
 			// At the stack bottom add the model call advisors.
 			// They play the role of the last advisors in the advisor chain.
@@ -789,6 +798,10 @@ public Map<String, Object> getToolContext() {
 			return this.toolContext;
 		}
 
+		public TemplateRenderer getPromptTemplateRenderer() {
+			return this.promptTemplateRenderer;
+		}
+
 		/**
 		 * Return a {@code ChatClient2Builder} to create a new {@code ChatClient2} whose
 		 * settings are replicated from this {@code ChatClientRequest}.
@@ -997,15 +1010,22 @@ public ChatClientRequestSpec user(Consumer<PromptUserSpec> consumer) {
 			return this;
 		}
 
+		public ChatClientRequestSpec promptTemplateRenderer(TemplateRenderer templateRenderer) {
+			Assert.notNull(templateRenderer, "templateRenderer cannot be null");
+			this.promptTemplateRenderer = templateRenderer;
+			return this;
+		}
+
 		public CallResponseSpec call() {
 			BaseAdvisorChain advisorChain = aroundAdvisorChainBuilder.build();
-			return new DefaultCallResponseSpec(toAdvisedRequest(this).toChatClientRequest(), advisorChain,
-					observationRegistry, observationConvention);
+			return new DefaultCallResponseSpec(toAdvisedRequest(this).toChatClientRequest(this.promptTemplateRenderer),
+					advisorChain, observationRegistry, observationConvention);
 		}
 
 		public StreamResponseSpec stream() {
 			BaseAdvisorChain advisorChain = aroundAdvisorChainBuilder.build();
-			return new DefaultStreamResponseSpec(toAdvisedRequest(this).toChatClientRequest(), advisorChain,
+			return new DefaultStreamResponseSpec(
+					toAdvisedRequest(this).toChatClientRequest(this.promptTemplateRenderer), advisorChain,
 					observationRegistry, observationConvention);
 		}
 

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

@@ -34,6 +34,7 @@
 import org.springframework.ai.chat.model.ChatModel;
 import org.springframework.ai.chat.model.ToolContext;
 import org.springframework.ai.chat.prompt.ChatOptions;
+import org.springframework.ai.chat.prompt.template.TemplateRenderer;
 import org.springframework.ai.model.function.FunctionCallback;
 import org.springframework.ai.tool.ToolCallback;
 import org.springframework.ai.tool.ToolCallbackProvider;
@@ -67,7 +68,7 @@ public DefaultChatClientBuilder(ChatModel chatModel, ObservationRegistry observa
 		Assert.notNull(observationRegistry, "the " + ObservationRegistry.class.getName() + " must be non-null");
 		this.defaultRequest = new DefaultChatClientRequestSpec(chatModel, null, Map.of(), null, Map.of(), List.of(),
 				List.of(), List.of(), List.of(), null, List.of(), Map.of(), observationRegistry,
-				customObservationConvention, Map.of());
+				customObservationConvention, Map.of(), null);
 	}
 
 	public ChatClient build() {
@@ -212,6 +213,12 @@ public Builder defaultToolContext(Map<String, Object> toolContext) {
 		return this;
 	}
 
+	public Builder defaultPromptTemplateRenderer(TemplateRenderer templateRenderer) {
+		Assert.notNull(templateRenderer, "templateRenderer cannot be null");
+		this.defaultRequest.promptTemplateRenderer(templateRenderer);
+		return this;
+	}
+
 	void addMessages(List<Message> messages) {
 		this.defaultRequest.messages(messages);
 	}