"""
matrice_vss.api
===============
FastAPI routes, Pydantic request/response schemas, and dependency helpers
for the VSS HTTP API.

Endpoints (mounted at ``/api/v1`` in ``main.py``)
--------------------------------------------------
``POST /query``
    Process a natural-language text query.  Returns a
    :class:`QueryResponseWithTrace` that includes the routed intent, the
    SQL query or VLM response, and an optional execution trace.

``POST /query/media``
    Process a query with a base64-encoded image attached.  Always routes
    to the VLM path.  Returns ``503`` if ``VSS_VLM_ENABLED=false``.

``GET /health``
    Liveness/readiness probe.  Reports status of ClickHouse, LLM, and VLM
    components individually as well as an aggregate
    ``healthy / degraded / unhealthy`` status.

Request / Response schemas
--------------------------
Pydantic models are defined in ``api.schemas``:

* :class:`QueryRequest` — ``query`` (str) + ``include_trace`` (bool)
* :class:`QueryWithMediaRequest` — adds ``media_type`` and ``media_base64``
* :class:`QueryResponse` — ``request_id``, ``status``, ``response``
* :class:`QueryResponseWithTrace` — extends with ``trace`` and ``metadata``
* :class:`ErrorResponse` — structured error payload
* :class:`HealthComponent` — per-component health status
* :class:`HealthResponse` — aggregate health payload

Usage
-----
The ``router`` (``APIRouter``) is registered in ``main.py``::

    from api.routes import router
    app.include_router(router, prefix="/api/v1", tags=["VSS"])

Schemas can be imported directly for use in tests or client code::

    from api.schemas import QueryRequest, QueryResponseWithTrace
"""

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] = {
        # api.routes
        "router": "routes",
        "get_orchestrator": "routes",
        # api.schemas
        "QueryRequest": "schemas",
        "QueryWithMediaRequest": "schemas",
        "QueryResponse": "schemas",
        "QueryResponseWithTrace": "schemas",
        "ErrorResponse": "schemas",
        "HealthComponent": "schemas",
        "HealthResponse": "schemas",
    }

    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 .routes import get_orchestrator, router  # noqa: F401
    from .schemas import (  # noqa: F401
        ErrorResponse,
        HealthComponent,
        HealthResponse,
        QueryRequest,
        QueryResponse,
        QueryResponseWithTrace,
        QueryWithMediaRequest,
    )

__all__: list[str] = [
    # routes
    "router",
    "get_orchestrator",
    # schemas
    "QueryRequest",
    "QueryWithMediaRequest",
    "QueryResponse",
    "QueryResponseWithTrace",
    "ErrorResponse",
    "HealthComponent",
    "HealthResponse",
]
