Architecture

superdialog/
  ├─ flow/                # Flow graph: nodes, edges, serialization
  ├─ machine/             # DialogStateMachine engine
  ├─ dialog_machine.py    # Public DialogMachine facade
  ├─ agent.py             # Agent Protocol + TurnResult
  ├─ agents/              # LLMAgent, LangChainAgent (non-DM brains)
  ├─ session/             # Session, SessionHandle, SessionWorker, stores, locks
  ├─ chat_context.py      # ChatContext, ChatMessage (LiveKit-aligned)
  ├─ flow_state.py        # FlowState (DM-specific runtime state)
  ├─ llm/                 # Model URI resolver and provider adapters
  ├─ tools/               # Python / HTTP / MCP tool wrappers
  ├─ cli/                 # superdialog chat / flow lint / flow draw / flow generate
  └─ adapters/            # LiveKit, PipeCat, FastAPI, WebSocket

flow = await create_dialog_flow(
    prompt="Confirm KYC. Ask for Aadhaar last 4 digits.",
    llm="openai/gpt-5.1",
)
flow.save("kyc.json")            # JSON-serializable, version-controllable
flow = Flow.load("kyc.json")

dialog_machine = DialogMachine(
    flow=flow,                # or FlowSet(...)
    llm="anthropic/claude-haiku-4-5",
    tools=[...],
    traversal_dir="./history",   # optional: auto-saves session JSON on completion
)

# Non-streaming - returns a complete Turn
reply = await dialog_machine.turn("hello")
print(reply.text)

# Streaming - returns an async iterator of StreamChunk
stream = await dialog_machine.turn("hello", stream=True)
async for chunk in stream:
    print(chunk.text, end="")

register_llm_provider(
    name="internal",
    base_url="https://llm.company.io/v1",
    api_key=os.environ["INTERNAL_LLM_KEY"],
    api_style="openai",
)
# Use as: "custom/internal/llama-3-70b-tuned"

PythonTool.of(my_function)               # infer id/name/schema from signature + docstring

HttpTool(
    id="lookup", name="lookup",
    description="Look up customer by Aadhaar",
    url="https://api.company.io/lookup",
    auth={"type": "bearer", "token": os.environ["KEY"]},
)

MCPTool(
    id="search", name="search",
    description="Search knowledge base",
    server="https://mcp.company.io",
)

worker = SessionWorker(
    agent_factory=lambda: DialogMachine(flow=flow, llm="openai/gpt-5.1"),
    store=InMemorySessionStore(),
)

async with worker.acquire(session_id) as h:
    reply = await h.turn(text)