Source code for app.domain.system.schemas._metrics

# SPDX-FileCopyrightText: 2026 Google LLC
# SPDX-License-Identifier: Apache-2.0

from __future__ import annotations

from app.lib.schema import CamelizedBaseStruct



[docs]
class SearchMetricsCreate(CamelizedBaseStruct, omit_defaults=True, kw_only=True):
    """Row inserted into ``search_metric``."""

    query_id: str
    user_id: str | None = None
    search_time_ms: float
    embedding_time_ms: float
    oracle_time_ms: float
    ai_time_ms: float = 0.0
    intent_time_ms: float = 0.0
    similarity_score: float | None = None
    result_count: int




[docs]
class PerformanceStats(CamelizedBaseStruct, omit_defaults=True):
    """Aggregate latency and volume across a window of ``search_metric`` rows."""

    total_searches: int
    avg_search_time_ms: float
    avg_oracle_time_ms: float
    avg_similarity_score: float




[docs]
class CacheStatsRow(CamelizedBaseStruct, omit_defaults=True):
    """Single-row projection from ``get-cache-stats``."""

    total_hits: int
    total_entries: int




[docs]
class CacheStats(CamelizedBaseStruct, omit_defaults=True):
    """Embedding-cache hit/usage rollup with derived hit rate."""

    total_hits: int
    total_entries: int
    cache_hit_rate: float




[docs]
class MetricCard(CamelizedBaseStruct, omit_defaults=True):
    """Single card on the metrics summary panel."""

    label: str
    value: str | float
    trend: str = "neutral"
    trend_value: str | float | None = None




[docs]
class MetricsSummary(CamelizedBaseStruct, omit_defaults=True):
    """Card list rendered client-side in the Explore dashboard."""

    cards: list[MetricCard]




[docs]
class MetricsTimeSeriesPoints(CamelizedBaseStruct, omit_defaults=True):
    """Per-stage latency series for the latency chart."""

    total_ms: list[float]
    oracle_ms: list[float]
    embedding_ms: list[float]




[docs]
class MetricsTimeSeriesRow(CamelizedBaseStruct, omit_defaults=True):
    """Single per-minute bucket projected from ``metrics-time-series``."""

    bucket: str
    total_ms: float
    oracle_ms: float
    embedding_ms: float




[docs]
class MetricsTimeSeries(CamelizedBaseStruct, omit_defaults=True):
    """Latency series payload consumed by ApexCharts."""

    labels: list[str]
    series: MetricsTimeSeriesPoints




[docs]
class MetricsScatterPoint(CamelizedBaseStruct, omit_defaults=True):
    """Single vector-search point for similarity-vs-latency charts."""

    similarity_score: float
    total_ms: float
    oracle_ms: float
    embedding_ms: float




[docs]
class MetricsBreakdownRow(CamelizedBaseStruct, omit_defaults=True):
    """Aggregate component timing row projected from ``search_metric``."""

    embedding_ms: float
    oracle_ms: float
    ai_ms: float
    intent_ms: float
    other_ms: float




[docs]
class MetricsBreakdown(CamelizedBaseStruct, omit_defaults=True):
    """Labels and values for the system breakdown chart."""

    labels: list[str]
    values: list[float]




[docs]
class MetricsCharts(CamelizedBaseStruct, omit_defaults=True):
    """Complete Explore dashboard chart payload."""

    time_series: MetricsTimeSeries
    scatter: list[MetricsScatterPoint]
    breakdown: MetricsBreakdown