"""Derive wire answers from a question's probability vector (Jev semantics).""" from __future__ import annotations import math from collections.abc import Sequence from typing import Final from jue_flash.api.schema import ( Answer, ChoiceAnswer, ChoiceQuestion, NoulAnswer, NoulQuestion, Question, ScoreAnswer, ScoreQuestion, option_keys, ) PROB_TOL: Final = 1e-4 def _clip01(x: float) -> float: return min(1.0, max(0.0, x)) def _checked(p: Sequence[float]) -> list[float]: values = [float(x) for x in p] if not values: raise ValueError("empty probability vector") non_finite = [(i, x) for i, x in enumerate(values) if not math.isfinite(x)] if non_finite: raise ValueError(f"non-finite probabilities (index, value): {non_finite}") out_of_range = [(i, x) for i, x in enumerate(values) if x < -PROB_TOL or x > 1.0 + PROB_TOL] if out_of_range: raise ValueError(f"probabilities outside [0, 1] beyond tolerance {PROB_TOL} (index, value): {out_of_range}") total = math.fsum(values) if abs(total - 1.0) > PROB_TOL: raise ValueError(f"probabilities sum to {total!r}, expected 1 within {PROB_TOL}") return [_clip01(x) for x in values] def choice_confidence(p: Sequence[float]) -> float: """``clip((K·p_max − 1)/(K − 1), 0, 1)``; 1 when K = 1.""" q = _checked(p) k = len(q) if k == 1: return 1.0 return _clip01((k * max(q) - 1.0) / (k - 1)) def score_expectation(p: Sequence[float]) -> float: """``Σ i·p_i`` with levels numbered from 0.""" q = _checked(p) return math.fsum(i * x for i, x in enumerate(q)) def score_confidence(p: Sequence[float]) -> float: """``clip(1 − Σ p_i·|i − mode| / U_K, 0, 1)`` with ``U_K = Σ_i |i − (K−1)/2| / K``.""" q = _checked(p) k = len(q) if k == 1: return 1.0 mode = max(range(k), key=q.__getitem__) spread = math.fsum(x * abs(i - mode) for i, x in enumerate(q)) centre = (k - 1) / 2 uniform_spread = math.fsum(abs(i - centre) for i in range(k)) / k return _clip01(1.0 - spread / uniform_spread) def build_answer(question: Question, probs: Sequence[float]) -> Answer: """Build the wire answer; ``probs`` is ordered like :func:`jue_flash.api.schema.option_keys`.""" keys = option_keys(question) if len(probs) != len(keys): raise ValueError(f"got {len(probs)} probabilities for {len(keys)} options {keys}") q = _checked(probs) probabilities = dict(zip(keys, q, strict=True)) if isinstance(question, NoulQuestion): return NoulAnswer(type="noul", noul=probabilities["true"]) if isinstance(question, ChoiceQuestion): best = max(range(len(q)), key=q.__getitem__) return ChoiceAnswer( type="choice", choice=keys[best], probabilities=probabilities, confidence=choice_confidence(q), ) if isinstance(question, ScoreQuestion): return ScoreAnswer( type="score", score=score_expectation(q), legend={str(level): entry for level, entry in enumerate(question.criteria)}, probabilities=probabilities, confidence=score_confidence(q), ) raise TypeError(f"not a question model: {type(question).__name__}") def round_probs(answer: Answer, digits: int) -> Answer: if digits < 0: raise ValueError(f"digits must be >= 0, got {digits}") if isinstance(answer, NoulAnswer): return answer.model_copy(update={"noul": round(answer.noul, digits)}) rounded = {key: round(p, digits) for key, p in answer.probabilities.items()} if isinstance(answer, ChoiceAnswer): return answer.model_copy(update={"probabilities": rounded, "confidence": round(answer.confidence, digits)}) if isinstance(answer, ScoreAnswer): return answer.model_copy( update={ "score": round(answer.score, digits), "probabilities": rounded, "confidence": round(answer.confidence, digits), } ) raise TypeError(f"not an answer model: {type(answer).__name__}")