Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

docs(calibrate): the calibration payload's contract must name binning_map and every shape it refuses

Aashish6d804082d072
diff --git a/laya/agent.py b/laya/agent.py
index 7714f1fc..dad3de1f 100644
--- a/laya/agent.py
+++ b/laya/agent.py
@@ -1995,7 +1995,8 @@ class Agent(HookRegistry):
return self.binning_map
def save_calibration(self, path: str) -> None:
- """Write temperatures and the checkpoint they were fitted for. Does not write weights."""
+ """Write `temperature`, `temperature_by_options`, `binning_map` when the agent has one, and
+ the checkpoint they were fitted for. Does not write weights."""
payload = calibration_payload(
self.temperature,
self.temperature_by_options,
@@ -2029,10 +2030,17 @@ class Agent(HookRegistry):
def load_calibration(self, path: str) -> None:
"""Read a JSON map written by `save_calibration` onto this agent.
+ The file carries three fields and all three are installed: `temperature`,
+ `temperature_by_options` and `binning_map`. A file with no `binning_map` key installs
+ `None`, so loading one clears a map this agent's `fit_binning` fitted -- the file is the
+ whole calibration state, not a patch onto the current one.
+
A file with no `version` is treated as version 1 and still loads. A newer file
whose recorded checkpoint does not match this agent warns and still loads.
- Values that are not numbers, or that sit outside `[TEMP_MIN, TEMP_MAX]`, are clamped
- with `clamp_temperature` the same way checkpoint load is.
+ Temperatures that are not numbers, or that sit outside `[TEMP_MIN, TEMP_MAX]`, are
+ clamped with `clamp_temperature` the same way checkpoint load is; binning values are
+ not clamped, they are refused with a `ValueError` naming the field, because an
+ out-of-range binning value would move a confidence with nothing to fall back to.
"""
with open(path) as f:
payload = json.load(f)
diff --git a/laya/calibrate.py b/laya/calibrate.py
index d7582ece..e5a5497f 100644
--- a/laya/calibrate.py
+++ b/laya/calibrate.py
@@ -521,7 +521,10 @@ def calibration_payload(
`temperature_by_options` (those live at the top of this payload).
`binning_map` is the optional histogram-binning recalibration map fitted by
- `fit_binning_map`; the key is omitted when no map is installed.
+ `fit_binning_map`; the key is omitted when no map is installed, which is `None`, not an empty
+ map. A map that fitted nothing -- `{}`, the return value when no bucket reached the sample
+ floor -- is still written, so the round trip through :func:`apply_calibration_payload` gives
+ `{}` back rather than `None`.
"""
payload = {
"version": CALIBRATION_VERSION,
@@ -602,22 +605,36 @@ def _install_temperatures(obj, temperature, temperature_by_options, warn: bool =
def apply_calibration_payload(obj, payload: Dict[str, Any]) -> None:
- """Copy `temperature` and `temperature_by_options` from a calibration payload onto `obj`.
+ """Copy `temperature`, `temperature_by_options` and `binning_map` onto `obj`.
+
+ Those are the three fields this reads and the three it writes. `binning_map` is installed
+ whatever the payload holds, including nothing: a payload with no ``binning_map`` key -- every
+ file written before histogram binning existed, and every agent that saved before
+ :meth:`Agent.fit_binning` ran -- installs `None`, which clears a map this object already
+ fitted. The file is the whole calibration state, not a patch onto the current one.
A missing `version` is version 1 (temperatures only, no checkpoint identity). Version
`CALIBRATION_VERSION` records the checkpoint the map was fitted for; a mismatch warns
- and still loads, so an older file never becomes a hard failure. Each value is passed
+ and still loads, so an older file never becomes a hard failure. Each temperature is passed
through `clamp_temperature`, so a non-numeric or out-of-range entry cannot crash a later
forward the way an unclamped zero used to.
- The payload's *shape* is checked before any of that, and refused with a `ValueError`
- naming the field: the values may be junk the clamp forgives, but a temperature that is
- not a list of three, a version that is not an integer, or a bucket map that is not an
- object is a file this code cannot read -- JSON gives `int`, `str`, `list` and `dict`
- for the three mistakes below just as happily as it gives the right shapes, and each
- used to fail with a raw `TypeError`/`AttributeError` from `len()`/`dict()`, or worse,
- to load: a `{"a": 1, "b": 2, "c": 3}` or `"abc"` has `len` 3 and used to pass the
- length check and install its *keys* as temperatures.
+ `temperature` and `binning_map` take opposite value policies, and that is the sentence to read
+ before writing a file by hand: a bad *temperature* is forgiven and clamped into
+ `[TEMP_MIN, TEMP_MAX]`, while a bad *binning value* is refused. Nothing recalibrates a
+ confidence the way an out-of-range binning value would, so there is no defensible fallback
+ for it.
+
+ The payload's *shape* is checked before any of that, and refused with a `ValueError` naming
+ the field: the values may be junk the clamp forgives, but the payload itself not being an
+ object, a `version` that is not an integer, a `temperature` that is not a list of three, a
+ `temperature_by_options` that is not an object, a `binning_map` that is not an object, or a
+ `binning_map` entry that is not an object with an integer `bins` >= 1 and `values` of exactly
+ that length holding finite numbers in [0, 1] is a file this code cannot read -- JSON gives
+ `int`, `str`, `list` and `dict` for each of those mistakes just as happily as it gives the
+ right shapes, and each used to fail with a raw `TypeError`/`AttributeError` from
+ `len()`/`dict()`, or worse, to load: a `{"a": 1, "b": 2, "c": 3}` or `"abc"` has `len` 3 and
+ used to pass the length check and install its *keys* as temperatures.
"""
if not isinstance(payload, dict):
raise ValueError("calibration JSON must be an object, got %s" % type(payload).__name__)
diff --git a/laya/onnx_agent.py b/laya/onnx_agent.py
index 34c94194..09d56425 100644
--- a/laya/onnx_agent.py
+++ b/laya/onnx_agent.py
@@ -222,7 +222,13 @@ class ONNXAgent(HookRegistry):
self.load_calibration(calibration)
def load_calibration(self, path: str) -> None:
- """Read a JSON map written by `save_calibration` onto this agent."""
+ """Read a JSON map written by `Agent.save_calibration` onto this agent.
+
+ The file carries three fields and all three are installed: `temperature`,
+ `temperature_by_options` and `binning_map`. A file with no `binning_map` key installs
+ `None`. Temperatures outside `[TEMP_MIN, TEMP_MAX]` are clamped on the way in; binning
+ values are refused with a `ValueError` naming the field rather than clamped.
+ """
from .calibrate import apply_calibration_payload
with open(path) as f:
payload = json.load(f)