Skip to content

PromptTemplate

PromptTemplate loads prompt templates from disk and renders them with a built-in template engine. Prompts are organized by category (one file per category) and accessed via dot-notation keys. The template engine supports variable interpolation, conditionals, iteration, and JSON serialization.

Import

import { PromptTemplate, PromptFormat } from "@modernpath/agent-framework";

Constructor

new PromptTemplate(promptsPath: string)
Parameter Type Description
promptsPath string Absolute or relative path to the directory containing prompt files.

Methods

Method Signature Description
load load(format?: PromptFormat): Promise<void> Reads all prompt files from promptsPath and registers templates. Format defaults to "yaml".
render render(key: string, context?: Record<string, any>): string Renders the template identified by key with the given context variables. Throws if the key is not found.
has has(key: string): boolean Returns true if a template with the given key exists.

PromptFormat

type PromptFormat = "yaml" | "json";

Template Syntax

The built-in template engine supports the following constructs:

Variable Interpolation

{{variable}}
{{nested.path}}

Resolves dot-separated paths against the context object. Returns an empty string for null or undefined values.

Conditionals

{{#if condition}}
  Content rendered when condition is truthy.
{{/if}}

The condition is resolved as a context path. Any truthy value (non-null, non-empty, non-zero) causes the block to render.

Iteration

{{#each items}}
  Item: {{name}} - {{value}}
{{/each}}

Iterates over an array in the context. Inside the block, array element properties are available directly. If the array element is a primitive, it is accessible via {{this}}.

JSON Serialization

{{json variable}}

Serializes the resolved value as a formatted JSON string (2-space indent). Useful for embedding structured data in prompts.

YAML Prompt File Example

Prompt files are organized with one file per category. The file name (without extension) becomes the category prefix.

prompts/synthesis.yaml
system: |
  You are an AI assistant analyzing building incidents.
  {{#if agentName}}Agent: {{agentName}}{{/if}}

user_template: |
  ## Context
  {{#if ragContext}}
  Retrieved knowledge:
  {{ragContext}}
  {{/if}}

  ## Telemetry Data
  {{#if telemetryData}}
  {{json telemetryData}}
  {{/if}}

  ## User Query
  {{prompt}}

grounding:
  with_sources: |
    Based on the following sources, provide your analysis.
    Sources:
    {{#each sources}}
    - {{documentName}} (score: {{score}})
    {{/each}}

The templates above register as:

  • synthesis.system
  • synthesis.user_template
  • synthesis.grounding.with_sources

Nested Prompt Structure

Templates can be nested arbitrarily. Objects with a template key are treated as leaf templates:

prompts/agent.yaml
parse:
  system: "Parse the following incident report."
  user:
    template: "Report: {{report}}\nPriority: {{priority}}"

rag:
  query_template: "Find documentation about {{topic}}"

This registers:

  • agent.parse.system
  • agent.parse.user (from the template key)
  • agent.rag.query_template

Code Example

import { PromptTemplate } from "@modernpath/agent-framework";

// Load prompts from a directory
const prompts = new PromptTemplate("./config/prompts");
await prompts.load("yaml");

// Check if a key exists before rendering
if (prompts.has("synthesis.system")) {
  const systemPrompt = prompts.render("synthesis.system", {
    agentName: "IncidentResolverAgent",
  });
  console.log(systemPrompt);
}

// Render with nested context
const userPrompt = prompts.render("synthesis.user_template", {
  ragContext: "Building temperature is 18.5C, setpoint is 21C.",
  telemetryData: {
    temperature: 18.5,
    setpoint: 21,
    outdoor: -5,
  },
  prompt: "Why is the building cold?",
});

// Render with iteration
const groundedPrompt = prompts.render("synthesis.grounding.with_sources", {
  sources: [
    { documentName: "heating-guide.md", score: 0.92 },
    { documentName: "troubleshooting.md", score: 0.87 },
  ],
});