Planck.Agent.Hooks.Compactor behaviour (Planck.Agent v0.1.7)

Copy Markdown View Source

Behaviour and default implementation for context compaction in Planck.Agent.

Behaviour

Use use Planck.Agent.Hooks.Compactor to implement a custom compaction strategy in a sidecar. The only required callback is compact/2; compact_timeout/0 has a default of 120000 ms.

defmodule MySidecar.Compactors.Builder do
  use Planck.Agent.Hooks.Compactor

  @impl true
  def compact(_model, messages) do
    summary = Message.new({:custom, :summary}, [{:text, summarise(messages)}])
    kept    = Enum.take(messages, -5)
    {:compact, summary, kept}
  end

  @impl true
  def compact_timeout, do: 60_000
end

Dispatch

Planck.Agent stores the resolved compactor module atom in state and calls compact/4 before every LLM turn:

Hooks.Compactor.compact(state.compactor, state.model, messages, state.sidecar_node)
  • module: nil — uses the built-in local LLM-based compactor.
  • module set, sidecar_node: nil — calls module.compact/2 in-process.
  • module set, sidecar_node set — calls the module on the remote node via RPC; falls back to the local LLM-based compactor on :badrpc.

Summary

Callbacks

compact(model, messages)

Compact the message list.

compact_timeout()

RPC call timeout in milliseconds when this compactor is invoked remotely.

Functions

compact(module, model, messages, sidecar_node)

Dispatch compaction for the given module, model, and messages.

default_compact_timeout()

Default RPC timeout used when a compactor module omits compact_timeout/0.

Callbacks

compact(model, messages)

@callback compact(model :: Planck.AI.Model.t(), messages :: [Planck.Agent.Message.t()]) ::
  {:compact, summary :: Planck.Agent.Message.t(),
   kept :: [Planck.Agent.Message.t()]}
  | :skip

Compact the message list.

Return {:compact, summary_msg, kept} to replace older messages with a summary, or :skip to leave the list unchanged.

compact_timeout()

@callback compact_timeout() :: pos_integer()

RPC call timeout in milliseconds when this compactor is invoked remotely.

Defaults to 120000 ms.

Functions

compact(module, model, messages, sidecar_node)

@spec compact(
  module() | nil,
  Planck.AI.Model.t(),
  [Planck.Agent.Message.t()],
  atom() | nil
) ::
  :skip | {:compact, Planck.Agent.Message.t(), [Planck.Agent.Message.t()]}

Dispatch compaction for the given module, model, and messages.

  • nil — runs the built-in local LLM-based compactor.
  • module set, sidecar_node: nil — calls module.compact/2 in-process.
  • module set, sidecar_node set — calls via RPC with local fallback on failure.

Returns :skip or {:compact, summary_msg, kept}.

default_compact_timeout()

@spec default_compact_timeout() :: pos_integer()

Default RPC timeout used when a compactor module omits compact_timeout/0.