Template Content

Dotprompt uses a template syntax based on Handlebars, the popular templating language with existing implementations in several programming languages. This syntax allows for dynamic content insertion and basic logic within prompts.

Language Basics

All Dotprompt implementations MUST implement the Handlebars features specified in these docs, but MAY also implement additional capabilities as documented in the Handlebars language specification.

Expressions

Handlebars expressions are contained within {{}} tags.

Variable Interpolation

• Syntax: {{variableName}} or {{object.propertyName}}
• Description: Inserts the value of the specified variable.
• Example: Hello, {{name}} from {{address.city}}!

Escaped Expressions

• Syntax: \{{variableName}} (escaped expression), {{{variableName}}}
• Description: Renders the literal text {{variableName}} without interpolation.
• Example: This is how you show a variable: \{{variableName}}

Built-in Helpers

Dotprompt provides several built-in helpers to enhance template functionality.

Conditional Blocks

#if

• Syntax: {{#if condition}}...{{/if}}
• Description: Renders the block if the condition is truthy.
• Example:

  {{#if isLoggedIn}}
    Welcome back!
  {{/if}}
  

else

• Syntax: {{#if condition}}...{{else}}...{{/if}}
• Description: Provides an alternative block to render if the condition is falsy.
• Example:

  {{#if isLoggedIn}}
    Welcome back!
  {{else}}
    Please log in.
  {{/if}}
  

#unless

• Syntax: {{#unless condition}}...{{/unless}}
• Description: Renders the block if the condition is falsy.
• Example:

  {{#unless isLoggedIn}}
    Please log in to continue.
  {{/unless}}
  

Iteration

#each

• Syntax: {{#each array}}...{{/each}}
• Description: Iterates over an array or object properties, assigning this to the currently enumerated item and @index to the index or key within the array or object.
• Example:

  {{#each items}}
    - {{this}} is item {{@index}}
  {{/each}}
  

Dotprompt Helpers

The following helpers MUST be included in all implementations of Dotprompt and provide the tools to manage multi-message and multi-modal prompting.

json

• Syntax: {{json varName}}
• Description: Serializes the provided variable into JSON and inserts it at the expression point.
• Example:

  Here is information about the current user:
  
  {{ json currentUser }}
  

role

• Syntax: {{role "roleName"}}
• Description: Begins a new message with the specified role for multi-message prompts.
• Example:

  {{role "system"}}
  You are a helpful AI assistant.
  {{role "user"}}
  What's the weather like today?
  

history

• Syntax: {{history}}
• Description: Inserts the conversation history (passed as messages when rendering the template) for multi-turn prompts.
• Example:

  {{role "system"}}
  You are a helpful AI assistant.
  {{history}}
  {{role "user"}}
  What was my last question about?
  

media

• Syntax: {{media url=urlVariable}}
• Description: Inserts media content (e.g., images) into the prompt.
• Example:

  Describe this image:
  {{media url=imageUrl}}
  

section

• Syntax: {{section "sectionName"}}
• Description: Manually positions specific sections within the prompt.
• Example:

  This is the main content.
  
  {{section "output"}}
  
  This comes after the output instructions.
  

Partials

Partials are reusable template snippets that can be included in other templates.

• Syntax: {{>partialName}}
• Description: Includes the content of the specified partial.
• Example:

  {{>header}}
  Main content goes here.
  {{>footer}}
  

Partial with Arguments

• Syntax: {{>partialName arg1=value1 arg2=value2}}
• Description: Includes a partial with specific arguments.
• Example:

  {{>greeting name=userName style=greetingStyle}}
  

Partial with Context

• Syntax: {{>partialName this}}
• Description: Passes the current context to the partial.
• Example:

  {{#each items}}
    {{>listItem this}}
  {{/each}}
  

Custom Helpers

All Dotprompt implementations MUST allow for the definition of custom helpers to extend Dotprompt syntax. The specific mechanism of custom helper registration is up to the specific implementation. Custom helpers are used in the following manner:

• Basic Custom Helper: {{customHelperName arg1 "arg2"}}
• Named Arguments: {{customHelperName arg1=var1 arg2="var2"}}

Context Variables

When rendering a template, additional contextual information is provided as variables with a special @ prefix. Some of these are built-in:

• @root: references the root variable context regardless of current this
• @first: true when iterating the first item of an #each block.
• @last: true when iterating the last item of an #each block.
• @key: key name for the current iteration of an #each block.
• @metadata: provides access to metadata of the currently running prompt and passed in data arguments.
  • @metadata.prompt: access to the frontmatter configuration of the current prompt.
  • @metadata.docs: access to the passed in document context of the current execution.
  • @metadata.messages: access to the message history of the current execution.

In addition to the above context variables, you can provide a context argument when rendering a template to add additional contextual information. for example, a context argument of {state: {name: 'Evelyn'}, isAdmin: true} would create @state and @isAdmin variables accessible from inside the prompt.