Source code for lalandre_rag.retrieval.metrics

"""Metrics hook interfaces for RAG retrieval instrumentation.

This package remains backend-agnostic. Services register a recorder backend
(Prometheus, OTEL, etc.) at startup.
"""

from abc import ABC, abstractmethod
from typing import Any




class RetrievalMetricsRecorder(ABC):
    """Backend-agnostic hook interface for retrieval metrics."""



    @abstractmethod
    def observe_phase(
        self,
        *,
        operation: str,
        phase: str,
        duration_seconds: float,
    ) -> None:
        """Record latency for one retrieval phase."""
        ...




    @abstractmethod
    def observe_error(
        self,
        *,
        operation: str,
        phase: str,
        exc_or_reason: Any,
    ) -> None:
        """Record one retrieval error or degradation reason."""
        ...




class _NoopRetrievalMetricsRecorder(RetrievalMetricsRecorder):
    def observe_phase(
        self,
        *,
        operation: str,
        phase: str,
        duration_seconds: float,
    ) -> None:
        return None

    def observe_error(
        self,
        *,
        operation: str,
        phase: str,
        exc_or_reason: Any,
    ) -> None:
        return None


_recorder: RetrievalMetricsRecorder = _NoopRetrievalMetricsRecorder()




def set_retrieval_metrics_recorder(recorder: RetrievalMetricsRecorder) -> None:
    """Register the active retrieval metrics recorder backend."""
    global _recorder
    _recorder = recorder





def observe_retrieval_phase(
    *,
    operation: str,
    phase: str,
    duration_seconds: float,
) -> None:
    """Forward one retrieval phase observation to the active recorder."""
    _recorder.observe_phase(
        operation=operation,
        phase=phase,
        duration_seconds=duration_seconds,
    )





def observe_retrieval_error(
    *,
    operation: str,
    phase: str,
    exc_or_reason: Any,
) -> None:
    """Forward one retrieval error observation to the active recorder."""
    _recorder.observe_error(
        operation=operation,
        phase=phase,
        exc_or_reason=exc_or_reason,
    )