Template

input_variables: set[str]

Return the set of variable names required by this template.

This enables building tools on top of templates (CLIs, web UIs, validators) that need to know what inputs are expected without executing the template.

>>> t = PromptTemplate("Hello {{ name }}, you are {{ age }} years old")
>>> t.input_variables
{'name', 'age'}

>>> rag = PromptTemplate('''
... {% for doc in docs %}
... {{ doc.content }}
... {% endfor %}
... Question: {{ question }}
... ''')
>>> rag.input_variables
{'docs', 'question'}

source: str

The original template source string.

strict: bool

Whether strict mode is enabled (undefined variables raise errors).

supports_system_role: bool

Check if this chat template explicitly handles the 'system' role.

Returns True if the template source contains explicit handling for system messages (e.g., message.role == 'system' or role == "system").

• This helps Chat implementations decide whether to:
• Pass system messages directly (if supported)
• Prepend system content to the first user message (if not supported)

>>> t = PromptTemplate.chatml()
>>> t.supports_system_role  # ChatML handles any role
True

>>> t = PromptTemplate("{{ messages[0].content }}")
>>> t.supports_system_role  # No role handling
False

supports_tools: bool

Check if this chat template has built-in tool/function calling support.

Returns True if the template source contains handling for tools, functions, or available_tools variables (common in HuggingFace templates for models like Llama-3, Qwen, etc.).

• This helps Chat implementations decide whether to:
• Let the template handle tool formatting (if supported)
• Handle tool formatting separately (if not supported)

When a template has built-in tool support but the Chat module also handles tools, pass an empty tools list to the template to avoid conflicts.

>>> t = PromptTemplate.chatml()
>>> t.supports_tools  # Basic ChatML has no tool handling
False

def __call__(
    self,
    debug: bool = False,
    strict: bool | None = None,
    variables: Any
) → str | DebugResult

Render the template with the given variables.

>>> t = PromptTemplate("Hello {{ name }}!")
>>> t(name="World")
'Hello World!'

def apply(
    self,
    messages: list[dict[str, Any]],
    debug: bool = False,
    strict: bool | None = None,
    add_generation_prompt: bool = True,
    bos_token: str = '',
    eos_token: str = '',
    kwargs: Any
) → str | DebugResult

Render chat messages using this template.

Convenience wrapper around __call__() with named parameters for common chat template variables.

>>> t = PromptTemplate.chatml()
>>> prompt = t.apply([
...     {"role": "system", "content": "You are helpful."},
...     {"role": "user", "content": "Hello!"},
... ])

def format(self, variables: Any) → str

Render the template with the given variables.

Familiar API for str.format() users.

>>> t = PromptTemplate("Hello {{ name }}!")
>>> t.format(name="World")
'Hello World!'

def from_chat_template(
    cls,
    model: str,
    strict: bool = False
) → PromptTemplate

Load a model's chat template as an inspectable PromptTemplate.

>>> t = PromptTemplate.from_chat_template("Qwen/Qwen3-0.6B")
>>> t.input_variables
{'messages', 'add_generation_prompt', ...}

def from_file(cls, path: str) → PromptTemplate

Load a template from a file.

>>> template = PromptTemplate.from_file("prompts/rag.j2")
>>> result = template(documents=docs, question="...")

def from_preset(cls, name: str) → PromptTemplate

Create a PromptTemplate from a built-in chat format preset.

Available presets: chatml, llama2, alpaca, vicuna, zephyr.

>>> t = PromptTemplate.from_preset("chatml")
>>> t.apply([{"role": "user", "content": "Hi"}])
'<|im_start|>user\\nHi<|im_end|>\\n<|im_start|>assistant\\n'

def partial(self, kwargs: Any) → PromptTemplate

Return a new PromptTemplate with some variables pre-filled.

>>> t = PromptTemplate("{{ persona }}\\n{{ query }}")
>>> chat = t.partial(persona="You are helpful")
>>> chat(query="Hello!")
'You are helpful\nHello!'

def register_filter(
    self,
    name: str,
    func: Any
) → PromptTemplate

Register a custom Python filter function.

>>> t = PromptTemplate("{{ name | shout }}")
>>> t.register_filter("shout", lambda s: s.upper() + "!")
>>> t(name="hello")
'HELLO!'

def render(
    self,
    strict: bool | None = None,
    variables: Any
) → str

Render the template with the given variables.

Familiar API for Jinja2 users.

>>> t = PromptTemplate("Hello {{ name }}!")
>>> t.render(name="World")
'Hello World!'

def validate(self, kwargs: Any) → ValidationResult

Validate inputs and prepare for efficient rendering.

>>> t = PromptTemplate("Hello {{ name }}, age {{ age }}")
>>> result = t.validate(name="Alice")
>>> result.is_valid
False
>>> result.required
{'age'}

filters: dict[str, Callable]

Custom filters for this environment.

Modify directly to add/remove filters, or use register_filter().

>>> env.filters["shout"] = lambda s: s.upper() + "!"

globals: dict[str, Any]

Global variables available to all templates in this environment.

These are merged with render-time variables, with render-time variables taking precedence.

>>> env.globals["app_name"] = "MyApp"
>>> env.globals["debug"] = True

strict: bool

Default strict mode for templates created from this environment.

def from_file(
    self,
    path: str | Path,
    strict: bool | None = None
) → PromptTemplate

Load a template from a file with this environment's configuration.

>>> t = env.from_file("prompts/greeting.j2")

def from_string(
    self,
    source: str,
    strict: bool | None = None
) → PromptTemplate

Create a template from a string with this environment's configuration.

>>> t = env.from_string("Hello {{ name | upper }}!")
>>> t(name="world")
'Hello WORLD!'

def register_filter(
    self,
    name: str,
    func: Callable
) → TemplateEnvironment

Register a filter for this environment.

>>> env.register_filter("upper", str.upper).register_filter("trim", str.strip)

def format_ansi(self) → str

Format output with ANSI colors for terminal display.

• Static text: normal (no color)
• Variables: cyan with variable name in parentheses
• Expressions: yellow

def format_plain(self) → str

Format output with plain text markers (no ANSI).

• Static text: unchanged
• Variables: «value» (var_name)
• Expressions: «value»

is_expression: bool

Whether this span came from a complex expression.

is_static: bool

Whether this span is static template text.

is_variable: bool

Whether this span came from a variable substitution.

is_valid: bool

Whether validation passed.

Returns True only if there are no missing required variables and no invalid (non-JSON-serializable) values.

summary: str

Human-readable summary of validation issues.

Returns empty string if validation passed.

>>> result.summary
'Missing required variables: name. Missing optional variables (have defaults): context'

def render(self, strict: bool | None = None) → str

Render the template using the validated variables.

This method reuses the JSON serialization from validation, avoiding the overhead of re-serializing large variables like RAG documents.

>>> docs = load_large_documents()  # 10MB of data
>>> result = template.validate(documents=docs, question="What is...?")
>>> if result.is_valid:
...     output = result.render()  # No re-serialization!

>>> result = template.validate(name="Alice")
>>> output = result.render(strict=True)  # Force strict for this render