"""
matrice_vss.storage
===================
Persistent storage layer for the VSS service.

Current components
------------------
``clickhouse_client`` module
    :class:`ClickHouseClient` — synchronous ClickHouse client built on top of
    ``clickhouse_connect``.  Provides connection management, health checking,
    and high-level query helpers for the VSS analytics schema.

    The :func:`get_clickhouse` factory returns a process-level singleton so
    that connection pooling is transparent to callers.

``cache`` module
    Reserved for future in-process or Redis-backed query-result caching.

Usage
-----
.. code-block:: python

    from storage.clickhouse_client import get_clickhouse

    ch = get_clickhouse()
    if ch.test_connection():
        rows, columns = ch.execute("SELECT count() FROM default.alert_instances")

Schema tables
-------------
``alert_instances``
    Individual alert events per application and camera.
``incidents``
    Detected incidents with severity levels.
``aggregated_analytics_totals``
    Aggregated analytics summaries (counts, totals) over time.
"""

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] = {
        "ClickHouseClient": "clickhouse_client",
        "get_clickhouse": "clickhouse_client",
    }

    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 .clickhouse_client import ClickHouseClient, get_clickhouse  # noqa: F401

__all__: list[str] = [
    "ClickHouseClient",
    "get_clickhouse",
]
