Cyclium.Synthesizer.Interactive.LLM behaviour (Cyclium v0.1.15)

Behaviour for LLM clients used by the Interactive synthesizer.

chat/3 is the text contract: the model replies with a JSON ActionPlan envelope as text, which the synthesizer parses.

chat_with_native_tools/4 is the optional native contract: tool signatures are passed to the provider as structured tools, and the model replies with validated tool_use blocks instead of a text envelope — removing the whole class of text-parse failures (smart quotes, dotted names, over-structured values). An adapter opts in simply by implementing it; the synthesizer auto-selects the native path when the actor's strategy_config sets tool_mode: :native and the configured client exports chat_with_native_tools/4. Return shape:

{:ok, %{
  tool_calls: [%{name: "tool__action", input: %{...}}],  # [] if none
  text: "assistant prose, if any",
  model: "model-id",   # optional
  usage: %{...}        # optional
}}

Summary

Callbacks

chat(system_prompt, user_message, opts)

chat_with_native_tools(system_prompt, user_message, tools, opts)

Callbacks

chat(system_prompt, user_message, opts)

@callback chat(system_prompt :: String.t(), user_message :: String.t(), opts :: keyword()) ::
  {:ok, String.t()} | {:error, :no_api_key} | {:error, {atom(), term()}}

chat_with_native_tools(system_prompt, user_message, tools, opts)

(optional)

@callback chat_with_native_tools(
  system_prompt :: String.t(),
  user_message :: String.t(),
  tools :: [map()],
  opts :: keyword()
) :: {:ok, map()} | {:error, :no_api_key} | {:error, {atom(), term()}}