Conversation context with message history and metadata.
Example
context = Puck.Context.new()
context = Puck.Context.add_message(context, :user, "Hello!")Summary
Functions
Adds a message to the context.
Clears all messages from the context, preserving metadata.
Compacts the context using the specified strategy.
Gets a value from the context metadata.
Returns the last message in the context, or nil if empty.
Returns the number of messages in the context.
Returns the messages in the context.
Creates a new empty context.
Updates the context metadata.
Returns the total token count from context metadata.
Types
@type t() :: %Puck.Context{messages: [Puck.Message.t()], metadata: map()}
Functions
Adds a message to the context.
Content can be a string (wrapped automatically), a single Part, or a list of Parts.
Examples
iex> context = Puck.Context.new()
iex> context = Puck.Context.add_message(context, :user, "Hello!")
iex> length(context.messages)
1Clears all messages from the context, preserving metadata.
Useful for starting a fresh conversation while keeping session information.
Examples
iex> context = Puck.Context.new(metadata: %{session_id: "abc123"})
iex> context = Puck.Context.add_message(context, :user, "Hello!")
iex> context = Puck.Context.clear(context)
iex> {context.messages, context.metadata}
{[], %{session_id: "abc123"}}Compacts the context using the specified strategy.
Delegates to Puck.Compaction.compact/2.
Examples
{:ok, compacted} = Puck.Context.compact(context, {Puck.Compaction.Summarize, %{
client: client,
keep_last: 3
}})Gets a value from the context metadata.
Examples
iex> context = Puck.Context.new(metadata: %{session_id: "abc123"})
iex> Puck.Context.get_metadata(context, :session_id)
"abc123"
iex> Puck.Context.get_metadata(context, :missing)
nilReturns the last message in the context, or nil if empty.
Examples
iex> context = Puck.Context.new()
iex> Puck.Context.last_message(context)
nilReturns the number of messages in the context.
Examples
iex> context = Puck.Context.new()
iex> Puck.Context.message_count(context)
0Returns the messages in the context.
Examples
iex> context = Puck.Context.new()
iex> context = Puck.Context.add_message(context, :user, "Hello!")
iex> length(Puck.Context.messages(context))
1Creates a new empty context.
Examples
iex> Puck.Context.new()
%Puck.Context{messages: [], metadata: %{}}
iex> Puck.Context.new(metadata: %{session_id: "abc123"})
%Puck.Context{messages: [], metadata: %{session_id: "abc123"}}Updates the context metadata.
Examples
iex> context = Puck.Context.new()
iex> context = Puck.Context.put_metadata(context, :session_id, "abc123")
iex> context.metadata
%{session_id: "abc123"}Returns the total token count from context metadata.
This value is tracked by the runtime after each LLM call. Returns 0 if no token information has been recorded.
Examples
iex> context = Puck.Context.new()
iex> Puck.Context.total_tokens(context)
0