Behaviour for lifecycle hooks.

Hooks observe and transform data at each stage of client execution. All callbacks are optional.

Return Types

• {:cont, value} - Continue with value
• {:halt, response} - Short-circuit with response
• {:error, reason} - Abort with error

Callbacks

• on_call_start/3 - Before LLM call
• on_call_end/3 - After successful call
• on_call_error/3 - On call failure
• on_stream_start/3, on_stream_chunk/3, on_stream_end/2 - Stream lifecycle
• on_backend_request/2, on_backend_response/2 - Backend lifecycle
• on_compaction_start/3, on_compaction_end/2 - Compaction lifecycle

Example

defmodule MyApp.LoggingHooks do
  @behaviour Puck.Hooks
  require Logger

  @impl true
  def on_call_start(_client, content, _context) do
    Logger.info("Call started")
    {:cont, content}
  end

  @impl true
  def on_call_end(_client, response, _context) do
    Logger.info("Call completed")
    {:cont, response}
  end
end

Usage

client = Puck.Client.new({Puck.Backends.ReqLLM, "anthropic:claude-sonnet-4-5"},
  hooks: MyApp.LoggingHooks
)

# Multiple hooks execute in order
Puck.call(client, "Hello", context,
  hooks: [MyApp.LoggingHooks, MyApp.MetricsHooks]
)