Puck.Compaction behaviour (Puck v0.2.11)

Copy Markdown View Source

Behaviour for context compaction strategies.

Context compaction reduces conversation history size while preserving essential information. This helps manage LLM context windows and avoid "context rot" - degraded performance as context length increases.

Callbacks

  • compact/2 - Compacts the context using the strategy's approach
  • should_compact?/2 - (optional) Returns whether compaction should occur
  • introspect/1 - (optional) Returns strategy metadata for observability

Example

defmodule MyApp.Compaction.Custom do
  @behaviour Puck.Compaction

  @impl true
  def compact(context, config) do
    # Custom compaction logic
    {:ok, compacted_context}
  end
end

Built-in Strategies

Usage

# Manual compaction
{:ok, compacted} = Puck.Compaction.compact(context, {Puck.Compaction.Summarize, %{
  client: client,
  keep_last: 3
}})

Summary

Types

config()
introspection()

Metadata returned by introspect/1 for observability.

result()

Callbacks

compact(t, config)

Compacts the context to reduce its size.

introspect(config)

Returns metadata about the compaction strategy.

should_compact?(t, config)

Returns whether the context should be compacted.

Functions

compact(context, arg)

Compacts a context using the specified strategy.

should_compact?(context, arg)

Checks if context should be compacted using the specified strategy.

Types

config()

@type config() :: map()

introspection()

@type introspection() :: %{:strategy => String.t(), optional(atom()) => term()}

Metadata returned by introspect/1 for observability.

result()

@type result() :: {:ok, Puck.Context.t()} | {:error, term()}

Callbacks

compact(t, config)

@callback compact(Puck.Context.t(), config()) :: result()

Compacts the context to reduce its size.

Parameters

  • context - The context to compact
  • config - Strategy-specific configuration

Returns

  • {:ok, compacted_context} on success
  • {:error, reason} on failure

introspect(config)

(optional) 
@callback introspect(config()) :: introspection()

Returns metadata about the compaction strategy.

Used by telemetry/tracing to identify the strategy being used.

Parameters

  • config - Strategy configuration

Expected Keys

  • :strategy - Strategy name (e.g., "summarize", "sliding_window")

should_compact?(t, config)

(optional) 
@callback should_compact?(Puck.Context.t(), config()) :: boolean()

Returns whether the context should be compacted.

Implementations can check token counts, message counts, or other criteria.

Parameters

  • context - The context to check
  • config - Strategy-specific configuration (may include thresholds)

Returns

  • true if compaction should occur
  • false otherwise

Functions

compact(context, arg)

Compacts a context using the specified strategy.

This is a convenience function that delegates to the strategy module.

Parameters

  • context - The context to compact
  • strategy_tuple - A tuple of {strategy_module, config}

Examples

{:ok, compacted} = Puck.Compaction.compact(context, {Puck.Compaction.Summarize, %{
  client: client,
  keep_last: 3
}})

should_compact?(context, arg)

Checks if context should be compacted using the specified strategy.

Falls back to true if the strategy doesn't implement should_compact?/2.

Parameters

  • context - The context to check
  • strategy_tuple - A tuple of {strategy_module, config}

Examples

if Puck.Compaction.should_compact?(context, {Puck.Compaction.Summarize, config}) do
  {:ok, compacted} = Puck.Compaction.compact(context, {Puck.Compaction.Summarize, config})
end