Introduce TemplateRenderer for prompt templating

pom.xml

@@ -33,6 +33,7 @@
 		<module>spring-ai-docs</module>
 		<module>spring-ai-bom</module>
 		<module>spring-ai-commons</module>
+		<module>spring-ai-template-st</module>
 		<module>spring-ai-client-chat</module>
 		<module>spring-ai-model</module>
 		<module>spring-ai-test</module>

spring-ai-bom/pom.xml

@@ -50,6 +50,12 @@
 				<version>${project.version}</version>
 			</dependency>
 
+			<dependency>
+				<groupId>org.springframework.ai</groupId>
+				<artifactId>spring-ai-template-st</artifactId>
+				<version>${project.version}</version>
+			</dependency>
+
 			<!-- Spring AI model -->
 
 			<dependency>

spring-ai-client-chat/src/test/java/org/springframework/ai/prompt/PromptTemplateTest.java

@@ -118,7 +118,7 @@ public void testRenderWithList() {
 
 		PromptTemplate unfilledPromptTemplate = new PromptTemplate(templateString);
 		assertThatExceptionOfType(IllegalStateException.class).isThrownBy(unfilledPromptTemplate::render)
-			.withMessage("Not all template variables were replaced. Missing variable names are [items]");
+			.withMessage("Not all variables were replaced in the template. Missing variable names are: [items].");
 	}
 
 	@Test

spring-ai-client-chat/src/test/java/org/springframework/ai/prompt/PromptTests.java

@@ -18,7 +18,6 @@
 
 import java.util.HashMap;
 import java.util.Map;
-import java.util.Set;
 
 import org.assertj.core.api.Assertions;
 import org.junit.jupiter.api.Test;
@@ -45,7 +44,7 @@ void newApiPlaygroundTests() {
 		// Try to render with missing value for template variable, expect exception
 		Assertions.assertThatThrownBy(() -> pt.render(model))
 			.isInstanceOf(IllegalStateException.class)
-			.hasMessage("Not all template variables were replaced. Missing variable names are [lastName]");
+			.hasMessage("Not all variables were replaced in the template. Missing variable names are: [lastName].");
 
 		pt.add("lastName", "Park"); // TODO investigate partial
 		String promptString = pt.render(model);
@@ -93,44 +92,6 @@ void newApiPlaygroundTests() {
 
 	}
 
-	@Test
-	void testSingleInputVariable() {
-		String template = "This is a {foo} test";
-		PromptTemplate promptTemplate = new PromptTemplate(template);
-		Set<String> inputVariables = promptTemplate.getInputVariables();
-		assertThat(inputVariables).isNotEmpty();
-		assertThat(inputVariables).hasSize(1);
-		assertThat(inputVariables).contains("foo");
-	}
-
-	@Test
-	void testMultipleInputVariables() {
-		String template = "This {bar} is a {foo} test";
-		PromptTemplate promptTemplate = new PromptTemplate(template);
-		Set<String> inputVariables = promptTemplate.getInputVariables();
-		assertThat(inputVariables).isNotEmpty();
-		assertThat(inputVariables).hasSize(2);
-		assertThat(inputVariables).contains("foo", "bar");
-	}
-
-	@Test
-	void testMultipleInputVariablesWithRepeats() {
-		String template = "This {bar} is a {foo} test {foo}.";
-		PromptTemplate promptTemplate = new PromptTemplate(template);
-		Set<String> inputVariables = promptTemplate.getInputVariables();
-		assertThat(inputVariables).isNotEmpty();
-		assertThat(inputVariables).hasSize(2);
-		assertThat(inputVariables).contains("foo", "bar");
-	}
-
-	@Test
-	void testBadFormatOfTemplateString() {
-		String template = "This is a {foo test";
-		Assertions.assertThatThrownBy(() -> new PromptTemplate(template))
-			.isInstanceOf(IllegalArgumentException.class)
-			.hasMessage("The template string is not valid.");
-	}
-
 	@Test
 	public void testPromptCopy() {
 		String template = "Hello, {name}! Your age is {age}.";

spring-ai-commons/src/main/java/org/springframework/ai/template/NoOpTemplateRenderer.java

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.template;
+
+import java.util.Map;
+
+import org.springframework.util.Assert;
+
+/**
+ * No-op implementation of {@link TemplateRenderer} that returns the template unchanged.
+ *
+ * @author Thomas Vitale
+ * @since 1.0.0
+ */
+public class NoOpTemplateRenderer implements TemplateRenderer {
+
+	@Override
+	public String apply(String template, Map<String, Object> variables) {
+		Assert.hasText(template, "template cannot be null or empty");
+		Assert.notNull(variables, "variables cannot be null");
+		Assert.noNullElements(variables.keySet(), "variables keys cannot be null");
+		return template;
+	}
+
+}

spring-ai-commons/src/main/java/org/springframework/ai/template/TemplateRenderer.java

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.template;
+
+import java.util.Map;
+import java.util.function.BiFunction;
+
+/**
+ * Renders a template using a given strategy.
+ *
+ * @author Thomas Vitale
+ * @since 1.0.0
+ */
+public interface TemplateRenderer extends BiFunction<String, Map<String, Object>, String> {
+
+	@Override
+	String apply(String template, Map<String, Object> variables);
+
+}

spring-ai-commons/src/main/java/org/springframework/ai/template/ValidationMode.java

@@ -0,0 +1,43 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.template;
+
+/**
+ * Validation modes for template renderers.
+ *
+ * @author Thomas Vitale
+ * @since 1.0.0
+ */
+public enum ValidationMode {
+
+	/**
+	 * If the validation fails, an exception is thrown. This is the default mode.
+	 */
+	THROW,
+
+	/**
+	 * If the validation fails, a warning is logged. The template is rendered with the
+	 * missing placeholders/variables. This mode is not recommended for production use.
+	 */
+	WARN,
+
+	/**
+	 * No validation is performed.
+	 */
+	NONE;
+
+}

spring-ai-commons/src/test/java/org/springframework/ai/template/NoOpTemplateRendererTests.java

@@ -0,0 +1,117 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.template;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Unit tests for {@link NoOpTemplateRenderer}.
+ *
+ * @author Thomas Vitale
+ */
+class NoOpTemplateRendererTests {
+
+	@Test
+	void shouldReturnUnchangedTemplate() {
+		NoOpTemplateRenderer renderer = new NoOpTemplateRenderer();
+		Map<String, Object> variables = new HashMap<>();
+		variables.put("name", "Spring AI");
+
+		String result = renderer.apply("Hello {name}!", variables);
+
+		assertThat(result).isEqualTo("Hello {name}!");
+	}
+
+	@Test
+	void shouldReturnUnchangedTemplateWithMultipleVariables() {
+		NoOpTemplateRenderer renderer = new NoOpTemplateRenderer();
+		Map<String, Object> variables = new HashMap<>();
+		variables.put("greeting", "Hello");
+		variables.put("name", "Spring AI");
+		variables.put("punctuation", "!");
+
+		String result = renderer.apply("{greeting} {name}{punctuation}", variables);
+
+		assertThat(result).isEqualTo("{greeting} {name}{punctuation}");
+	}
+
+	@Test
+	void shouldNotAcceptEmptyTemplate() {
+		NoOpTemplateRenderer renderer = new NoOpTemplateRenderer();
+		Map<String, Object> variables = new HashMap<>();
+
+		assertThatThrownBy(() -> renderer.apply("", variables)).isInstanceOf(IllegalArgumentException.class)
+			.hasMessageContaining("template cannot be null or empty");
+	}
+
+	@Test
+	void shouldNotAcceptNullTemplate() {
+		NoOpTemplateRenderer renderer = new NoOpTemplateRenderer();
+		Map<String, Object> variables = new HashMap<>();
+
+		assertThatThrownBy(() -> renderer.apply(null, variables)).isInstanceOf(IllegalArgumentException.class)
+			.hasMessageContaining("template cannot be null or empty");
+	}
+
+	@Test
+	void shouldNotAcceptNullVariables() {
+		NoOpTemplateRenderer renderer = new NoOpTemplateRenderer();
+		String template = "Hello!";
+
+		assertThatThrownBy(() -> renderer.apply(template, null)).isInstanceOf(IllegalArgumentException.class)
+			.hasMessageContaining("variables cannot be null");
+	}
+
+	@Test
+	void shouldNotAcceptVariablesWithNullKeySet() {
+		NoOpTemplateRenderer renderer = new NoOpTemplateRenderer();
+		String template = "Hello!";
+		Map<String, Object> variables = new HashMap<String, Object>();
+		variables.put(null, "Spring AI");
+
+		assertThatThrownBy(() -> renderer.apply(template, variables)).isInstanceOf(IllegalArgumentException.class)
+			.hasMessageContaining("variables keys cannot be null");
+	}
+
+	@Test
+	void shouldReturnUnchangedComplexTemplate() {
+		NoOpTemplateRenderer renderer = new NoOpTemplateRenderer();
+		Map<String, Object> variables = new HashMap<>();
+		variables.put("header", "Welcome");
+		variables.put("user", "Spring AI");
+		variables.put("items", "one, two, three");
+		variables.put("footer", "Goodbye");
+
+		String template = """
+				{header}
+				User: {user}
+				Items: {items}
+				{footer}
+				""";
+
+		String result = renderer.apply(template, variables);
+
+		assertThat(result).isEqualToNormalizingNewlines(template);
+	}
+
+}

spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc

@@ -43,6 +43,11 @@ To use this automation:
 
 This approach can save time and reduce the chance of errors when upgrading multiple projects or complex codebases.
 
+[[upgrading-to-1-0-0-m8]]
+== Upgrading to 1.0.0-M8
+
+* The `PromptTemplate` API has been redesigned to support a more flexible and extensible way of templating prompts, relying on a new `TemplateRenderer` API. As part of this change, the `getInputVariables()` and `validate()` methods have been deprecated and will throw an `UnsupportedOperationException` if called. Any logic specific to a template engine should be available through the `TemplateRenderer` API.
+
 [[upgrading-to-1-0-0-m7]]
 == Upgrading to 1.0.0-M7
 

spring-ai-model/pom.xml

@@ -47,6 +47,12 @@
 			<version>${project.parent.version}</version>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.ai</groupId>
+			<artifactId>spring-ai-template-st</artifactId>
+			<version>${project.parent.version}</version>
+		</dependency>
+
 		<dependency>
 			<groupId>io.micrometer</groupId>
 			<artifactId>micrometer-observation</artifactId>
@@ -63,12 +69,6 @@
 			<artifactId>reactor-core</artifactId>
 		</dependency>
 
-		<dependency>
-			<groupId>org.antlr</groupId>
-			<artifactId>ST4</artifactId>
-			<version>${ST4.version}</version>
-		</dependency>
-
 		<!-- ANTLR for Filter Expression Parsing -->
 		<dependency>
 			<groupId>org.antlr</groupId>