# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. """A LightGBM regression booster as numbers the box can carry and evaluate without LightGBM (docs/methods.md B9). Standard library only; one file for the cloud (building/) and the box (edge/cantabile_edge/lgbtrees.py, a copy: building/test_boxmodel.py checks they are the same). pack(dump) takes LightGBM's dump_model() (one tree per round, numerical splits only, objective regression: no output transform) and gives {"enc": "lgbm-trees-v1", "n": trees, "data": base64(zlib(trees))}; per tree, little-endian: uint16 the number of leaves L; L-1 internal nodes of (uint8 feature, uint8 decision: bit 1 default left, bits 2-3 the missing type 0 none / 1 zero / 2 NaN, int16 left, int16 right: >= 0 an internal node, < 0 the leaf ~child, float64 threshold); L float64 leaf values. Nodes by LightGBM's split_index, leaves by its leaf_index. Doubles as they are. Trees(enc, n_features).predict(rows) sums the leaves in LightGBM's order with its decision rule (tree.h NumericalDecision), so it gives LightGBM's raw score to the last bit (measured 2026-11-04: max relative difference 0.0 over 192 slots). lgbm-trees-v2 (2026-11-04, methods.md B10), written only for a booster that needs it (a categorical split or linear leaves; else v1, which older agents read): per tree uint16 L, uint8 flags (bit 0: linear leaves); the L-1 nodes as v1, decision bit 0 set for a categorical split, whose threshold is then the index of its category set; uint16 the number of sets, each uint8 n and n uint16 categories (those going left); the L leaf values; with linear leaves per leaf float64 constant, uint8 n and n (uint8 feature, float64 coefficient). Categorical rule (tree.h CategoricalDecision): NaN or a negative value right, else left if the integer is in the set. A linear leaf: constant plus the coefficients times the values in LightGBM's order; a NaN among them: the leaf's value.""" from __future__ import annotations import base64 import math import struct import zlib ENCODING = "lgbm-trees-v1" ENCODING_V2 = "lgbm-trees-v2" NODE = struct.Struct(" int: return int(n["split_index"]) if "split_index" in n else ~int(n.get("leaf_index", 0)) def _walk(root: dict) -> tuple[dict[int, dict], dict[int, dict]]: nodes: dict[int, dict] = {} leaves: dict[int, dict] = {} stack = [root] while stack: n = stack.pop() if "split_index" in n: if n.get("decision_type", "<=") not in ("<=", "=="): raise ValueError(f"a split {n.get('decision_type')!r}: not supported") nodes[int(n["split_index"])] = n stack += [n["left_child"], n["right_child"]] else: leaves[int(n.get("leaf_index", 0))] = n k = len(leaves) if sorted(nodes) != list(range(k - 1)) or sorted(leaves) != list(range(k)): raise ValueError("a tree's node or leaf indices are not contiguous") return nodes, leaves def _needs_v2(dump: dict) -> bool: for t in dump["tree_info"]: nodes, leaves = _walk(t["tree_structure"]) if any(n.get("decision_type") == "==" for n in nodes.values()) or any("leaf_coeff" in x for x in leaves.values()): return True return False def pack_tree(root: dict, v2: bool = False) -> bytes: """One tree (dump_model()'s tree_info[i]["tree_structure"]).""" if "split_index" not in root and not v2: # no split: one leaf return struct.pack(" 255 or any(not 0 <= x < 65536 for x in c): raise ValueError("a categorical split: at most 255 categories below 65536") out.append(struct.pack(f" 255: raise ValueError("a linear leaf") out.append(struct.pack(" dict: """A booster's dump_model() as lgbm-trees-v1, or v2 where it has categorical splits or linear leaves.""" if dump.get("num_class", 1) != 1 or dump.get("num_tree_per_iteration", 1) != 1: raise ValueError("one tree per round only") obj = str(dump.get("objective") or "").split(" ")[0] if obj != "regression": raise ValueError(f"objective {obj!r}: regression only (no output transform)") v2 = _needs_v2(dump) raw = b"".join(pack_tree(t["tree_structure"], v2) for t in dump["tree_info"]) return {"enc": ENCODING_V2 if v2 else ENCODING, "n": len(dump["tree_info"]), "data": base64.b64encode(zlib.compress(raw, 9)).decode()} class Trees: """lgbm-trees-v1, checked (ValueError): every child a later node or a leaf (no loops), features in range, finite leaves.""" def __init__(self, enc: dict, n_features: int): if not isinstance(enc, dict) or enc.get("enc") not in (ENCODING, ENCODING_V2): raise ValueError(f"trees: {ENCODING} or {ENCODING_V2} only") v2 = enc["enc"] == ENCODING_V2 z = zlib.decompressobj() try: raw = z.decompress(base64.b64decode(str(enc.get("data")), validate=True), MAX_RAW) except zlib.error as e: raise ValueError(f"trees: {e}") from None if z.unconsumed_tail: raise ValueError("trees: too large") if not z.eof: raise ValueError("trees: truncated") self.trees = [] off = 0 try: while off < len(raw): (k,) = struct.unpack_from("= n_features or (dec & 1 and not v2) or (dec >> 2) & 3 > 2 or math.isnan(threshold): raise ValueError("trees: a split") nodes.append([f, threshold, bool(dec & 2), (dec >> 2) & 3, left, right, bool(dec & 1)]) if v2: (ncat,) = struct.unpack_from("= n_features or not math.isfinite(c): raise ValueError("trees: a linear leaf") terms.append((f, c)) if not math.isfinite(const): raise ValueError("trees: a linear leaf") lin.append((const, terms)) self.trees.append((nodes, leaves, lin)) if len(self.trees) > MAX_TREES: raise ValueError("trees: too many") except struct.error as e: raise ValueError(f"trees: truncated ({e})") from None if len(self.trees) != int(enc.get("n", -1)): raise ValueError("trees: count") def predict_row(self, x) -> float: """LightGBM's raw score for one row: per tree, a split goes left where the value is <= its threshold; a NaN counts 0 unless the split knows NaN; the split's missing values (zero or NaN, by its type) go its default way; the leaves summed in order.""" total = 0.0 for nodes, leaves, lin in self.trees: i = 0 if nodes else ~0 while i >= 0: f, threshold, default_left, missing, left, right, cat = nodes[i] v = x[f] if cat: i = right if v != v or v < 0 or int(v) not in threshold else left continue if v != v and missing != 2: v = 0.0 if (missing == 1 and -ZERO <= v <= ZERO) or (missing == 2 and v != v): i = left if default_left else right else: i = left if v <= threshold else right if lin is None: total += leaves[~i] continue out = lin[~i][0] for f, c in lin[~i][1]: v = x[f] if v != v: out = leaves[~i] break out += c * v total += out return total def predict(self, rows) -> list[float]: """Rows: a list of lists or a 2-D numpy array (as Booster.predict).""" rows = rows.tolist() if hasattr(rows, "tolist") else rows return [self.predict_row([float(v) for v in r]) for r in rows]