Messages API Reference
The messages system provides unified message types for LLM communication.
BaseMessage
Base class for all message types.
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__
def __len__(self) -> int
Get the length of the message content.
__getitem__
def __getitem__(self, index) -> BaseMessage
Get a slice of the message content.
__add__ / __radd__
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).
class SystemMessage(BaseMessage):
"""A message from the system."""
content: str
role: str = "system"
Example
from llamabot.components.messages import SystemMessage
msg = SystemMessage(content="You are a helpful assistant.")
HumanMessage
Message from a human user.
class HumanMessage(BaseMessage):
"""A message from a human."""
content: str
role: str = "user"
Example
from llamabot.components.messages import HumanMessage
msg = HumanMessage(content="What is Python?")
AIMessage
Message from the AI assistant.
class AIMessage(BaseMessage):
"""A message from the AI."""
content: str
role: str = "assistant"
Example
from llamabot.components.messages import AIMessage
msg = AIMessage(content="Python is a programming language.")
DeveloperMessage
Message from the developer (for development context).
class DeveloperMessage(BaseMessage):
"""A message from the developer."""
content: str
role: str = "developer"
Example
from llamabot.components.messages import DeveloperMessage
msg = DeveloperMessage(content="Add error handling to this function.")
ToolMessage
Message representing tool execution results.
class ToolMessage(BaseMessage):
"""A message from a tool."""
content: str
role: str = "tool"
Example
from llamabot.components.messages import ToolMessage
msg = ToolMessage(content="Tool execution result")
RetrievedMessage
Message retrieved from document store or memory.
class RetrievedMessage(BaseMessage):
"""A message retrieved from the history."""
content: str
role: str = "system"
Example
from llamabot.components.messages import RetrievedMessage
msg = RetrievedMessage(content="Retrieved document content")
ImageMessage
Message containing an image.
class ImageMessage(BaseMessage):
"""A message containing an image."""
content: str # Base64-encoded image or file path
role: str = "user"
Constructor
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
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
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
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
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
from llamabot.components.messages import dev
msg = dev("Add error handling")
msgs = dev("Refactor code", "Add tests")
system
def system(content: str) -> SystemMessage
Create a system message.
Parameters
- content (
str): System prompt content
Returns
- SystemMessage: System message
Example
from llamabot.components.messages import system
msg = system("You are a helpful assistant.")
to_basemessage
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
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
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
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
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
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