Skip to main content

mellea.stdlib.components.chat

Chat primitives: the Message and ToolMessage components.

Defines Message, the Component subtype used to represent a single turn in a chat history with a role (user, assistant, system, or tool), text content, and optional images and documents attachments. Also provides ToolMessage (a Message subclass that carries the tool name and arguments), and utilities for converting a Context into a flat list of Message objects: as_chat_history (strict typing) and as_generic_chat_history (flexible with configurable formatter).

Functions​

FUNC as_chat_history ​

as_chat_history(ctx: Context) -> list[Message]

Returns a list of Messages corresponding to a Context.

Args:

Returns:

  • List of Message objects in conversation order.

Raises:

  • ValueError: If the context history is non-linear and cannot be cast to a flat list.
  • AssertionError: If any entry in the context cannot be converted to a Message.

FUNC as_generic_chat_history ​

as_generic_chat_history(ctx: Context, formatter: Callable[[object], str] | None = None) -> list[Message]

Returns a list of Messages corresponding to a Context, with flexible type handling.

This function is more permissive than as_chat_history(), allowing arbitrary component types. Unknown types are converted to strings using a configurable formatter, making it suitable for general-purpose use where context composition may be heterogeneous.

The formatter is applied to:

  • ModelOutputThunk with non-Message parsed_repr
  • CBlock subclasses (subclasses only; plain CBlock is stringified)
  • Other unknown component types

Existing Message objects are preserved as-is; their content is not formatted. This design preserves Message fidelity while providing an escape hatch for unknown types.

Args:

  • ctx: A linear Context that may contain Message, ModelOutputThunk, or other Component types.
  • formatter: Optional callable that converts unknown types to strings. Defaults to _default_formatter which logs a warning and stringifies.

Returns:

  • List of Message objects in conversation order.

Raises:

  • ValueError: If the context history is non-linear and cannot be cast to a flat list.

Classes​

CLASS Message ​

A single Message in a Chat history.

Args:

  • role: The role that this message came from (e.g., "user", "assistant").
  • content: The content of the message.
  • images: Optional images associated with the message.
  • documents: Optional documents associated with the message.

Attributes:

  • Role: Type alias for the allowed role literals: "system", "user", "assistant", or "tool".

Methods:

FUNC images ​

images(self) -> None | list[str]

Returns the images associated with this message as list of base 64 strings.

FUNC parts ​

parts(self) -> list[Component | CBlock]

Return the constituent parts of this message, including content, documents, and images.

Returns:

  • list[Component | CBlock]: A list beginning with the content block,
  • followed by any attached documents and image blocks.

FUNC format_for_llm ​

format_for_llm(self) -> TemplateRepresentation

Formats the content for a Language Model.

Returns:

  • The formatted output suitable for language models.

CLASS ToolMessage ​

Adds the name field for function name.

Args:

  • role: The role of this message; most backends use "tool".
  • content: The content of the message; should be a stringified version of tool_output.
  • tool_output: The output of the tool or function call.
  • name: The name of the tool or function that was called.
  • args: The arguments passed to the tool.
  • tool: The ModelToolCall representation.

Attributes:

  • arguments: The arguments that were passed to the tool; stored from the args constructor parameter.