History

These are the objects used internally within each class to trace everything.

View source

MessageHistory

A message history class for storing conversation messages with multi-modal support.

Behaves like a list - can be iterated, indexed, and checked for length. Use list() or .to_list() to get the raw list of messages.

This class supports: - Simple text messages - Multi-modal content (images, files, audio) - Tool calls and responses - Rich metadata and timestamps

The message format is OpenAI-compatible for maximum interoperability.

Example

# Simple text message
history = MessageHistory()
history.add_message("user", "Hello!")

# Iterate directly
for msg in history:
    print(msg['role'], msg['content'])

# Convert to list
msg_list = history.to_list()
msg_list = list(history)  # Also works

# Check if empty
if history:
    print("Has messages")

# Access by index
first = history[0]
last = history[-1]

# Multi-modal message
history.add_message(
    "user",
    [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "https://..."}}
    ]
)

# Tool call message
history.add_tool_call(
    tool_calls=[{"id": "call_123", "type": "function", "function": {"name": "get_weather", "arguments": '{"city": "NYC"}'}}]
)

# Tool response message
history.add_tool_response(
    tool_call_id="call_123",
    content="Temperature: 72°F",
    name="get_weather"
)

__bool__

__bool__() -> bool

Check if history has messages.

__getitem__

__getitem__(index: int) -> Dict[str, Any]

__getitem__(index: slice) -> List[Dict[str, Any]]

__getitem__(
    index: Union[int, slice],
) -> Union[Dict[str, Any], List[Dict[str, Any]]]

Access messages by index or slice.

__init__

__init__(messages: Optional[List[Dict[str, Any]]] = None)

Initialize message history.

PARAMETER	DESCRIPTION
messages	List of message dictionaries in OpenAI format TYPE: Optional[List[Dict[str, Any]]] DEFAULT: None

__iter__

__iter__() -> Iterator[Dict[str, Any]]

Iterate over messages.

__len__

__len__() -> int

Get number of messages.

__repr__

__repr__() -> str

String representation.

add_message

add_message(
    role: RoleType,
    content: Union[str, List[Dict[str, Any]]],
    name: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    timestamp: Optional[str] = None,
) -> None

Add a simple message to the history.

PARAMETER	DESCRIPTION
role	The role of the message sender ("user", "assistant", "system", "tool") TYPE: RoleType
content	The message content (string or list of content parts for multi-modal) TYPE: Union[str, List[Dict[str, Any]]]
name	Optional name for the message sender (useful for multi-agent scenarios) TYPE: Optional[str] DEFAULT: None
metadata	Optional metadata dictionary TYPE: Optional[Dict[str, Any]] DEFAULT: None
timestamp	Optional ISO format timestamp (auto-generated if not provided) TYPE: Optional[str] DEFAULT: None

add_tool_call

add_tool_call(
    tool_calls: List[Dict[str, Any]],
    content: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    timestamp: Optional[str] = None,
) -> None

Add an assistant message with tool calls.

PARAMETER	DESCRIPTION
tool_calls	List of tool call dictionaries. Each should have: - id: Unique identifier for the tool call - type: Usually "function" - function: Dict with "name" and "arguments" (JSON string) TYPE: List[Dict[str, Any]]
content	Optional text content accompanying the tool calls TYPE: Optional[str] DEFAULT: None
metadata	Optional metadata dictionary TYPE: Optional[Dict[str, Any]] DEFAULT: None
timestamp	Optional ISO format timestamp (auto-generated if not provided) TYPE: Optional[str] DEFAULT: None

add_tool_response

add_tool_response(
    tool_call_id: str,
    content: str,
    name: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    timestamp: Optional[str] = None,
) -> None

Add a tool response message.

PARAMETER	DESCRIPTION
tool_call_id	The ID of the tool call this is responding to TYPE: str
content	The tool's output/response TYPE: str
name	Optional name of the tool TYPE: Optional[str] DEFAULT: None
metadata	Optional metadata dictionary TYPE: Optional[Dict[str, Any]] DEFAULT: None
timestamp	Optional ISO format timestamp (auto-generated if not provided) TYPE: Optional[str] DEFAULT: None

clear

clear() -> None

Clear all messages from the history.

filter_by_role

filter_by_role(role: RoleType) -> List[Dict[str, Any]]

Get all messages with a specific role.

PARAMETER	DESCRIPTION
role	The role to filter by TYPE: RoleType

RETURNS	DESCRIPTION
List[Dict[str, Any]]	List of messages with the specified role

get_last_message

get_last_message() -> Optional[Dict[str, Any]]

Get the most recent message.

RETURNS	DESCRIPTION
Optional[Dict[str, Any]]	The last message or None if history is empty

to_list

to_list() -> List[Dict[str, Any]]

Get the raw list of messages.

RETURNS	DESCRIPTION
List[Dict[str, Any]]	List of message dictionaries in OpenAI format

to_openai_format

to_openai_format() -> List[Dict[str, Any]]

Convert to OpenAI API format (strips metadata/timestamps).

RETURNS	DESCRIPTION
List[Dict[str, Any]]	List of messages in OpenAI format

ToolInvocationHistory

A small history container for tool / invocation events.

Tool calls tend to be structured (inputs, outputs, timestamps). This class stores invocation records separately from conversational messages.

__len__

__len__() -> int

Get number of invocations.