jue-flash / jue_flash /api /derive.py
Jue1Dev's picture
Jue-Flash: fast open-weight calibrated decision model for cybersecurity
fb34cd2
Raw History Blame Contribute Delete
4.18 kB
"""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__}")