Session

A Session in LionAGI manages multiple conversation “branches” and the mail transfer mechanism between them. It provides a higher-level container for coordinating multiple parallel or sequential Branches, handling multi-agent or multi-threaded conversation flows. Each branch has its own messages, tools, iModels, and logs, while the Session orchestrates how they interact.

1. The Session Class

Purpose: - Holds a collection of Branch objects in branches. - Maintains a default_branch for convenience (the main or

currently active branch).

  • Optionally organizes mail exchange via MailManager or Exchange for multi-agent or multi-branch communication.

Key Attributes:

  • branches (Pile[Branch]): The collection of branches in this session.

  • default_branch (Branch): One branch designated as the “default” conversation context. If none is specifically set, it’s the first created.

  • mail_transfer (Exchange): Manages sending/receiving mail for these branches (not always strictly needed, but helpful in multi-agent use-cases).

  • mail_manager (MailManager): Alternative mail manager approach, also controlling which sources are recognized as senders/recipients.

2. Creation & Basics

When you create a Session, it automatically initializes:

  1. An empty Pile[Branch].

  2. A “default branch” (though you can override it).

  3. A MailManager plus a potential Exchange.

Example:

from lionagi.session.session import Session

sess = Session()
# -> a new session with a default Branch

# create an additional branch
br2 = sess.new_branch(name="SecondConversation")

3. Branch Management

Branch Lifecycle:

  • new_branch(...)(): Creates a new Branch, optionally specifying system message, user ID, initial tools, etc. The new branch is included in the session’s branches, and if there was no default branch, it sets this new one as default.

  • remove_branch(branch, delete=False)(): Removes a branch from the session (by ID or object). If delete=True, it also tries to delete the branch object in memory (though in Python, it just drops references).

  • split(branch)() / asplit(branch)(): Clones an existing branch, preserving its messages and tools, creating a new one in the session. This is helpful if you want to “fork” the conversation.

  • change_default_branch(branch)(): Points default_branch to another existing branch.

4. Mail Operations

Session includes:

  • mail_transfer (Exchange)

  • mail_manager (MailManager)

A session might manage multi-branch mail flows:

  • collect(...)(): Collect mail from specific branches (or all).

  • send(...)(): Send mail to specific branches (or all).

  • collect_send_all(receive_all=False)(): Combined approach to gather all outgoing mail from branches, send to recipients, and optionally have them “receive” it as well, so messages or tools are recognized in other branches.

Example:

# 1) Suppose we have branch A and B in the session
# 2) We do something that prepares mail in branch A's outbox
# 3) We "collect" from A and "send" to B

sess.collect(from_=[branchA.id])
sess.send(to_=[branchB.id])
# branchB can then .receive(...) or we can do
sess.collect_send_all(receive_all=True)

This centralization ensures you can run multi-agent or multi-branch scenarios all within the same Session context.

5. Inspecting Messages

Concatenation of messages from multiple branches:

  • concat_messages(branches=..., exclude_clone=..., exclude_load=...)() returns a Pile[RoledMessage] with the combined messages from the chosen branches, optionally excluding those flagged as clones or loads.

  • to_df(...)(): Returns a Pandas DataFrame of the combined messages for easy offline analysis or logging.

Example:

# all messages in a DataFrame
df = sess.to_df(exclude_clone=True)
print(df.head())

6. Example Flow

from lionagi.session.session import Session

# 1) Create a Session
sess = Session()
# => includes one default branch

# 2) Possibly create more branches
new_br = sess.new_branch(name="ResearchThread")
# => add a second conversation branch

# 3) Interact in default branch
final_resp = await sess.default_branch.communicate(
    instruction="Hello, how can I help?",
    guidance="Be concise",
)

# 4) Switch default if needed
sess.change_default_branch(new_br)

# 5) Tools or multi-branch mail...
#  Collect from one branch, send to another
#  or forcibly 'split' a branch to fork the conversation.

# 6) Inspect messages across all branches
df = sess.to_df()
print(df)

Summary

Session is the top-level aggregator for multi-branch usage within LionAGI, uniting:

  • A list of branches (each with its own conversation context),

  • A mail manager or exchange for multi-agent or multi-thread communication,

  • Tools for quickly copying or merging messages between branches (splitting, removing, or changing the default branch).

Hence, the Session offers a robust environment for advanced multi-conversation or multi-agent setups, ensuring coordination and integration at scale.