"""Stateless Phase 5 — final evaluation & reporting.

Platform owns the live session and supplies interview_mode, Q&A, optional
transcript, trusted turn scores, and authorized media evidence.
"""

from __future__ import annotations

import logging
from collections import defaultdict
from typing import Any

from app.prompts import Persona
from app.schemas.common import JobStatus
from app.schemas.final_evaluation import (
    DEFAULT_REQUIRED_SKILL_LEVEL,
    AggregatedScores,
    CategoryScore,
    CategoryScoreBrief,
    CategoryWeight,
    FinalEvaluationDetails,
    FinalEvaluationRequest,
    FinalEvaluationResponse,
    FinalReport,
    HiringFitRecommendation,
    MetricAssessment,
    QaItemIn,
    QuestionReviewBrief,
    QuestionScoreItem,
    RecommendationBrief,
    ScoreProvenance,
    SkillAssessmentBrief,
    SkillGapAnalysis,
    SkillGapFinding,
    SkillStatus,
    SkillTarget,
    TurnScoreIn,
)
from app.schemas.interviews import (
    EvaluateAnswerRequest,
    InterviewMode,
)
from app.services.interviews.core import InterviewsService, _band_for_score
from app.services.shared.ai_generate import generate_json

logger = logging.getLogger(__name__)


def _resolve_score_band(score: float | None, band: str | None) -> str | None:
    """Prefer a real supplied band; otherwise derive from score. Drop placeholders."""
    raw = (band or "").strip()
    if raw and raw.lower() not in {
        "example",
        "example-score_band",
        "string",
        "null",
        "none",
    }:
        return raw
    if score is None:
        return None
    try:
        return _band_for_score(float(score)).value
    except (TypeError, ValueError):
        return None

DEFAULT_CATEGORY_WEIGHTS: dict[str, tuple[str, float]] = {
    "correctness": ("Correctness", 1.2),
    "relevance": ("Relevance", 1.0),
    "depth": ("Depth", 1.1),
    "problem_solving": ("Problem-solving", 1.1),
    "completeness": ("Completeness", 1.0),
}

TEXT_COMM_KEYS = ("clarity", "structure", "written_communication")


def _clamp01(value: Any, default: float | None = 0.0) -> float | None:
    if value is None:
        return default
    try:
        v = float(value)
    except (TypeError, ValueError):
        return default
    return max(0.0, min(1.0, v))


def _resolve_weights(
    custom: list[CategoryWeight],
) -> dict[str, tuple[str, float]]:
    if not custom:
        return dict(DEFAULT_CATEGORY_WEIGHTS)
    out: dict[str, tuple[str, float]] = {}
    for item in custom:
        key = (item.key or "").strip()
        if not key:
            continue
        label = item.label or DEFAULT_CATEGORY_WEIGHTS.get(key, (key, 1.0))[0]
        if key in DEFAULT_CATEGORY_WEIGHTS and not item.label:
            label = DEFAULT_CATEGORY_WEIGHTS[key][0]
        out[key] = (label, float(item.weight))
    return out or dict(DEFAULT_CATEGORY_WEIGHTS)


def _merge_skill_tags(
    existing: list[str],
    *,
    question: str,
    required_skills: list[str],
    skill_targets: list[SkillTarget],
) -> list[str]:
    """Keep explicit tags; add defensible question-text matches to named skills."""
    out: list[str] = []
    seen: set[str] = set()
    for tag in existing:
        name = (tag or "").strip()
        if name and name.lower() not in seen:
            seen.add(name.lower())
            out.append(name)
    names = list(required_skills or [])
    names.extend(t.skill for t in (skill_targets or []) if t.skill)
    q = (question or "").lower()
    for skill in names:
        name = (skill or "").strip()
        if not name or name.lower() in seen:
            continue
        # Require whole-token / clear substring presence in the question stem.
        if name.lower() in q:
            seen.add(name.lower())
            out.append(name)
    return out


def _score_key(question_id: str | None, turn_index: int | None) -> str | None:
    if question_id:
        return f"qid:{question_id}"
    if turn_index is not None:
        return f"idx:{turn_index}"
    return None


def _match_supplied(
    item: QaItemIn,
    index: int,
    by_key: dict[str, TurnScoreIn],
) -> TurnScoreIn | None:
    for key in (
        _score_key(item.question_id, None),
        _score_key(None, item.turn_index if item.turn_index is not None else index),
    ):
        if key and key in by_key:
            return by_key[key]
    return None


def _derive_aggregate_provenance(
    item_provenances: list[ScoreProvenance],
) -> ScoreProvenance:
    """Aggregates are never labeled 'supplied' — only derived labels."""
    usable = [
        p
        for p in item_provenances
        if p
        in {
            ScoreProvenance.SUPPLIED,
            ScoreProvenance.CALCULATED,
            ScoreProvenance.CALCULATED_FROM_SUPPLIED,
        }
    ]
    if not usable:
        return ScoreProvenance.UNAVAILABLE
    if all(p == ScoreProvenance.SUPPLIED for p in usable):
        return ScoreProvenance.CALCULATED_FROM_SUPPLIED
    if all(p == ScoreProvenance.CALCULATED for p in usable):
        return ScoreProvenance.CALCULATED
    if all(
        p
        in {
            ScoreProvenance.SUPPLIED,
            ScoreProvenance.CALCULATED_FROM_SUPPLIED,
        }
        for p in usable
    ):
        return ScoreProvenance.CALCULATED_FROM_SUPPLIED
    return ScoreProvenance.CALCULATED


def aggregate_categories(
    question_scores: list[QuestionScoreItem],
    weights: dict[str, tuple[str, float]],
) -> AggregatedScores:
    """Score each category only from mapped dimension / category_keys evidence."""
    dim_sums: dict[str, float] = defaultdict(float)
    dim_counts: dict[str, int] = defaultdict(int)
    dim_evidence: dict[str, list[str]] = defaultdict(list)
    dim_provs: dict[str, list[ScoreProvenance]] = defaultdict(list)
    turn_scores_list: list[float] = []
    turn_provs: list[ScoreProvenance] = []
    any_dim_or_map = False

    for qs in question_scores:
        if qs.score is not None:
            turn_scores_list.append(float(qs.score))
            turn_provs.append(qs.provenance)

        mapped_keys = {k.strip() for k in (qs.category_keys or []) if k and k.strip()}
        dim_keys = {str(k).strip() for k in (qs.dimensions or {}).keys() if k}
        if mapped_keys or dim_keys:
            any_dim_or_map = True

        # Category scores from explicit dimension evidence only — never invent from
        # question overall. Do NOT filter dimensions by category_keys: if Platform
        # (or rubric) supplies a dimension (e.g. relevance), it must count even when
        # qa_items.category_keys omitted that key.
        enriched = set(qs.enriched_dimension_keys or [])
        for key, val in (qs.dimensions or {}).items():
            key_s = str(key).strip()
            if not key_s:
                continue
            score = _clamp01(val, default=None)
            if score is None:
                continue
            if key_s in enriched:
                dim_prov = ScoreProvenance.CALCULATED
            elif qs.provenance == ScoreProvenance.SUPPLIED:
                dim_prov = ScoreProvenance.SUPPLIED
            else:
                dim_prov = qs.provenance
            dim_sums[key_s] += score
            dim_counts[key_s] += 1
            dim_provs[key_s].append(dim_prov)
            if qs.explanation and len(dim_evidence[key_s]) < 3:
                dim_evidence[key_s].append(str(qs.explanation)[:160])
            elif qs.question_id and len(dim_evidence[key_s]) < 3:
                dim_evidence[key_s].append(
                    f"q={qs.question_id} dim={key_s} score={score:.2f}"
                )

    configured = {k: w for k, (_l, w) in weights.items()}
    category_scores: list[CategoryScore] = []
    missing: list[str] = []
    available: list[tuple[str, float, float, ScoreProvenance]] = []
    # (key, score, configured_weight, provenance)

    for key, (label, weight) in weights.items():
        n = dim_counts.get(key, 0)
        if n <= 0:
            missing.append(key)
            category_scores.append(
                CategoryScore(
                    key=key,
                    label=label,
                    score=None,
                    weight=weight,
                    effective_weight=None,
                    sample_size=0,
                    evidence=[],
                    provenance=ScoreProvenance.UNAVAILABLE,
                )
            )
            continue
        cat_score = dim_sums[key] / n
        prov = _derive_aggregate_provenance(dim_provs[key])
        available.append((key, cat_score, weight, prov))
        category_scores.append(
            CategoryScore(
                key=key,
                label=label,
                score=round(cat_score, 3),
                weight=weight,
                effective_weight=None,  # filled after normalize
                sample_size=n,
                evidence=list(dim_evidence.get(key) or [])[:3],
                provenance=prov,
            )
        )

    fallback: str | None = None
    overall: float | None = None
    overall_prov = ScoreProvenance.UNAVAILABLE
    weights_effective: dict[str, float] = {}

    # Effective weights among available categories (for reporting only).
    if available:
        weight_sum = sum(w for _k, _s, w, _p in available if w > 0)
        if weight_sum <= 0:
            n_av = len(available)
            for key, _score, _w, _prov in available:
                weights_effective[key] = round(1.0 / n_av, 6)
        else:
            for key, _score, w, _prov in available:
                weights_effective[key] = round(w / weight_sum, 6)
        for c in category_scores:
            if c.key in weights_effective:
                c.effective_weight = weights_effective[c.key]

    # Overall aggregation policy: mean of question totals when present.
    # Never substitute overall into missing categories; never invent category scores.
    if turn_scores_list:
        overall = round(sum(turn_scores_list) / len(turn_scores_list), 3)
        overall_prov = _derive_aggregate_provenance(turn_provs)
        all_supplied = bool(turn_provs) and all(
            p == ScoreProvenance.SUPPLIED for p in turn_provs
        )
        fallback = (
            "mean_of_supplied_question_scores"
            if all_supplied
            else "mean_question_scores"
        )
    elif available:
        weight_sum = sum(w for _k, _s, w, _p in available if w > 0) or len(available)
        overall = round(
            sum(s * (w if weight_sum and w else 1.0) for _k, s, w, _p in available)
            / weight_sum,
            3,
        )
        overall_prov = _derive_aggregate_provenance([p for *_a, p in available])
        fallback = "weighted_available_categories"
    else:
        overall = None
        overall_prov = ScoreProvenance.UNAVAILABLE

    if not any_dim_or_map and weights:
        missing = list(weights.keys())

    return AggregatedScores(
        overall_score=overall,
        max_score=1.0,
        question_count=len(question_scores),
        category_scores=category_scores,
        question_scores=question_scores,
        weights_configured=configured,
        weights_effective=weights_effective,
        missing_categories=missing,
        fallback=fallback,
        weights_used=weights_effective or configured,
        overall_provenance=overall_prov,
    )


def analyze_skill_gaps(
    *,
    skill_targets: list[SkillTarget],
    required_skills: list[str],
    question_scores: list[QuestionScoreItem],
) -> SkillGapAnalysis:
    """Map skills only from explicit skill_tags evidence — never invent demos."""
    targets: dict[str, float | None] = {}
    for t in skill_targets:
        name = (t.skill or "").strip()
        if name:
            targets[name] = t.required_level
    for name in required_skills:
        key = (name or "").strip()
        if key and key not in targets:
            targets[key] = None

    # Collect question scores per skill tag
    by_skill: dict[str, list[tuple[float, ScoreProvenance, str]]] = defaultdict(list)
    for qs in question_scores:
        if qs.score is None:
            continue
        for tag in qs.skill_tags or []:
            skill = tag.strip()
            if not skill:
                continue
            evidence = (
                f"q={qs.question_id or qs.turn_index} score={qs.score:.2f}"
            )
            by_skill[skill].append((float(qs.score), qs.provenance, evidence))

    gaps: list[SkillGapFinding] = []
    strengths: list[str] = []
    skill_scores: list[MetricAssessment] = []
    demos_for_readiness: list[float] = []

    if not targets:
        return SkillGapAnalysis(
            overall_readiness=None,
            readiness_provenance=ScoreProvenance.UNAVAILABLE,
            default_required_level=DEFAULT_REQUIRED_SKILL_LEVEL,
            strengths=[],
            gaps=[],
            recommended_prep_focus=[],
            skill_scores=[],
        )

    for skill, req_raw in targets.items():
        req = (
            float(req_raw)
            if req_raw is not None
            else DEFAULT_REQUIRED_SKILL_LEVEL
        )
        samples = by_skill.get(skill) or []
        if not samples:
            gaps.append(
                SkillGapFinding(
                    skill=skill,
                    required_level=req,
                    demonstrated_level=None,
                    gap=None,
                    priority="medium",
                    needs_more_evidence=True,
                    evidence=(
                        "Insufficient evidence — no qa_items.skill_tags mapped "
                        f"to {skill!r}"
                    ),
                    improvement_suggestions=[
                        f"Map at least one question with skill_tags including {skill}",
                    ],
                    provenance=ScoreProvenance.UNAVAILABLE,
                )
            )
            skill_scores.append(
                MetricAssessment(
                    key=skill,
                    label=skill,
                    score=None,
                    provenance=ScoreProvenance.UNAVAILABLE,
                    detail="No mapped question evidence",
                )
            )
            continue

        demo = sum(s for s, _p, _e in samples) / len(samples)
        demos_for_readiness.append(demo)
        prov = _derive_aggregate_provenance([p for _s, p, _e in samples])
        gap = max(0.0, round(req - demo, 3))
        # Low performance vs insufficient evidence: we have evidence here
        needs_more = False
        if demo >= req:
            strengths.append(skill)
        gaps.append(
            SkillGapFinding(
                skill=skill,
                required_level=req,
                demonstrated_level=round(demo, 3),
                gap=gap,
                priority="high" if gap >= 0.4 else "medium" if gap >= 0.2 else "low",
                needs_more_evidence=needs_more,
                evidence="; ".join(e for _s, _p, e in samples[:3]),
                improvement_suggestions=(
                    []
                    if gap < 0.15
                    else [
                        f"Ask for a concrete {skill} example with metrics",
                    ]
                ),
                provenance=prov,
            )
        )
        skill_scores.append(
            MetricAssessment(
                key=skill,
                label=skill,
                score=round(demo, 3),
                provenance=prov,
                detail=f"Mean of {len(samples)} mapped question score(s)",
                evidence={"samples": [e for _s, _p, e in samples[:5]]},
            )
        )

    if demos_for_readiness:
        readiness = round(sum(demos_for_readiness) / len(demos_for_readiness), 3)
        readiness_prov = ScoreProvenance.CALCULATED
        if all(
            g.provenance == ScoreProvenance.CALCULATED_FROM_SUPPLIED
            for g in gaps
            if g.demonstrated_level is not None
        ):
            readiness_prov = ScoreProvenance.CALCULATED_FROM_SUPPLIED
    else:
        readiness = None
        readiness_prov = ScoreProvenance.UNAVAILABLE

    prep = [
        g.skill
        for g in gaps
        if g.needs_more_evidence or (g.gap is not None and g.gap >= 0.25)
    ][:5]

    return SkillGapAnalysis(
        overall_readiness=readiness,
        readiness_provenance=readiness_prov,
        default_required_level=DEFAULT_REQUIRED_SKILL_LEVEL,
        strengths=strengths,
        gaps=gaps,
        recommended_prep_focus=prep,
        skill_scores=skill_scores,
    )


def hiring_fit_local(
    *,
    overall_score: float | None,
    skill_gap: SkillGapAnalysis,
    question_count: int,
    category_scores: list[CategoryScore],
) -> HiringFitRecommendation:
    """Transparent advisory fit — omit numeric score when inputs unavailable."""
    available_cats = [c for c in category_scores if c.score is not None]
    weak_cats = [c for c in available_cats if (c.score or 0) < 0.5]
    high_gaps = [
        g
        for g in skill_gap.gaps
        if g.demonstrated_level is not None and (g.gap or 0) >= 0.35
    ]
    insufficient = [g for g in skill_gap.gaps if g.needs_more_evidence]

    formula = (
        "hiring_fit = clamp01(0.6 * overall + 0.4 * skill_readiness); "
        "caps: question_count<2 → ≤0.55; ≥3 high skill gaps → ≤0.55; "
        "each weak category (−0.05, floor 0.35). Labels: "
        "≥0.85 strong_yes, ≥0.70 yes, ≥0.50 maybe, else no."
    )

    readiness = skill_gap.overall_readiness
    readiness_available = (
        readiness is not None
        and skill_gap.readiness_provenance != ScoreProvenance.UNAVAILABLE
    )

    if overall_score is None and not readiness_available:
        return HiringFitRecommendation(
            hiring_fit_score=None,
            hiring_fit_label="insufficient_data",
            recommendation="hold_for_human_review",
            formula=formula,
            supporting_evidence=[
                "Overall score unavailable",
                "Skill readiness unavailable",
            ],
            limitations=["Numeric hiring-fit omitted — insufficient scored evidence"],
            missing_information=[
                f"Insufficient evidence for: {g.skill}" for g in insufficient[:6]
            ]
            or ["Need scored Q&A or supplied turn scores"],
            requires_human_review=True,
        )

    # Never fabricate skill_readiness from overall.
    if overall_score is not None and not readiness_available:
        score = float(overall_score)
        formula = (
            "hiring_fit = overall_only_when_skill_readiness_unavailable; "
            "skill_readiness excluded (unavailable — not substituted). "
            "Labels: ≥0.85 strong_yes, ≥0.70 yes, ≥0.50 maybe, else no."
        )
        evidence = [
            f"overall={overall_score:.3f}",
            "skill_readiness=unavailable (not substituted)",
            f"hiring_fit={score:.3f} (overall-only documented fallback)",
            f"questions_scored={question_count}",
            f"readiness_provenance={skill_gap.readiness_provenance.value}",
        ]
    elif readiness_available and overall_score is None:
        score = float(readiness)  # type: ignore[arg-type]
        formula = (
            "hiring_fit = skill_readiness_only_when_overall_unavailable; "
            "Labels: ≥0.85 strong_yes, ≥0.70 yes, ≥0.50 maybe, else no."
        )
        evidence = [
            "overall=unavailable",
            f"skill_readiness={readiness:.3f}",
            f"hiring_fit={score:.3f}",
            f"questions_scored={question_count}",
        ]
    else:
        assert overall_score is not None and readiness is not None
        score = _clamp01(0.6 * overall_score + 0.4 * readiness) or 0.0
        evidence = [
            f"overall={overall_score:.3f}",
            f"skill_readiness={readiness:.3f}",
            f"raw=0.6*overall+0.4*readiness → {score:.3f}",
            f"questions_scored={question_count}",
        ]

    if question_count < 2:
        score = min(score, 0.55)
    # Category/skill caps only when those signals are part of the composite.
    if readiness_available:
        if len(high_gaps) >= 3:
            score = min(score, 0.55)
        if weak_cats:
            score = min(score, max(0.35, score - 0.05 * len(weak_cats)))
    evidence.append(f"after_caps={score:.3f}")

    if score >= 0.85:
        label, rec = "strong_yes", "advance"
    elif score >= 0.70:
        label, rec = "yes", "advance_with_conditions"
    elif score >= 0.50:
        label, rec = "maybe", "hold_for_follow_up"
    else:
        label, rec = "no", "do_not_advance"
    for c in sorted(available_cats, key=lambda x: x.score or 0, reverse=True)[:3]:
        if (c.score or 0) >= 0.6:
            evidence.append(f"category {c.key}={c.score:.2f}")

    limitations = [
        "Advisory only — final hiring decisions require human review",
        "Scores reflect this request payload only",
    ]
    if question_count < 3:
        limitations.append("Few scored answers — recommendation confidence is limited")
    if insufficient:
        limitations.append(
            "Skills lacking mapped evidence: "
            + ", ".join(g.skill for g in insufficient[:4])
        )

    missing = [
        f"More evidence needed for: {g.skill}" for g in insufficient[:8]
    ] or ["None critical — still requires human review"]

    return HiringFitRecommendation(
        hiring_fit_score=round(score, 3),
        hiring_fit_label=label,
        recommendation=rec,
        formula=formula,
        supporting_evidence=evidence[:8],
        limitations=limitations,
        missing_information=missing,
        requires_human_review=True,
    )


def build_final_report(
    *,
    role_title: str,
    aggregated: AggregatedScores,
    skill_gap: SkillGapAnalysis,
    hiring_fit: HiringFitRecommendation,
    candidate_name: str | None,
    include_answer_feedback: bool,
) -> FinalReport:
    name = candidate_name or "Candidate"
    strengths: list[str] = []
    weaknesses: list[str] = []
    recommendations: list[str] = list(skill_gap.recommended_prep_focus)

    for c in aggregated.category_scores:
        if c.score is None:
            continue
        if c.score >= 0.7:
            strengths.append(f"{c.label} ({c.score:.2f})")
        elif c.score < 0.55:
            weaknesses.append(f"{c.label} ({c.score:.2f})")

    for s in skill_gap.strengths[:5]:
        if s not in strengths:
            strengths.append(f"Skill signal: {s}")
    for g in skill_gap.gaps:
        if g.needs_more_evidence:
            line = f"Insufficient evidence — {g.skill}"
            if line not in weaknesses:
                weaknesses.append(line)
            recommendations.extend(g.improvement_suggestions[:1])
        elif (g.gap or 0) >= 0.3:
            line = f"Gap — {g.skill}"
            if line not in weaknesses:
                weaknesses.append(line)
            recommendations.extend(g.improvement_suggestions[:1])

    for qs in aggregated.question_scores:
        for s in qs.strengths[:1]:
            if s not in strengths and len(strengths) < 8:
                strengths.append(s)
        for w in qs.weaknesses[:1]:
            if w not in weaknesses and len(weaknesses) < 8:
                weaknesses.append(w)
        recommendations.extend(qs.improvement_feedback[:1])

    if not strengths:
        strengths = ["Limited positive evidence captured in this interview"]
    if not weaknesses:
        weaknesses = ["No major weaknesses flagged — verify with human panel"]

    seen: set[str] = set()
    actionable: list[str] = []
    for r in recommendations:
        key = r.strip().lower()
        if key and key not in seen:
            seen.add(key)
            actionable.append(r)
        if len(actionable) >= 8:
            break
    if not actionable:
        actionable = ["Validate depth with a focused technical follow-up panel"]

    overall_txt = (
        f"{aggregated.overall_score:.2f}"
        if aggregated.overall_score is not None
        else "n/a"
    )
    fit_txt = (
        f"{hiring_fit.hiring_fit_score:.2f}"
        if hiring_fit.hiring_fit_score is not None
        else "n/a"
    )
    overview = (
        f"{name} scored {overall_txt} overall across "
        f"{aggregated.question_count} evaluated answer(s) for {role_title}. "
        f"Hiring-fit label: {hiring_fit.hiring_fit_label} (score {fit_txt})."
    )
    if aggregated.fallback:
        overview += f" Overall used fallback={aggregated.fallback}."
    summary = (
        f"{overview} Strengths center on {', '.join(strengths[:3])}. "
        f"Focus areas: {', '.join(weaknesses[:3])}."
    )

    cat_lines = "\n".join(
        (
            f"- **{c.label}**: {c.score:.2f} (weight {c.weight}, "
            f"effective {c.effective_weight})"
            if c.score is not None
            else f"- **{c.label}**: unavailable (configured weight {c.weight})"
        )
        for c in aggregated.category_scores
    )
    gap_lines = "\n".join(
        (
            f"- {g.skill}: demonstrated {g.demonstrated_level}, gap {g.gap} "
            f"({g.priority}, {g.provenance.value})"
            if g.demonstrated_level is not None
            else f"- {g.skill}: insufficient evidence ({g.provenance.value})"
        )
        for g in skill_gap.gaps[:8]
    )
    md = (
        f"# Final Interview Report\n\n"
        f"**Candidate:** {name}\n"
        f"**Role:** {role_title}\n"
        f"**Overall score:** {overall_txt}\n"
        f"**Hiring fit:** {hiring_fit.hiring_fit_label} ({fit_txt})\n\n"
        f"## Performance overview\n{overview}\n\n"
        f"## Category scores\n{cat_lines}\n\n"
        f"## Strengths\n"
        + "\n".join(f"- {s}" for s in strengths)
        + "\n\n## Weaknesses\n"
        + "\n".join(f"- {w}" for w in weaknesses)
        + "\n\n## Recommendations\n"
        + "\n".join(f"- {r}" for r in actionable)
        + f"\n\n## Skill gaps\n{gap_lines or '- None flagged'}\n\n"
        f"## Recommendation\n"
        f"{hiring_fit.recommendation} — {hiring_fit.human_review_note}\n"
    )

    return FinalReport(
        summary=summary,
        performance_overview=overview,
        strengths=strengths[:8],
        weaknesses=weaknesses[:8],
        actionable_recommendations=actionable[:8],
        answer_level_feedback=(
            aggregated.question_scores if include_answer_feedback else []
        ),
        markdown=md,
    )


def _extract_nested_score(blob: dict[str, Any] | None, *keys: str) -> float | None:
    if not isinstance(blob, dict):
        return None
    for key in keys:
        if key in blob:
            return _clamp01(blob[key], default=None)
    for nest in ("overall", "scores", "result", "summary", "dimensions"):
        child = blob.get(nest)
        if isinstance(child, dict):
            for key in keys:
                if key in child:
                    return _clamp01(child[key], default=None)
            if "score" in child:
                return _clamp01(child["score"], default=None)
    if "score" in blob:
        return _clamp01(blob["score"], default=None)
    return None


async def _text_communication_metrics(
    *,
    interview_mode: InterviewMode,
    role_title: str,
    question_scores: list[QuestionScoreItem],
    qa_items: list[QaItemIn],
    media: Any,
    language: str,
    interview_id: str | None,
) -> list[MetricAssessment]:
    """Text clarity/structure/organization/relevance — never A/V delivery."""
    out: list[MetricAssessment] = []
    wanted = (
        ("clarity", "Text clarity"),
        ("structure", "Written structure"),
        ("organization", "Organization"),
        ("relevance", "Relevance"),
    )
    comm = getattr(media, "communication_analysis", None) if media else None
    calculated: dict[str, tuple[float, dict[str, Any]]] = {}

    # Prefer Platform-supplied communication_analysis
    if isinstance(comm, dict):
        for key, _label in wanted:
            # structure may alias organization
            score = _extract_nested_score(comm, key)
            if score is None and key == "structure":
                score = _extract_nested_score(comm, "organization")
            if score is not None:
                calculated[key] = (score, {"source": "media_evidence.communication_analysis"})

    # Text mode (or any mode with answers): use CommunicationAnalysisService
    answers = [
        {"question": q.question, "answer": q.answer}
        for q in qa_items
        if (q.answer or "").strip()
    ]
    if not answers:
        answers = [
            {
                "question": qs.question_text or "",
                "answer": (qs.explanation or ""),
            }
            for qs in question_scores
            if qs.question_text
        ]

    need_calc = [k for k, _ in wanted if k not in calculated]
    if need_calc and answers and interview_mode == InterviewMode.TEXT:
        try:
            from app.schemas.communication_analysis import CommunicationAnalysisRequest
            from app.services.analysis.communication import CommunicationAnalysisService

            resp = await CommunicationAnalysisService().analyze(
                CommunicationAnalysisRequest(
                    interview_id=interview_id,
                    role_title=role_title,
                    answers=answers,
                    include_voice_delivery=False,
                    language=language,
                )
            )
            mapping = {
                "clarity": resp.clarity,
                "organization": resp.organization,
                "relevance": resp.relevance,
                "structure": resp.structure or resp.organization,
            }
            for key in need_calc:
                dim = mapping.get(key)
                if dim is not None and dim.score is not None:
                    calculated[key] = (
                        float(dim.score),
                        {
                            "source": "communication_analysis_service",
                            "evidence": list(dim.evidence or [])[:3],
                        },
                    )
        except Exception as exc:  # noqa: BLE001
            logger.warning("text communication analysis failed: %s", exc)

    # Rubric dimension fallback
    for key, _label in wanted:
        if key in calculated:
            continue
        dim_key = "completeness" if key == "structure" else key
        vals: list[tuple[float, ScoreProvenance]] = []
        for qs in question_scores:
            if dim_key in (qs.dimensions or {}):
                v = _clamp01(qs.dimensions[dim_key], default=None)
                if v is not None:
                    vals.append((v, qs.provenance))
        if vals:
            avg = sum(v for v, _p in vals) / len(vals)
            calculated[key] = (
                round(avg, 3),
                {
                    "source": f"question_dimensions.{dim_key}",
                    "sample_size": len(vals),
                    "provenance": _derive_aggregate_provenance(
                        [p for _v, p in vals]
                    ).value,
                },
            )

    for key, label in wanted:
        if key in calculated:
            score, evid = calculated[key]
            prov = (
                ScoreProvenance.SUPPLIED
                if evid.get("source") == "media_evidence.communication_analysis"
                else ScoreProvenance.CALCULATED
            )
            out.append(
                MetricAssessment(
                    key=f"text_{key}",
                    label=label,
                    score=round(float(score), 3),
                    provenance=prov,
                    detail=str(evid.get("source")),
                    evidence=evid if isinstance(evid, dict) else {},
                )
            )
        else:
            out.append(
                MetricAssessment(
                    key=f"text_{key}",
                    label=label,
                    score=None,
                    provenance=ScoreProvenance.UNAVAILABLE,
                    detail=(
                        "No communication_analysis evidence and no answer text "
                        "to evaluate"
                        if interview_mode == InterviewMode.TEXT
                        else f"Text {key} not available for mode={interview_mode.value}"
                    ),
                )
            )
    return out


def _media_metrics(
    mode: InterviewMode,
    media: Any,
    warnings: list[str],
) -> tuple[MetricAssessment | None, MetricAssessment | None, list[MetricAssessment]]:
    """A/V delivery metrics only — kept separate from text communication."""
    behavioral: MetricAssessment | None = None
    communication: MetricAssessment | None = None
    extras: list[MetricAssessment] = []

    audio = getattr(media, "audio_analysis", None) if media else None
    video = getattr(media, "video_intelligence", None) if media else None
    beh = getattr(media, "behavioral_analysis", None) if media else None
    comm = getattr(media, "communication_analysis", None) if media else None

    if beh:
        score = _extract_nested_score(beh, "behavioral_score", "score", "overall_score")
        behavioral = MetricAssessment(
            key="behavioral",
            label="Behavioral",
            score=score,
            provenance=(
                ScoreProvenance.SUPPLIED if score is not None else ScoreProvenance.UNAVAILABLE
            ),
            detail="From supplied behavioral_analysis evidence"
            if score is not None
            else "behavioral_analysis present but no score field",
            evidence=beh if isinstance(beh, dict) else {},
        )
    else:
        behavioral = MetricAssessment(
            key="behavioral",
            label="Behavioral",
            score=None,
            provenance=ScoreProvenance.UNAVAILABLE,
            detail="No authorized behavioral_analysis evidence supplied",
        )

    # Top-level communication stays text-oriented summary from communication_analysis
    if comm:
        score = _extract_nested_score(
            comm, "communication_score", "clarity", "score", "overall_score"
        )
        communication = MetricAssessment(
            key="communication_text",
            label="Communication (text analysis)",
            score=score,
            provenance=(
                ScoreProvenance.SUPPLIED if score is not None else ScoreProvenance.UNAVAILABLE
            ),
            detail="From supplied communication_analysis (text) — not A/V delivery"
            if score is not None
            else "communication_analysis present but no score field",
            evidence=comm if isinstance(comm, dict) else {},
        )
    else:
        communication = MetricAssessment(
            key="communication_text",
            label="Communication (text analysis)",
            score=None,
            provenance=ScoreProvenance.UNAVAILABLE,
            detail="No authorized communication_analysis evidence supplied",
        )

    def _delivery(audio_blob: Any, *, reason: str) -> MetricAssessment:
        if audio_blob:
            score = _extract_nested_score(
                audio_blob, "delivery_score", "pacing_score", "confidence", "score"
            )
            return MetricAssessment(
                key="voice_delivery",
                label="Voice delivery / pacing",
                score=score,
                provenance=(
                    ScoreProvenance.SUPPLIED
                    if score is not None
                    else ScoreProvenance.UNAVAILABLE
                ),
                detail="From supplied audio_analysis evidence"
                if score is not None
                else "audio_analysis present but no delivery score",
                evidence=audio_blob if isinstance(audio_blob, dict) else {},
            )
        warnings.append(reason)
        return MetricAssessment(
            key="voice_delivery",
            label="Voice delivery / pacing",
            score=None,
            provenance=ScoreProvenance.UNAVAILABLE,
            detail=reason,
        )

    if mode == InterviewMode.VOICE:
        extras.append(
            _delivery(
                audio,
                reason="Voice delivery metrics unavailable — no audio_analysis evidence",
            )
        )
    elif mode == InterviewMode.VIDEO:
        extras.append(
            _delivery(
                audio,
                reason="Video mode: audio delivery requires audio_analysis evidence",
            )
        )
        if video:
            score = _extract_nested_score(
                video, "engagement_score", "presence_score", "score", "overall_score"
            )
            extras.append(
                MetricAssessment(
                    key="video_presence",
                    label="Video presence",
                    score=score,
                    provenance=(
                        ScoreProvenance.SUPPLIED
                        if score is not None
                        else ScoreProvenance.UNAVAILABLE
                    ),
                    detail="From supplied video_intelligence evidence"
                    if score is not None
                    else "video_intelligence present but no score field",
                    evidence=video if isinstance(video, dict) else {},
                )
            )
        else:
            extras.append(
                MetricAssessment(
                    key="video_presence",
                    label="Video presence",
                    score=None,
                    provenance=ScoreProvenance.UNAVAILABLE,
                    detail="Video mode: visual metrics require video_intelligence evidence",
                )
            )
            warnings.append(
                "Video presence metrics unavailable — no video_intelligence evidence"
            )
    else:
        # text mode — A/V delivery explicitly unavailable
        extras.append(
            MetricAssessment(
                key="voice_delivery",
                label="Voice delivery / pacing",
                score=None,
                provenance=ScoreProvenance.UNAVAILABLE,
                detail="Not applicable for text interview_mode",
            )
        )

    return behavioral, communication, extras


def _skill_status(finding: SkillGapFinding) -> SkillStatus:
    if (
        finding.demonstrated_level is None
        or finding.needs_more_evidence
        or finding.provenance == ScoreProvenance.UNAVAILABLE
    ):
        return SkillStatus.NOT_ASSESSED
    req = finding.required_level
    if req is None:
        req = DEFAULT_REQUIRED_SKILL_LEVEL
    if float(finding.demonstrated_level) >= float(req) or (finding.gap or 0) < 0.2:
        return SkillStatus.ASSESSED
    return SkillStatus.NEEDS_IMPROVEMENT


def _short_summary(
    *,
    candidate_name: str | None,
    role_title: str,
    overall: float | None,
    strengths: list[str],
    improvements: list[str],
    rec_label: str,
) -> str:
    name = candidate_name or "Candidate"
    score_txt = f"{overall:.2f}" if overall is not None else "n/a"
    s0 = strengths[0] if strengths else "limited positive evidence"
    i0 = improvements[0] if improvements else "further panel review"
    return (
        f"{name} scored {score_txt} for {role_title}. "
        f"Strength: {s0}. Focus: {i0}. Advisory fit: {rec_label}."
    )


def _essential_warnings(warnings: list[str]) -> list[str]:
    keep: list[str] = []
    for w in warnings:
        low = w.lower()
        if any(
            p in low
            for p in (
                "aggregation policy",
                "missing category",
                "dimension enrichment",
                "evaluation failed",
                "no question-level",
                "audio_analysis",
                "video_intelligence",
                "skill_readiness",
            )
        ):
            keep.append(w)
        if len(keep) >= 5:
            break
    return keep


def _local_ai_explanation(
    question: str,
    *,
    role_title: str,
    required_skills: list[str],
) -> str:
    """Deterministic Review-UI concept guide when LLM is unavailable."""
    q = (question or "").strip()
    if not q:
        return (
            f"For a {role_title} interview, answers should address the ask directly "
            "with clear reasoning and role-relevant evidence."
        )
    skills = ", ".join(required_skills[:4]) if required_skills else "role-critical skills"
    lower = q.lower()
    if any(k in lower for k in ("hook", "react", "state", "component")):
        return (
            "This concept is fundamental to modern React development. "
            "The correct answer names the intended declarative approach and briefly "
            "explains how it keeps component state predictable and maintainable."
        )
    if any(k in lower for k in ("cache", "redis", "ttl", "cdn")):
        return (
            "Strong answers describe a concrete caching strategy for the workload, "
            "including invalidation/TTL trade-offs and how correctness and latency "
            "are validated under load."
        )
    if any(k in lower for k in ("design", "architect", "system", "scale")):
        return (
            "A solid answer outlines requirements, proposes a clear design, "
            "calls out trade-offs and failure modes, and explains how success "
            "would be measured."
        )
    return (
        f"A strong answer for this {role_title} question states the core concept "
        f"clearly, ties it to {skills}, and shows structured reasoning with "
        "enough concrete detail to demonstrate real understanding."
    )


async def _attach_ai_explanations(
    *,
    question_scores: list[QuestionScoreItem],
    role_title: str,
    job_description: str | None,
    required_skills: list[str],
    language: str,
) -> list[QuestionScoreItem]:
    """Add Review-UI ai_explanation (how to answer) — one batched LLM call."""
    pending: list[tuple[int, str, str]] = []
    for idx, qs in enumerate(question_scores):
        if qs.ai_explanation and qs.ai_explanation.strip():
            continue
        qtext = (qs.question_text or "").strip()
        if not qtext:
            continue
        qid = qs.question_id or f"turn-{qs.turn_index}"
        pending.append((idx, qid, qtext))

    if not pending:
        return question_scores

    def local() -> dict:
        return {
            "explanations": [
                {
                    "id": qid,
                    "ai_explanation": _local_ai_explanation(
                        qtext,
                        role_title=role_title,
                        required_skills=required_skills,
                    ),
                }
                for _i, qid, qtext in pending
            ]
        }

    system = (
        "You write short Review-UI 'AI Explanation' blurbs for interview questions. "
        "For each question, explain how it should be answered: the core concept and "
        "the intended approach a strong candidate would take. "
        "1–3 concise sentences. Do NOT score the candidate. Do NOT invent companies, "
        "metrics, or technologies not implied by the question/role. "
        "Return JSON only: {\"explanations\":[{\"id\":string,\"ai_explanation\":string}]}"
    )
    user = (
        f"Role: {role_title}\nLanguage: {language}\n"
        f"JD: {(job_description or 'n/a')[:1200]}\n"
        f"Skills: {required_skills}\n"
        f"Questions: {[ {'id': qid, 'question': qtext} for _i, qid, qtext in pending ]}"
    )
    try:
        data, _stub, _provider = await generate_json(
            system=system, user=user, local_factory=local
        )
    except Exception as exc:  # noqa: BLE001
        logger.warning("ai_explanation generation failed: %s", exc)
        data = local()

    by_id: dict[str, str] = {}
    if isinstance(data, dict):
        for row in data.get("explanations") or []:
            if not isinstance(row, dict):
                continue
            rid = str(row.get("id") or "").strip()
            text = str(row.get("ai_explanation") or "").strip()
            if rid and text:
                by_id[rid] = text[:480]

    out: list[QuestionScoreItem] = []
    for idx, qs in enumerate(question_scores):
        if qs.ai_explanation and qs.ai_explanation.strip():
            out.append(qs)
            continue
        qid = qs.question_id or f"turn-{qs.turn_index}"
        text = by_id.get(qid) or _local_ai_explanation(
            qs.question_text or "",
            role_title=role_title,
            required_skills=required_skills,
        )
        out.append(qs.model_copy(update={"ai_explanation": text}))
    return out


def _build_question_reviews(
    *,
    question_scores: list[QuestionScoreItem],
    qa_items: list[QaItemIn],
) -> list[QuestionReviewBrief]:
    answers_by_qid: dict[str, str] = {}
    answers_by_idx: dict[int, str] = {}
    questions_by_qid: dict[str, str] = {}
    for i, item in enumerate(qa_items):
        idx = item.turn_index if item.turn_index is not None else i
        answers_by_idx[idx] = item.answer or ""
        if item.question_id:
            answers_by_qid[item.question_id] = item.answer or ""
            questions_by_qid[item.question_id] = item.question
    reviews: list[QuestionReviewBrief] = []
    for qs in question_scores:
        answer = None
        if qs.question_id and qs.question_id in answers_by_qid:
            answer = answers_by_qid[qs.question_id]
        elif qs.turn_index in answers_by_idx:
            answer = answers_by_idx[qs.turn_index]
        question = qs.question_text
        if not question and qs.question_id:
            question = questions_by_qid.get(qs.question_id)
        reviews.append(
            QuestionReviewBrief(
                question_id=qs.question_id,
                turn_index=qs.turn_index,
                question=question,
                answer=answer,
                score=qs.score,
                score_band=qs.score_band,
                ai_explanation=qs.ai_explanation,
            )
        )
    return reviews


def _build_skills_brief(skill_gap: SkillGapAnalysis) -> list[SkillAssessmentBrief]:
    out: list[SkillAssessmentBrief] = []
    for g in skill_gap.gaps:
        status = _skill_status(g)
        out.append(
            SkillAssessmentBrief(
                skill=g.skill,
                score=(
                    None
                    if status == SkillStatus.NOT_ASSESSED
                    else g.demonstrated_level
                ),
                status=status,
                required_level=g.required_level,
            )
        )
    return out


class FinalEvaluationService:
    def __init__(self, *, interviews: InterviewsService | None = None) -> None:
        self._interviews = interviews or InterviewsService()

    async def evaluate(
        self, payload: FinalEvaluationRequest
    ) -> FinalEvaluationResponse:
        """Orchestrate media by mode, score, persist; completed only after DB save."""
        from app.schemas.common import JobStatus
        from app.schemas.final_evaluation import RecommendationBrief
        from app.services.interviews import evaluation_store
        from app.services.interviews.evaluation_media import (
            EvaluationMediaError,
            prepare_media_for_evaluation,
        )

        warnings: list[str] = []
        # Optional workflow mode check
        try:
            from app.services.interviews.workflow_store import get_workflow_by_interview_id

            wf = get_workflow_by_interview_id(payload.interview_id)
            if wf is not None and (wf.mode or "").lower() not in {
                "",
                payload.interview_mode.value,
                "ai",
            }:
                warnings.append(
                    f"Workflow mode={wf.mode!r} differs from request "
                    f"interview_mode={payload.interview_mode.value!r}; using request mode"
                )
        except Exception:  # noqa: BLE001
            logger.debug("workflow mode lookup skipped", exc_info=True)

        row = evaluation_store.begin_processing(
            candidate_id=payload.candidate_id,
            interview_id=payload.interview_id,
            interview_mode=payload.interview_mode.value,
            role_title=payload.role_title,
            company_name=payload.company_name,
        )
        evaluation_id = row.evaluation_id
        evaluation_version = int(row.evaluation_version or 1)

        try:
            if payload.interview_mode.value == "voice":
                evaluation_store.update_stage(
                    evaluation_id, processing_stage="transcribing"
                )
            elif payload.interview_mode.value == "video":
                evaluation_store.update_stage(
                    evaluation_id, processing_stage="video_analyzing"
                )

            prep = await prepare_media_for_evaluation(payload)
            warnings.extend(prep.warnings)
            evaluation_store.update_stage(
                evaluation_id,
                processing_stage="evaluating",
                transcription_refs=prep.transcription_refs,
                video_analysis_refs=prep.video_analysis_refs,
            )
            work = payload.model_copy(
                update={
                    "qa_items": prep.qa_items,
                    "media_evidence": prep.media_evidence,
                }
            )
            result = await self._evaluate_core(work)
            for w in warnings:
                if w not in result.warnings:
                    result.warnings.append(w)

            question_evaluations = [
                q.model_dump(mode="json") for q in (result.questions or [])
            ]
            competency_scores = [
                c.model_dump(mode="json") for c in (result.categories or [])
            ]
            rec = (
                result.recommendation.model_dump(mode="json")
                if result.recommendation
                else {}
            )
            payload_snap = result.model_dump(mode="json")
            try:
                saved = evaluation_store.mark_completed(
                    evaluation_id,
                    overall_score=result.overall_score,
                    competency_scores=competency_scores,
                    question_evaluations=question_evaluations,
                    strengths=list(result.strengths or []),
                    improvement_areas=list(result.improvement_areas or []),
                    evaluation_summary=result.summary or "",
                    final_recommendation=rec,
                    result_payload=payload_snap,
                    transcription_refs=prep.transcription_refs,
                    video_analysis_refs=prep.video_analysis_refs,
                )
            except Exception as exc:  # noqa: BLE001
                evaluation_store.mark_failed(
                    evaluation_id,
                    error_code="persist_failed",
                    error_message=str(exc),
                    processing_stage="saving",
                )
                return FinalEvaluationResponse(
                    correlation_id=payload.correlation_id,
                    interview_id=payload.interview_id,
                    interview_mode=payload.interview_mode,
                    candidate_id=payload.candidate_id,
                    candidate_name=payload.candidate_name,
                    company_name=payload.company_name,
                    role_title=payload.role_title,
                    evaluation_id=evaluation_id,
                    evaluation_status="failed",
                    evaluation_version=evaluation_version,
                    processing_stage="saving",
                    error_code="persist_failed",
                    summary="Evaluation scoring succeeded but failed to save results",
                    recommendation=RecommendationBrief(
                        label="review_required",
                        action="hold",
                        reason="Persist failed — re-run evaluation",
                    ),
                    warnings=list(result.warnings) + [str(exc)],
                    status=JobStatus.FAILED,
                    stub=False,
                    message="Evaluation not completed — save failed",
                )

            result.evaluation_id = saved.evaluation_id if saved else evaluation_id
            result.evaluation_status = "completed"
            result.evaluation_version = (
                int(saved.evaluation_version) if saved else evaluation_version
            )
            result.processing_stage = "completed"
            result.company_name = payload.company_name
            result.message = (
                "Final evaluation completed and saved — "
                "hiring recommendation requires human review"
            )
            return result

        except EvaluationMediaError as exc:
            evaluation_store.mark_failed(
                evaluation_id,
                error_code=exc.code,
                error_message=str(exc),
                processing_stage="media_failed",
            )
            return FinalEvaluationResponse(
                correlation_id=payload.correlation_id,
                interview_id=payload.interview_id,
                interview_mode=payload.interview_mode,
                candidate_id=payload.candidate_id,
                candidate_name=payload.candidate_name,
                company_name=payload.company_name,
                role_title=payload.role_title,
                evaluation_id=evaluation_id,
                evaluation_status="failed",
                evaluation_version=evaluation_version,
                processing_stage="media_failed",
                error_code=exc.code,
                summary=f"Evaluation failed during media processing: {exc}",
                recommendation=RecommendationBrief(
                    label="review_required",
                    action="hold",
                    reason=str(exc),
                ),
                warnings=warnings + [str(exc)],
                status=JobStatus.FAILED,
                stub=False,
                message=str(exc),
            )
        except Exception as exc:  # noqa: BLE001
            logger.exception("final_evaluation failed")
            evaluation_store.mark_failed(
                evaluation_id,
                error_code="evaluation_failed",
                error_message=str(exc),
                processing_stage="evaluating",
            )
            return FinalEvaluationResponse(
                correlation_id=payload.correlation_id,
                interview_id=payload.interview_id,
                interview_mode=payload.interview_mode,
                candidate_id=payload.candidate_id,
                candidate_name=payload.candidate_name,
                company_name=payload.company_name,
                role_title=payload.role_title,
                evaluation_id=evaluation_id,
                evaluation_status="failed",
                evaluation_version=evaluation_version,
                processing_stage="evaluating",
                error_code="evaluation_failed",
                summary=f"Evaluation failed: {exc}",
                recommendation=RecommendationBrief(
                    label="review_required",
                    action="hold",
                    reason=str(exc),
                ),
                warnings=warnings + [str(exc)],
                status=JobStatus.FAILED,
                stub=False,
                message=str(exc),
            )

    async def _evaluate_core(
        self, payload: FinalEvaluationRequest
    ) -> FinalEvaluationResponse:
        warnings: list[str] = []
        degraded = False
        logger.info(
            "final_evaluation mode=%s interview_id=%s qa=%s supplied_scores=%s",
            payload.interview_mode.value,
            payload.interview_id,
            len(payload.qa_items),
            len(payload.turn_scores),
        )

        by_key: dict[str, TurnScoreIn] = {}
        for ts in payload.turn_scores:
            if ts.provenance not in {
                ScoreProvenance.SUPPLIED,
                ScoreProvenance.CALCULATED,
            }:
                warnings.append(
                    f"Ignored turn score with provenance={ts.provenance.value}"
                )
                continue
            if not (0.0 <= ts.score <= 1.0):
                warnings.append("Ignored out-of-range turn score")
                continue
            key = _score_key(ts.question_id, ts.turn_index)
            if key is None:
                warnings.append("Ignored turn score without question_id or turn_index")
                continue
            if key in by_key:
                warnings.append(f"Duplicate turn score key {key} — keeping first")
                continue
            by_key[key] = ts

        qa_items = list(payload.qa_items)
        if not qa_items and payload.transcript:
            questions = [
                t for t in payload.transcript if (t.role or "").lower() == "interviewer"
            ]
            answers = [
                t for t in payload.transcript if (t.role or "").lower() == "candidate"
            ]
            for i, q in enumerate(questions):
                ans = answers[i].text if i < len(answers) else ""
                qa_items.append(
                    QaItemIn(
                        question_id=f"t-{i + 1}",
                        question=q.text or f"Question {i + 1}",
                        answer=ans,
                        turn_index=i,
                    )
                )
            if qa_items:
                warnings.append("Q&A derived from transcript turns")

        question_scores: list[QuestionScoreItem] = []
        used_supplied_keys: set[str] = set()

        weights_for_enrich = (
            set(w.key.strip() for w in payload.category_weights if w.key.strip())
            if payload.category_weights
            else set()
        )

        for i, item in enumerate(qa_items):
            supplied = _match_supplied(item, i, by_key)
            if supplied is not None:
                key = _score_key(supplied.question_id, supplied.turn_index) or _score_key(
                    item.question_id,
                    item.turn_index if item.turn_index is not None else i,
                )
                if key:
                    used_supplied_keys.add(key)
                    for alt in (
                        _score_key(item.question_id, None),
                        _score_key(
                            None,
                            item.turn_index if item.turn_index is not None else i,
                        ),
                    ):
                        if alt:
                            used_supplied_keys.add(alt)

                dims = dict(supplied.dimensions or {})
                enriched_keys: list[str] = []
                # Enrich only when Platform sent no dimensions at all.
                # Partial supplied dimensions are trusted as-is (missing cats → unavailable).
                # Never replace the trusted total score.
                need_enrich = not dims
                if need_enrich and (item.answer or "").strip():
                    try:
                        eval_resp = await self._interviews.evaluate_answer(
                            EvaluateAnswerRequest(
                                interview_id=payload.interview_id,
                                interview_mode=payload.interview_mode,
                                persona=Persona.TECHNICAL,
                                role_title=payload.role_title,
                                job_description=payload.job_description,
                                question=item.question,
                                candidate_answer=item.answer,
                                skills_focus=list(payload.required_skills),
                                language=payload.language,
                                options=dict(payload.options or {}),
                            )
                        )
                        for d in eval_resp.dimensions or []:
                            if d.key and d.key not in dims:
                                dims[d.key] = float(d.score)
                                enriched_keys.append(d.key)
                        if eval_resp.stub:
                            degraded = True
                    except Exception as exc:  # noqa: BLE001
                        warnings.append(
                            f"Dimension enrichment failed for "
                            f"{item.question_id or i}: {exc}"
                        )

                skill_tags = list(item.skill_tags or []) or list(
                    supplied.skill_tags or []
                )
                skill_tags = _merge_skill_tags(
                    skill_tags,
                    question=item.question,
                    required_skills=list(payload.required_skills or []),
                    skill_targets=list(payload.skill_targets or []),
                )

                question_scores.append(
                    QuestionScoreItem(
                        question_id=item.question_id or supplied.question_id,
                        question_text=item.question,
                        turn_index=item.turn_index if item.turn_index is not None else i,
                        score=supplied.score,
                        score_band=_resolve_score_band(
                            supplied.score, supplied.score_band
                        ),
                        dimensions=dims,
                        enriched_dimension_keys=enriched_keys,
                        category_keys=list(item.category_keys or []),
                        skill_tags=skill_tags,
                        strengths=list(supplied.strengths)[:5],
                        weaknesses=list(supplied.weaknesses)[:5],
                        improvement_feedback=list(supplied.improvement_feedback)[:5],
                        explanation=supplied.explanation,
                        provenance=ScoreProvenance.SUPPLIED,
                    )
                )
                continue

            try:
                eval_resp = await self._interviews.evaluate_answer(
                    EvaluateAnswerRequest(
                        interview_id=payload.interview_id,
                        interview_mode=payload.interview_mode,
                        persona=Persona.TECHNICAL,
                        role_title=payload.role_title,
                        job_description=payload.job_description,
                        question=item.question,
                        candidate_answer=item.answer,
                        skills_focus=list(payload.required_skills),
                        language=payload.language,
                        options=dict(payload.options or {}),
                    )
                )
                dims = {
                    d.key: float(d.score)
                    for d in (eval_resp.dimensions or [])
                    if d.key
                }
                skill_tags = _merge_skill_tags(
                    list(item.skill_tags or []),
                    question=item.question,
                    required_skills=list(payload.required_skills or []),
                    skill_targets=list(payload.skill_targets or []),
                )
                calc_band = (
                    eval_resp.score_band.value if eval_resp.score_band else None
                )
                question_scores.append(
                    QuestionScoreItem(
                        question_id=item.question_id,
                        question_text=item.question,
                        turn_index=item.turn_index if item.turn_index is not None else i,
                        score=eval_resp.score,
                        score_band=_resolve_score_band(eval_resp.score, calc_band),
                        dimensions=dims,
                        category_keys=list(item.category_keys or []),
                        skill_tags=skill_tags,
                        strengths=list(eval_resp.strengths or [])[:5],
                        weaknesses=list(eval_resp.weaknesses or [])[:5],
                        improvement_feedback=list(
                            eval_resp.improvement_feedback or []
                        )[:5],
                        explanation=eval_resp.explanation or eval_resp.feedback,
                        provenance=ScoreProvenance.CALCULATED,
                    )
                )
                if eval_resp.stub:
                    degraded = True
            except Exception as exc:  # noqa: BLE001
                logger.warning("evaluate_answer in final-eval failed: %s", exc)
                degraded = True
                warnings.append(f"Turn {i} evaluation failed; score unavailable: {exc}")
                question_scores.append(
                    QuestionScoreItem(
                        question_id=item.question_id,
                        question_text=item.question,
                        turn_index=item.turn_index if item.turn_index is not None else i,
                        score=None,
                        category_keys=list(item.category_keys or []),
                        skill_tags=list(item.skill_tags or []),
                        provenance=ScoreProvenance.UNAVAILABLE,
                        explanation=f"Evaluation failed: {exc}",
                    )
                )

        for key, ts in by_key.items():
            if key in used_supplied_keys:
                continue
            # Skip if qid already represented
            if ts.question_id and any(
                q.question_id == ts.question_id for q in question_scores
            ):
                continue
            idx = ts.turn_index if ts.turn_index is not None else len(question_scores)
            question_scores.append(
                QuestionScoreItem(
                    question_id=ts.question_id,
                    question_text=None,
                    turn_index=idx,
                    score=ts.score,
                    score_band=_resolve_score_band(ts.score, ts.score_band),
                    dimensions=dict(ts.dimensions),
                    strengths=list(ts.strengths)[:5],
                    weaknesses=list(ts.weaknesses)[:5],
                    improvement_feedback=list(ts.improvement_feedback)[:5],
                    explanation=ts.explanation,
                    provenance=ScoreProvenance.SUPPLIED,
                )
            )

        if not question_scores:
            warnings.append("No question-level scores available")
            degraded = True

        # Review-UI concept guides (how each question should be answered)
        question_scores = await _attach_ai_explanations(
            question_scores=question_scores,
            role_title=payload.role_title,
            job_description=payload.job_description,
            required_skills=list(payload.required_skills or []),
            language=payload.language,
        )
        question_reviews = _build_question_reviews(
            question_scores=question_scores,
            qa_items=qa_items,
        )

        weights = _resolve_weights(payload.category_weights)
        aggregated = aggregate_categories(question_scores, weights)
        if aggregated.fallback:
            warnings.append(
                f"Overall aggregation policy={aggregated.fallback}"
            )
        if aggregated.missing_categories:
            warnings.append(
                "Missing category evidence (excluded from weighted overall): "
                + ", ".join(aggregated.missing_categories)
            )

        skill_gap = analyze_skill_gaps(
            skill_targets=list(payload.skill_targets or []),
            required_skills=list(payload.required_skills or []),
            question_scores=question_scores,
        )
        hiring_fit = hiring_fit_local(
            overall_score=aggregated.overall_score,
            skill_gap=skill_gap,
            question_count=aggregated.question_count,
            category_scores=aggregated.category_scores,
        )
        want_details = bool(payload.include_details) or bool(
            (payload.options or {}).get("include_details")
        )
        include_answers = bool(payload.include_answer_feedback) or want_details

        report = build_final_report(
            role_title=payload.role_title,
            aggregated=aggregated,
            skill_gap=skill_gap,
            hiring_fit=hiring_fit,
            candidate_name=payload.candidate_name or payload.candidate_id,
            include_answer_feedback=include_answers,
        )
        # Skip markdown in default concise path
        if not want_details:
            report = report.model_copy(update={"markdown": None, "answer_level_feedback": []})

        if want_details:
            try:
                enriched, stub, provider = await generate_json(
                    system=(
                        "You refine an interview final report. Return JSON: "
                        "{\"summary\",\"performance_overview\",\"strengths\":[],"
                        "\"weaknesses\":[],\"actionable_recommendations\":[]}. "
                        "Do not invent facts not supported by the provided "
                        "scores/evidence. Keep hiring decisions for humans."
                    ),
                    user=(
                        f"Mode: {payload.interview_mode.value}\n"
                        f"Role: {payload.role_title}\n"
                        f"Overall: {aggregated.overall_score}\n"
                        f"Fallback: {aggregated.fallback}\n"
                        f"Categories: {[c.model_dump() for c in aggregated.category_scores]}\n"
                        f"Draft summary: {report.summary}\n"
                        f"Strengths: {report.strengths}\nWeaknesses: {report.weaknesses}\n"
                        f"Recommendations: {report.actionable_recommendations}\n"
                        f"Skill gaps: {[g.model_dump() for g in skill_gap.gaps[:6]]}\n"
                        f"Hiring fit: {hiring_fit.model_dump()}"
                    ),
                    local_factory=lambda: {
                        "summary": report.summary,
                        "performance_overview": report.performance_overview,
                        "strengths": report.strengths,
                        "weaknesses": report.weaknesses,
                        "actionable_recommendations": report.actionable_recommendations,
                    },
                )
                if stub:
                    degraded = True
                    warnings.append(f"Report narrative used fallback: {provider}")
                if isinstance(enriched, dict):
                    report = report.model_copy(
                        update={
                            "summary": str(enriched.get("summary") or report.summary),
                            "performance_overview": str(
                                enriched.get("performance_overview")
                                or report.performance_overview
                            ),
                            "strengths": list(
                                enriched.get("strengths") or report.strengths
                            )[:8],
                            "weaknesses": list(
                                enriched.get("weaknesses") or report.weaknesses
                            )[:8],
                            "actionable_recommendations": list(
                                enriched.get("actionable_recommendations")
                                or report.actionable_recommendations
                            )[:8],
                        }
                    )
            except Exception as exc:  # noqa: BLE001
                logger.warning("final report enrichment failed: %s", exc)
                degraded = True
                warnings.append(f"Report enrichment failed; local report used: {exc}")

        behavioral: MetricAssessment | None = None
        communication: MetricAssessment | None = None
        media_metrics: list[MetricAssessment] = []
        text_communication: list[MetricAssessment] = []
        if want_details:
            behavioral, communication, media_metrics = _media_metrics(
                payload.interview_mode, payload.media_evidence, warnings
            )
            text_communication = await _text_communication_metrics(
                interview_mode=payload.interview_mode,
                role_title=payload.role_title,
                question_scores=question_scores,
                qa_items=qa_items,
                media=payload.media_evidence,
                language=payload.language,
                interview_id=payload.interview_id,
            )

        if payload.candidate_id and aggregated.overall_score is not None:
            try:
                from app.services.talent.performance import CandidatePerformanceService

                source_type = str(
                    (payload.options or {}).get("performance_source_type")
                    or "recruiter_interview"
                )
                company_id = (payload.options or {}).get("company_id")
                if isinstance(company_id, str):
                    company_id = company_id.strip() or None
                else:
                    company_id = None
                CandidatePerformanceService().record_from_final_evaluation(
                    candidate_id=payload.candidate_id,
                    company_id=company_id,
                    interview_id=payload.interview_id or "stateless",
                    role_title=payload.role_title,
                    overall_01=aggregated.overall_score,
                    category_scores=[
                        c.model_dump()
                        for c in aggregated.category_scores
                        if c.score is not None
                    ],
                    strengths=list(report.strengths or []),
                    growth_areas=list(report.weaknesses or []),
                    verified_skills=list(skill_gap.strengths or [])[:20],
                    hiring_fit_label=hiring_fit.hiring_fit_label,
                    hiring_fit_score_01=hiring_fit.hiring_fit_score or 0.0,
                    source_type=source_type
                    if source_type
                    in {
                        "mock_interview",
                        "recruiter_interview",
                        "candidate_scoring",
                        "ingest",
                    }
                    else "recruiter_interview",
                    meta={
                        "skill_gap_readiness": skill_gap.overall_readiness,
                        "question_count": aggregated.question_count,
                        "interview_mode": payload.interview_mode.value,
                        "overall_provenance": aggregated.overall_provenance.value,
                    },
                )
            except Exception:  # noqa: BLE001
                logger.exception(
                    "candidate performance persist skipped for interview=%s",
                    payload.interview_id,
                )

        strengths = [
            s
            for s in (report.strengths or [])
            if not s.lower().startswith("insufficient evidence")
        ][:3]
        improvements = [
            w
            for w in (report.weaknesses or [])
            if not w.lower().startswith("insufficient evidence")
        ][:3]
        # not_assessed skills are never listed as improvement weaknesses
        skills_brief = _build_skills_brief(skill_gap)
        categories_brief = [
            CategoryScoreBrief(key=c.key, label=c.label, score=c.score)
            for c in aggregated.category_scores
        ]
        reason_bits = list(hiring_fit.supporting_evidence or [])[:2]
        if not reason_bits:
            reason_bits = [hiring_fit.human_review_note]
        recommendation = RecommendationBrief(
            label=hiring_fit.hiring_fit_label,
            action=hiring_fit.recommendation,
            reason="; ".join(reason_bits),
            score=hiring_fit.hiring_fit_score,
            requires_human_review=True,
        )
        summary = _short_summary(
            candidate_name=payload.candidate_name or payload.candidate_id,
            role_title=payload.role_title,
            overall=aggregated.overall_score,
            strengths=strengths,
            improvements=improvements,
            rec_label=hiring_fit.hiring_fit_label,
        )

        details: FinalEvaluationDetails | None = None
        if want_details:
            details = FinalEvaluationDetails(
                max_score=aggregated.max_score,
                overall_provenance=aggregated.overall_provenance,
                aggregation_fallback=aggregated.fallback,
                aggregated=aggregated,
                report=report,
                skill_gap=skill_gap,
                hiring_fit=hiring_fit,
                behavioral=behavioral,
                communication=communication,
                text_communication=text_communication,
                media_metrics=media_metrics,
                degraded=degraded,
            )

        return FinalEvaluationResponse(
            correlation_id=payload.correlation_id,
            interview_id=payload.interview_id,
            interview_mode=payload.interview_mode,
            candidate_id=payload.candidate_id,
            candidate_name=payload.candidate_name,
            role_title=payload.role_title,
            question_count=aggregated.question_count,
            overall_score=aggregated.overall_score,
            summary=summary,
            strengths=strengths,
            improvement_areas=improvements,
            skills=skills_brief,
            categories=categories_brief,
            questions=question_reviews,
            recommendation=recommendation,
            warnings=_essential_warnings(warnings),
            details=details,
            status=JobStatus.SUCCEEDED,
            stub=degraded,
            message=(
                "Final evaluation completed — hiring recommendation requires human review"
            ),
        )
