"""Turn Clairic head tensors into typed answers. Logits are converted to NumPy before any reduction that the reference runs in float64 (estimate CDFs). Nothing here allocates a float64 MLX array. """ from __future__ import annotations import calendar import datetime import math from decimal import ROUND_HALF_UP, Decimal from typing import Any import numpy as np from clairic_mlx import constants as C from clairic_mlx.schema_util import ( allowed_decimals, date_granularity, duration_unit, estimate_range, estimate_step, estimate_value, from_unit, is_date_estimate, null_threshold, snap, snap_quantile, ) def _softmax(logits: np.ndarray) -> np.ndarray: shifted = logits.astype(np.float64) - np.max(logits, axis=-1, keepdims=True) exp = np.exp(shifted) return exp / exp.sum(axis=-1, keepdims=True) def _log_softmax(logits: np.ndarray) -> np.ndarray: values = logits.astype(np.float64) shifted = values - np.max(values, axis=-1, keepdims=True) return shifted - np.log(np.exp(shifted).sum(axis=-1, keepdims=True)) def number_parts(logits: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]: sign = logits[..., :2] exponent = logits[..., 2 : 2 + C.EXPONENT_CLASSES] digits = logits[..., 2 + C.EXPONENT_CLASSES :].reshape(logits.shape[:-1] + (C.NUMBER_DIGITS, 10)) return sign, exponent, digits def decode_number(logits: np.ndarray, spec: dict[str, Any]) -> tuple[float | int, float]: sign_logits, exponent_logits, digit_logits = number_parts(np.asarray(logits, dtype=np.float32).reshape(-1)) exponent_log = _log_softmax(exponent_logits[None])[0] exponent_class = int(np.argmax(exponent_log)) log_probability = float(exponent_log[exponent_class]) if exponent_class == 0: return 0, math.exp(log_probability) power = exponent_class - 1 + C.MIN_EXPONENT decimals = allowed_decimals(spec) kept = C.NUMBER_DIGITS if decimals is None else power + decimals + 1 if kept < 0: return 0, math.exp(log_probability) digit_log = _log_softmax(digit_logits) digit_log[0, 0] = C.MASKED digits = np.argmax(digit_log, axis=-1).tolist() sign_log = _log_softmax(sign_logits[None])[0] sign = int(np.argmax(sign_log)) kept = min(kept, C.NUMBER_DIGITS) log_probability += float(sign_log[sign]) log_probability += sum(float(digit_log[position, digits[position]]) for position in range(kept)) if kept < C.NUMBER_DIGITS: rounding = digit_log[kept, 5:] if digits[kept] >= 5 else digit_log[kept, :5] log_probability += float(np.log(np.exp(rounding - rounding.max()).sum()) + rounding.max()) magnitude = Decimal(int("".join(str(digit) for digit in digits))).scaleb(power - C.NUMBER_DIGITS + 1) if decimals is not None: magnitude = magnitude.quantize(Decimal(1).scaleb(-decimals), rounding=ROUND_HALF_UP) if magnitude == 0: return 0, math.exp(log_probability) value = -magnitude if sign else magnitude if decimals == 0 or (value == value.to_integral_value() and abs(value) < 2**53): return int(value), math.exp(log_probability) return float(value), math.exp(log_probability) def date_parts(logits: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: flat = np.asarray(logits, dtype=np.float32).reshape(-1) digits = flat[: C.YEAR_DIGITS * 10].reshape(C.YEAR_DIGITS, 10) cursor = C.YEAR_DIGITS * 10 year = flat[cursor : cursor + C.YEAR_CLASSES] cursor += C.YEAR_CLASSES month = flat[cursor : cursor + 12] day = flat[cursor + 12 : cursor + 12 + 31] return digits, year, month, day def decode_date(logits: np.ndarray) -> tuple[str, float]: digit_logits, year_logits, month_logits, day_logits = date_parts(logits) class_log = _log_softmax(year_logits[None])[0] year_class = int(np.argmax(class_log)) log_probability = float(class_log[year_class]) if year_class < C.YEAR_OUTSIDE: year = C.YEAR_LOW + year_class else: digit_log = _log_softmax(digit_logits) digits = np.argmax(digit_log, axis=-1).tolist() if digits == [0, 0, 0, 0]: masked = digit_log[3].copy() masked[0] = C.MASKED digits[3] = int(np.argmax(masked)) year = int("".join(str(digit) for digit in digits)) log_probability += float(sum(digit_log[position, digit] for position, digit in enumerate(digits))) month_log = _log_softmax(month_logits[None])[0] day_log = _log_softmax(day_logits[None])[0] joint = month_log[:, None] + day_log[None, :] lengths = np.array([calendar.monthrange(year, month)[1] for month in range(1, 13)]) joint = np.where(np.arange(31)[None, :] >= lengths[:, None], C.MASKED, joint) best = int(np.argmax(joint)) month, day = divmod(best, 31) log_probability += float(joint.reshape(-1)[best]) return datetime.date(year, month + 1, day + 1).isoformat(), math.exp(log_probability) def decode_time(logits: np.ndarray) -> tuple[str, float]: flat = np.asarray(logits, dtype=np.float32).reshape(-1) parts = [flat[:24], flat[24:84], flat[84:144]] logs = [_log_softmax(part[None])[0] for part in parts] values = [int(np.argmax(part)) for part in logs] confidence = math.exp(sum(float(part[value]) for part, value in zip(logs, values))) return f"{values[0]:02d}:{values[1]:02d}:{values[2]:02d}", confidence def edge_number(value: float) -> tuple[int, int, list[int], float]: if value == 0 or not math.isfinite(value): return C.EDGE_ZERO, 1, [0] * C.LEXICAL_DIGITS, 0.0 mantissa, exponent = f"{abs(value):.{C.LEXICAL_DIGITS + 8}e}".split("e") power, digits = int(exponent), mantissa.replace(".", "") sign = C.EDGE_NEGATIVE if value < 0 else C.EDGE_POSITIVE if power < C.MIN_EXPONENT: return sign, 1, [0] * C.LEXICAL_DIGITS, 0.0 if power > C.MAX_EXPONENT: return sign, C.EXPONENT_CLASSES - 1, [9] * C.LEXICAL_DIGITS, 1.0 return ( sign, power - C.MIN_EXPONENT + 1, [int(digit) for digit in digits[: C.LEXICAL_DIGITS]], float("0." + digits[C.LEXICAL_DIGITS :]), ) def lexical_bin_log_probs( number_logits: np.ndarray, edge_sign: np.ndarray, edge_class: np.ndarray, edge_digits: np.ndarray, edge_frac: np.ndarray, ) -> np.ndarray: """Float64 mixture used by the reference. The result is returned as float32.""" sign, exponent, digits = number_parts(np.asarray(number_logits, dtype=np.float64)) sign_probs = _softmax(sign) exponent_probs = _softmax(exponent) zero = exponent_probs[:, :1] nonzero = exponent_probs[:, 1:] / np.maximum(1.0 - zero, 1e-300) below_class = np.cumsum(nonzero, axis=-1) - nonzero leading = digits[:, :1].copy() leading[:, :, 0] = -np.inf digit_probs = _softmax(np.concatenate([leading, digits[:, 1 : C.LEXICAL_DIGITS]], axis=1)) below_digit = np.cumsum(digit_probs, axis=-1) - digit_probs classes = np.clip(edge_class - 1, 0, nonzero.shape[1] - 1).astype(np.int64) within = np.asarray(edge_frac, dtype=np.float64) for position in reversed(range(C.LEXICAL_DIGITS)): index = edge_digits[..., position].astype(np.int64) within = np.take_along_axis(below_digit[:, position], index, axis=1) + np.take_along_axis( digit_probs[:, position], index, axis=1 ) * within magnitude = np.take_along_axis(below_class, classes, axis=1) + np.take_along_axis(nonzero, classes, axis=1) * within negative = sign_probs[:, 1:] * (1.0 - zero) positive = sign_probs[:, :1] * (1.0 - zero) cdf = np.where( edge_sign == C.EDGE_NEGATIVE, negative * (1.0 - magnitude), np.where(edge_sign == C.EDGE_ZERO, np.broadcast_to(negative, magnitude.shape), negative + zero + positive * magnitude), ) mass = np.maximum(cdf[:, 1:] - cdf[:, :-1], 0.0) + 1e-30 logged = np.log(mass) - np.log(mass.sum(axis=-1, keepdims=True)) return logged.astype(np.float32) def mixed_estimate_logits(output: dict[str, np.ndarray], row: int, spec: dict[str, Any]) -> np.ndarray: logits = np.asarray(output["estimate"][row], dtype=np.float32) if "estimate_number" not in output or "estimate_gate" not in output: return logits if is_date_estimate(spec) and date_granularity(spec) != "year": return logits low, high, scale = estimate_range(spec) bins = logits.shape[-1] parts = [edge_number(from_unit(index / bins, low, high, scale)) for index in range(bins + 1)] sign = np.array([[part[0] for part in parts]]) classes = np.array([[part[1] for part in parts]]) digits = np.array([[digit for part in parts for digit in part[2]]]).reshape(1, bins + 1, C.LEXICAL_DIGITS) fractions = np.array([[part[3] for part in parts]], dtype=np.float64) lexical = lexical_bin_log_probs( np.asarray(output["estimate_number"][row], dtype=np.float32)[None], sign, classes, digits, fractions, )[0] gate = float(np.asarray(output["estimate_gate"][row], dtype=np.float32)) range_part = _log_softmax(logits[None])[0].astype(np.float32) mixed = np.logaddexp(math.log(1 / (1 + math.exp(-gate))) + lexical, math.log(1 / (1 + math.exp(gate))) + range_part) return mixed.astype(np.float32) def decode_estimate( logits: np.ndarray, offsets: np.ndarray, overflow: np.ndarray, spec: dict[str, Any], include_quantiles: bool, ) -> dict[str, Any]: probabilities = _softmax(np.asarray(logits, dtype=np.float32).reshape(1, -1))[0].astype(np.float64) cdf = np.cumsum(probabilities) bins = probabilities.shape[0] shift = 1.0 / (1.0 + np.exp(-np.asarray(offsets, dtype=np.float64).reshape(-1))) low, high, scale = estimate_range(spec) centers = (np.arange(bins) + shift) / bins mean = float(sum(probability * from_unit(float(center), low, high, scale) for probability, center in zip(probabilities, centers))) raw_mean = float(sum(probability * center for probability, center in zip(probabilities, centers))) value = from_unit(raw_mean, low, high, scale) if scale == "log" else mean def quantile(fraction: float) -> float: index = int(min(np.searchsorted(cdf, fraction, side="left"), bins - 1)) previous = float(cdf[index - 1]) if index else 0.0 inside = (fraction - previous) / probabilities[index] if probabilities[index] > 0 else 0.5 return (index + min(1.0, max(0.0, inside))) / bins step = estimate_step(spec) points = [from_unit(quantile(fraction / 100.0), low, high, scale) for fraction in range(1, 100)] if step > 0: points = [snap_quantile(point, step, low, high) for point in points] value = snap(mean, step, low, high) if is_date_estimate(spec): value = estimate_value(spec, value) mean_value = estimate_value(spec, mean) points = [estimate_value(spec, point) for point in points] else: mean_value = mean prediction: dict[str, Any] = { "value": value, "mean": mean_value, "median": points[49], "p10": points[9], "p90": points[89], } if include_quantiles: prediction["quantiles"] = points if not is_date_estimate(spec): sides = _softmax(np.concatenate([np.zeros(1, dtype=np.float32), np.asarray(overflow, dtype=np.float32).reshape(-1)])) prediction["p_below"] = float(sides[1]) prediction["p_above"] = float(sides[2]) return prediction def sigmoid(values: np.ndarray) -> np.ndarray: values = np.asarray(values, dtype=np.float64) return 1.0 / (1.0 + np.exp(-values)) def decode_fields( output: dict[str, np.ndarray], fields: list[tuple[str, str, dict[str, Any]]], include_quantiles: bool, ) -> dict[str, dict[str, Any]]: """fields is (name, kind, spec) in head order.""" p_null = sigmoid(np.asarray(output["null"], dtype=np.float32)).tolist() rows: dict[str, list[int]] = {name: [] for name in ("text", "number", "date", "time", "estimate")} for position, (_, kind, _) in enumerate(fields): if kind in ("date", "datetime"): rows["date"].append(position) if kind in ("time", "datetime"): rows["time"].append(position) if kind in ("number", "estimate", "text"): rows[kind].append(position) index = {group: {position: row for row, position in enumerate(group_rows)} for group, group_rows in rows.items()} predictions: dict[str, dict[str, Any]] = {} for position, (name, kind, spec) in enumerate(fields): if kind == "estimate": row = index["estimate"][position] predictions[name] = decode_estimate( mixed_estimate_logits(output, row, spec), output["estimate_offset"][row], output["estimate_overflow"][row], spec, include_quantiles, ) continue if kind in ("number_list", "date_list", "text", "text_list"): continue prediction: dict[str, Any] = {"p_null": float(p_null[position])} if kind == "number": value, confidence = decode_number(output["number"][index["number"][position]], spec) if spec["type"] == "duration": prediction["unit"] = duration_unit(spec) elif kind == "date": value, confidence = decode_date(output["date"][index["date"][position]]) elif kind == "time": value, confidence = decode_time(output["time"][index["time"][position]]) else: day, day_confidence = decode_date(output["date"][index["date"][position]]) clock, clock_confidence = decode_time(output["time"][index["time"][position]]) value, confidence = f"{day}T{clock}", day_confidence * clock_confidence prediction["guess"] = value prediction["confidence"] = confidence prediction["value"] = None if p_null[position] >= null_threshold(spec) else value predictions[name] = prediction return predictions