"""pathways.nodes - Node types for pathways.

FOUNDATIONAL (declare data flow):
- InputNode: Declares pathway inputs with optional schema validation
- OutputNode: Declares pathway outputs with mapping from upstream nodes

PROCESSING (do the work):
- ToolNode: Calls any tool (web.search, code.execute, etc.)
- LLMNode: Direct LLM generation with optional tool calling
- TransformNode: Safe expression evaluation

COMPOSITION (pathways in pathways):
- PathwayNode: Execute a registered sub-pathway

ORCHESTRATION (multi-agent):
- HandoffNode: Route + delegate to the best-matching agent

FLOW CONTROL:
- ConditionalNode: Branch based on condition (if/else)

STATEFUL (for orchestration - use with mode=stateful):
- StageNode: Orchestration state with agent + transitions
- LoopNode: Iteration until condition
- CheckpointNode: Persistence point for resume

Usage (DAG mode):
    from core.pathways import Pathway, PathwayVM
    from core.pathways.nodes import InputNode, OutputNode, ToolNode

    pathway = Pathway(id="example", name="Example")
    pathway.add_node("input", InputNode(input_schema={"text": {"type": "string"}}))
    pathway.add_node("process", ToolNode(tool="transform.uppercase", args={"text": "{{input.text}}"}))
    pathway.add_node("output", OutputNode(mapping={"result": "{{process.output.result}}"}))
    pathway.connect("input", "process")
    pathway.connect("process", "output")
    record = await vm.execute(pathway, {"text": "hello"})

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(agent_id="coordinator", goal="Gather requirements"))
    pathway.add_node("build", StageNode(agent_id="builder", goal="Build solution"))
    pathway.connect("intake", "build", when="{{intake.ready}}")

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

# =============================================================================
# TOOL DTOS (needed for tool calling)
# =============================================================================
from core.pathways.models.tool import (
    ToolCall,
    ToolCallPlan,
    ToolExecutionResult,
    ToolResult,
)
from core.pathways.nodes.base import NodeBase

# =============================================================================
# PROCESSING + STATEFUL NODES (individual modules)
# =============================================================================
from core.pathways.nodes.checkpoint import CheckpointNode
from core.pathways.nodes.code_execute import CodeExecuteNode

# =============================================================================
# EXECUTION RECORDS (needed by VM)
# =============================================================================
from core.pathways.nodes.execution import (
    PathwayEvent,
    PathwayMetrics,
    PathwayRecord,
    PathwayStatus,
)

# =============================================================================
# FLOW CONTROL (from flow.py)
# =============================================================================
from core.pathways.nodes.flow import ConditionalNode

# =============================================================================
# FOUNDATIONAL - Input/Output declaration (from foundational.py)
# =============================================================================
from core.pathways.nodes.foundational import InputNode, OutputNode
from core.pathways.nodes.handoff import HandoffNode
from core.pathways.nodes.llm import LLMNode
from core.pathways.nodes.loop import LoopNode

# =============================================================================
# NODE TYPE REGISTRY (API discovery + validation)
# =============================================================================
from core.pathways.nodes.registry import NodeTypeExample, NodeTypeRegistry, NodeTypeSpec
from core.pathways.nodes.stage import StageNode
from core.pathways.nodes.sub_pathway import PathwayNode
from core.pathways.nodes.tool import ToolNode
from core.pathways.nodes.transform import TransformNode

# =============================================================================
# PUBLIC API
# =============================================================================

__all__ = [
    "CheckpointNode",
    "CodeExecuteNode",
    "ConditionalNode",
    "HandoffNode",
    "InputNode",
    "LLMNode",
    "LoopNode",
    "NodeBase",
    "NodeTypeExample",
    "NodeTypeRegistry",
    "NodeTypeSpec",
    "OutputNode",
    "PathwayEvent",
    "PathwayMetrics",
    "PathwayNode",
    "PathwayRecord",
    "PathwayStatus",
    "StageNode",
    "ToolCall",
    "ToolCallPlan",
    "ToolExecutionResult",
    "ToolNode",
    "ToolResult",
    "TransformNode",
]
