pratikgx's picture
Add unofficial MLX port of Cloudflare Clairic and Clairic-flash (code only, no weights)
b729e44 verified
Raw History Blame Contribute Delete
14.1 kB
"""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