# `Puck.Context`
[🔗](https://github.com/bradleygolden/puck/blob/v0.2.25/lib/puck/context.ex#L1)

Conversation context with message history and metadata.

## Example

    context = Puck.Context.new()
    context = Puck.Context.add_message(context, :user, "Hello!")

# `t`

```elixir
@type t() :: %Puck.Context{messages: [Puck.Message.t()], metadata: map()}
```

# `add_message`

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)
    1

# `clear`

Clears 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"}}

# `compact`

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
    }})

# `get_metadata`

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)
    nil

# `last_message`

Returns the last message in the context, or nil if empty.

## Examples

    iex> context = Puck.Context.new()
    iex> Puck.Context.last_message(context)
    nil

# `message_count`

Returns the number of messages in the context.

## Examples

    iex> context = Puck.Context.new()
    iex> Puck.Context.message_count(context)
    0

# `messages`

Returns 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))
    1

# `new`

Creates 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"}}

# `put_metadata`

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"}

# `total_tokens`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*