"""Pathways - The execution substrate of AlbusOS.

Pathways are the runtime that coordinates computation:
- Tool call = single-node pathway
- Tool chain = multi-node pathway
- Orchestration = stateful pathway with StageNodes

Core components:
- Pathway: The graph model (nodes + connections + mode)
- PathwayBuilder: Fluent API for programmatic pathway construction
- PathwayMode: dag (default) or stateful
- PathwayVM: The graph executor
- PathwaySession: Multi-turn state for stateful pathways
- Context: Services available during execution
- Nodes: ToolNode, LLMNode, TransformNode, StageNode, LoopNode, CheckpointNode, etc.

Usage (DAG mode - default):
    from core.pathways import Pathway, PathwayVM, Context
    from core.pathways.nodes import ToolNode

    pathway = Pathway(id="example", name="Example")
    pathway.add_node("step1", ToolNode(tool="web.search", ...))

    ctx = Context(tools={...})
    vm = PathwayVM(ctx)
    result = await vm.execute(pathway, {"query": "hello"})

Usage (Fluent Builder API):
    from core.builders import PathwayBuilder
    from core.pathways.pathway import PathwayMode

    pathway = (
        PathwayBuilder("my-pathway")
        .stateful()
        .input({"query": "string"})
        .tool("search", "web.search", args={"query": "{{input.query}}"})
        .llm("summarize", prompt="Summarize: {{search.output}}")
        .output({"summary": "{{summarize.output}}"})
        .connect("input", "search")
        .connect("search", "summarize")
        .connect("summarize", "output")
        .build()
    )

Usage (Stateful mode - for orchestration):
    from core.pathways import Pathway, PathwayMode, PathwaySession
    from core.pathways.nodes import StageNode

    pathway = Pathway(id="orchestration", mode=PathwayMode.STATEFUL)
    pathway.add_node("intake", StageNode(goal="Gather requirements", ...))
    pathway.add_node("design", StageNode(goal="Design solution", ...))

    session = PathwaySession(pathway_id=pathway.id, current_stage="intake")
    result = await vm.execute_stateful(pathway, session, user_input)
"""

# IMPORTANT:
# Keep this package `__init__` minimal. In Python, importing any
# `core.pathways.*` submodule executes `core/pathways/__init__.py` first.
# If we re-export Pathway/Builder/VM here, we create circular imports
# (builders ↔ pathways) during tool loading and pytest collection.
#
# Import from concrete modules instead:
# - `core.pathways.pathway`, `core.pathways.vm`, `core.pathways.context`,
#   `core.pathways.session`, `core.builders.pathway`.

__all__: list[str] = []
