Sessions

The LLM remembers nothing. That’s a feature — until you want it to.

hb.LLM stays stateless on purpose. Conversation history is just a message list you pass to chat or stream. When you need multi-turn chat without rebuilding that list every time, LLMSession holds the history and optional tools for you.

1. Motivation

You can manage history yourself when you only need one or two turns:

import heavenbase as hb

messages = [
    {"role": "user", "content": "Remember the code word is hb-ok."},
    {"role": "assistant", "content": "Remembered."},
    {"role": "user", "content": "What is the code word?"},
]

answer = hb.LLM(preset="chat").chat(messages)

This pattern is enough for pipelines that already carry state elsewhere.

2. Session Tools

LLMSession can hold session tools and use them on every turn. Tools follow the same tools=[...] contract as LLM.chat: Python callables, Tool, Toolkit, and schema dictionaries are accepted.

import heavenbase as hb
from heavenbase.utils import LLMSession


def add(left: int, right: int) -> int:
    """Add two numbers."""
    return left + right


session = LLMSession(hb.LLM(preset="chat"))
session.add_tool(add)

answer = session.send("Use the add tool for 2 + 3.")
print(answer["content"])

External MCP servers import as session Toolkits:

session = LLMSession(hb.LLM(preset="chat"))
session.add_mcp("http://127.0.0.1:7001/mcp")
session.send("What tools are available?")

The session stores the assistant tool call, the role="tool" result, and the final assistant response in messages. See Tool Use for the full executable-tool contract.

3. Session Lifecycle

LLMSession exposes small helpers for interactive workflows:

session.undo()        # drop the latest user turn and everything after it
session.clear()       # reset message history
session.list_tools()  # active runtime tool names

Persist only messages — runtime MCP Toolkits are not safe to serialize:

session.save("./session.json")
restored = LLMSession.load("./session.json", llm=hb.LLM(preset="chat"))

to_dict() and from_dict() return JSON-safe payloads with the same message-only contract. Callers that already own history can mutate session.messages directly or pass that history to stateless LLM.chat(...); the session does not expose role-specific append helpers.

4. CLI Interactive Sessions

Start a multi-turn CLI session with the chat preset:

hb llm session

Type messages at the >>> prompt. Slash commands:

Command	Action
`/help`	Show available commands
`/save <path>`	Save message history to JSON
`/load <path>`	Load message history from JSON
`/clear`	Clear the session
`/regen <seed>`	Regenerate the last response with an optional seed
`/back`	Remove the latest user turn
`/tools`	List attached tools
`/mcp SOURCE`	Attach an MCP Toolkit mid-session
`/bye`, `/exit`	Quit

Attach MCP tools at startup with repeated --mcp values:

hb llm session --mcp http://127.0.0.1:7001/mcp
hb llm session --mcp quickstart.math-tools:-1
hb llm session --mcp math-tools

Inside a running session, add more tools with /mcp:

>>> /mcp quickstart.math-tools:-1
>>> What's 42 * 73?

The canonical Toolkit ref form is namespace.toolkit:version. Negative versions count back from latest: -1 is latest, -2 is second-most latest. When a provider emits separate thinking content, the CLI session prints it inside <think> and </think> before the visible assistant text. Tool iterations print step-by-step with STEPS: 001 / 020, followed by tool calls and tool results.

5. Inspect Resolved State

Use spec when you need to see how a client resolved:

import heavenbase as hb

llm = hb.LLM(model="ds-flash", provider="deepseek")

print(llm.spec.to_dict())
print(llm.spec.engine.apply(llm.spec, profile="print"))

spec.to_dict() is a reconstructive envelope whose bindings may contain credentials. Do not log it. The print Apply profile returns the redacted inspection view. Resolved specs also produce stable hash keys for deduplication and cache lookup:

spec_key = llm.spec.hash_key()
client_key = llm.spec.client_key()

client_key() includes only gateway client construction fields, so duplicate LLM instances can reuse the same in-memory OpenAI-compatible SDK client.

Summary

hb.LLM remains stateless; LLMSession owns runtime message history.
Saved sessions contain messages, not live MCP Toolkit objects.
Use the redacted print Apply profile for route inspection.

Further Exploration

Related resources:

Tool Use — schema-only and executable tools, MCP Toolkits, and structured output.
LLM Chat — message inputs, streaming, and include projection.
First LLM — CLI session tour and MCP attachment from the quickstart.

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Session Tools

3. Session Lifecycle

4. CLI Interactive Sessions

5. Inspect Resolved State

Summary

Further Exploration

​1. Motivation

​2. Session Tools

​3. Session Lifecycle

​4. CLI Interactive Sessions

​5. Inspect Resolved State

​Summary

​Further Exploration

1. Motivation

2. Session Tools

3. Session Lifecycle

4. CLI Interactive Sessions

5. Inspect Resolved State

Summary

Further Exploration