morphtree 2.1.0__py3-none-win_amd64.whl

morphtree/booster.py

@@ -0,0 +1,252 @@
+"""One native scalar boosting loop for binary logloss and squared error."""
+from __future__ import annotations
+
+from array import array
+import math
+import random
+
+from .backend import PythonBackend
+from .data import Binner
+from .config import AlgorithmGenome, validate_task_genome
+from .metrics import logloss, sigmoid, rmse, multiclass_metrics
+from .tree import HistogramTree
+
+
+class TrainingCache:
+    """One fit-call cache. Never shared with other datasets or a full-data refit."""
+    def __init__(self, X_train, X_search, backend):
+        self.X_train, self.X_search, self.backend = X_train, X_search, backend
+        self.entries = {}
+
+    def get(self, genome, params):
+        key = (genome.binning_policy, params.max_bins)
+        if key not in self.entries:
+            binner = Binner(params.max_bins, genome.binning_policy).fit(self.X_train)
+            self.entries[key] = (binner, self.backend.bin(binner, self.X_train), self.backend.bin(binner, self.X_search))
+        return self.entries[key]
+
+
+class BinaryHistogramBooster:
+    """Historical private name retained; regression uses this same tree/fit loop."""
+    def __init__(self, genome, params, seed=42, backend=None, *, memory_enabled=True, collect_diagnostics=False,
+                 objective='binary_logloss', n_classes=None):
+        if objective not in ('binary_logloss', 'squared_error', 'softmax', 'ovr'):
+            raise ValueError('Unsupported boosting objective')
+        validate_task_genome('binary' if objective=='binary_logloss' else 'regression' if objective=='squared_error' else 'multiclass',genome)
+        if objective != 'binary_logloss' and (memory_enabled or collect_diagnostics):
+            raise ValueError('New tasks support fixed Base without memory or discovery')
+        if objective in ('softmax', 'ovr') and (type(n_classes) is not int or n_classes < 2):
+            raise ValueError('Multiclass requires an integer class dimension of at least two')
+        self.n_classes = n_classes
+        self.objective = objective
+        self.memory_enabled = memory_enabled
+        self.collect_diagnostics = collect_diagnostics
+        self.genome, self.params, self.seed = genome, params, seed
+        self.backend = backend or PythonBackend()
+        self.binner = None
+        self.trees, self.steps = [], []
+        self.base_score = 0.0
+        self.n_features_ = 0
+        self.memory_ = None
+        self.search_curve_ = []
+        self.stopped_early_ = False
+
+    def fit(self, X, y, *, eval_set=None, callback=None, cache=None, early_stopping_rounds=0, prepared_data=None):
+        if prepared_data is not None and (cache is not None or eval_set is not None):
+            raise ValueError('Prepared training data cannot be mixed with another cache/evaluation scope')
+        if self.n_classes is not None:
+            return self._fit_multiclass(X, y, eval_set, callback, early_stopping_rounds, prepared_data)
+        self.n_features_ = len(X[0])
+        if self.objective == 'squared_error':
+            self.base_score = y[0] if all(v == y[0] for v in y) else math.fsum(v / len(y) for v in y)
+        else:
+            prior = min(1 - 1e-12, max(1e-12, sum(y) / len(y)))
+            self.base_score = math.log(prior / (1 - prior))
+        if prepared_data is not None:
+            self.binner, Xb = prepared_data.get(X, self.genome, self.params, self.backend)
+            eval_bins = None
+        elif cache is not None:
+            if cache.X_train is not X or eval_set is None or cache.X_search is not eval_set[0]:
+                raise ValueError('Training cache belongs to different input objects')
+            self.binner, Xb, eval_bins = cache.get(self.genome, self.params)
+        else:
+            self.binner = Binner(self.params.max_bins, self.genome.binning_policy).fit(X)
+            Xb = self.backend.bin(self.binner, X)
+            eval_bins = self.backend.bin(self.binner, eval_set[0]) if eval_set else None
+        sizes = [len(c) + 2 for c in self.binner.thresholds]
+        rng = random.Random(self.seed)
+        raw = [self.base_score] * len(y)
+        eval_raw = [self.base_score] * len(eval_set[1]) if eval_set else None
+        needs_memory = (self.memory_enabled or self.collect_diagnostics or self.genome.error_policy != "none"
+                        or self.genome.sample_policy != "uniform" or self.genome.leaf_policy == "uncertainty"
+                        or "UNCERTAINTY_GAIN" in self.genome.split_program)
+        if needs_memory:
+            from .diagnostics import ErrorMemory
+            self.memory_ = ErrorMemory(len(y), self.params.error_memory_beta)
+        else:
+            self.memory_ = None
+        no_uncertainty = array("d", [0.0]) * len(y)
+        self.trees, self.steps, self.search_curve_ = [], [], []
+        self.stopped_early_ = False
+        sample_count = self.params.row_sample_count(len(y))
+        best_loss, best_count, stale = math.inf, 0, 0
+        for iteration in range(self.params.n_estimators):
+            p, gradient, hessian = (self.backend.regression_gradients(raw, y) if self.objective == 'squared_error'
+                                    else self.backend.gradients(raw, y))
+            if needs_memory:
+                if not self.memory_enabled:
+                    self.memory_ = ErrorMemory(len(y), self.params.error_memory_beta)
+                self.memory_.update(y, p)
+            residual = array("d", (label - probability for label, probability in zip(y, p)))
+            uncertainty = self.memory_.uncertainty if needs_memory else no_uncertainty
+            if self.genome.error_policy == "persistent_weighting":
+                for i, hardness in enumerate(self.memory_.hardness):
+                    weight = 1 + self.params.error_weight * hardness
+                    gradient[i] *= weight
+                    hessian[i] *= weight
+            ids = None
+            if sample_count < len(y):
+                count = sample_count
+                if self.genome.sample_policy == "uniform":
+                    ids = sorted(rng.sample(range(len(y)), count))
+                else:
+                    weights = self.memory_.hardness if self.genome.sample_policy == "hardness" else self.memory_.uncertainty
+                    keys = [(-math.log(max(rng.random(), 1e-15)) / max(w, 1e-6), i) for i, w in enumerate(weights)]
+                    ids = sorted(i for _, i in sorted(keys)[:count])
+            tree = HistogramTree(self.genome, self.params, self.backend).fit(Xb, gradient, hessian, residual, uncertainty,
+                                                                                 rng, indices=ids, sizes=sizes)
+            step = self.params.learning_rate
+            if self.genome.update_policy == "decay":
+                step /= 1 + self.params.update_decay * iteration / max(self.params.n_estimators - 1, 1)
+            raw = self.backend.add_update(raw, step, tree.predict_binned(Xb))
+            self.trees.append(tree)
+            self.steps.append(step)
+            loss = None
+            if eval_set:
+                eval_raw = self.backend.add_update(eval_raw, step, tree.predict_binned(eval_bins))
+                loss = (rmse(eval_set[1], eval_raw) if self.objective == 'squared_error'
+                        else logloss(eval_set[1], self.backend.probabilities(eval_raw)))
+                self.search_curve_.append(loss)
+                if loss < best_loss - (0.0 if self.objective == 'squared_error' else 1e-12):
+                    best_loss, best_count, stale = loss, len(self.trees), 0
+                else:
+                    stale += 1
+            if callback is not None and callback(iteration + 1, loss) is False:
+                self.stopped_early_ = True
+                break
+            if early_stopping_rounds and eval_set and stale >= early_stopping_rounds:
+                self.stopped_early_ = True
+                break
+        if early_stopping_rounds and best_count and best_count < len(self.trees):
+            self.trees = self.trees[:best_count]
+            self.steps = self.steps[:best_count]
+            # Rebuild memory so it describes the retained ensemble, not discarded trees.
+            raw = [self.base_score] * len(y)
+            if needs_memory:
+                self.memory_ = ErrorMemory(len(y), self.params.error_memory_beta)
+            for tree, step in zip(self.trees, self.steps):
+                if needs_memory:
+                    self.memory_.update(y, self.backend.probabilities(raw))
+                raw = self.backend.add_update(raw, step, tree.predict_binned(Xb))
+        if needs_memory:
+            self.memory_.update(y, self.backend.probabilities(raw))
+        if any(not math.isfinite(float(v)) for v in raw):
+            raise ArithmeticError("Training produced nonfinite predictions")
+        return self
+
+    def _fit_multiclass(self, X, y, eval_set, callback, early_stopping_rounds, prepared_data=None):
+        """K scalar trees per round; one binner/tree builder and O(n*K) scores.
+
+        Derivatives of every class use the same frozen round probabilities.
+        OvR optimizes K binary losses; only its output is simplex-normalized.
+        """
+        k = self.n_classes
+        self.n_features_ = len(X[0])
+        counts = [0]*k
+        for label in y:
+            counts[label] += 1
+        priors = [min(1-1e-12, max(1e-12, count/len(y))) for count in counts]
+        self.base_score = [math.log(p) if self.objective == 'softmax' else math.log(p/(1-p)) for p in priors]
+        if self.objective == 'softmax':
+            self.backend.center_multiclass([self.base_score])
+        if prepared_data is None:
+            self.binner = Binner(self.params.max_bins, self.genome.binning_policy).fit(X)
+            bins = self.backend.bin(self.binner, X)
+        else:
+            self.binner, bins = prepared_data.get(X, self.genome, self.params, self.backend)
+        eval_bins = self.backend.bin(self.binner, eval_set[0]) if eval_set else None
+        sizes = [len(c)+2 for c in self.binner.thresholds]
+        raw = self.backend.multiclass_raw(self.base_score, len(y))
+        eval_raw = self.backend.multiclass_raw(self.base_score, len(eval_set[1])) if eval_set else None
+        rng = random.Random(self.seed)
+        zeros = array('d', [0.])*len(y)
+        self.trees, self.steps, self.search_curve_ = [], [], []
+        self.stopped_early_ = False
+        best, best_count, stale = math.inf, 0, 0
+        count = self.params.row_sample_count(len(y))
+        for iteration in range(self.params.n_estimators):
+            probabilities = self.backend.multiclass_probabilities(raw, self.objective, normalize=False)
+            for column in range(k):
+                if callback is not None and callback(iteration, None) is False:
+                    # A partial round must never become a fitted/serialized model.
+                    raise RuntimeError('Multiclass fit interrupted during a round')
+                gradient, hessian = self.backend.multiclass_gradient_column(probabilities, y, column, self.objective)
+                residual = array('d', (-v for v in gradient))
+                ids = sorted(rng.sample(range(len(y)), count)) if count < len(y) else None
+                tree = HistogramTree(self.genome, self.params, self.backend).fit(
+                    bins, gradient, hessian, residual, zeros, rng, indices=ids, sizes=sizes)
+                step = self.params.learning_rate
+                self.backend.multiclass_update(raw, column, step, tree.predict_binned(bins))
+                if eval_set:
+                    self.backend.multiclass_update(eval_raw, column, step, tree.predict_binned(eval_bins))
+                self.trees.append(tree)
+                self.steps.append(step)
+            if self.objective == 'softmax':
+                self.backend.center_multiclass(raw)
+                if eval_set:
+                    self.backend.center_multiclass(eval_raw)
+            loss = None
+            if eval_set:
+                loss = multiclass_metrics(eval_set[1], self.backend.multiclass_probabilities(eval_raw, self.objective))['logloss']
+                self.search_curve_.append(loss)
+                if loss < best:
+                    best, best_count, stale = loss, len(self.trees), 0
+                else:
+                    stale += 1
+            if callback is not None and callback(iteration+1, loss) is False:
+                self.stopped_early_ = True
+                break
+            if early_stopping_rounds and eval_set and stale >= early_stopping_rounds:
+                self.stopped_early_ = True
+                break
+        if early_stopping_rounds and best_count:
+            self.trees, self.steps = self.trees[:best_count], self.steps[:best_count]
+        if any(not math.isfinite(float(v)) for row in raw for v in row):
+            raise ArithmeticError('Multiclass training produced nonfinite scores')
+        return self
+
+    def predict_raw(self, X):
+        if self.binner is None:
+            raise RuntimeError("Booster is not fitted")
+        Xb = self.backend.bin(self.binner, X)
+        if self.n_classes is not None:
+            raw = self.backend.multiclass_raw(self.base_score, len(X))
+            for index, (tree, step) in enumerate(zip(self.trees, self.steps)):
+                column = index % self.n_classes
+                self.backend.multiclass_update(raw, column, step, tree.predict_binned(Xb))
+                if column == self.n_classes-1 and self.objective == 'softmax':
+                    self.backend.center_multiclass(raw)
+            return raw
+        raw = [self.base_score] * len(X)
+        for tree, step in zip(self.trees, self.steps):
+            raw = self.backend.add_update(raw, step, tree.predict_binned(Xb))
+        return raw
+
+    def predict_proba(self, X):
+        if self.n_classes is not None:
+            return self.backend.multiclass_probabilities(self.predict_raw(X), self.objective)
+        return self.backend.probabilities(self.predict_raw(X))
+
+    def to_dict(self):
+        return {"base_score": self.base_score, "n_features": self.n_features_, "binner": self.binner.to_dict(),
+                "steps": self.steps, "trees": [tree.to_dict() for tree in self.trees]}

morphtree/cli.py

@@ -0,0 +1,52 @@
+"""Inspect, predict and export saved public MorphTree models (no training)."""
+import argparse,json
+from pathlib import Path
+from . import load_model
+from .persistence import regular_file_size,read_regular_bytes,decode_json_bytes,LoadLimits
+
+
+class _NamedRows:
+    """JSON rows with column names for both supported model generations."""
+    def __init__(self,rows,names):
+        self.rows=rows;self.columns=tuple(names);self.shape=(len(rows),len(names))
+    def __len__(self):return len(self.rows)
+    def to_numpy(self):return self.rows
+    def itertuples(self,index=False,name=None):return iter(self.rows)
+    @property
+    def iloc(self):return self
+    def __getitem__(self,key):
+        class Column:
+            def __init__(self,values):self.array=values
+        return Column([row[key[1]] for row in self.rows[key[0]]])
+
+def main(argv=None):
+    p=argparse.ArgumentParser(description=__doc__)
+    p.add_argument('command',choices=('inspect','predict','export'))
+    p.add_argument('--model',required=True);p.add_argument('--sha256')
+    p.add_argument('--input');p.add_argument('--output')
+    a=p.parse_args(argv)
+    try:
+        m=load_model(a.model,sha256=a.sha256)
+        if a.command=='inspect':v={'program':m.get_algorithm_program(),'recipe':m.get_recipe(),'history':m.get_mutation_history()}
+        elif a.command=='export':
+            if not a.output:raise ValueError('--output required')
+            m.export_standalone(a.output);v={'standalone':a.output,'new_fits':0}
+        else:
+            if not a.input:raise ValueError('--input required')
+            f=Path(a.input)
+            from .scalable import managed_resources
+            from .resource_plan import io_seconds
+            size=regular_file_size(f);res=managed_resources('auto',io_seconds(size))
+            if size<1:raise ValueError('Nonempty regular JSON input required')
+            res.reserve(size*12+4096,'CLI JSON input workspace')
+            raw=read_regular_bytes(f,max(1,res.bytes_limit//12))
+            positional=raw.lstrip().startswith(b'[')
+            if positional:raw=b'{"rows":'+raw+b'}'
+            v=decode_json_bytes(raw,LoadLimits(max_bytes=max(1,res.bytes_limit//12)+9),reserve=res.reserve)
+            if positional:v=v['rows']
+            x=_NamedRows(v['rows'],v['columns']) if type(v) is dict and set(v)=={'columns','rows'} else v
+            v={'prediction':m.predict(x).tolist()}
+            if m.task_!='regression':v['probabilities']=m.predict_proba(x).tolist()
+        print(json.dumps(v,ensure_ascii=False,allow_nan=False));return 0
+    except (ValueError,TypeError,OSError,RuntimeError,ImportError,MemoryError) as e:p.exit(2,type(e).__name__+': '+str(e)+'\n')
+if __name__=='__main__':raise SystemExit(main())

morphtree/config.py

@@ -0,0 +1,262 @@
+"""Immutable structural genes, numerical parameters and protocol settings."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, replace
+import hashlib
+import json
+import math
+from numbers import Real
+
+VERSION = "0.6.0.dev0"
+SPEC_VERSION = 1
+POLICIES = {
+    "growth_policy": ("leafwise", "depthwise", "lookahead"),
+    "binning_policy": ("quantile", "uniform"),
+    "missing_policy": ("learned", "left", "right"),
+    "leaf_policy": ("newton", "smoothed", "clipped", "uncertainty"),
+    "regularization_policy": ("global", "depth_scaled"),
+    "sample_policy": ("uniform", "hardness", "uncertainty"),
+    "error_policy": ("none", "persistent_weighting"),
+    "local_policy": ("none", "low_support", "missing_heavy"),
+    "update_policy": ("constant", "decay"),
+}
+SIGNALS = ("OBJECTIVE_GAIN", "RESIDUAL_VARIANCE_GAIN", "BALANCE", "HESSIAN_BALANCE", "UNCERTAINTY_GAIN")
+
+
+def checked_number(name, value, low=0.0, high=None, *, strict=False):
+    """Validate the actual float used by the runtime, not a wider external scalar."""
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise ValueError(f"{name} must be a finite real number")
+    try:
+        value = float(value)
+    except (OverflowError, TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be representable as a finite Python float") from exc
+    if not math.isfinite(value):
+        raise ValueError(f"{name} must be a finite number")
+    if value < low or (strict and value == low) or (high is not None and value > high):
+        raise ValueError(f"{name} is outside its permitted range")
+    return value
+
+
+def _set_number(instance, name, low=0.0, high=None, *, strict=False):
+    value = checked_number(name, getattr(instance, name), low, high, strict=strict)
+    object.__setattr__(instance, name, value)
+
+
+def checked_int(name, value, low, high):
+    if type(value) is not int or not low <= value <= high:
+        raise ValueError(f"{name} must be an integer in [{low}, {high}]")
+
+
+def canonical_hash(data):
+    text = json.dumps(data, sort_keys=True, separators=(",", ":"), allow_nan=False)
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def validate_program(program):
+    if not isinstance(program, (list, tuple)) or not 1 <= len(program) <= 15:
+        raise ValueError("A split program needs 1..15 instructions")
+    depth = 0
+    for token in program:
+        if not isinstance(token, str):
+            raise ValueError("Program instructions must be strings")
+        if token in SIGNALS:
+            depth += 1
+        elif token in ("MUL_SLOT:0", "MUL_SLOT:1"):
+            if depth < 1:
+                raise ValueError("Split program stack underflow")
+        elif token in ("ADD", "MUL", "MIN", "MAX"):
+            if depth < 2:
+                raise ValueError("Split program stack underflow")
+            depth -= 1
+        else:
+            raise ValueError(f"Unknown split instruction: {token}")
+    if depth != 1 or "OBJECTIVE_GAIN" not in program:
+        raise ValueError("Split program must return one score and include OBJECTIVE_GAIN")
+
+
+@dataclass(frozen=True)
+class AlgorithmGenome:
+    growth_policy: str = "leafwise"
+    binning_policy: str = "quantile"
+    missing_policy: str = "learned"
+    leaf_policy: str = "newton"
+    regularization_policy: str = "global"
+    sample_policy: str = "uniform"
+    error_policy: str = "none"
+    local_policy: str = "none"
+    update_policy: str = "constant"
+    split_program: tuple[str, ...] = ("OBJECTIVE_GAIN",)
+
+    def __post_init__(self):
+        for name, choices in POLICIES.items():
+            if getattr(self, name) not in choices:
+                raise ValueError(f"Invalid {name}")
+        validate_program(self.split_program)
+        object.__setattr__(self, "split_program", tuple(self.split_program))
+
+    def mutate(self, **changes):
+        return replace(self, **changes)
+
+    def to_dict(self):
+        data = asdict(self)
+        data["split_program"] = list(self.split_program)
+        return data
+
+    def fingerprint(self):
+        return canonical_hash({"spec_version": SPEC_VERSION, "genome": self.to_dict()})
+
+    def active_parameters(self):
+        names = ["learning_rate", "n_estimators", "max_bins", "max_leaves", "max_depth", "min_samples_leaf",
+                 "l1", "l2", "min_hessian", "min_gain", "feature_fraction", "row_fraction"]
+        conditional = {
+            "path_smooth": self.leaf_policy == "smoothed",
+            "max_delta_step": self.leaf_policy == "clipped",
+            "depth_reg_strength": self.regularization_policy == "depth_scaled",
+            "error_memory_beta": self.error_policy != "none" or self.sample_policy != "uniform",
+            "error_weight": self.error_policy != "none",
+            "update_decay": self.update_policy == "decay",
+            "gate_strength": self.local_policy != "none" or self.leaf_policy == "uncertainty",
+        }
+        names.extend(name for name, active in conditional.items() if active)
+        names.extend(f"signal_slot_{i}" for i in range(2) if f"MUL_SLOT:{i}" in self.split_program)
+        return tuple(names)
+
+    def complexity(self):
+        base = AlgorithmGenome()
+        return sum(getattr(self, k) != getattr(base, k) for k in POLICIES) + len(self.split_program) - 1
+
+
+@dataclass(frozen=True)
+class HyperParams:
+    learning_rate: float = 0.1
+    n_estimators: int = 32
+    max_bins: int = 31
+    max_leaves: int = 7
+    max_depth: int = 5
+    min_samples_leaf: int = 6
+    l1: float = 0.0
+    l2: float = 2.0
+    min_hessian: float = 1e-3
+    min_gain: float = 1e-5
+    feature_fraction: float = 1.0
+    row_fraction: float = 0.8
+    path_smooth: float = 8.0
+    max_delta_step: float = 2.0
+    depth_reg_strength: float = 0.2
+    error_memory_beta: float = 0.9
+    error_weight: float = 1.0
+    update_decay: float = 0.75
+    gate_strength: float = 1.0
+    signal_slot_0: float = 0.25
+    signal_slot_1: float = 0.25
+
+    def __post_init__(self):
+        for name, low, high in (("n_estimators", 1, 4096), ("max_bins", 2, 4096), ("max_leaves", 2, 4096),
+                                ("max_depth", 1, 128), ("min_samples_leaf", 1, 10**9)):
+            checked_int(name, getattr(self, name), low, high)
+        _set_number(self, "learning_rate", 0, 1, strict=True)
+        _set_number(self, "min_hessian", 0, 1e6, strict=True)
+        for name in ("l1", "l2", "min_gain", "path_smooth", "depth_reg_strength", "error_weight", "update_decay", "gate_strength"):
+            _set_number(self, name, 0, 1e6)
+        _set_number(self, "max_delta_step", 0, 1e6, strict=True)
+        for name in ("feature_fraction", "row_fraction"):
+            _set_number(self, name, 0, 1, strict=True)
+        _set_number(self, "error_memory_beta", 0, 1)
+        if self.error_memory_beta >= 1:
+            raise ValueError("error_memory_beta must be less than 1")
+        for name in ("signal_slot_0", "signal_slot_1"):
+            _set_number(self, name, 0, 10)
+
+    def row_sample_count(self, n_rows):
+        """Fixed-size training subsample; leaf support can require the full dataset."""
+        if type(n_rows) is not int or n_rows < 1:
+            raise ValueError("n_rows must be a positive Python integer")
+        return min(n_rows, max(2 * self.min_samples_leaf, round(n_rows * self.row_fraction)))
+
+
+@dataclass(frozen=True)
+class MorphTreeConfig:
+    seed: int = 42
+    search_fraction: float = 0.15
+    guard_fraction: float = 0.15
+    enable_morphing: bool = False
+    enable_tuning: bool = True
+    structural_rounds: int = 16
+    structural_mutants: int = 3
+    structural_patience: int = 2
+    structural_evaluations: int | None = None
+    search_timeout: float | None = None
+    freeze_on_budget: bool = False
+    diagnostic_guidance: bool = False
+    memory_enabled: bool = False
+    min_morph_improvement: float = 0.0002
+    guard_tolerance: float = 0.001
+    global_guard_tolerance: float = 0.002
+    complexity_penalty: float = 0.00001
+    confidence_z: float = 0.0
+    probe_fraction: float = 0.35
+    probe_margin: float = 0.04
+    tuner: str = "none"
+    tune_trials: int = 16
+    optuna_startup_trials: int = 5
+    tune_patience: int = 6
+    tune_timeout: float | None = None
+    early_stopping_rounds: int = 6
+    optuna_storage: str | None = None
+    optuna_study_name: str | None = None
+    refit_full: bool = True
+
+    def __post_init__(self):
+        for name in ("enable_morphing", "enable_tuning", "refit_full", "freeze_on_budget", "diagnostic_guidance", "memory_enabled"):
+            if type(getattr(self, name)) is not bool:
+                raise ValueError(f"{name} must be a bool")
+        for name, low, high in (("seed", 0, 2**32 - 1), ("structural_rounds", 0, 10000),
+                                ("structural_mutants", 1, 128), ("structural_patience", 1, 100),
+                                ("tune_trials", 1, 100000), ("tune_patience", 1, 10000),
+                                ("optuna_startup_trials", 1, 100000),
+                                ("early_stopping_rounds", 0, 4096)):
+            checked_int(name, getattr(self, name), low, high)
+        for name in ("search_fraction", "guard_fraction"):
+            _set_number(self, name, 0, 0.5, strict=True)
+        if self.search_fraction + self.guard_fraction >= 0.6:
+            raise ValueError("SEARCH and GUARD must leave more than 40% for TRAIN")
+        for name in ("min_morph_improvement", "guard_tolerance", "global_guard_tolerance", "complexity_penalty", "probe_margin"):
+            _set_number(self, name, 0, 10)
+        _set_number(self, "confidence_z", 0, 5)
+        _set_number(self, "probe_fraction", 0, 1)
+        if self.tune_timeout is not None:
+            _set_number(self, "tune_timeout", 0, 1e9, strict=True)
+        if self.search_timeout is not None:
+            _set_number(self, "search_timeout", 0, 1e9, strict=True)
+        if self.structural_evaluations is not None:
+            checked_int("structural_evaluations", self.structural_evaluations, 0, 1000000)
+        if self.tuner not in ("none", "native", "optuna"):
+            raise ValueError("tuner must be none, native or optuna")
+        for name in ("optuna_storage", "optuna_study_name"):
+            value = getattr(self, name)
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                raise ValueError(f"{name} must be a nonempty string or None")
+
+
+# Versioned experimental capability; consolidated config.py is unchanged.
+TASK_GROWTH_FORMATS = {'regression':'MorphTreeRegressionGrowthV2',
+                       'multiclass':'MorphTreeMulticlassGrowthV2'}
+
+def validate_task_genome(task, genome):
+    if task not in ('binary','multiclass','regression') or not isinstance(genome,AlgorithmGenome):
+        raise ValueError('Known task and native AlgorithmGenome required')
+    if task!='binary' and (genome.split_program not in (("OBJECTIVE_GAIN",),("OBJECTIVE_GAIN","BALANCE","MUL")) or genome!=AlgorithmGenome(growth_policy=genome.growth_policy,split_program=genome.split_program)):
+        raise ValueError('ADV001 laboratory admits growth and objective-times-balance only; not a public format qualification')
+    return genome
+
+def decode_task_genome(task, payload):
+    if payload.get('format')!=TASK_GROWTH_FORMATS[task]:
+        if 'genome' in payload:raise ValueError('Legacy native format cannot acquire a genome field')
+        return AlgorithmGenome()
+    if type(payload.get('genome')) is not dict:
+        raise ValueError('V2 native growth requires an explicit genome')
+    try:genome=validate_task_genome(task,AlgorithmGenome(**payload['genome']))
+    except (TypeError,ValueError):raise ValueError('Invalid task-compatible V2 genome') from None
+    if genome==AlgorithmGenome():raise ValueError('Base retains its legacy native format')
+    return genome

morphtree/control.py

@@ -0,0 +1,20 @@
+"""Cooperative cancellation at candidate and boosting-iteration boundaries."""
+import time
+
+class SearchInterrupted(Exception):
+    def __init__(self, reason):
+        self.reason = reason
+        super().__init__(reason)
+
+class RunControl:
+    def __init__(self, cancel=None, timeout=None):
+        if cancel is not None and not callable(cancel):
+            raise ValueError('cancel must be callable or None')
+        self.cancel = cancel
+        self.deadline = None if timeout is None else time.monotonic() + timeout
+
+    def check(self):
+        if self.cancel is not None and self.cancel():
+            raise SearchInterrupted('cancelled')
+        if self.deadline is not None and time.monotonic() >= self.deadline:
+            raise SearchInterrupted('timeout')