Compile a template to check for syntax errors.

Creates a clean copy with reset version history

@spec estimate_tokens(t(), inputs :: map()) :: integer()

Estimates the number of tokens that would be used by this template. This is useful for ensuring prompts don't exceed model token limits.

Note: This is a very rough estimation - tokens vary by model.

@spec format(t(), inputs :: map(), opts :: keyword()) :: String.t()

Format the template with inputs to replace with assigns. It returns the formatted text.

template = Jido.AI.Prompt.Template.from_string!("Suggest a name for a company that makes <%= @product %>?")
Jido.AI.Prompt.Template.format(template, %{product: "colorful socks"})
#=> "Suggest a name for a company that makes colorful socks?"

A Template supports storing input values on the struct. These could be set when the template is defined. If an input value is not provided when the format function is called, any inputs on the struct will be used.

Same as format/2 but raises on error.

@spec format_composed(t(), sub_templates :: map(), inputs :: map()) :: String.t()

Format a template with sub-templates.

This is useful when you want to compose a template from other templates. The sub-templates can be either Template structs or strings.

Example

main = Template.new!(%{text: "Header: <%= @intro %>

Body: <%= @body %>"})

intro = Template.new!(%{text: "Welcome <%= @name %>!"})
body = "This is the body text."

Template.format_composed(main, %{intro: intro, body: body}, %{name: "Alice"})
#=> "Header: Welcome Alice!

Body: This is the body text."

@spec format_text(text :: String.t(), inputs :: map(), engine :: :eex) :: String.t()

Format the template text with inputs to replace placeholders.

Operates directly on text to apply the inputs. This does not take the Template struct.

Jido.AI.Prompt.Template.format_text("Hi! My name is <%= @name %>.", %{name: "Jose"})
#=> "Hi! My name is Jose."

@spec from_string(text :: String.t(), opts :: keyword()) ::
  {:ok, t()} | {:error, String.t()}

Build a Template struct from a string.

Shortcut function for building a user prompt.

{:ok, template} = Jido.AI.Prompt.Template.from_string("Suggest a name for a company that makes <%= @product %>?")

@spec from_string!(text :: String.t(), opts :: keyword()) :: t() | no_return()

Build a Template struct from a string and return the struct or error if invalid.

Shortcut function for building a user prompt.

template = Jido.AI.Prompt.Template.from_string!("Suggest a name for a company that makes <%= @product %>?")

@spec from_string_with_defaults(
  text :: String.t(),
  defaults :: map(),
  opts :: keyword()
) ::
  {:ok, t()} | {:error, String.t()}

Build a Template with default values for parameters.

This is useful when you want to set some default values that can be overridden later.

template = Jido.AI.Prompt.Template.from_string_with_defaults(
  "Hello <%= @name %>, welcome to <%= @service %>!",
  %{service: "Jido AI"}
)
Jido.AI.Prompt.Template.format(template, %{name: "Alice"})
#=> "Hello Alice, welcome to Jido AI!"

@spec from_string_with_defaults!(
  text :: String.t(),
  defaults :: map(),
  opts :: keyword()
) ::
  t() | no_return()

Build a Template with default values for parameters. Raises an exception if the template is invalid.

template = Jido.AI.Prompt.Template.from_string_with_defaults!(
  "Hello <%= @name %>, welcome to <%= @service %>!",
  %{service: "Jido AI"}
)

Increments the version number of the template. Returns a new template with the incremented version and adds the previous version to history.

Lists all available versions of the template

@spec new(attrs :: map()) :: {:ok, t()} | {:error, String.t()}

Create a new Template struct using the attributes.

Example

{:ok, template} = Jido.AI.Prompt.Template.new(%{text: "My template", role: :user})

@spec new!(attrs :: map()) :: t() | no_return()

Create a new Template struct using the attributes. If invalid, an exception is raised with the reason.

Example

A template is created using a simple map with text and role keys.

Jido.AI.Prompt.Template.new!(%{text: "My template", role: :user})

Typically a template is used with parameter substitution as that's it's primary purpose. EEx is used to render the final text.

Jido.AI.Prompt.Template.new!(%{
  text: "My name is <%= @user_name %>. Warmly welcome me.",
  role: :user
})

@spec record_usage(t(), map()) :: t()

Records usage statistics for the template.

Parameters

• template: The template to update
• metrics: A map containing metrics to record, such as:
  • tokens_used: Number of tokens used in the response
  • response_time_ms: Time taken to generate response
  • success: Whether the generation was successful

Example

template = record_usage(template, %{
  tokens_used: 150,
  response_time_ms: 500,
  success: true
})

Rolls back to a specific version if it exists in history

Sanitizes user inputs to prevent template injection attacks.

Returns the NimbleOptions schema for Template.

@spec to_message(t(), inputs :: map()) ::
  {:ok, Jido.AI.Prompt.MessageItem.t()} | {:error, String.t()}

Convert a template to a MessageItem struct.

This is useful when you want to use a template as part of a conversation.

@spec to_message!(t(), inputs :: map()) ::
  Jido.AI.Prompt.MessageItem.t() | no_return()

Convert a template to a MessageItem struct. Raises if there's an error.

@spec to_messages!(list(), inputs :: map()) :: [Jido.AI.Prompt.MessageItem.t()]

Convert a list of templates, message items, and strings to a list of message items.

This is useful when you want to build a conversation from a mix of templates and messages.

Example

t1 = Template.new!(%{text: "System: <%= @sysinfo %>", role: :system})
t2 = Template.new!(%{text: "Question: <%= @question %>", role: :user})

messages = Template.to_messages!([t1, t2, "A direct user string"], %{
  sysinfo: "Guide the user",
  question: "What is 2+2?"
})

Updates template text and automatically increments version

Validates the syntax of a template without evaluating it.