Branch: The Orchestrator¶

Overview¶

A Branch represents a single “branch” of conversation in LionAGI. It manages:

A LogManager for storing logs,
A LogManagerConfig (if needed),
A Element as the base object,
A Communicatable mailbox for cross-branch communication,
A Relational link,
A SenderRecipient to identify user or role,
A MessageManager for messages (system instructions, user instructions, model responses),
An ActionManager for tools,
An iModelManager for multiple LLM or model references (like “chat”, “parse”),
Utility methods for “chat,” “operate,” “parse,” “act,” etc. (documented in Branch-Level Operations).

Contents¶

Branch¶

class lionagi.session.branch.Branch¶

Inherits from: Element, Communicatable, Relational

Manages a conversation ‘branch’ with messages, tools, and iModels.

The Branch class serves as a high-level interface or orchestrator that:

Handles message management (MessageManager)

Registers and invokes tools/actions (ActionManager)

Manages model instances (iModelManager)

Logs activity (LogManager)

Communicates via mailboxes (Mailbox)

Key responsibilities:

Storing and organizing messages, including system instructions, user instructions, and model responses

Handling asynchronous or synchronous execution of LLM calls and tool invocations

Providing a consistent interface for “operate,” “chat,” “communicate,” “parse,” etc.

userSenderRecipient, optional
The user or sender context for this branch

namestr, optional
A human-readable name for this branch

messagesPile[RoledMessage], optional
Initial messages for seeding the MessageManager

systemSystem | JsonValue, optional
Optional system-level configuration or message for the LLM

system_senderSenderRecipient, optional
Sender to attribute to the system message if it is added

chat_modeliModel | dict, optional
The primary “chat” iModel for conversation

parse_modeliModel | dict, optional
The “parse” iModel for structured data parsing

imodeliModel, optional
Deprecated. Alias for chat_model

toolsFuncTool | list[FuncTool], optional
Tools or a list of tools for the ActionManager

log_configLogManagerConfig | dict, optional
Configuration dict or object for the LogManager

system_datetimebool | str, optional
Whether to include timestamps in system messages

system_templateTemplate | str, optional
Optional Jinja2 template for system messages

system_template_contextdict, optional
Context for rendering the system template

logsPile[Log], optional
Existing logs to seed the LogManager

**kwargs
Additional parameters passed to Element parent init

userSenderRecipient | None
The user or “owner” of this branch (often tied to a session)

namestr | None
A human-readable name for this branch

mailboxMailbox
A mailbox for sending and receiving Package objects to/from other branches

systemSystem | None
The system message/configuration, if any

msgsMessageManager
Returns the associated MessageManager

actsActionManager
Returns the associated ActionManager for tool management

mdlsiModelManager
Returns the associated iModelManager

messagesPile[RoledMessage]
Convenience property to retrieve all messages from MessageManager

logsPile[Log]
Convenience property to retrieve all logs from the LogManager

chat_modeliModel
The primary “chat” model (iModel) used for conversational LLM calls

parse_modeliModel
The “parse” model (iModel) used for structured data parsing

toolsdict[str, Tool]
All registered tools (actions) in the ActionManager

Common usage: 1. Instantiate a Branch, optionally providing a system message and some initial tools 2. Use chat() or communicate() for user queries 3. If you want structured responses or function calls, use operate() 4. If you want to parse or validate final text, use parse() 5. Tools can be registered anytime via acts or with the arguments to the constructor

Also includes mailbox-based methods like send() and receive() for cross-branch or cross-system communication in a multi-agent scenario.

Key Differences from a Basic Session¶

Where a simpler “session” might just store messages + call an LLM, Branch expands that concept by:

Integrating advanced log management with a LogManager.
Holding a mailbox (like an email or queue system) so that branches can pass Package objects to each other.
Tying in a ActionManager for immediate function or tool calls.
Potentially linking to a “Graph” node or referencing relations (due to the Relational inheritance).
Providing clone operations if you want to copy the conversation state to a new branch.