Branch¶

class Branch(Element, Relational)

One stateful unit of model work: manages message history, tools, model access, logs, optional memory, and LLM operations. Most SDK usage starts here.

Constructor¶

branch = li.Branch(
    chat_model=li.iModel(model="gpt-4o"),
    system="You are a research assistant.",
    name="researcher",
)

Properties¶

Operations¶

operate() — universal structured operation¶

from pydantic import BaseModel

class Summary(BaseModel):
    title: str
    key_points: list[str]

result = await branch.operate(
    instruction="Summarize this paper: ...",
    response_format=Summary,
    actions=True,
    tools=["search"],
    action_strategy="concurrent",
)
# result: Summary instance

Routes through the Middle protocol: communicate for API endpoints and run_and_collect for CLI endpoints. Supports tool calling, structured output, and streaming persistence. Registered tools are only exposed and invoked when actions=True (or the supplied Instruct enables actions); passing tools= alone does not enable them.

A response that sets action_strategy to "sequential" narrows a "concurrent" call for that turn only: its tool calls run one at a time, in request order, under the caller's call_params except max_concurrent, which is 1 for that batch (the timeout, retries and throttle still apply). The guard reads the fields the parsed response actually set, so a field the turn omits is not read as a declaration even when the response model's own default for it is "sequential", while an explicit "sequential" narrows even when it equals that default. A value a validator assigns or injects counts as a declaration, because the parsed model has set the field; the field is read by its field name, so a turn that sends only an alias leaves it at its default and does not narrow unless the model accepts the field name too (populate_by_name=True). A response never widens a "sequential" call, and an action_strategy="sequential" argument is not narrowed this way: act() awaits its calls in request order without applying call_params.

Returns: list | BaseModel | None | dict | str

For cookbook usage, see Research synthesis.

communicate() — single-turn with history accumulation¶

result = await branch.communicate(
    "What are the main causes of climate change?",
    response_format=None,  # returns str
)
# adds both user message and assistant response to branch.messages

Simpler than operate() — no tool calling. Accumulates messages in history automatically. Use when you need history building without tool invocation.

Returns: BaseModel | dict | str | None

chat() — low-level, unrecorded invocation¶

text = await branch.chat("Draft an outline for a research paper on RAG.")
# does NOT add to branch.messages — caller manages history

Low-level building block. It does not add messages to history and returns the assistant response value, usually a string, by default.

Request the generated message objects explicitly when you need them:

instruction_msg, response_msg = await branch.chat(
    "Draft an outline for a research paper on RAG.",
    return_ins_res_message=True,
)

Returns: str by default, or (Instruction, AssistantResponse) when return_ins_res_message=True.

chat_and_record() — low-level invocation with history¶

text = await branch.chat_and_record("Draft an outline for a research paper on RAG.")

Calls chat(return_ins_res_message=True), adds both generated messages through the hook-aware async message path, and returns the assistant response string. Use it when you need chat()'s low-level parameters but still want observers and persistence to see the turn. For ordinary stateful calls, prefer communicate().

run() — streaming CLI endpoint¶

async for msg in branch.run("Write a detailed analysis of..."):
    if hasattr(msg, "content"):
        print(msg.content, end="", flush=True)

Async generator — yields RoledMessage objects as chunks arrive. Requires a CLI endpoint model (e.g., iModel(provider="claude_code", model="sonnet")).

parse() — structured extraction from text¶

class Verdict(BaseModel):
    score: int
    reasoning: str

verdict = await branch.parse(
    text='{"score": 8, "reasoning": "Strong methodology"}',
    response_format=Verdict,
    handle_validation="raise",
)

Extracts structured data from raw text without a new LLM call (unless retries are needed). Fuzzy key matching is enabled by default — handles minor key name variations from the model.

Returns: BaseModel | dict | str | None

act() — tool execution¶

responses = await branch.act(
    action_request=[{"function": "search", "arguments": {"query": "LLM benchmarks 2025"}}],
    strategy="concurrent",
)

Directly invoke tool calls. Takes ActionRequest, dict, or list.

Returns: list[ActionResponse]

ReAct() — think-act-observe reasoning loops¶

result = await branch.ReAct(
    instruct={"instruction": "Find the latest papers on diffusion models and summarize."},
    tools=["search", "read_url"],
    max_extensions=5,
    response_format=ResearchReport,
)

Multi-round reasoning with tool use. Iterates until max_extensions or a terminal response.

Returns: the final answer or result by default. With return_analysis=True, returns the collected outputs as a list.

For a full working example, see Research synthesis.

interpret() — prompt rewriting¶

refined = await branch.interpret(
    "llm stuff for code gen",
    domain="software engineering",
    style="precise and technical",
)
# refined: "Explain LLM-based code generation techniques for production use."

Rewrites raw user input into a refined prompt. Does not add to history.

Tool management¶

# register functions
branch.register_tools([search_fn, read_file_fn])

# register with update=True to overwrite existing
branch.register_tools(new_search_fn, update=True)

# register an API endpoint as a callable tool
branch.connect(
    provider="openai",
    endpoint="chat",
    name="gpt_tool",
    description="GPT-4o as a callable tool",
)

Context manager¶

async with li.Branch(chat_model=li.iModel(model="gpt-4o")) as branch:
    result = await branch.operate(instruction="Analyze this dataset: ...")
# logs auto-dumped on exit

Serialization¶

# round-trip
data = branch.to_dict()
restored = li.Branch.from_dict(data)

# messages as DataFrame
df = branch.to_df()

# clone (sync or async)
b2 = branch.clone()
b2 = await branch.aclone(sender=new_sender_id)

# dump logs
branch.dump_logs(clear=True, persist_path="./logs/session.json")
await branch.adump_logs(clear=False)

Branch.from_dict reads its input as trusted. The class names it holds are resolved as ADR-0001 D3 describes, which can import a module the data names, and its stored models choose the provider, model, base URL and request settings. Restore only data that your own process, or a writer you trust, produced.

Some settings lionagi sends with an HTTP model's requests belong to the process restoring the data rather than to the data, so a stored model never supplies them, whoever wrote it: a credential, the local-network opt-in, a header that can carry a credential (one named as a credential, such as Authorization or x-api-key, one whose name ends in -Key, Cookie and X-Auth), the Host header, and any client option other than its headers. iModel.from_dict attaches the provider's credential from the environment only when the stored base URL is the provider's registered one, and takes the local-network setting from the provider's registration; a stored config can turn that setting off, never on, and any stored value but true turns it off. The opt-in admits loopback addresses only (localhost, 127.0.0.1, ::1). A caller that wants another endpoint, credential or setting passes it, and a key passed without a base_url goes to the stored URL:

live = li.iModel(provider="openai", base_url=url, api_key="MY_GATEWAY_KEY")
restored = li.Branch.from_dict(data, chat_model=live, parse_model=live)
model = li.iModel.from_dict(model_data, base_url=url, api_key="MY_GATEWAY_KEY")

A string api_key is read first as the name of a lionagi setting or an environment variable that holds the key, and is used as the key itself only when no setting or variable of that name is set, so "MY_GATEWAY_KEY" above names a variable. Pass a SecretStr to give the key itself.

A CLI model sends no request of its own, so the rule above does not reach it. Its settings are restored as stored, and the child process it starts reads them: Codex config_overrides can name another provider URL and the environment variable its key is read from, Claude Code's settings and permission_mode set what that child may do, and a stored mcp_servers or mcp_config names the MCP servers it starts. The child inherits this process's environment unless a live caller sets one. Restore a CLI row only from a writer you trust.

Next: Session — manage multiple branches