morphtree 2.1.0__py3-none-win_amd64.whl

morphtree/data.py

@@ -0,0 +1,300 @@
+"""Input contracts, deterministic splits and compact train-only binning."""
+from __future__ import annotations
+
+from array import array
+from bisect import bisect_left, bisect_right
+import csv
+import math
+from numbers import Real
+import random
+
+from .config import checked_int
+
+
+def get_feature_names(X):
+    if not hasattr(X, "columns"):
+        return None
+    names = list(X.columns)
+    validate_names(names, len(names))
+    return names
+
+
+def validate_names(names, count):
+    if names is not None:
+        if not isinstance(names, (list, tuple)) or len(names) != count:
+            raise ValueError("Feature names must match the number of columns")
+        if any(not isinstance(x, str) or not x for x in names) or len(set(names)) != len(names):
+            raise ValueError("Feature names must be unique nonempty strings")
+
+
+def validate_X(X, n_features=None, expected_names=None, *, allow_empty=False):
+    names = get_feature_names(X)
+    if names is not None and expected_names is not None:
+        if set(names) != set(expected_names):
+            raise ValueError("Feature schema mismatch: missing or extra columns")
+        X = X.loc[:, list(expected_names)]
+    if hasattr(X, "to_numpy"):
+        X = X.to_numpy()
+    if hasattr(X, "ndim") and X.ndim != 2:
+        raise ValueError("X must have exactly two dimensions")
+    if n_features is not None and hasattr(X, "shape") and len(X.shape) == 2 and X.shape[1] != n_features:
+        raise ValueError(f"X must have exactly {n_features} features")
+    if hasattr(X, "tolist"):
+        X = X.tolist()
+    if isinstance(X, (str, bytes)):
+        raise ValueError("X must be a matrix of numeric rows")
+    try:
+        rows = list(X)
+    except TypeError as exc:
+        raise ValueError("X must be a matrix") from exc
+    if not rows:
+        if allow_empty and n_features is not None:
+            return []
+        raise ValueError("X must contain at least one row")
+    width = n_features
+    output = []
+    for row in rows:
+        if isinstance(row, (str, bytes)):
+            raise ValueError("Each row must be a numeric sequence")
+        try:
+            values = list(row)
+        except TypeError as exc:
+            raise ValueError("X must have exactly two dimensions") from exc
+        if width is None:
+            width = len(values)
+        if not width or len(values) != width:
+            raise ValueError(f"X must have exactly {width} features in each row")
+        converted = []
+        for value in values:
+            if value is None:
+                converted.append(math.nan)
+            elif isinstance(value, Real):
+                try:
+                    number = float(value)
+                except (ValueError, OverflowError) as exc:
+                    raise ValueError("Feature outside supported floating-point range") from exc
+                if math.isinf(number):
+                    raise ValueError("X may contain missing values but not infinity")
+                converted.append(number)
+            else:
+                raise ValueError("X must contain numeric values, None or NaN")
+        output.append(converted)
+    return output
+
+
+def validate_y(y, n, *, both_classes=False):
+    if hasattr(y, "ndim") and y.ndim != 1:
+        raise ValueError("y must be one-dimensional")
+    if hasattr(y, "tolist"):
+        y = y.tolist()
+    if isinstance(y, (str, bytes)):
+        raise ValueError("y must contain numeric 0/1 labels")
+    try:
+        values = list(y)
+    except TypeError as exc:
+        raise ValueError("y must be a one-dimensional sequence") from exc
+    if len(values) != n or not values:
+        raise ValueError("y must contain one label for every nonempty input row")
+    if any(not isinstance(v, Real) or not math.isfinite(v) or v not in (0, 1) for v in values):
+        raise ValueError("Only one-dimensional numeric 0/1 labels are supported")
+    out = [int(v) for v in values]
+    if both_classes and len(set(out)) != 2:
+        raise ValueError("Training and selection splits must each contain both classes")
+    return out
+
+
+def validate_xy(X, y, n_features=None, expected_names=None, *, both_classes=True):
+    X = validate_X(X, n_features, expected_names)
+    return X, validate_y(y, len(X), both_classes=both_classes)
+
+
+def validate_regression_y(y, n):
+    """Finite scalar targets; bound magnitude to the shared tree/format range."""
+    if hasattr(y, 'ndim') and y.ndim != 1:
+        raise ValueError('Regression y must be one-dimensional')
+    if hasattr(y, 'tolist'):
+        y = y.tolist()
+    if isinstance(y, (str, bytes)):
+        raise ValueError('Regression y must contain real numbers')
+    try:
+        values = list(y)
+    except TypeError as exc:
+        raise ValueError('Regression y must be a one-dimensional sequence') from exc
+    if len(values) != n or not values:
+        raise ValueError('Regression y must contain one target for every nonempty input row')
+    output = []
+    for value in values:
+        if isinstance(value, bool) or not isinstance(value, Real):
+            raise ValueError('Regression targets must be finite real numbers, excluding bool')
+        try:
+            number = float(value)
+        except (ValueError, OverflowError) as exc:
+            raise ValueError('Regression target outside floating-point range') from exc
+        if not math.isfinite(number) or abs(number) > 1e100:
+            raise ValueError('Regression targets must be finite with magnitude at most 1e100')
+        output.append(number)
+    return output
+
+
+def validate_multiclass_y(y, n, classes=None):
+    """TRAIN-derived sorted classes: homogeneous strings or signed 64-bit ints."""
+    if hasattr(y, 'ndim') and y.ndim != 1:
+        raise ValueError('Multiclass y must be one-dimensional')
+    if hasattr(y, 'tolist'):
+        y = y.tolist()
+    if isinstance(y, (str, bytes)):
+        raise ValueError('Multiclass y must be a label sequence')
+    try:
+        values = list(y)
+    except TypeError as exc:
+        raise ValueError('Multiclass y must be a label sequence') from exc
+    if len(values) != n or not values:
+        raise ValueError('One label is required for every nonempty input row')
+    if not (all(type(v) is int and -(2**63) <= v < 2**63 for v in values)
+            or all(type(v) is str and 0 < len(v) <= 256 for v in values)):
+        raise ValueError('Classes must be homogeneous strings (1..256 chars) or signed 64-bit integers, excluding bool')
+    if classes is None:
+        classes = tuple(sorted(set(values)))
+        if not 2 <= len(classes) <= 100:
+            raise ValueError('Multiclass TRAIN requires 2..100 observed classes')
+    if type(values[0]) is not type(classes[0]):
+        raise ValueError('Label type does not match TRAIN classes')
+    lookup = {label: i for i, label in enumerate(classes)}
+    if any(value not in lookup for value in values):
+        raise ValueError('Label not observed in TRAIN; class vocabulary never learns from validation/test')
+    return [lookup[value] for value in values], tuple(classes)
+
+
+def split_indices(y, search_fraction, guard_fraction, seed):
+    rng = random.Random(seed)
+    train, search, guard = [], [], []
+    for label in (0, 1):
+        ids = [i for i, value in enumerate(y) if value == label]
+        if len(ids) < 3:
+            raise ValueError("Automatic splitting requires at least 3 examples per class; provide explicit splits")
+        rng.shuffle(ids)
+        ns = max(1, round(len(ids) * search_fraction))
+        ng = max(1, round(len(ids) * guard_fraction))
+        while ns + ng >= len(ids):
+            if ns >= ng and ns > 1:
+                ns -= 1
+            elif ng > 1:
+                ng -= 1
+            else:
+                raise ValueError("Too few examples for three disjoint splits")
+        search.extend(ids[:ns])
+        guard.extend(ids[ns:ns + ng])
+        train.extend(ids[ns + ng:])
+    for ids in (train, search, guard):
+        rng.shuffle(ids)
+    return train, search, guard
+
+
+def regression_split_indices(n, search_fraction, guard_fraction, seed):
+    """Target-independent, reproducible partition; every row belongs to one split."""
+    if n < 3:
+        raise ValueError('Regression tuning requires at least 3 rows; provide explicit SEARCH and GUARD')
+    ids = list(range(n))
+    random.Random(seed).shuffle(ids)
+    ns = max(1, round(n * search_fraction))
+    ng = max(1, round(n * guard_fraction))
+    while ns + ng >= n:
+        if ns >= ng and ns > 1:
+            ns -= 1
+        elif ng > 1:
+            ng -= 1
+        else:
+            raise ValueError('Too few rows for three disjoint regression splits')
+    return ids[ns + ng:], ids[:ns], ids[ns:ns + ng]
+
+
+def subset(X, y, ids):
+    return [X[i] for i in ids], [y[i] for i in ids]
+
+
+def stable_midpoint(a, b):
+    # Avoid overflow and keep the boundary strictly greater than a for bisect_right.
+    mid = a + (b - a) / 2 if (a >= 0) == (b >= 0) else a / 2 + b / 2
+    return b if mid <= a else mid
+
+
+class Binner:
+    """Bin zero is missing; observed bins are 1..max_bins."""
+    def __init__(self, max_bins=31, policy="quantile"):
+        checked_int("max_bins", max_bins, 2, 4096)
+        if policy not in ("quantile", "uniform"):
+            raise ValueError("Unknown binning policy")
+        self.max_bins, self.policy = max_bins, policy
+        self.thresholds = None
+
+    def fit(self, X):
+        cuts = []
+        for j in range(len(X[0])):
+            nominal = getattr(X, '_nominal_sizes', {}).get(j)
+            if nominal is not None:
+                cuts.append(tuple(float(v) for v in range(nominal + 1)))
+                continue
+            column = X.column(j) if hasattr(X, '_compact_columns') else (row[j] for row in X)
+            values = sorted(v for v in column if not math.isnan(v))
+            # Only <=max_bins distinct values need enumeration. Otherwise the
+            # existing rank quantiles need the sorted observations and extrema,
+            # not a second O(n)-sized set/list or a second sort. Bisect skips
+            # duplicate runs, so low-cardinality columns do not incur a Python
+            # scan per observation. Preserve each first stable representative,
+            # including the sign of zero, as sorted(set(values)) did.
+            unique, position = [], 0
+            while position < len(values) and len(unique) <= self.max_bins:
+                value = values[position]
+                unique.append(value)
+                position = bisect_right(values, value, position + 1)
+            if len(unique) <= 1:
+                thresholds = []
+            elif len(unique) <= self.max_bins:
+                thresholds = [stable_midpoint(a, b) for a, b in zip(unique, unique[1:])]
+            elif self.policy == "uniform":
+                low, high = values[0], values[bisect_left(values, values[-1])]
+                thresholds = [low * (1 - k / self.max_bins) + high * (k / self.max_bins) for k in range(1, self.max_bins)]
+            else:
+                thresholds = [values[min(len(values) - 1, (k * len(values)) // self.max_bins)] for k in range(1, self.max_bins)]
+            cuts.append(tuple(sorted({v for v in thresholds if values[0] < v <= values[-1]})) if thresholds else ())
+        self.thresholds = tuple(cuts)
+        return self
+
+    def transform(self, X):
+        if self.thresholds is None:
+            raise RuntimeError("Binner is not fitted")
+        kind = "B" if self.max_bins <= 255 else "H"
+        return [array(kind, (0 if math.isnan(row[j]) else bisect_right(cuts, row[j]) + 1 for row in X))
+                for j, cuts in enumerate(self.thresholds)]
+
+    def to_dict(self):
+        return {"max_bins": self.max_bins, "policy": self.policy, "thresholds": [list(c) for c in self.thresholds]}
+
+
+def read_csv(path, target=None, expected_names=None):
+    with open(path, encoding="utf-8-sig", newline="") as handle:
+        reader = csv.reader(handle)
+        try:
+            names = next(reader)
+        except StopIteration as exc:
+            raise ValueError("CSV is empty") from exc
+        validate_names(names, len(names))
+        if target is not None and target not in names:
+            raise ValueError(f"Target column {target!r} not found")
+        features = [c for c in names if c != target]
+        if expected_names is not None:
+            if set(features) != set(expected_names):
+                raise ValueError("CSV feature schema mismatch")
+            features = list(expected_names)
+        indices = [names.index(c) for c in features]
+        X, y = [], []
+        for line, row in enumerate(reader, 2):
+            if len(row) != len(names):
+                raise ValueError(f"Malformed CSV row {line}")
+            try:
+                X.append([float(row[j]) if row[j].strip().lower() not in ("", "nan", "none", "null") else None for j in indices])
+                if target is not None:
+                    y.append(float(row[names.index(target)]))
+            except ValueError as exc:
+                raise ValueError(f"Nonnumeric CSV value at row {line}") from exc
+    return X, y if target is not None else None, features

morphtree/diagnostics.py

@@ -0,0 +1,158 @@
+"""Persistent sample-error memory and bounded, explicitly heuristic diagnosis."""
+from __future__ import annotations
+from array import array
+from dataclasses import dataclass
+import math
+
+class ErrorMemory:
+
+    def __init__(self, size, beta=0.9):
+        self.beta = beta
+        self.ema_error = array('d', [0.0]) * size
+        self.signed_residual_ema = array('d', [0.0]) * size
+        self.wrong_streak = array('I', [0]) * size
+        self.uncertainty = array('d', [0.0]) * size
+        self.hardness = array('d', [0.0]) * size
+        self.direction_consistency = array('d', [0.0]) * size
+        self.updates = 0
+
+    def update(self, y, p):
+        if len(y) != len(self.ema_error) or len(p) != len(y):
+            raise ValueError('ErrorMemory sample alignment mismatch')
+        self.updates += 1
+        correction = 1 - self.beta ** self.updates
+        for i, (label, probability) in enumerate(zip(y, p)):
+            residual = label - probability
+            self.ema_error[i] = self.beta * self.ema_error[i] + (1 - self.beta) * abs(residual)
+            self.signed_residual_ema[i] = self.beta * self.signed_residual_ema[i] + (1 - self.beta) * residual
+            self.wrong_streak[i] = min(2 ** 32 - 1, self.wrong_streak[i] + 1) if (probability >= 0.5) != label else 0
+            self.uncertainty[i] = 4 * probability * (1 - probability)
+            mean_error = self.ema_error[i] / max(correction, 1e-12)
+            self.direction_consistency[i] = abs(self.signed_residual_ema[i]) / max(self.ema_error[i], 1e-12)
+            self.hardness[i] = min(1.0, 0.7 * mean_error + 0.3 * min(self.wrong_streak[i] / 8, 1.0))
+
+    def summary(self):
+        n = max(1, len(self.ema_error))
+        return {'updates': self.updates, 'mean_error_ema': math.fsum(self.ema_error) / n, 'mean_hardness': math.fsum(self.hardness) / n, 'persistent_fraction': sum((v >= 3 for v in self.wrong_streak)) / n, 'mean_uncertainty': math.fsum(self.uncertainty) / n, 'mean_direction_consistency': math.fsum(self.direction_consistency) / n, 'max_wrong_streak': max(self.wrong_streak, default=0)}
+
+@dataclass(frozen=True)
+class Diagnosis:
+    name: str
+    strength: float
+    confidence: float
+    evidence: str
+
+class ErrorProfiler:
+    """Diagnostics are hypotheses, not identified causes of prediction errors."""
+
+    def profile(self, X_train, y_train, memory, X_search, y_search, p_search):
+        if memory is None or len(memory.ema_error) != len(y_train):
+            raise ValueError('Profiler requires aligned persistent TRAIN error memory')
+        n = len(y_search)
+        residuals = [label - p for label, p in zip(y_search, p_search)]
+        absolute = [abs(r) for r in residuals]
+        mean = math.fsum(absolute) / n
+        bias = abs(math.fsum(residuals) / n)
+        variance = math.fsum((r * r for r in residuals)) / n - (math.fsum(residuals) / n) ** 2
+        memory_stats = memory.summary()
+        confidence = min(1.0, math.sqrt(n / 120))
+        groups = []
+        local_gap, missing_gap, small_gap = (0.0, 0.0, 0.0)
+        partition_bits = []
+        for j in range(len(X_train[0])):
+            present = sorted((row[j] for row in X_train if not math.isnan(row[j])))
+            threshold = 0.5 * present[(len(present) - 1) // 2] + 0.5 * present[len(present) // 2] if present else 0.0
+            low = [i for i, row in enumerate(X_search) if not math.isnan(row[j]) and row[j] <= threshold]
+            high = [i for i, row in enumerate(X_search) if not math.isnan(row[j]) and row[j] > threshold]
+            missing = [i for i, row in enumerate(X_search) if math.isnan(row[j])]
+            partition_bits.append([not math.isnan(row[j]) and row[j] > threshold for row in X_search])
+            for name, ids in (('low', low), ('high', high), ('missing', missing)):
+                if len(ids) < 3:
+                    continue
+                group_error = math.fsum((absolute[i] for i in ids)) / len(ids)
+                gap = max(0.0, group_error - mean)
+                support = min(1.0, len(ids) / 20)
+                local_gap = max(local_gap, gap * support)
+                if name == 'missing':
+                    missing_gap = max(missing_gap, gap * support)
+                if len(ids) < max(8, n * 0.1):
+                    small_gap = max(small_gap, gap * support)
+                groups.append({'feature': j, 'region': name, 'count': len(ids), 'error': group_error, 'excess_error': gap})
+        class_errors = []
+        for label in (0, 1):
+            ids = [i for i, value in enumerate(y_search) if value == label]
+            class_errors.append(math.fsum((absolute[i] for i in ids)) / max(len(ids), 1))
+        imbalance = min(y_train.count(0), y_train.count(1)) / len(y_train)
+        interaction = 0.0
+        for a in range(min(4, len(partition_bits))):
+            for b in range(a + 1, min(4, len(partition_bits))):
+                for abit, bbit in ((False, False), (False, True), (True, False), (True, True)):
+                    ids = [i for i in range(n) if partition_bits[a][i] == abit and partition_bits[b][i] == bbit]
+                    if len(ids) >= 5:
+                        signed = abs(math.fsum((residuals[i] for i in ids)) / len(ids))
+                        interaction = max(interaction, max(0.0, signed - bias - local_gap) * min(1, len(ids) / 20))
+        strengths = {'PERSISTENT_ERROR': memory_stats['persistent_fraction'], 'HIGH_RESIDUAL_VARIANCE': min(1, variance * 4), 'SIGNED_BIAS': min(1, bias * 4), 'HIGH_UNCERTAINTY': memory_stats['mean_uncertainty'], 'LOCAL_ERROR_CONCENTRATION': min(1, local_gap * 4), 'SMALL_UNSTABLE_REGION': min(1, small_gap * 4), 'MISSING_RELATED_ERROR': min(1, missing_gap * 4), 'IMBALANCE_RELATED_ERROR': min(1, abs(class_errors[0] - class_errors[1]) * 3) if imbalance < 0.35 else 0.0, 'INTERACTION_LIKE_ERROR': min(1, interaction * 3), 'NOISE_LIKE': min(1, mean * 2) * max(0, 1 - local_gap * 5 - bias * 4 - interaction * 3), 'LOW_STRUCTURED_ERROR': max(0, 1 - max(local_gap * 4, missing_gap * 4, bias * 4, interaction * 3))}
+        diagnoses = [Diagnosis(name, float(strength), confidence, 'TRAIN persistent memory and SEARCH residual partitions') for name, strength in strengths.items()]
+        return {'diagnoses': [d.__dict__ for d in diagnoses], 'memory': memory_stats, 'regions': sorted(groups, key=lambda g: g['excess_error'], reverse=True)[:8], 'search_mean_absolute_residual': mean, 'search_signed_bias': bias, 'confidence': confidence, 'interpretation': 'heuristic hypotheses, not causal conclusions'}
+
+    def profile_task(self, X, y, prediction, task):
+        """Current-parent TRAIN-OOF residual hypotheses, not predictive utility.
+
+        Multiclass uses its true K-vector residuals, not binary training.
+        Regression stays continuous and is scaled using TRAIN targets only.
+        The bounded region probe follows the existing profiler's logic.
+        """
+        n = len(y)
+        if task not in ('multiclass', 'regression') or not n or len(X) != n or (len(prediction) != n):
+            raise ValueError('Aligned task-specific residual data required')
+        if task == 'regression':
+            if any((type(v) not in (int, float) or not math.isfinite(v) for v in list(y) + list(prediction))):
+                raise ValueError('Finite continuous targets/predictions required')
+            mean = math.fsum((v / n for v in y))
+            scale = math.hypot(*(v - mean for v in y)) / math.sqrt(n)
+            scale = scale if scale > 1e-12 else 1.0
+            vectors = [[(a - b) / scale for a, b in zip(y, prediction)]]
+            labels = [None]
+        else:
+            labels = sorted(set(y))
+            k = len(labels)
+            scale = 1.0
+            if labels != list(range(k)) or k < 2 or any((type(p) is not list or len(p) != k or any((type(v) not in (int, float) or not math.isfinite(v) or v < 0 for v in p)) or (abs(math.fsum(p) - 1) > 1e-12) for p in prediction)):
+                raise ValueError('Native contiguous K-class normalized probabilities required')
+            vectors = [[int(label == c) - p[c] for label, p in zip(y, prediction)] for c in labels]
+        probes = [self._task_residual_probe(X, r) for r in vectors]
+        names = ('INTERACTION_LIKE_ERROR', 'SMALL_UNSTABLE_REGION')
+        confidence = min(1.0, math.sqrt(n / 120.0))
+        return {'task': task, 'rows': n, 'target_scale_TRAIN_only': scale, 'diagnoses': [{'name': name, 'strength': max((p[name] for p in probes)), 'confidence': confidence, 'evidence': 'Current-parent TRAIN-OOF residual partitions'} for name in names], 'per_output': [{'class': c, 'probe': p} for c, p in zip(labels, probes)], 'policy_id': 'PRODUCT002_TASK_OOF_HEURISTIC_V1', 'fold_stability': 'UNKNOWN_NOT_ESTIMATED_FROM_ONE_STREAM', 'interpretation': 'Bounded residual associations; no causal or prospective utility claim'}
+
+    def _task_residual_probe(self, X, residual):
+        n = len(residual)
+        absolute = [abs(v) for v in residual]
+        if any((not math.isfinite(v) for v in absolute)):
+            raise ValueError('Residual overflow')
+        mean = math.fsum(absolute) / n
+        bias = abs(math.fsum(residual) / n)
+        local = small = interaction = 0.0
+        bits = []
+        for j in range(len(X[0])):
+            present = sorted((row[j] for row in X if not math.isnan(row[j])))
+            threshold = 0.5 * present[(len(present) - 1) // 2] + 0.5 * present[len(present) // 2] if present else 0.0
+            low = [i for i, row in enumerate(X) if not math.isnan(row[j]) and row[j] <= threshold]
+            high = [i for i, row in enumerate(X) if not math.isnan(row[j]) and row[j] > threshold]
+            missing = [i for i, row in enumerate(X) if math.isnan(row[j])]
+            bits.append([not math.isnan(row[j]) and row[j] > threshold for row in X])
+            for ids in (low, high, missing):
+                if len(ids) < 3:
+                    continue
+                gap = max(0.0, math.fsum((absolute[i] for i in ids)) / len(ids) - mean) * min(1.0, len(ids) / 20.0)
+                local = max(local, gap)
+                if len(ids) < max(8, n * 0.1):
+                    small = max(small, gap)
+        for a in range(min(4, len(bits))):
+            for b in range(a + 1, min(4, len(bits))):
+                for av, bv in ((False, False), (False, True), (True, False), (True, True)):
+                    ids = [i for i in range(n) if bits[a][i] == av and bits[b][i] == bv]
+                    if len(ids) >= 5:
+                        signed = abs(math.fsum((residual[i] for i in ids)) / len(ids))
+                        interaction = max(interaction, max(0.0, signed - bias - local) * min(1.0, len(ids) / 20.0))
+        return {'INTERACTION_LIKE_ERROR': min(1.0, interaction * 3.0), 'SMALL_UNSTABLE_REGION': min(1.0, small * 4.0), 'mean_absolute_residual': mean, 'absolute_signed_bias': bias, 'local_excess': local}

morphtree/estimators.py

@@ -0,0 +1,156 @@
+"""Task-specific public estimators sharing the existing evolutionary engine."""
+import copy
+
+from .api import MorphTree
+
+
+def _score_targets(y, length):
+    from ._experimental.preprocessing import _m26_scalar
+    values = y.tolist() if hasattr(y, 'tolist') else y
+    if not isinstance(values, (list, tuple)) or not values or len(values) != length:
+        raise ValueError('score requires nonempty aligned scalar targets')
+    values = [_m26_scalar(value) for value in values]
+    if any(value is None for value in values):
+        raise ValueError('Missing score targets are unsupported')
+    return values
+
+
+class _TaskEstimator:
+    _task_kind = None
+    _fitted_attributes = frozenset(('task_', 'n_features_in_', 'feature_names_in_',
+        'best_family_', 'best_params_', 'stop_reason_', 'last_attempt_'))
+
+    def __init__(self, *, random_state=None, verbosity=0, use_optuna=True,
+                 max_mutations=2, time_budget='auto', n_trials='auto', n_jobs=1,
+                 capacity=None, mode='adaptive', operators=None):
+        self._engine = MorphTree(task=self._task_kind, random_state=random_state,
+            verbosity=verbosity, use_optuna=use_optuna, max_mutations=max_mutations,
+            time_budget=time_budget, n_trials=n_trials, n_jobs=n_jobs,
+            capacity=capacity, mode=mode, operators=operators)
+
+    def get_params(self, deep=True):
+        engine = self._engine
+        return copy.deepcopy(dict(random_state=engine.random_state,
+            verbosity=engine.verbose, use_optuna=engine.tuning != 'none',
+            max_mutations=engine._max_mutations, time_budget=engine.time_budget,
+            n_trials=engine.n_trials, n_jobs=engine.n_jobs, capacity=engine.capacity,
+            mode=engine.mode,
+            operators=('growth_policy:depthwise',) if engine._research_growth else None))
+
+    def set_params(self, **values):
+        params = self.get_params()
+        if set(values) - set(params):
+            raise ValueError('Unknown estimator parameter: ' + ', '.join(sorted(set(values)-set(params))))
+        replacement = type(self)(**(params | values))
+        self._engine = replacement._engine
+        return self
+
+    def __getattr__(self, name):
+        # Forward only documented attributes; do not expose the internal engine
+        # as if the task facade itself were a raw native learner.
+        if name in self._fitted_attributes or (name == 'classes_' and self._task_kind == 'classification'):
+            return copy.deepcopy(getattr(self._engine, name))
+        if name in ('random_state', 'verbosity', 'use_optuna', 'max_mutations',
+                    'time_budget', 'n_trials', 'n_jobs', 'capacity', 'mode', 'operators'):
+            return self.get_params()[name]
+        raise AttributeError(name)
+
+    def fit(self, X, y):
+        # Input materialization, context/sealed-data guards, finite budgets and
+        # fit rollback remain in the same engine as the legacy MorphTree API.
+        self._engine.fit(X, y)
+        return self
+
+    def predict(self, X):
+        from .prediction_output import prediction_array
+        return prediction_array(self._engine.predict(X),regression=self._task_kind=='regression')
+
+    def save(self, path, *, variant='all'):
+        return self._engine.save(path, variant=variant)
+
+    @classmethod
+    def load(cls, path, *, sha256=None, workdir=None):
+        engine = MorphTree.load(path, sha256=sha256, workdir=workdir)
+        allowed = ('binary', 'multiclass') if cls._task_kind == 'classification' else ('regression',)
+        if engine.task_ not in allowed:
+            workspace = getattr(engine, '_loaded_workspace', None)
+            if workspace is not None:
+                workspace.cleanup()
+            raise ValueError('Saved model task is incompatible with ' + cls.__name__)
+        # Keep loaded weights, encoder, variants, recipe and evidence unchanged.
+        # A classifier refit may switch between binary and multiclass targets.
+        engine.task = cls._task_kind
+        obj = cls.__new__(cls)
+        obj._engine = engine
+        return obj
+
+    def report(self):
+        return self._engine.report()
+
+    def get_search_report(self):
+        return self._engine.get_search_report()
+
+    def get_algorithm_program(self):
+        return self._engine.get_algorithm_program()
+
+    def get_mutation_history(self):
+        return self._engine.get_mutation_history()
+
+    def get_recipe(self):
+        return self._engine.get_recipe()
+
+    def cost_report(self):
+        return self._engine.cost_report()
+
+    def available_variants(self):
+        return self._engine.available_variants()
+
+    def save_recipe(self, path, *, variant='selected'):
+        return self._engine.save_recipe(path, variant=variant)
+
+    def export_python(self, path, *, variant='selected',output_format='python'):
+        if output_format not in ('python','numpy'):raise ValueError('output_format must be python or numpy')
+        if output_format=='python':return self._engine.export_python(path,variant=variant)
+        from .prediction_output import numpy_export_source
+        from .persistence import atomic_text,read_regular_bytes
+        import hashlib
+        # Keep the historical public-output guards and owned work directory.
+        with self._engine._public_output(path):
+            self._engine.export_python(path,variant=variant)
+            source=read_regular_bytes(path,32*1024**2).decode('utf8')
+            source=numpy_export_source(source,self.classes_ if self._task_kind=='classification' else [],self._task_kind=='regression')
+            if len(source.encode('utf8'))>32*1024**2:raise MemoryError('Historical standalone source cap exceeded')
+            atomic_text(path,source)
+        return hashlib.sha256(source.encode('utf8')).hexdigest()
+
+    def export_standalone(self,path,*,output_format='python'):
+        return self.export_python(path,output_format=output_format)
+
+    def export_algorithm(self, path):
+        return self._engine.export_algorithm(path)
+
+
+class MorphTreeClassifier(_TaskEstimator):
+    """Native evolutionary classification; resolves binary versus multiclass."""
+    _task_kind = 'classification'
+    _estimator_type = 'classifier'
+
+    def predict_proba(self, X):
+        from .prediction_output import probability_array
+        return probability_array(self._engine.predict_proba(X),len(self.classes_),n_samples=len(X))
+
+    def score(self, X, y):
+        prediction = self.predict(X)
+        targets = _score_targets(y, len(prediction))
+        return sum(a == (b.item() if hasattr(b,'item') else b) for a, b in zip(targets, prediction)) / len(targets)
+
+
+class MorphTreeRegressor(_TaskEstimator):
+    """Native evolutionary regression with an explicitly numeric target."""
+    _task_kind = 'regression'
+    _estimator_type = 'regressor'
+
+    def score(self, X, y):
+        from .metrics import r2_score
+        prediction = self.predict(X)
+        return r2_score(_score_targets(y, len(prediction)), prediction)

morphtree/examples.py

@@ -0,0 +1,25 @@
+"""Normal user code, executed by an approved host in this qualification build.
+
+No Session, checkpoint, campaign identifier or research directory is an API
+argument. Current standalone training remains disabled until a run is approved.
+The same function works for binary, multiclass and regression targets.
+"""
+from morphtree import MorphTree
+
+
+def train(X_train, y_train, *, task='auto', time_budget=300):
+    model=MorphTree(task=task,mode='baseline',random_state=42,
+                    tuning='none',time_budget=time_budget)
+    model.fit(X_train,y_train)
+    return model
+
+
+def save_and_predict(model, X_test, path, export_path):
+    model.save(path)
+    restored=MorphTree.load(path)
+    predictions=restored.predict(X_test)
+    probabilities=(restored.predict_proba(X_test)
+                   if restored.task_!='regression' else None)
+    restored.export_python(export_path)
+    return {'predictions':predictions,'probabilities':probabilities,
+            'recipe':restored.recipe(),'configuration':restored.get_params()}