prompttrail.agent.templates package

Module contents

Templates package for PromptTrail agent.

Control module provides control flow templates for building conversation templates. Core module provides base classes and utilities for building conversation templates. Tool module provides tool use related templates for building conversation templates.

class prompttrail.agent.templates.AnthropicToolingTemplate(tools: List[Tool], role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'assistant', template_id: str | None = None, model: AnthropicModel | None = None, **kwargs)

Bases: ToolingTemplateBase

Anthropic-specific implementation of tool handling template.

This template handles the Anthropic-specific format for tool calls and results, adapting them to the common interface provided by ToolingTemplate.

See documentation: https://docs.anthropic.com/en/docs/build-with-claude/tool-use

__init__(tools: List[Tool], role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'assistant', template_id: str | None = None, model: AnthropicModel | None = None, **kwargs)

Initialize the template with tools.

Parameters:

tools – List of tools available for the model to use
role – Message role (defaults to “assistant”)
template_id – Optional template identifier
**kwargs – Additional arguments passed to parent class

format_tool_call(message: Message | Session) → Dict[str, Any] | None

Extract tool call information from Anthropic message format.

Parameters:: message – Message from Anthropic API response or Session containing messages
Returns:: Optional dictionary containing tool call details, or None if no tool call present

format_tool_result(result: ToolResult) → Message

Format tool result for Anthropic message format.

Parameters:: result – Result from tool execution
Returns:: Formatted message containing the tool result

Final message format should be like this:

{
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
            "content": "15 degrees"
        }
    ]
}

class prompttrail.agent.templates.AssistantTemplate(content: str | None = None, template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True, disable_jinja: bool = False, model: Model | None = None)

Bases: GenerateTemplate

Template for assistant messages with optional LLM generation.

__init__(content: str | None = None, template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True, disable_jinja: bool = False, model: Model | None = None): Initialize logging for the class.

class prompttrail.agent.templates.BreakTemplate(template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None)

Bases: ControlTemplate

__init__(template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None)

A template for breaking the loop.

after_transform is unavailable for BreakTemplate because it may skipped when the break is executed.

create_stack(session: Session) → Stack

Create a stack for the control template.

Parameters:: session – The current session of the conversation.
Returns:: The created stack.

walk(visited_templates: Set[Template] | None = None) → Generator[Template, None, None]

Traverse the template and its child templates in a depth-first manner. Control templates should override this method as they usually have child templates.

Parameters:: visited_templates – Set of visited templates to avoid infinite recursion.
Yields:: The template and its child templates.

class prompttrail.agent.templates.ControlTemplate(template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True)

Bases: Template

Base class for control flow templates.

abstract __init__(template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True): Initialize logging for the class.

abstract create_stack(session: Session) → Stack

Create a stack for the control template.

Parameters:: session – The current session of the conversation.
Returns:: The created stack.

abstract walk(visited_templates: Set[Template] | None = None) → Generator[Template, None, None]

Traverse the template and its child templates in a depth-first manner. Control templates should override this method as they usually have child templates.

Parameters:: visited_templates – Set of visited templates to avoid infinite recursion.
Yields:: The template and its child templates.

class prompttrail.agent.templates.EndTemplate(farewell_message: str | None = None)

Bases: Template

A special template for the end of the conversation.

When runner reaches this template, the conversation is forced to stop. This template is a singleton. before_transform and after_transform are unavailable for EndTemplate.

__init__(farewell_message: str | None = None): Initialize logging for the class.

before_transform = []

create_stack(session: Session) → Stack: Create stack frame for this template.

template_id = 'END'

class prompttrail.agent.templates.Event(event_type: str, payload: Dict[str, Any])

Bases: object

Represents an event in the template rendering process.

event_type

The type of the event.

Type:: str

payload

The data associated with the event.

Type:: Dict[str, Any]

__init__(event_type: str, payload: Dict[str, Any]) → None

event_type: str

payload: Dict[str, Any]

class prompttrail.agent.templates.ExecuteToolTemplate(tool: Tool, role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'user', template_id: str | None = None, **kwargs)

Bases: GenerateTemplate

Template for executing a tool with arguments automatically extracted from metadata.

__init__(tool: Tool, role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'user', template_id: str | None = None, **kwargs)

Initialize the template with tool and arguments.

Parameters:

tool – Tool instance to execute
role – Message role (defaults to “user”)
template_id – Optional template identifier
**kwargs – Additional arguments passed to parent class

class prompttrail.agent.templates.GenerateTemplate(role: Literal['system', 'user', 'assistant', 'tool_result', 'control'], template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging=True, disable_jinja=False, model: Model | None = None)

Bases: MessageTemplate

Template that generates content using an LLM.

__init__(role: Literal['system', 'user', 'assistant', 'tool_result', 'control'], template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging=True, disable_jinja=False, model: Model | None = None): Initialize logging for the class.

class prompttrail.agent.templates.IfTemplate(condition: Callable[[Session], bool], true_template: Template, false_template: Template | None = None, template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True)

Bases: ControlTemplate

__init__(condition: Callable[[Session], bool], true_template: Template, false_template: Template | None = None, template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True)

A template for a conditional control flow.

Parameters:

condition (Condition) – Condition to be checked.
true_template (Template) – Template to be rendered if the condition is met.
false_template (Optional[Template], optional) – Template to be rendered if the condition is not met. Defaults to None. If None, this template return no message.
template_id (Optional[str], optional) – Template ID of this template. Defaults to None.
before_transform (Optional[List[TransformHook]], optional) – `TrnasformHook`s to be applied before rendering. Defaults to None.
after_transform (Optional[List[TransformHook]], optional) – `TrnasformHook`s to be applied after rendering. Defaults to None.

create_stack(session: Session) → Stack

Create a stack for the control template.

Parameters:: session – The current session of the conversation.
Returns:: The created stack.

walk(visited_templates: Set[Template] | None = None) → Generator[Template, None, None]

Traverse the template and its child templates in a depth-first manner. Control templates should override this method as they usually have child templates.

Parameters:: visited_templates – Set of visited templates to avoid infinite recursion.
Yields:: The template and its child templates.

class prompttrail.agent.templates.LinearTemplate(templates: Sequence[Template], template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True)

Bases: ControlTemplate

__init__(templates: Sequence[Template], template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True)

A template for a linear control flow. Unlike LoopTemplate, this template exits after rendering all the child templates.

Parameters:

templates (Sequence[Template]) – Templates to be rendered. Execution order is the same as the order of the list.
template_id (Optional[str], optional) – Template ID of this template. Defaults to None.
before_transform (Optional[List[TransformHook]], optional) – `TrnasformHook`s to be applied before rendering. Defaults to None.
after_transform (Optional[List[TransformHook]], optional) – `TrnasformHook`s to be applied after rendering. Defaults to None.

create_stack(session: Session) → LinearTemplateStack

Create a stack for the control template.

Parameters:: session – The current session of the conversation.
Returns:: The created stack.

walk(visited_templates: Set[Template] | None = None) → Generator[Template, None, None]

Traverse the template and its child templates in a depth-first manner. Control templates should override this method as they usually have child templates.

Parameters:: visited_templates – Set of visited templates to avoid infinite recursion.
Yields:: The template and its child templates.

class prompttrail.agent.templates.LoopTemplate(templates: Sequence[Template], exit_condition: Callable[[Session], bool] | None = None, template_id: str | None = None, exit_loop_count: int | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True)

Bases: ControlTemplate

__init__(templates: Sequence[Template], exit_condition: Callable[[Session], bool] | None = None, template_id: str | None = None, exit_loop_count: int | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True)

A template for a loop control flow. Unlike LinearTemplate, this template loops over the child templates until the exit condition is met.

Parameters:

templates (Sequence[Template]) – Templates to be looped. Execution order is the same as the order of the list.
exit_condition (Optional[Condition], optional) – If set, the loop is broken when the condition is met. Defaults to None (Infinite loop).
template_id (Optional[str], optional) – Template ID of this template. Defaults to None.
exit_loop_count (Optional[int], optional) – If set, the loop is broken when the loop count is over this number. Defaults to None (Infinite loop).
before_transform (Optional[List[TransformHook]], optional) – `TrnasformHook`s to be applied before rendering. Defaults to None.
after_transform (Optional[List[TransformHook]], optional) – `TrnasformHook`s to be applied after rendering. Defaults to None.

create_stack(session: Session) → Stack

Create a stack for the control template.

Parameters:: session – The current session of the conversation.
Returns:: The created stack.

walk(visited_templates: Set[Template] | None = None) → Generator[Template, None, None]

Traverse the template and its child templates in a depth-first manner. Control templates should override this method as they usually have child templates.

Parameters:: visited_templates – Set of visited templates to avoid infinite recursion.
Yields:: The template and its child templates.

class prompttrail.agent.templates.MessageTemplate(content: str, role: Literal['system', 'user', 'assistant', 'tool_result', 'control'], template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True, disable_jinja: bool = False)

Bases: Template

Template that creates a message using Jinja2 templating.

__init__(content: str, role: Literal['system', 'user', 'assistant', 'tool_result', 'control'], template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True, disable_jinja: bool = False): Initialize logging for the class.

create_stack(session: Session) → Stack: Create stack frame for this template.

class prompttrail.agent.templates.OpenAIToolingTemplate(tools: List[Tool], role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'assistant', template_id: str | None = None, model: OpenAIModel | None = None, **kwargs)

Bases: ToolingTemplateBase

OpenAI-specific implementation of tool handling template.

This template handles the OpenAI-specific format for function calls and results, adapting them to the common interface provided by ToolingTemplate.

__init__(tools: List[Tool], role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'assistant', template_id: str | None = None, model: OpenAIModel | None = None, **kwargs)

Initialize the template with tools.

Parameters:

tools – List of tools available for the model to use
role – Message role (defaults to “assistant”)
template_id – Optional template identifier
**kwargs – Additional arguments passed to parent class

check_tool_arguments(args_str: str, tool: Tool) → Dict[str, Any]

Validate and process tool arguments

Parameters:

args_str – JSON string of arguments from the API
tool – Tool instance to validate against

Returns:

Processed arguments

Return type:

Dict[str, Any]

Raises:

ValueError – If required arguments are missing or types don’t match
json.JSONDecodeError – If arguments string is not valid JSON

format_tool_call(message: Message) → Dict[str, Any] | None

Extract tool call information from OpenAI message format.

Parameters:: message – Message from OpenAI API response
Returns:: Optional dictionary containing tool call details, or None if no tool call present

static format_tool_result(result: ToolResult) → Message

Format tool result for OpenAI message format.

Parameters:: result – Result from tool execution
Returns:: Formatted message containing the tool result

pydantic model prompttrail.agent.templates.Stack

Bases: BaseModel

Stack frame for template execution.

Fields:

template_id (str)

field template_id: str [Required]

class prompttrail.agent.templates.SystemTemplate(content: str, template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging=True, disable_jinja=False)

Bases: MessageTemplate

Template for system messages.

__init__(content: str, template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging=True, disable_jinja=False): Initialize logging for the class.

class prompttrail.agent.templates.Template(template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True)

Bases: Debuggable

Base template class for creating messages and controlling flow.

Subclasses must implement _render() and create_stack() methods.

abstract __init__(template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True): Initialize logging for the class.

abstract create_stack(session: Session) → Stack: Create stack frame for this template.

render(session: Session) → Generator[Message | Event, None, Session]

Render template with hooks and error handling.

Yields:: Union[Message, Event] – The next message or event in the rendering process.

walk(visited_templates: Set[Template] | None = None) → Generator[Template, None, None]: Walk through template tree yielding each template once.

class prompttrail.agent.templates.ToolingTemplate(tools: List[Tool], role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'assistant', template_id: str | None = None, model: Model | None = None, **kwargs)

Bases: ToolingTemplateBase

Unified tooling template for different LLM providers.

__init__(tools: List[Tool], role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'assistant', template_id: str | None = None, model: Model | None = None, **kwargs)

Initialize the template with tools.

Parameters:

tools – List of tools available for the model to use
role – Message role (defaults to “assistant”)
template_id – Optional template identifier
**kwargs – Additional arguments passed to parent class

class prompttrail.agent.templates.ToolingTemplateBase(tools: List[Tool], role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'assistant', template_id: str | None = None, model: Model | None = None, **kwargs)

Bases: GenerateTemplate

Base template for tool handling across different models.

This template provides a common interface for handling tool calls and results across different LLM providers. Each provider should implement their own format_tool_call and format_tool_result methods to handle provider-specific message formats.

__init__(tools: List[Tool], role: Literal['system', 'user', 'assistant', 'tool_result', 'control'] = 'assistant', template_id: str | None = None, model: Model | None = None, **kwargs)

Initialize the template with tools.

Parameters:

tools – List of tools available for the model to use
role – Message role (defaults to “assistant”)
template_id – Optional template identifier
**kwargs – Additional arguments passed to parent class

get_tool(name: str) → Tool

Get tool by name.

Parameters:: name – Name of the tool to retrieve
Returns:: Tool instance
Raises:: ValueError – If tool is not found

tools: Dict[str, Tool] = {}

class prompttrail.agent.templates.UserTemplate(content: str | None = None, description: str | None = None, default: str | None = None, template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True, disable_jinja: bool = False)

Bases: MessageTemplate

Template for user messages with optional interactive input.

__init__(content: str | None = None, description: str | None = None, default: str | None = None, template_id: str | None = None, before_transform: List[SessionTransformer] | SessionTransformer | None = None, after_transform: List[SessionTransformer] | SessionTransformer | None = None, enable_logging: bool = True, disable_jinja: bool = False): Initialize logging for the class.