"""
matrice_vss.orchestration
=========================
LangGraph state machine and supporting utilities for the VSS Mode 1 query
workflow.

This sub-package wires together intent classification, SQL execution, VLM
inference, and response composition into a single directed graph that is
executed asynchronously per request.

Components
----------
``state`` module
    :class:`VSSState` — the ``TypedDict`` shared across every graph node.
    Factory (:func:`create_state`), mutation helpers (:func:`add_trace`,
    :func:`set_error`).

``graph`` module
    :class:`VSSOrchestrator` — compiles and runs the LangGraph application.
    Module-level convenience function :func:`run_query`.

``scheduler`` module
    Reserved for future background / scheduled task support.

Public API
----------
.. code-block:: python

    from orchestration.state import VSSState, create_state, add_trace, set_error
    from orchestration.graph import VSSOrchestrator, run_query

Workflow
--------
::

    [classify_intent]
          │
    ┌─────┴──────┐
    ▼            ▼
  [sql]        [vlm]
    │            │
    ├─ escalate ─┤
    ▼            ▼
     [compose_response]
          │
         END
"""

from __future__ import annotations

from typing import TYPE_CHECKING


def __getattr__(name: str):  # noqa: N807
    """Lazy-load public symbols from child modules on first access."""
    import importlib

    _symbol_map: dict[str, str] = {
        # orchestration.state
        "VSSState": "state",
        "create_state": "state",
        "add_trace": "state",
        "set_error": "state",
        # orchestration.graph
        "VSSOrchestrator": "graph",
        "run_query": "graph",
    }

    if name in _symbol_map:
        module = importlib.import_module(
            f".{_symbol_map[name]}", package=__name__
        )
        value = getattr(module, name)
        globals()[name] = value
        return value

    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")


if TYPE_CHECKING:  # pragma: no cover
    from .state import (  # noqa: F401
        VSSState,
        add_trace,
        create_state,
        set_error,
    )
    from .graph import VSSOrchestrator, run_query  # noqa: F401

__all__: list[str] = [
    # state
    "VSSState",
    "create_state",
    "add_trace",
    "set_error",
    # graph
    "VSSOrchestrator",
    "run_query",
]
