@spec compile(
  PtcRunner.SubAgent.t(),
  keyword()
) :: {:ok, PtcRunner.SubAgent.CompiledAgent.t()} | {:error, PtcRunner.Step.t()}

Compiles a SubAgent into a reusable PTC-Lisp function.

The LLM is called once during compilation to derive the logic. The resulting CompiledAgent can then be executed many times without further LLM calls, making it efficient for processing many items with deterministic logic.

Requirements

• max_turns: 1 - Only single-shot agents can be compiled
• output: :ptc_lisp - Only PTC-Lisp output mode (not :json)

Tool Support

• Pure Elixir tools - Supported, executed directly
• LLMTool - Supported (requires LLM at runtime)
• SubAgentTool - Supported if child agent has no mission_timeout

When SubAgentTools are present, the compiled agent requires an llm option at execute time for the child agents.

Options

• llm - Required. LLM callback used once during compilation. Can be a function or atom.
• llm_registry - Required if llm is an atom. Maps atoms to LLM callbacks.
• sample - Optional sample data to help LLM understand the input structure (default: %{})

Returns

• {:ok, CompiledAgent.t()} - Successfully compiled agent
• {:error, Step.t()} - Compilation failed (agent execution failed)

Examples

iex> tools = %{"double" => fn %{"n" => n} -> n * 2 end}
iex> agent = PtcRunner.SubAgent.new(
...>   prompt: "Double the input number {{n}}",
...>   signature: "(n :int) -> {result :int}",
...>   tools: tools,
...>   max_turns: 1
...> )
iex> mock_llm = fn _ -> {:ok, ~S|(return {:result (tool/double {:n data/n})})|} end
iex> {:ok, compiled} = PtcRunner.SubAgent.Compiler.compile(agent, llm: mock_llm, sample: %{n: 5})
iex> compiled.signature
"(n :int) -> {result :int}"
iex> is_binary(compiled.source)
true
iex> is_function(compiled.execute, 2)
true
iex> result = compiled.execute.(%{n: 10}, [])
iex> result.return.result
20

Agents with LLMTool compile successfully (LLMTool requires LLM at runtime):

iex> alias PtcRunner.SubAgent.LLMTool
iex> tools = %{"classify" => LLMTool.new(prompt: "Classify {{x}}", signature: "(x :string) -> :string")}
iex> agent = PtcRunner.SubAgent.new(prompt: "Process {{item}}", signature: "(item :string) -> {category :string}", tools: tools, max_turns: 1)
iex> {:ok, compiled} = PtcRunner.SubAgent.Compiler.compile(agent, llm: fn _ -> {:ok, ~S|(return {:category "test"})|} end)
iex> compiled.llm_required?
true