PtcRunner.SubAgent.Prompt (PtcRunner v0.4.1)

View Source

System prompt generation for SubAgent LLM interactions.

Orchestrates prompt generation by combining sections from sub-modules:

  • Prompt.DataInventory - Context variables with types and samples
  • Prompt.Tools - Available tool schemas and signatures
  • Prompt.Output - Expected return format from signature

Customization

The system_prompt field on SubAgent accepts:

  • Map - :prefix, :suffix, :language_spec, :output_format
  • Function - fn default_prompt -> modified_prompt end
  • String - Complete override

Language Spec

The :language_spec option can be:

Default: :single_shot for max_turns: 1, :multi_turn otherwise.

Examples

iex> agent = PtcRunner.SubAgent.new(prompt: "Add {{x}} and {{y}}")
iex> context = %{x: 5, y: 3}
iex> prompt = PtcRunner.SubAgent.Prompt.generate(agent, context: context)
iex> prompt =~ "## Role"
true
iex> prompt =~ "ctx/x"
true

Summary

Functions

apply_customization(base_prompt, override)

Apply system prompt customization (string override, function, or map with prefix/suffix).

generate(agent, opts \\ [])

Generate a complete system prompt for a SubAgent.

generate_data_inventory(context, context_signature \\ nil, field_descriptions \\ nil)

See PtcRunner.SubAgent.Prompt.DataInventory.generate/3.

generate_error_recovery_prompt(error_context)

Generate error recovery prompt for parse failures.

generate_tool_schemas(tools, tool_catalog \\ nil, multi_turn? \\ true)

Generate tool schemas section. Delegates to PtcRunner.SubAgent.Prompt.Tools.generate/3.

resolve_language_spec(spec, context)

Resolve a language_spec value to a string.

truncate_if_needed(prompt, limit_config)

Truncate prompt if it exceeds the configured character limit.

Functions

apply_customization(base_prompt, override)

@spec apply_customization(String.t(), PtcRunner.SubAgent.system_prompt_opts() | nil) ::
  String.t()

Apply system prompt customization (string override, function, or map with prefix/suffix).

Examples

iex> PtcRunner.SubAgent.Prompt.apply_customization("base", nil)
"base"

iex> PtcRunner.SubAgent.Prompt.apply_customization("base", "override")
"override"

iex> PtcRunner.SubAgent.Prompt.apply_customization("base", fn p -> "PREFIX\n" <> p end)
"PREFIX\nbase"

generate(agent, opts \\ [])

@spec generate(
  PtcRunner.SubAgent.t(),
  keyword()
) :: String.t()

Generate a complete system prompt for a SubAgent.

Options: context (map), error_context (map for recovery prompts).

Examples

iex> agent = PtcRunner.SubAgent.new(prompt: "Process data")
iex> prompt = PtcRunner.SubAgent.Prompt.generate(agent, context: %{user: "Alice"})
iex> prompt =~ "## Role" and prompt =~ "thinking:"
true

generate_data_inventory(context, context_signature \\ nil, field_descriptions \\ nil)

See PtcRunner.SubAgent.Prompt.DataInventory.generate/3.

generate_error_recovery_prompt(error_context)

@spec generate_error_recovery_prompt(map()) :: String.t()

Generate error recovery prompt for parse failures.

Examples

iex> error = %{type: :parse_error, message: "Unexpected token"}
iex> PtcRunner.SubAgent.Prompt.generate_error_recovery_prompt(error) =~ "Previous Turn Error"
true

generate_tool_schemas(tools, tool_catalog \\ nil, multi_turn? \\ true)

Generate tool schemas section. Delegates to PtcRunner.SubAgent.Prompt.Tools.generate/3.

The multi_turn? parameter controls whether return/fail tools are included. Defaults to true for backward compatibility.

resolve_language_spec(spec, context)

@spec resolve_language_spec(String.t() | atom() | (map() -> String.t()), map()) ::
  String.t()

Resolve a language_spec value to a string.

Examples

iex> PtcRunner.SubAgent.Prompt.resolve_language_spec("custom prompt", %{})
"custom prompt"

iex> spec = PtcRunner.SubAgent.Prompt.resolve_language_spec(:single_shot, %{})
iex> is_binary(spec) and String.contains?(spec, "PTC-Lisp")
true

iex> callback = fn ctx -> if ctx.turn > 1, do: "multi", else: "single" end
iex> PtcRunner.SubAgent.Prompt.resolve_language_spec(callback, %{turn: 1})
"single"

truncate_if_needed(prompt, limit_config)

@spec truncate_if_needed(String.t(), map() | nil) :: String.t()

Truncate prompt if it exceeds the configured character limit.

Examples

iex> PtcRunner.SubAgent.Prompt.truncate_if_needed("short", nil)
"short"

iex> result = PtcRunner.SubAgent.Prompt.truncate_if_needed(String.duplicate("x", 1000), %{max_chars: 100})
iex> result =~ "truncated"
true