src/api/dto/system.py

"""DTOs for /system/* endpoints (health + version).

See ``BACKEND_BUILD.md §7`` for the inventory and ``§11.6`` for the
mandatory ``stalePricing`` field. All fields are camelCase on the wire via
the :class:`ApiModel` alias generator.
"""

from __future__ import annotations

from .common import ApiModel


class HealthCheck(ApiModel):
    """Per-dependency probe result.

    Mirrors the shape of ``src.lib.system.models.CheckResult`` but stays on
    the wire side so backend refactors of the probe internals don't ripple
    into the frontend. ``ok`` is the single field the dashboard reads to
    decide red/green.
    """

    name: str
    ok: bool
    detail: str | None = None
    fix_hint: str | None = None


class HealthResponse(ApiModel):
    """Aggregate health payload for ``GET /system/health``.

    ``stalePricing`` is mandatory (CONTRACT.md §12 / BACKEND_BUILD.md §11.6):
    a list of tool names whose ``cost_model.last_updated`` is older than 90
    days. Empty list means "all good". The frontend renders a warning chip
    when this is non-empty so the user gets nudged to refresh
    ``tools_registry.yaml`` quarterly.
    """

    ok: bool
    db: HealthCheck
    qdrant: HealthCheck
    storage: HealthCheck
    api_keys: HealthCheck
    stale_pricing: list[str]


class VersionResponse(ApiModel):
    """``GET /system/version`` — git sha + masked config snapshot.

    ``config`` is the merged config.yaml with secret-shaped values redacted
    (api keys, tokens, urls that embed credentials). See ``BACKEND_BUILD.md
    §7`` for the spec; the masking is implemented in ``src/api/config.py``.
    """

    git_sha: str
    config: dict