Chat sessions

ChatSession combines source routing, tools, conversation history, and structured outputs. Reuse a session for follow-up questions, and stream answers and tool progress as they happen.

Example: Ask a follow-up question

You're reviewing inventory before placing an order. Ask which products need restocking, then follow up with how many units to order using the same conversation.

Create the sample database

import pandas as pd

from tabulaflow.data import DataConnectorRegistry, SQLConnector

stock = await SQLConnector.from_url_async("sqlite+aiosqlite:///:memory:", read_only=False)
registry = DataConnectorRegistry()
# Make the connector available to the session.
registry.register("stock", stock)
await stock.write_dataframe_async(
    pd.DataFrame(
        columns=["product", "on_hand", "reorder_point"],
        data=[
            ("USB-C dock", 3, 10),
            ("Laptop stand", 18, 8),
            ("HDMI cable", 4, 12),
        ],
    ),
    "inventory",
)

from tabulaflow.agents import ChatSession


session = ChatSession(registry=registry, model="openai:gpt-5.6-sol", reasoning="low")

result = await session.run("Which products are below their reorder point?")
print(result.text)

Reuse the session for the follow-up below; it retains the first question and answer.

Stream answers and progress

Ask how much to order, using the previous turn's context:

async for event in session.run_stream("How many units of each should I order to reach those levels?"):
    if event.kind == "tool_started":
        print("\nTool:", event.name)
    elif event.kind == "answer_delta":
        print(event.content, end="", flush=True)
    elif event.kind == "turn_finished":
        result = event.result

Sample output

The following products are below their reorder point:

- HDMI cable — on hand: 4, reorder point: 12 (short by 8)
- USB-C dock — on hand: 3, reorder point: 10 (short by 7)
Order quantities to reach each product's reorder point:

- HDMI cable — order 8 units (reorder point 12 minus on hand 4)
- USB-C dock — order 7 units (reorder point 10 minus on hand 3)

turn_finished provides the complete result, including its output artifacts and usage. See the event reference for all event types.

Inspect the completed turn's token usage and estimated API cost:

usage = result.usage
if usage is not None:
    print("\nRequests:", usage.api_requests)
    print("Input tokens:", usage.input_tokens)
    print("Output tokens:", usage.output_tokens)
    print(f"Estimated cost: ${usage.api_cost_usd:.6f}")

Set OPENAI_API_KEY, then run both turns:

tabulaflow examples run chat-sessions

Manage a conversation

Start a new conversation while keeping the session's connectors and stored outputs:

session.reset_conversation()

Long conversations use automatic context compaction. ChatSession and DataConnectorRegistry are async context managers; closing the registry closes the connectors registered with it. See the session reference for configuration and lifecycle details.