kodeagent.history_formatter#

History formatting strategies for agent message history.

This module provides the Strategy pattern implementation for formatting agent message history for LLM consumption. Different agent types (ReAct, CodeAct) have different formatting requirements, particularly for tool calls.

CodeActHistoryFormatter

Formats CodeAct agent history with code-based pseudo tool calls.

HistoryFormatter

Abstract base class for formatting agent message history for LLM calls.

LLMMessage

A dictionary subclass that hides internal metadata from LLM APIs.

ReActHistoryFormatter

Formats ReAct agent history with action-based tool calls.

History formatting strategies for agent message history.

This module provides the Strategy pattern implementation for formatting agent message history for LLM consumption. Different agent types (ReAct, CodeAct) have different formatting requirements, particularly for tool calls.

class kodeagent.history_formatter.CodeActHistoryFormatter[source]#

Bases: HistoryFormatter

Formats CodeAct agent history with code-based pseudo tool calls.

CodeAct agents use a code field and format it as a pseudo tool call with the name ‘code_execution’. They do not track pending tool calls.

format_tool_call(msg: ChatMessage, state: dict) → dict[source]#

Format CodeAct code as pseudo tool call.

Parameters:

  • msg – Message containing code.

  • state – Mutable state dict to update with tool call ID.

Returns:

Formatted pseudo tool call dictionary.

should_format_as_tool_call(msg: ChatMessage) → bool[source]#

Check if message has code field for tool call.

Parameters:

msg – The message to check.

Returns:

True if message is an assistant message with code and no final answer.

class kodeagent.history_formatter.HistoryFormatter[source]#

Bases: ABC

Abstract base class for formatting agent message history for LLM calls.

This class defines the interface for formatting strategies. Subclasses implement agent-specific logic for detecting and formatting tool calls.

abstract format_tool_call(msg: ChatMessage, state: dict) → dict[source]#

Format a message as a tool call.

Parameters:

  • msg – The message containing tool call information.

  • state – Mutable state dict with keys: - last_tool_call_id: The most recent tool call ID - pending_tool_call: Whether a tool call is awaiting response

Returns:

Formatted tool call dictionary with role, content, and tool_calls.

pydantic_to_dict(msg: ChatMessage) → dict[source]#

Convert Pydantic message to dict with proper formatting and metadata.

Parameters:

msg – The Pydantic ChatMessage (ReActChatMessage or CodeActChatMessage).

Returns:

A dictionary representation compliant with OpenAPI/LLM specs, including metadata fields prefixed with ‘_’.

abstract should_format_as_tool_call(msg: ChatMessage) → bool[source]#

Determine if a message should be formatted as a tool call.

Parameters:

msg – The message to check.

Returns:

True if the message should be formatted as a tool call.

class kodeagent.history_formatter.LLMMessage(**kwargs: Any)[source]#

Bases: dict

A dictionary subclass that hides internal metadata from LLM APIs. This is used during converstion of Pydantic structured reponse to a dict for LLM APIs.

Standard keys (role, content, tool_calls, tool_call_id, name) are stored in the dictionary itself. Non-standard keys (starting with ‘_’ or ‘files’) are stored as instance attributes. This ensures that only compliant keys are serialized to JSON or iterated over when passed to LLM APIs like LiteLLM.

Create an LLM-compliant message with hidden metadata.

Parameters:

  • **kwargs – Message fields, including standard (role, content, etc.)

  • non-standard (and)

get(key: str, default: Any | None = None) → Any[source]#

Get a value with an optional default, checking both storage and attributes.

update(*args, **kwargs)[source]#

Update standard keys or metadata.

class kodeagent.history_formatter.ReActHistoryFormatter[source]#

Bases: HistoryFormatter

Formats ReAct agent history with action-based tool calls.

ReAct agents use an action/args structure for tool calls and track pending tool calls to add placeholders for interrupted executions.

format_tool_call(msg: ChatMessage, state: dict) → dict[source]#

Format ReAct action as tool call.

Parameters:

  • msg – Message containing action and args.

  • state – Mutable state dict to update with tool call ID.

Returns:

Formatted tool call dictionary.

should_format_as_tool_call(msg: ChatMessage) → bool[source]#

Check if message has action field for tool call.

Parameters:

msg – The message to check.

Returns:

True if message is an assistant message with an action and no final answer.