PtcRunner.Prompts (PtcRunner v0.10.1)

Copy Markdown View Source

Centralized prompt loading for PtcRunner.

All prompt templates are loaded from priv/prompts/ at compile time and exposed through this module. Changes to prompt files trigger recompilation.

Prompt Files (2-Axis Architecture)

Language specs are composed from two axes plus optional capabilities:

AxisFileFunction
Referencereference.mdreference/0
Behaviorbehavior-single-shot.mdbehavior_single_shot/0
Behaviorbehavior-multi-turn.mdbehavior_multi_turn/0
Return modebehavior-return-explicit.mdbehavior_return_explicit/0
Capabilitycapability-journal.mdcapability_journal/0

Other Prompt Files

FileFunctionUsed By
json-system.mdjson_system/0JsonMode
json-user.mdjson_user/0JsonMode
json-error.mdjson_error/0JsonMode
tool-calling-system.mdtool_calling_system/0ToolCallingMode
turn-feedback-must-return.mdmust_return_warning/0TurnFeedback
turn-feedback-retry.mdretry_feedback/0TurnFeedback

File Format

Prompt files use HTML comment markers to separate metadata from content:

# Title
Description for maintainers.

<!-- version: 1 -->
<!-- date: 2026-01-01 -->

<!-- PTC_PROMPT_START -->
Actual prompt content here.
<!-- PTC_PROMPT_END -->

Content between PTC_PROMPT_START and PTC_PROMPT_END markers is extracted. If no markers exist, the entire file (trimmed) is used.

Mustache Templates

Some prompts use Mustache templating (e.g., turn-feedback-must-return.md):

  • {{variable}} - Simple substitution
  • {{#section}}...{{/section}} - Conditional/iteration
  • {{^section}}...{{/section}} - Inverted (if falsy)

See PtcRunner.Mustache for expansion.

Adding New Prompts

  1. Create priv/prompts/my-prompt.md with markers
  2. Add to this module:
    • @my_prompt_file path
    • @external_resource @my_prompt_file
    • @my_prompt loaded content
    • def my_prompt, do: @my_prompt
  3. Document in the table above

Summary

Functions

behavior_multi_turn()

Shared multi-turn core: one code block per turn, state, short programs.

behavior_multi_turn_with_header()

Raw header + content for behavior-multi-turn.md.

behavior_return_explicit()

Explicit return fragment: use (return ...) / (fail ...).

behavior_return_explicit_with_header()

Raw header + content for behavior-return-explicit.md.

behavior_single_shot()

Single-shot behavior: last expression is the answer, one turn.

behavior_single_shot_with_header()

Raw header + content for behavior-single-shot.md.

capability_journal()

Journal capability: task caching, step-done, semantic progress.

capability_journal_with_header()

Raw header + content for capability-journal.md.

get(arg1)

Get a prompt by key.

json_error()

Text mode (JSON variant) error feedback template (Mustache).

json_system()

Text mode (JSON variant) system prompt.

json_user()

Text mode (JSON variant) user message template (Mustache).

list()

List all available prompt keys.

must_return_warning()

Final work turn warning template (Mustache).

reference()

Language reference: tool syntax, Java interop, restrictions.

reference_with_header()

Raw header + content for reference.md.

retry_feedback()

Retry phase feedback template (Mustache).

tool_calling_system()

Tool calling mode system prompt.

Functions

behavior_multi_turn()

@spec behavior_multi_turn() :: String.t()

Shared multi-turn core: one code block per turn, state, short programs.

behavior_multi_turn_with_header()

@spec behavior_multi_turn_with_header() :: {String.t(), String.t()}

Raw header + content for behavior-multi-turn.md.

behavior_return_explicit()

@spec behavior_return_explicit() :: String.t()

Explicit return fragment: use (return ...) / (fail ...).

behavior_return_explicit_with_header()

@spec behavior_return_explicit_with_header() :: {String.t(), String.t()}

Raw header + content for behavior-return-explicit.md.

behavior_single_shot()

@spec behavior_single_shot() :: String.t()

Single-shot behavior: last expression is the answer, one turn.

behavior_single_shot_with_header()

@spec behavior_single_shot_with_header() :: {String.t(), String.t()}

Raw header + content for behavior-single-shot.md.

capability_journal()

@spec capability_journal() :: String.t()

Journal capability: task caching, step-done, semantic progress.

capability_journal_with_header()

@spec capability_journal_with_header() :: {String.t(), String.t()}

Raw header + content for capability-journal.md.

get(arg1)

@spec get(atom()) :: String.t() | nil

Get a prompt by key.

Examples

iex> prompt = PtcRunner.Prompts.get(:reference)
iex> String.contains?(prompt, "<role>")
true

iex> PtcRunner.Prompts.get(:unknown)
nil

json_error()

@spec json_error() :: String.t()

Text mode (JSON variant) error feedback template (Mustache).

json_system()

@spec json_system() :: String.t()

Text mode (JSON variant) system prompt.

json_user()

@spec json_user() :: String.t()

Text mode (JSON variant) user message template (Mustache).

list()

@spec list() :: [atom()]

List all available prompt keys.

Examples

iex> keys = PtcRunner.Prompts.list()
iex> :reference in keys
true

must_return_warning()

@spec must_return_warning() :: String.t()

Final work turn warning template (Mustache).

Variables: has_retries (bool), retry_count (int).

reference()

@spec reference() :: String.t()

Language reference: tool syntax, Java interop, restrictions.

reference_with_header()

@spec reference_with_header() :: {String.t(), String.t()}

Raw header + content for reference.md.

retry_feedback()

@spec retry_feedback() :: String.t()

Retry phase feedback template (Mustache).

Variables: is_final_retry, current_retry, total_retries, retries_remaining, next_turn.

tool_calling_system()

@spec tool_calling_system() :: String.t()

Tool calling mode system prompt.