# Messages API Reference The messages system provides unified message types for LLM communication. ## BaseMessage Base class for all message types. ```python class BaseMessage(BaseModel): """A base message class.""" role: str content: str prompt_hash: str | None = None tool_calls: list = [] ``` ### Attributes - **role** (`str`): The role of the message sender (`"system"`, `"user"`, `"assistant"`, `"tool"`) - **content** (`str`): The message content - **prompt_hash** (`str | None`, default: `None`): Optional hash of the prompt - **tool_calls** (`list`, default: `[]`): List of tool calls associated with the message ### Methods #### `__len__` ```python def __len__(self) -> int ``` Get the length of the message content. #### `__getitem__` ```python def __getitem__(self, index) -> BaseMessage ``` Get a slice of the message content. #### `__add__` / `__radd__` ```python def __add__(self, other: str) -> BaseMessage def __radd__(self, other: str) -> BaseMessage ``` Concatenate strings with message content. ## Message Types ### SystemMessage Message from the system (system prompt). ```python class SystemMessage(BaseMessage): """A message from the system.""" content: str role: str = "system" ``` #### Example ```python from llamabot.components.messages import SystemMessage msg = SystemMessage(content="You are a helpful assistant.") ``` ### HumanMessage Message from a human user. ```python class HumanMessage(BaseMessage): """A message from a human.""" content: str role: str = "user" ``` #### Example ```python from llamabot.components.messages import HumanMessage msg = HumanMessage(content="What is Python?") ``` ### AIMessage Message from the AI assistant. ```python class AIMessage(BaseMessage): """A message from the AI.""" content: str role: str = "assistant" ``` #### Example ```python from llamabot.components.messages import AIMessage msg = AIMessage(content="Python is a programming language.") ``` ### DeveloperMessage Message from the developer (for development context). ```python class DeveloperMessage(BaseMessage): """A message from the developer.""" content: str role: str = "developer" ``` #### Example ```python from llamabot.components.messages import DeveloperMessage msg = DeveloperMessage(content="Add error handling to this function.") ``` ### ToolMessage Message representing tool execution results. ```python class ToolMessage(BaseMessage): """A message from a tool.""" content: str role: str = "tool" ``` #### Example ```python from llamabot.components.messages import ToolMessage msg = ToolMessage(content="Tool execution result") ``` ### RetrievedMessage Message retrieved from document store or memory. ```python class RetrievedMessage(BaseMessage): """A message retrieved from the history.""" content: str role: str = "system" ``` #### Example ```python from llamabot.components.messages import RetrievedMessage msg = RetrievedMessage(content="Retrieved document content") ``` ### ImageMessage Message containing an image. ```python class ImageMessage(BaseMessage): """A message containing an image.""" content: str # Base64-encoded image or file path role: str = "user" ``` #### Constructor ```python def __init__( self, content: Union[str, Path], role: str = "user", prompt_hash: str | None = None, tool_calls: list = None, ) ``` #### Parameters - **content** (`Union[str, Path]`): Path to image file, URL of image, or base64-encoded image - **role** (`str`, default: `"user"`): Role of the message sender - **prompt_hash** (`str | None`, default: `None`): Optional prompt hash - **tool_calls** (`list`, default: `None`): Optional tool calls #### Example ```python from llamabot.components.messages import ImageMessage from pathlib import Path # From file path msg = ImageMessage(content=Path("image.jpg")) # From URL msg = ImageMessage(content="https://example.com/image.jpg") ``` ## Helper Functions ### `user` ```python def user(*content: Union[str, Path]) -> Union[HumanMessage, ImageMessage, list] ``` Create user messages, automatically detecting images. #### Parameters - **content**: One or more strings or image paths #### Returns - **Union[HumanMessage, ImageMessage, list]**: Message(s) created from content #### Example ```python from llamabot.components.messages import user # Text message msg = user("What is this?") # Image message msg = user("/path/to/image.jpg") # Text and image msgs = user("What is this?", "/path/to/image.jpg") ``` ### `dev` ```python def dev(*content: str) -> Union[DeveloperMessage, list[DeveloperMessage]] ``` Create developer messages for development context. #### Parameters - **content**: One or more strings #### Returns - **Union[DeveloperMessage, list[DeveloperMessage]]**: Developer message(s) #### Example ```python from llamabot.components.messages import dev msg = dev("Add error handling") msgs = dev("Refactor code", "Add tests") ``` ### `system` ```python def system(content: str) -> SystemMessage ``` Create a system message. #### Parameters - **content** (`str`): System prompt content #### Returns - **SystemMessage**: System message #### Example ```python from llamabot.components.messages import system msg = system("You are a helpful assistant.") ``` ### `to_basemessage` ```python def to_basemessage( messages: Union[ str, BaseMessage, list[Union[str, BaseMessage]], Callable, ] ) -> list[BaseMessage] ``` Convert various input types to a list of BaseMessage objects. #### Parameters - **messages**: Can be: - String (converted to HumanMessage) - BaseMessage object - List of strings or BaseMessage objects - Callable function (called and result converted) #### Returns - **list[BaseMessage]**: List of BaseMessage objects #### Example ```python from llamabot.components.messages import to_basemessage, HumanMessage # String msgs = to_basemessage("Hello") # Message object msgs = to_basemessage(HumanMessage(content="Hello")) # List msgs = to_basemessage(["Hello", "World"]) # Mixed msgs = to_basemessage([ "Hello", HumanMessage(content="World") ]) ``` ## Usage Examples ### Creating Messages ```python from llamabot.components.messages import ( SystemMessage, HumanMessage, AIMessage, user, dev, system ) # System prompt sys_msg = system("You are a helpful assistant.") # User message user_msg = user("What is Python?") # AI response ai_msg = AIMessage(content="Python is a programming language.") ``` ### With Images ```python from llamabot.components.messages import user, ImageMessage from pathlib import Path # Using user() helper msg = user("/path/to/image.jpg") # Direct ImageMessage msg = ImageMessage(content=Path("image.jpg")) # Text and image msgs = user("What is this?", "/path/to/image.jpg") ``` ### With Bots ```python import llamabot as lmb from llamabot.components.messages import HumanMessage bot = lmb.SimpleBot("You are helpful.") # String (automatically converted) response = bot("Hello") # Message object response = bot(HumanMessage(content="Hello")) # Multiple messages response = bot("First message", "Second message") ``` ## Message Hierarchy ```text BaseMessage (base class) ├── SystemMessage (system prompts) ├── HumanMessage (user input) ├── DeveloperMessage (development context) ├── AIMessage (AI responses) │ ├── ThoughtMessage (agent reasoning) │ └── ObservationMessage (tool observations) ├── ToolMessage (tool execution results) ├── RetrievedMessage (retrieved documents) └── ImageMessage (image content) ``` ## Related Classes - **SimpleBot**: Uses messages for LLM communication - **ChatMemory**: Stores and retrieves messages - **QueryBot**: Uses RetrievedMessage for document retrieval ## See Also - [SimpleBot Reference](../bots/simplebot.md) - [Chat Memory Reference](./chat_memory.md) - [Which Bot Should I Use?](../../getting-started/which-bot.md)