morphtree 2.1.0__py3-none-win_amd64.whl

morphtree/mutations.py

@@ -0,0 +1,205 @@
+"""Error-guided structural programs, novelty memory and local plateau protocol."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import time
+import random
+
+from .config import POLICIES
+from .diagnostics import ErrorProfiler
+from .metrics import logloss, paired_improvement
+from .control import RunControl, SearchInterrupted
+
+
+@dataclass(frozen=True)
+class Mutation:
+    genome: object
+    gene: str
+    reason: str
+    relevance: float
+
+
+def propose_mutations(genome, profile):
+    strengths = {item["name"]: item["strength"] * item["confidence"] for item in profile["diagnoses"]}
+    mapping = {
+        "growth_policy": ("INTERACTION_LIKE_ERROR", "SMALL_UNSTABLE_REGION"),
+        "binning_policy": ("LOCAL_ERROR_CONCENTRATION", "SIGNED_BIAS"),
+        "missing_policy": ("MISSING_RELATED_ERROR",),
+        "leaf_policy": ("HIGH_UNCERTAINTY", "SIGNED_BIAS", "NOISE_LIKE"),
+        "regularization_policy": ("SMALL_UNSTABLE_REGION", "NOISE_LIKE"),
+        "sample_policy": ("PERSISTENT_ERROR", "IMBALANCE_RELATED_ERROR"),
+        "error_policy": ("PERSISTENT_ERROR", "IMBALANCE_RELATED_ERROR"),
+        "local_policy": ("LOCAL_ERROR_CONCENTRATION", "MISSING_RELATED_ERROR"),
+        "update_policy": ("NOISE_LIKE", "HIGH_RESIDUAL_VARIANCE"),
+    }
+    proposals = []
+    for gene, values in POLICIES.items():
+        diagnosis = max(mapping[gene], key=lambda key: strengths.get(key, 0))
+        relevance = 0.02 + strengths.get(diagnosis, 0)
+        for value in values:
+            if value != getattr(genome, gene):
+                proposals.append(Mutation(genome.mutate(**{gene: value}), gene,
+                                          f"Hypothesis {diagnosis}: change {gene} to {value}", relevance))
+    programs = [
+        ("OBJECTIVE_GAIN",),
+        ("OBJECTIVE_GAIN", "BALANCE", "MUL"),
+        ("OBJECTIVE_GAIN", "HESSIAN_BALANCE", "MUL"),
+        ("OBJECTIVE_GAIN", "RESIDUAL_VARIANCE_GAIN", "MUL_SLOT:0", "ADD"),
+        ("OBJECTIVE_GAIN", "UNCERTAINTY_GAIN", "MUL_SLOT:1", "ADD"),
+    ]
+    # Construct new bounded expressions from the incumbent, rather than only selecting templates.
+    for signal, slot in (("RESIDUAL_VARIANCE_GAIN", 0), ("UNCERTAINTY_GAIN", 1)):
+        if signal not in genome.split_program and len(genome.split_program) + 3 <= 15:
+            programs.append(genome.split_program + (signal, f"MUL_SLOT:{slot}", "ADD"))
+    if "BALANCE" not in genome.split_program and len(genome.split_program) + 2 <= 15:
+        programs.append(genome.split_program + ("BALANCE", "MUL"))
+    for program in programs:
+        if program != genome.split_program:
+            reason = "HIGH_RESIDUAL_VARIANCE" if "RESIDUAL_VARIANCE_GAIN" in program else "HIGH_UNCERTAINTY"
+            proposals.append(Mutation(genome.mutate(split_program=program), "split_program",
+                                      f"Hypothesis {reason}: construct bounded split program", 0.03 + strengths.get(reason, 0)))
+    unique = {p.genome.fingerprint(): p for p in proposals}
+    return sorted(unique.values(), key=lambda p: (-p.relevance, p.gene, p.genome.fingerprint()))
+
+
+class StructuralSearch:
+    """A plateau is relative to the fully evaluated current neighborhood and fixed numbers."""
+    def __init__(self, config):
+        self.config = config
+        self.control = RunControl(timeout=config.search_timeout)
+
+    def run(self, initial, evaluate, X_train, y_train, X_search, y_search, X_guard, y_guard):
+        incumbent = initial
+        base_guard = logloss(y_guard, incumbent.predict_proba(X_guard))
+        history, profiles, seen = [], [], {}
+        final_coverage = {}
+        stalled = 0
+        stop_reason = "budget_exhausted"
+        plateau = False
+        for round_index in range(1, self.config.structural_rounds + 1):
+            try:
+                self.control.check()
+            except SearchInterrupted as exc:
+                stop_reason = exc.reason
+                break
+            genome = incumbent.genome
+            parent = genome.fingerprint()
+            old_search_p = incumbent.predict_proba(X_search)
+            old_search = logloss(y_search, old_search_p)
+            old_guard = logloss(y_guard, incumbent.predict_proba(X_guard))
+            if parent not in seen:
+                profile = ErrorProfiler().profile(X_train, y_train, incumbent.memory_, X_search, y_search, old_search_p)
+                proposals = propose_mutations(genome, profile)
+                if not self.config.diagnostic_guidance:
+                    random.Random(str(self.config.seed) + parent).shuffle(proposals)
+                excluded = []
+                if incumbent.params.row_sample_count(len(y_train)) == len(y_train):
+                    active = []
+                    for proposal in proposals:
+                        only_sampling = proposal.genome.mutate(sample_policy=genome.sample_policy) == genome
+                        if proposal.gene == "sample_policy" and only_sampling:
+                            excluded.append({"gene": proposal.gene, "fingerprint": proposal.genome.fingerprint(),
+                                             "reason": "all_training_rows_selected_at_fixed_parameters"})
+                        else:
+                            active.append(proposal)
+                    proposals = active
+                seen[parent] = {"profile": profile, "proposals": proposals, "excluded": excluded,
+                                "full": set(), "screened": set()}
+                profiles.append({"fingerprint": parent, "excluded_inactive_mutations": excluded, **profile})
+            state = seen[parent]
+            proposals = state["proposals"]
+            untried = [p for p in proposals if p.genome.fingerprint() not in state["full"] | state["screened"]]
+            # Screened candidates are deferred, not declared rejected. All must be fully checked for a plateau.
+            deferred = [p for p in proposals if p.genome.fingerprint() in state["screened"]]
+            queue = untried if untried else deferred
+            width = self.config.structural_mutants
+            if state["profile"]["confidence"] < 0.5:
+                width = min(width, 2)
+            candidates = queue[:width]
+            if not candidates:
+                plateau, stop_reason = True, "verified_local_plateau"
+                final_coverage = {"available": len(proposals), "fully_evaluated": len(state["full"]), "screened_pending": 0,
+                                  "excluded_inactive": state["excluded"]}
+                break
+            winner = None
+            for proposal in candidates:
+                if self.config.structural_evaluations is not None and len(history) >= self.config.structural_evaluations:
+                    break
+                candidate_start = time.perf_counter()
+                child_fp = proposal.genome.fingerprint()
+                is_confirmation = child_fp in state["screened"]
+                probe_step = max(2, int(self.config.probe_fraction * incumbent.params.n_estimators))
+                can_probe = not is_confirmation and self.config.probe_fraction > 0 and probe_step < incumbent.params.n_estimators
+                did_screen = False
+
+                def probe(iteration, loss):
+                    nonlocal did_screen
+                    self.control.check()
+                    if can_probe and iteration == probe_step and len(incumbent.search_curve_) >= iteration:
+                        if loss > incumbent.search_curve_[iteration - 1] + self.config.probe_margin:
+                            did_screen = True
+                            return False
+                    return True
+
+                try:
+                    self.control.check()
+                    child = evaluate(proposal.genome, incumbent.params, callback=probe)
+                except SearchInterrupted as exc:
+                    stop_reason = exc.reason
+                    history.append({'round': round_index, 'parent_fingerprint': parent, 'child_fingerprint': child_fp,
+                                    'gene': proposal.gene, 'reason': proposal.reason, 'stage': 'interrupted',
+                                    'decision': exc.reason, 'accepted': False,
+                                    'cost_seconds': time.perf_counter() - candidate_start})
+                    break
+                record = {"round": round_index, "parent_fingerprint": parent, "child_fingerprint": child_fp,
+                          "gene": proposal.gene, "reason": proposal.reason, "relevance": proposal.relevance,
+                          "stage": "confirmation" if is_confirmation else "full", "accepted": False,
+                          "params_unchanged": child.params == initial.params}
+                record['cost_seconds'] = time.perf_counter() - candidate_start
+                record['trees_trained'] = len(child.trees) if hasattr(child, 'trees') else None
+                if did_screen:
+                    state["screened"].add(child_fp)
+                    record.update(stage="cheap_probe", search_loss=child.search_curve_[-1], guard_loss=None,
+                                  decision="deferred_for_full_check")
+                    history.append(record)
+                    continue
+                state["screened"].discard(child_fp)
+                state["full"].add(child_fp)
+                child_p = child.predict_proba(X_search)
+                search_loss = logloss(y_search, child_p)
+                guard_loss = logloss(y_guard, child.predict_proba(X_guard))
+                improvement, lower, se = paired_improvement(y_search, old_search_p, child_p, self.config.confidence_z)
+                penalty = self.config.complexity_penalty * max(0, proposal.genome.complexity() - genome.complexity())
+                threshold = self.config.min_morph_improvement + penalty
+                qualifies = lower > threshold and guard_loss <= min(old_guard + self.config.guard_tolerance,
+                                                                   base_guard + self.config.global_guard_tolerance)
+                record.update(search_loss=search_loss, guard_loss=guard_loss, search_delta=improvement,
+                              lower_gain=lower, gain_standard_error=se, guard_delta=old_guard - guard_loss,
+                              decision="eligible_not_selected" if qualifies else "rejected")
+                history.append(record)
+                if qualifies and (winner is None or search_loss + penalty < winner[0]):
+                    winner = (search_loss + penalty, child, record)
+            if winner:
+                incumbent = winner[1]
+                winner[2].update(accepted=True, decision="committed")
+                stalled = 0
+            else:
+                stalled += 1
+            final_coverage = {"available": len(proposals), "fully_evaluated": len(state["full"]),
+                              "screened_pending": len(state["screened"]), "excluded_inactive": state["excluded"]}
+            if stop_reason in ('cancelled', 'timeout'):
+                break
+            exhausted = len(state["full"]) == len(proposals) and not state["screened"]
+            required_stalls = min(self.config.structural_patience, max(1, math.ceil(len(proposals) / width)))
+            if winner is None and exhausted and stalled >= required_stalls:
+                plateau, stop_reason = True, "verified_local_plateau"
+                break
+            if self.config.structural_evaluations is not None and len(history) >= self.config.structural_evaluations:
+                break
+        if not plateau and history and history[-1]["parent_fingerprint"] != incumbent.genome.fingerprint():
+            final_coverage = {"available": None, "fully_evaluated": 0, "screened_pending": 0,
+                              "note": "new incumbent has not yet been explored"}
+        return incumbent, {"stop_reason": stop_reason, "plateau_reached": plateau, "history": history,
+                           "profiles": profiles, "coverage": final_coverage,
+                           "scope": "active one-step neighborhood; reported no-op exclusions; fixed HyperParams; current TRAIN/SEARCH/GUARD"}

morphtree/native_lab_backend.py

@@ -0,0 +1,79 @@
+"""Integrated native execution with unchanged public estimator signatures."""
+from contextlib import contextmanager
+from contextvars import ContextVar
+import time
+from .scalable_backend import ScalableBackend
+from ._native.buffers import UnsupportedBuffers
+
+_ACTIVE=ContextVar('morphtree_native_lab_backend',default=None);_PYTHON=object()
+
+
+class NativeSession:
+    def __init__(self,*,histogram_only=False):
+        from ._native.loader import get_runtime,runtime_info
+        self.kernel=get_runtime();self.info=runtime_info();self.binary_sha256=self.info['binary_sha256'];self.histogram_only=histogram_only
+        self.calls=0;self.fallback_calls=0;self.indices_copy_bytes=0;self.seconds=0.;self.traversal_calls=0;self.small_batch_python_calls=0;self.traversal_fallback_calls=0
+    def create(self,nominal_sizes):return (NativeHistogramBackend if self.histogram_only else NativeBackend)(self,nominal_sizes)
+    def report(self):
+        return dict(backend='MORPHTREE_INTEGRATED_NATIVE_ABI1',binary_sha256=self.binary_sha256,
+                    histogram_calls=self.calls,fallback_calls=self.fallback_calls,
+                    indices_copy_bytes=self.indices_copy_bytes,histogram_seconds_including_bridge=self.seconds,
+                    traversal_calls=self.traversal_calls,small_batch_python_calls=self.small_batch_python_calls,
+                    traversal_fallback_calls=self.traversal_fallback_calls,
+                    scope='Current process execution telemetry,not restored historical fit cost',runtime={**self.info,'cache':self.kernel.trees.report()})
+
+
+class NativeHistogramBackend(ScalableBackend):
+    name='morphtree-native-histogram'
+    def __init__(self,session,nominal_sizes=None):super().__init__(nominal_sizes);self.session=session
+    def histogram(self,column,indices,g,h,r,u,size):
+        tick=time.perf_counter()
+        try:
+            result,copied=self.session.kernel.histogram(column,indices,g,h,r,u,size)
+        except UnsupportedBuffers:
+            self.session.fallback_calls+=1
+            return super().histogram(column,indices,g,h,r,u,size)
+        # Native rejection/error is not a fallback:it must stop qualification.
+        self.session.calls+=1;self.session.seconds+=time.perf_counter()-tick
+        self.session.indices_copy_bytes+=copied
+        return result
+
+
+class NativeBackend(NativeHistogramBackend):
+    name='morphtree-integrated-native'
+    def predict_tree(self,nodes,columns):
+        # INTEGRATED013:Python wins at1/8/32rows,C wins from128rows.
+        # Equivalent execution route only;no row limit or sampling.
+        if columns and len(columns[0])<128:
+            self.session.small_batch_python_calls+=1;return ScalableBackend.predict_tree(self,nodes,columns)
+        try:result=self.session.kernel.predict_tree(nodes,columns)
+        except UnsupportedBuffers:
+            self.session.traversal_fallback_calls+=1;return ScalableBackend.predict_tree(self,nodes,columns)
+        self.session.traversal_calls+=1;return result
+
+def bind_backend():
+    """One provider captured per fit/load/export;verified native use is automatic."""
+    active=_ACTIVE.get()
+    if active is _PYTHON:return ScalableBackend
+    return (NativeSession() if active is None else active).create
+
+
+@contextmanager
+def _scope(value):
+    if _ACTIVE.get() is not None:raise RuntimeError('Nested native backend scopes are not supported')
+    token=_ACTIVE.set(value)
+    try:yield value
+    finally:_ACTIVE.reset(token)
+
+@contextmanager
+def python_backend_scope():
+    """Explicit reference route for qualification,not a public estimator knob."""
+    with _scope(_PYTHON):yield
+
+@contextmanager
+def native_histogram_scope():
+    with _scope(NativeSession(histogram_only=True)) as value:yield value
+
+@contextmanager
+def native_backend_scope():
+    with _scope(NativeSession()) as value:yield value

morphtree/numpy_backend.py

@@ -0,0 +1,180 @@
+"""NumPy kernels only. Training still uses the native MorphTree tree builder."""
+from __future__ import annotations
+
+import numpy as np
+import math
+from .backend import PythonBackend
+from .metrics import sigmoid
+
+_FLOAT64_EPS = float(np.finfo(np.float64).eps)
+
+
+class NumpyBackend(PythonBackend):
+    name = "numpy"
+
+    def __init__(self):
+        self.split_calls = 0
+        self.canonical_split_fallbacks = 0
+
+    def bin(self, binner, X):
+        matrix = np.asarray(X, dtype=np.float64)
+        out = np.empty((len(binner.thresholds), len(X)), dtype=np.uint8 if binner.max_bins <= 255 else np.uint16)
+        for j, cuts in enumerate(binner.thresholds):
+            values = matrix[:, j]
+            out[j] = np.where(np.isnan(values), 0, np.searchsorted(cuts, values, side="right") + 1)
+        return out
+
+    def gradients(self, raw, y):
+        values = np.asarray(raw, dtype=np.float64)
+        probabilities = np.fromiter((sigmoid(float(v)) for v in values), dtype=np.float64, count=len(values))
+        return probabilities.tolist(), probabilities - np.asarray(y), np.maximum(probabilities * (1 - probabilities), 1e-12)
+
+    def probabilities(self, raw):
+        return [sigmoid(float(v)) for v in raw]
+
+    def regression_gradients(self, raw, y):
+        values = np.asarray(raw, dtype=np.float64)
+        return values.tolist(), values - np.asarray(y, dtype=np.float64), np.ones(len(y), dtype=np.float64)
+
+    def multiclass_raw(self, prior, n):
+        return np.tile(np.asarray(prior, dtype=np.float64), (n, 1))
+
+    def multiclass_gradient_column(self, probabilities, y, column, strategy):
+        values = np.fromiter((row[column] for row in probabilities), dtype=np.float64, count=len(y))
+        factor = 2. if strategy == 'softmax' else 1.
+        return values - (np.asarray(y) == column), np.maximum(factor*values*(1-values), 1e-12)
+
+    def multiclass_update(self, raw, column, step, prediction):
+        raw[:, column] += step * np.asarray(prediction)
+
+    def node_statistics(self, Xb, ids, g, h, u, features, need_missing, need_uncertainty):
+        indices = np.asarray(ids, dtype=np.intp)
+        missing = float(np.mean(np.any(Xb[np.ix_(features, indices)] == 0, axis=0))) if need_missing else 0.0
+        # Gather in C, then keep the reference fsum on the same ordered floats.
+        uncertainty = math.fsum(np.asarray(u)[indices].tolist()) / max(len(ids), 1) if need_uncertainty else 0.0
+        return math.fsum(np.asarray(g)[indices].tolist()), math.fsum(np.asarray(h)[indices].tolist()), uncertainty, missing
+
+    def histogram(self, column, indices, g, h, r, u, size):
+        ids = np.asarray(indices, dtype=np.intp)
+        bins = column[ids]
+        return np.vstack((np.bincount(bins, minlength=size),
+                          *(np.bincount(bins, weights=np.asarray(values)[ids], minlength=size) for values in (g, h, r, u))))
+
+    def subtract(self, parent, child):
+        out = parent - child
+        out[0] = np.maximum(out[0], 0)
+        out[2] = np.maximum(out[2], 0)
+        return out
+
+    def cumulative(self, histogram):
+        return np.cumsum(histogram[:, 1:], axis=1)
+
+    def partition(self, column, ids, cut, missing_left):
+        indices = np.asarray(ids, dtype=np.intp)
+        bins = column[indices]
+        mask = np.where(bins == 0, missing_left, bins <= cut)
+        return indices[mask].tolist(), indices[~mask].tolist()
+
+    def add_update(self, raw, step, prediction):
+        return np.asarray(raw, dtype=np.float64) + step * prediction
+
+    def predict_tree(self, nodes, Xb):
+        # Tiny batches spend more time allocating vector queues than traversing.
+        # The reference walk preserves missing routes and cycle bounds exactly.
+        if Xb.shape[1] <= 16:
+            return np.asarray(PythonBackend.predict_tree(self, nodes, Xb), dtype=np.float64)
+        out = np.empty(Xb.shape[1], dtype=np.float64)
+        queue = [(0, np.arange(Xb.shape[1]))]
+        visits = 0
+        while queue:
+            index, rows = queue.pop()
+            visits += 1
+            if visits > len(nodes):
+                raise ValueError("Invalid cyclic tree")
+            if not len(rows):
+                continue
+            node = nodes[index]
+            if node.is_leaf:
+                out[rows] = node.value
+                continue
+            bins = Xb[node.feature, rows]
+            mask = np.where(bins == 0, node.missing_left, bins <= node.threshold_bin)
+            if mask.any():
+                queue.append((node.left, rows[mask]))
+            if (~mask).any():
+                queue.append((node.right, rows[~mask]))
+        return out
+
+    def fast_split(self, hist, total, depth, genome, params):
+        self.split_calls += 1
+        directions = np.asarray((True, False) if genome.missing_policy == "learned" else (genome.missing_policy == "left",))
+        if len(directions) == 2 and not hist[:, 0].any():
+            # Both routes are exactly identical; retain the core's first tie.
+            directions = directions[:1]
+        cumulative = np.column_stack((np.zeros(5), np.cumsum(hist[:, 1:], axis=1)))
+        left = cumulative[:, :, None] + hist[:, 0, None, None] * directions[None, None, :]
+        right = np.asarray(total)[:, None, None] - left
+        ln, lg, lh, lr, lu = left
+        rn, rg, rh, rr, ru = right
+        n, G, H, R, U = total
+        valid = (ln >= params.min_samples_leaf) & (rn >= params.min_samples_leaf) & (lh >= params.min_hessian) & (rh >= params.min_hessian)
+        if not valid.any():
+            return None
+        factor = params.depth_reg_strength if genome.regularization_policy == "depth_scaled" else 0.0
+        l2_child = params.l2 * (1 + factor * (depth + 1))
+        l2_parent = params.l2 * (1 + factor * depth)
+        score_left = np.maximum(np.abs(lg) - params.l1, 0) ** 2 / np.maximum(lh + l2_child, 1e-12)
+        score_right = np.maximum(np.abs(rg) - params.l1, 0) ** 2 / np.maximum(rh + l2_child, 1e-12)
+        parent = max(abs(G) - params.l1, 0) ** 2 / max(H + l2_parent, 1e-12)
+        # Programs usually consume one signal; do not allocate unused arrays.
+        program = genome.split_program
+        signals = {"OBJECTIVE_GAIN": 0.5 * (score_left + score_right - parent)}
+        if 'RESIDUAL_VARIANCE_GAIN' in program or 'UNCERTAINTY_GAIN' in program:
+            safe_ln, safe_rn = np.maximum(ln, 1), np.maximum(rn, 1)
+        if 'RESIDUAL_VARIANCE_GAIN' in program:
+            signals['RESIDUAL_VARIANCE_GAIN'] = np.maximum(0, lr * lr / safe_ln + rr * rr / safe_rn - R * R / n)
+        if 'BALANCE' in program:
+            signals['BALANCE'] = 2 * np.minimum(ln, rn) / n
+        if 'HESSIAN_BALANCE' in program:
+            signals['HESSIAN_BALANCE'] = 2 * np.minimum(lh, rh) / max(H, 1e-12)
+        if 'UNCERTAINTY_GAIN' in program:
+            signals['UNCERTAINTY_GAIN'] = (lu / safe_ln - ru / safe_rn) ** 2 * ln * rn / n
+        stack = []
+        for token in genome.split_program:
+            if token in signals:
+                stack.append(signals[token])
+            elif token.startswith("MUL_SLOT:"):
+                stack[-1] = stack[-1] * getattr(params, f"signal_slot_{token[-1]}")
+            else:
+                b, a = stack.pop(), stack.pop()
+                if token == "ADD":
+                    stack.append(a + b)
+                elif token == "MUL":
+                    stack.append(a * b)
+                elif token == "MIN":
+                    stack.append(np.minimum(a, b))
+                else:
+                    stack.append(np.maximum(a, b))
+        finite_valid = valid & np.isfinite(stack[0])
+        if not finite_valid.any():
+            return None
+        maximum = float(np.max(stack[0][finite_valid]))
+        # Conservative error envelope: near admission or a rounding boundary,
+        # the core evaluates the SAME histogram with canonical scalar operations.
+        # This does not change min_gain or the probability tolerance.
+        scale = max(1., abs(parent), float(score_left.max()), float(score_right.max()), abs(maximum))
+        error = 64 * _FLOAT64_EPS * scale
+        contenders = stack[0][finite_valid & (stack[0] >= maximum - 1e-12 - error)]
+        rounding_ambiguous = len(contenders) > 1 and float(contenders.min()) != maximum and np.any(
+            np.abs((contenders * 1e12) % 1 - .5) * 1e-12 <= error)
+        if abs(maximum - params.min_gain) <= error or rounding_ambiguous:
+            self.canonical_split_fallbacks += 1
+            return NotImplemented
+        gains = np.where(finite_valid & (stack[0] > params.min_gain), stack[0], -np.inf)
+        # Same 12-decimal score ordering and first-in-order tie rule as the core.
+        flat = int(np.argmax(np.round(gains, 12)))
+        cut, direction_index = np.unravel_index(flat, gains.shape)
+        gain = float(gains[cut, direction_index])
+        if gain <= params.min_gain:
+            return None
+        return gain, int(cut), bool(directions[direction_index])

morphtree/optuna_tuner.py

@@ -0,0 +1,154 @@
+"""Optional Optuna TPE, pruning, conditional search and context-checked resume."""
+from __future__ import annotations
+
+from dataclasses import asdict, replace
+import math
+
+from .config import VERSION, canonical_hash
+from .tuning import bounded_parameter, decide_tuned_candidate, prediction_loss, tunable_parameters, tuning_record
+from .control import RunControl, SearchInterrupted
+
+
+def sampler_options(config):
+    # Pin options whose defaults differ between Optuna 4 and 5.
+    return dict(n_startup_trials=config.optuna_startup_trials, multivariate=False,
+                constant_liar=False, n_ei_candidates=24)
+
+
+def study_context(base, config, dataset, base_guard_limit):
+    import optuna
+    return canonical_hash({'dataset': dataset, 'genome': base.genome.to_dict(),
+        'parameters': asdict(base.params), 'seed': config.seed,
+        'early_stopping': config.early_stopping_rounds, 'version': VERSION,
+        'metric': 'regression_rmse_v1' if getattr(base, 'objective', 'binary_logloss') == 'squared_error' else 'binary_logloss_v1',
+        'search_space': {'version': 1, 'active': tunable_parameters(base.genome)},
+        'guard_tolerance': config.guard_tolerance, 'global_guard_tolerance': config.global_guard_tolerance,
+        'base_guard_limit': base_guard_limit, 'sampler': {'name': 'TPE', **sampler_options(config)},
+        'optuna_major': int(optuna.__version__.split('.')[0])})
+
+
+class OptunaTuner:
+    def __init__(self):
+        self.study = None
+        self.context = None
+
+    def optimize(self, base, evaluate, X_search, y_search, X_guard, y_guard, config, base_guard_limit):
+        try:
+            import optuna
+        except ImportError as exc:
+            raise ImportError("Optuna is optional: install morphtree[optuna] or choose tuner='none'") from exc
+        before = prediction_loss(base, X_search, y_search)
+        guard_before = prediction_loss(base, X_guard, y_guard)
+        record = tuning_record(base.genome, before, guard_before)
+        record["backend"] = "optuna"
+        # Includes the runtime version, exact TRAIN/SEARCH contents, genome, baseline numbers and seed.
+        context = study_context(base, config, self.context, base_guard_limit)
+        control = RunControl(getattr(self, 'cancel', None), config.tune_timeout)
+        storage = None
+        try:
+            if config.optuna_storage is not None:
+                from sqlalchemy.pool import NullPool
+                storage = optuna.storages.RDBStorage(config.optuna_storage, engine_kwargs={"poolclass": NullPool})
+            self.study = optuna.create_study(direction="minimize", sampler=optuna.samplers.TPESampler(seed=config.seed, **sampler_options(config)),
+                                        pruner=optuna.pruners.MedianPruner(n_startup_trials=3, n_warmup_steps=5),
+                                        storage=storage, study_name=config.optuna_study_name or "MorphTree-" + context[:20],
+                                        load_if_exists=config.optuna_storage is not None)
+        except Exception:
+            if storage is not None:
+                storage.remove_session()
+            raise RuntimeError('Unable to initialize Optuna storage or study; check private runtime settings') from None
+        stored_context = self.study.user_attrs.get("morphtree_context")
+        if stored_context is not None and stored_context != context:
+            if storage is not None:
+                storage.remove_session()
+            raise ValueError("Optuna study context mismatch: do not mix runtime versions, datasets, genomes or "
+                             "baseline parameters; use a new study name")
+        if self.study.trials and stored_context is None:
+            if storage is not None:
+                storage.remove_session()
+            raise ValueError("Refusing to reuse an existing study without MorphTree context")
+        self.study.set_user_attr("morphtree_context", context)
+        self.study.set_user_attr("structural_fingerprint", base.genome.fingerprint())
+        active = tunable_parameters(base.genome)
+
+        def objective(trial):
+            control.check()
+            values = {}
+            for name in active:
+                initial = getattr(base.params, name)
+                if name in ("n_estimators", "max_leaves", "min_samples_leaf"):
+                    low = bounded_parameter(name, initial * 0.5)
+                    high = bounded_parameter(name, initial * 1.6)
+                    values[name] = trial.suggest_int(name, low, max(low, high))
+                else:
+                    low = bounded_parameter(name, max(initial, 0.01) * 0.5)
+                    high = bounded_parameter(name, max(initial, 0.01) * 1.8)
+                    values[name] = trial.suggest_float(name, low, max(low, high), log=low > 0)
+            params = replace(base.params, **values)
+
+            def callback(iteration, loss):
+                control.check()
+                trial.report(loss, iteration)
+                if trial.should_prune():
+                    raise optuna.TrialPruned()
+                return True
+
+            candidate = evaluate(base.genome, params, callback=callback, early_stopping_rounds=config.early_stopping_rounds)
+            if len(candidate.trees) < params.n_estimators:
+                params = replace(params, n_estimators=len(candidate.trees))
+                candidate = evaluate(base.genome, params, callback=lambda iteration, loss: control.check())
+            if candidate.genome.fingerprint() != record["frozen_fingerprint"]:
+                raise RuntimeError("Optuna attempted to change the frozen genome")
+            trial.set_user_attr("effective_parameters", asdict(params))
+            loss = prediction_loss(candidate, X_search, y_search)
+            guard_loss = prediction_loss(candidate, X_guard, y_guard)
+            if not math.isfinite(loss) or not math.isfinite(guard_loss):
+                raise ArithmeticError('Nonfinite trial metric')
+            feasible = guard_loss <= min(guard_before + config.guard_tolerance,
+                                        base_guard_limit + config.global_guard_tolerance)
+            trial.set_user_attr('guard_loss', guard_loss)
+            trial.set_user_attr('feasible', feasible)
+            return loss
+
+        first_new_trial = len(self.study.trials)
+        if first_new_trial:
+            # RNG state is not persisted by Optuna. Avoid replaying identical startup proposals after reopening.
+            self.study.sampler = optuna.samplers.TPESampler(seed=(config.seed + first_new_trial) % (2**32), **sampler_options(config))
+        try:
+            self.study.optimize(objective, n_trials=config.tune_trials, timeout=config.tune_timeout, n_jobs=1,
+                                show_progress_bar=False, catch=(ArithmeticError, ValueError))
+            control.check()
+        except SearchInterrupted as exc:
+            record['stop_reason'] = exc.reason
+        complete = [trial for trial in self.study.trials if trial.state == optuna.trial.TrialState.COMPLETE
+                    and trial.value is not None and math.isfinite(trial.value) and "effective_parameters" in trial.user_attrs]
+        feasible = [trial for trial in complete if trial.user_attrs.get('feasible') is True]
+        record["trials"] = [{"index": trial.number, "state": trial.state.name, "search_loss": trial.value,
+                              "parameters": trial.params, 'guard_loss': trial.user_attrs.get('guard_loss'),
+                              'feasible': trial.user_attrs.get('feasible', False)} for trial in self.study.trials]
+        record["new_trials"] = len(self.study.trials) - first_new_trial
+        record['sampler'] = {'name': 'TPE', **sampler_options(config)}
+        record['sampling_note'] = 'Startup uses random sampling; requested trials do not prove adaptive execution'
+        record["study_context"] = context
+        record["completed_trials"] = len(complete)
+        record['feasible_trials'] = len(feasible)
+        if feasible and 'stop_reason' not in record:
+            best_trial = min(feasible, key=lambda trial: trial.value)
+            try:
+                control.check()
+                candidate = evaluate(base.genome, replace(base.params, **best_trial.user_attrs["effective_parameters"]),
+                                     callback=lambda iteration, loss: control.check())
+            except SearchInterrupted as exc:
+                record['stop_reason'] = exc.reason
+                candidate = base
+        else:
+            candidate = base
+            record["reason"] = "no_completed_trials"
+        selected, record = decide_tuned_candidate(base, candidate, record, X_search, y_search, X_guard, y_guard, config, base_guard_limit)
+        if not complete:
+            record.update(completed=False, accepted=False, reason="no_completed_trials")
+        elif not feasible:
+            record.update(completed=True, accepted=False, reason='no_feasible_trials')
+        if storage is not None:
+            storage.remove_session()
+        return selected, record