Configure nested template interpretation (#1978)

Signed-off-by: Arnab Nandy <arnab_nandy7@yahoo.com>

Author: arnabnandy7

embabel-agent-api/src/main/kotlin/com/embabel/agent/spi/config/spring/AgentPlatformConfiguration.kt

@@ -101,7 +101,9 @@ class AgentPlatformConfiguration(
     }
 
     @Bean
-    fun templateRenderer(): TemplateRenderer = JinjavaTemplateRenderer()
+    @ConditionalOnMissingBean(TemplateRenderer::class)
+    fun templateRenderer(properties: AgentPlatformProperties): TemplateRenderer =
+        JinjavaTemplateRenderer(properties.template)
 
     /**
      * Fallback if we don't have a more interesting logger

embabel-agent-api/src/main/kotlin/com/embabel/agent/spi/config/spring/AgentPlatformProperties.kt

@@ -16,6 +16,7 @@
 package com.embabel.agent.spi.config.spring
 
 import com.embabel.agent.core.ActionQos
+import com.embabel.common.textio.template.JinjaProperties
 import org.springframework.boot.context.properties.ConfigurationProperties
 import org.springframework.boot.context.properties.NestedConfigurationProperty
 
@@ -53,6 +54,9 @@ class AgentPlatformProperties {
     @field:NestedConfigurationProperty
     var llmOperations: LlmOperationsConfig = LlmOperationsConfig()
 
+    @field:NestedConfigurationProperty
+    var template: JinjaProperties = JinjaProperties()
+
     @field:NestedConfigurationProperty
     var processIdGeneration: ProcessIdGenerationConfig = ProcessIdGenerationConfig()
 

embabel-agent-api/src/test/kotlin/com/embabel/agent/config/AgentPlatformPropertiesIntegrationTest.kt

@@ -27,6 +27,7 @@ import org.springframework.boot.context.properties.bind.Binder
 import org.springframework.boot.test.context.SpringBootTest
 import org.springframework.context.annotation.Bean
 import org.springframework.core.env.Environment
+import org.springframework.mock.env.MockEnvironment
 import org.springframework.test.context.ActiveProfiles
 import org.springframework.test.context.TestPropertySource
 
@@ -173,6 +174,10 @@ import org.springframework.test.context.TestPropertySource
         "embabel.agent.platform.llm-operations.prompts.generate-examples-by-default=false",
         "embabel.agent.platform.llm-operations.data-binding.max-attempts=20",
         "embabel.agent.platform.llm-operations.data-binding.fixed-backoff-millis=50",
+        "embabel.agent.platform.template.prefix=classpath:/custom-prompts/",
+        "embabel.agent.platform.template.suffix=.j2",
+        "embabel.agent.platform.template.fail-on-unknown-tokens=true",
+        "embabel.agent.platform.template.nested-interpretation-enabled=true",
         "embabel.agent.platform.models.anthropic.max-attempts=8",
         "embabel.agent.platform.models.anthropic.backoff-millis=3000",
         "embabel.agent.platform.models.openai.max-attempts=12",
@@ -257,6 +262,29 @@ class AgentPlatformPropertiesIntegrationTest {
         assertThat(properties.llmOperations.dataBinding.fixedBackoffMillis).isEqualTo(50L)
     }
 
+    @Test
+    fun `should bind template properties correctly`() {
+        assertThat(properties.template.prefix).isEqualTo("classpath:/custom-prompts/")
+        assertThat(properties.template.suffix).isEqualTo(".j2")
+        assertThat(properties.template.failOnUnknownTokens).isTrue()
+        assertThat(properties.template.nestedInterpretationEnabled).isTrue()
+    }
+
+    @Test
+    fun `should bind a partial template configuration using defaults`() {
+        val environment = MockEnvironment()
+            .withProperty("embabel.agent.platform.template.nested-interpretation-enabled", "true")
+
+        val bound = Binder.get(environment)
+            .bind("embabel.agent.platform", AgentPlatformProperties::class.java)
+            .get()
+
+        assertThat(bound.template.prefix).isEqualTo("classpath:/prompts/")
+        assertThat(bound.template.suffix).isEqualTo(".jinja")
+        assertThat(bound.template.failOnUnknownTokens).isFalse()
+        assertThat(bound.template.nestedInterpretationEnabled).isTrue()
+    }
+
     @Test
     fun `should bind model provider properties correctly`() {
         assertThat(properties.models.anthropic.maxAttempts).isEqualTo(8)
@@ -284,6 +312,10 @@ class AgentPlatformPropertiesIntegrationTest {
         assertThat(defaultProperties.scanning.annotation).isTrue()
         assertThat(defaultProperties.ranking.maxAttempts).isEqualTo(5)
         assertThat(defaultProperties.autonomy.agentConfidenceCutOff).isEqualTo(0.6)
+        assertThat(defaultProperties.template.prefix).isEqualTo("classpath:/prompts/")
+        assertThat(defaultProperties.template.suffix).isEqualTo(".jinja")
+        assertThat(defaultProperties.template.failOnUnknownTokens).isFalse()
+        assertThat(defaultProperties.template.nestedInterpretationEnabled).isFalse()
         assertThat(defaultProperties.models.anthropic.maxAttempts).isEqualTo(10)
         assertThat(defaultProperties.models.openai.maxAttempts).isEqualTo(10)
         assertThat(defaultProperties.test.mockMode).isTrue()

embabel-agent-api/src/test/kotlin/com/embabel/agent/spi/config/spring/AgentPlatformConfigurationTemplateTest.kt

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2024-2026 Embabel Pty Ltd.
+ *
+ * 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
+ *
+ * http://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 com.embabel.agent.spi.config.spring
+
+import com.embabel.common.textio.template.JinjaProperties
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.jupiter.api.Test
+
+class AgentPlatformConfigurationTemplateTest {
+
+    private val configuration = AgentPlatformConfiguration()
+
+    @Test
+    fun `template renderer should preserve nested template syntax by default`() {
+        val renderer = configuration.templateRenderer(AgentPlatformProperties())
+
+        val result = renderer.renderLiteralTemplate(
+            "{{ message }}",
+            mapOf("message" to "compute {{ 7*7 }} now"),
+        )
+
+        assertThat(result).isEqualTo("compute {{ 7*7 }} now")
+    }
+
+    @Test
+    fun `template renderer should support explicitly enabled nested interpretation`() {
+        val properties = AgentPlatformProperties().apply {
+            template = JinjaProperties(nestedInterpretationEnabled = true)
+        }
+        val renderer = configuration.templateRenderer(properties)
+
+        val result = renderer.renderLiteralTemplate(
+            "{{ message }}",
+            mapOf("message" to "compute {{ 7*7 }} now"),
+        )
+
+        assertThat(result).isEqualTo("compute 49 now")
+    }
+}

embabel-agent-docs/src/main/asciidoc/reference/configuration/page.adoc

@@ -731,6 +731,36 @@ TIP: For models with extended thinking enabled (like Claude with thinking mode),
 
 NOTE: The HTTP client configuration applies to all model providers that use Spring's `RestClient` and `WebClient`, including OpenAI, Anthropic, and OpenAI-compatible endpoints.
 
+===== Template Renderer
+
+From the `JinjaProperties` nested in `AgentPlatformProperties` - Jinja template renderer configuration.
+
+[cols="3,2,1,4",options="header"]
+|===
+|Property |Type |Default |Description
+
+|`embabel.agent.platform.template.prefix`
+|String
+|`classpath:/prompts/`
+|Spring resource prefix used to load templates
+
+|`embabel.agent.platform.template.suffix`
+|String
+|`.jinja`
+|Suffix added to template names that do not already include it
+
+|`embabel.agent.platform.template.fail-on-unknown-tokens`
+|Boolean
+|`false`
+|Whether rendering fails when a template contains unknown tokens
+
+|`embabel.agent.platform.template.nested-interpretation-enabled`
+|Boolean
+|`false`
+|Whether template syntax inside substituted values is evaluated recursively. Do not enable this for untrusted or user-provided values.
+
+|===
+
 ===== Server-Sent Events
 
 From `AgentPlatformProperties.SseConfig` - server-sent events configuration.

embabel-agent-docs/src/main/asciidoc/reference/templates/page.adoc

@@ -12,6 +12,26 @@ You can also specify a full resource path with https://docs.spring.io/spring-fra
 
 Once you have specified the template, you can create objects using a model map.
 
+Template syntax inside substituted values is treated as literal data by default.
+This prevents values such as user-provided text containing `{{ expression }}` from being evaluated recursively.
+
+The renderer can be configured under `embabel.agent.platform.template`:
+
+[source,yaml]
+----
+embabel:
+  agent:
+    platform:
+      template:
+        prefix: "classpath:/prompts/"
+        suffix: ".jinja"
+        fail-on-unknown-tokens: false
+        nested-interpretation-enabled: false
+----
+
+WARNING: Enabling `nested-interpretation-enabled` re-evaluates template syntax found inside substituted values.
+Do not enable it for templates that interpolate untrusted or user-provided text.
+
 An example:
 
 [tabs]
@@ -125,4 +145,4 @@ val result = context.ai()
 
 TIP: Don't rush to externalize prompts.
 In modern languages with multi-line strings, it's often easier to keep prompts in the codebase.
-Externalizing them can sacrifice type safety and lead to complexity and maintenance challenges.
+Externalizing them can sacrifice type safety and lead to complexity and maintenance challenges.