BeamAgent.Context (beam_agent v0.1.0)

Copy Markdown View Source

Owns the information sent to the model.

Older messages may be deterministically compressed, but the original goal and optional system prompt are always preserved.

Summary

Types

compression_metadata()
message()
t()

Functions

add_assistant_message(context, content)

Appends an assistant reply.

add_tool_result(context, result)

Appends a tool result.

add_user_message(context, content)

Appends a user message.

compress(context, opts)

Deterministically compresses context if its rendered message count exceeds opts[:max_messages] (required): the oldest messages are folded into context.summary (capped at opts[:summary_char_limit], default

messages(context)

Renders context into the ordered list of messages sent to the model: optional system prompt, the goal as a user message, the compressed-history summary (if any) as a system message, then the accumulated messages.

new(goal, opts \\ [])

Starts a fresh context for goal, optionally with a :system_prompt.

Types

compression_metadata()

@type compression_metadata() :: %{
  :compressed? => boolean(),
  :before_count => non_neg_integer(),
  :after_count => non_neg_integer(),
  :compressed_messages => non_neg_integer(),
  optional(:summary_chars) => non_neg_integer()
}

message()

@type message() :: %{role: atom(), content: term()}

t()

@type t() :: %BeamAgent.Context{
  goal: String.t(),
  messages: [message()],
  summary: String.t() | nil,
  system_prompt: String.t() | nil
}

Functions

add_assistant_message(context, content)

@spec add_assistant_message(t(), term()) :: t()

Appends an assistant reply.

add_tool_result(context, result)

@spec add_tool_result(t(), term()) :: t()

Appends a tool result.

add_user_message(context, content)

@spec add_user_message(t(), term()) :: t()

Appends a user message.

compress(context, opts)

@spec compress(
  t(),
  keyword()
) ::
  {:ok, t(), compression_metadata()}
  | {:error, {:context_limit_too_small, map()}}

Deterministically compresses context if its rendered message count exceeds opts[:max_messages] (required): the oldest messages are folded into context.summary (capped at opts[:summary_char_limit], default

  1. and dropped from messages. Returns {:ok, context, metadata} (unchanged if under the limit, with metadata.compressed? == false), or {:error, {:context_limit_too_small, %{...}}} if :max_messages is too small to hold the goal + optional system prompt + at least one summary/message slot.

messages(context)

@spec messages(t()) :: [message()]

Renders context into the ordered list of messages sent to the model: optional system prompt, the goal as a user message, the compressed-history summary (if any) as a system message, then the accumulated messages.

new(goal, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: t()

Starts a fresh context for goal, optionally with a :system_prompt.