"""Sanitize normalized retrieval telemetry for the output ``diagnostics``.

The evaluators consume the full normalized telemetry produced by
:class:`RetrievalArtifactProvider`. For output we surface only a sanitized
subset — what the retrieval system actually returned — so authors can debug
failing retrieval evaluations from the output alone.

This module produces the ``retrieval_executions`` *member* of the extensible
``diagnostics`` container. The container itself (and the attach / suppression
policy) is assembled by ``evaluation_runner``; this function is pure: telemetry
dict in, sanitized dict out, no I/O and no policy decisions.

"""

from __future__ import annotations

from typing import Any, Dict, List, Optional


def sanitize_retrieval_diagnostics(
    retrieval_telemetry: Optional[Dict[str, Any]],
) -> Dict[str, Any]:
    """Return the sanitized ``retrieval_executions`` diagnostics member.

    ``retrieval_telemetry`` is the normalized telemetry dict from
    ``RetrievalArtifactProvider.normalize()`` (or ``None`` / ``{}`` when no
    telemetry was produced).

    Returns ``{"retrieval_executions": [...]}`` always (possibly empty).
    Never raises — malformed or missing input yields an empty list.
    """
    if not isinstance(retrieval_telemetry, dict):
        return {"retrieval_executions": []}

    raw_executions = retrieval_telemetry.get("retrieval_executions")
    if not isinstance(raw_executions, list):
        return {"retrieval_executions": []}

    sanitized: List[Dict[str, Any]] = []
    for execution in raw_executions:
        if not isinstance(execution, dict):
            continue
        sanitized.append(_sanitize_execution(execution))

    return {"retrieval_executions": sanitized}


def _sanitize_execution(execution: Dict[str, Any]) -> Dict[str, Any]:
    """Keep only the evaluator-debugging fields of one execution."""
    return {
        "capability": execution.get("capability"),
        "status": execution.get("status"),
        "queries": _sanitize_queries(execution.get("queries")),
        "totalResultCount": execution.get("totalResultCount"),
        "retrievalHits": _sanitize_hits(execution.get("retrievalHits")),
    }


def _sanitize_queries(queries: Any) -> List[Dict[str, Any]]:
    """Keep ``queryString`` and ``filterExpression`` per query."""
    if not isinstance(queries, list):
        return []
    sanitized: List[Dict[str, Any]] = []
    for query in queries:
        if not isinstance(query, dict):
            continue
        sanitized.append({
            "queryString": query.get("queryString"),
            "filterExpression": query.get("filterExpression"),
        })
    return sanitized


def _sanitize_hits(hits: Any) -> List[Dict[str, Any]]:
    """Keep ``rank``, ``webUrl`` and extract ``text`` per hit."""
    if not isinstance(hits, list):
        return []
    sanitized: List[Dict[str, Any]] = []
    for hit in hits:
        if not isinstance(hit, dict):
            continue
        sanitized.append({
            "rank": hit.get("rank"),
            "webUrl": hit.get("webUrl"),
            "extracts": _sanitize_extracts(hit.get("extracts")),
        })
    return sanitized


def _sanitize_extracts(extracts: Any) -> List[Dict[str, Any]]:
    """Keep only extract ``text`` (no ``relevanceScore``)."""
    if not isinstance(extracts, list):
        return []
    sanitized: List[Dict[str, Any]] = []
    for extract in extracts:
        if not isinstance(extract, dict):
            continue
        text = extract.get("text")
        if not isinstance(text, str):
            continue
        sanitized.append({"text": text})
    return sanitized