morphtree 2.1.0__py3-none-win_amd64.whl

morphtree/tree.py

@@ -0,0 +1,231 @@
+"""Histogram GBDT tree, explicit missing splits and histogram subtraction."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, replace
+import heapq
+import math
+
+from .backend import PythonBackend
+
+
+def run_program(program, signals, slots):
+    """Small bounded stack interpreter. No eval, exec or code compilation."""
+    stack = []
+    for token in program:
+        if token in signals:
+            stack.append(signals[token])
+        elif token.startswith("MUL_SLOT:"):
+            stack[-1] *= slots[int(token[-1])]
+        else:
+            right, left = stack.pop(), stack.pop()
+            if token == "ADD":
+                stack.append(left + right)
+            elif token == "MUL":
+                stack.append(left * right)
+            elif token == "MIN":
+                stack.append(min(left, right))
+            elif token == "MAX":
+                stack.append(max(left, right))
+            else:
+                raise ValueError("Unknown program instruction")
+    return stack[0]
+
+
+def soft_threshold(g, l1):
+    return math.copysign(max(abs(g) - l1, 0.0), g)
+
+
+@dataclass(frozen=True)
+class TreeNode:
+    is_leaf: bool = True
+    value: float = 0.0
+    feature: int = -1
+    threshold_bin: int = -1
+    missing_left: bool = True
+    left: int = -1
+    right: int = -1
+    depth: int = 0
+
+
+class HistogramTree:
+    def __init__(self, genome, params, backend=None):
+        self.genome, self.params = genome, params
+        self.backend = backend or PythonBackend()
+        self.nodes = ()
+        self.root_count = 0
+        self.histogram_builds = 0
+        self.histogram_subtractions = 0
+
+    def effective_l2(self, depth):
+        factor = 1 + self.params.depth_reg_strength * depth if self.genome.regularization_policy == "depth_scaled" else 1
+        return self.params.l2 * factor
+
+    def score(self, g, h, depth):
+        thresholded = soft_threshold(g, self.params.l1)
+        return thresholded * thresholded / max(h + self.effective_l2(depth), 1e-12)
+
+    def leaf_value(self, g, h, count, depth, uncertainty, missing_ratio):
+        value = -soft_threshold(g, self.params.l1) / max(h + self.effective_l2(depth), 1e-12)
+        if self.genome.leaf_policy == "smoothed":
+            value *= count / (count + self.params.path_smooth)
+        elif self.genome.leaf_policy == "clipped":
+            value = max(-self.params.max_delta_step, min(self.params.max_delta_step, value))
+        elif self.genome.leaf_policy == "uncertainty":
+            value /= 1 + self.params.gate_strength * uncertainty
+        gate = (self.genome.local_policy == "low_support" and count < max(8, self.root_count / 16))
+        gate = gate or (self.genome.local_policy == "missing_heavy" and missing_ratio >= 0.5)
+        if gate:
+            value /= 1 + self.params.gate_strength
+        return value
+
+    def _histograms(self, Xb, ids, g, h, r, u, features, sizes):
+        self.histogram_builds += len(features)
+        return {f: self.backend.histogram(Xb[f], ids, g, h, r, u, sizes[f]) for f in features}
+
+    def _best_split(self, histograms, depth, features):
+        best = None
+        if depth >= self.params.max_depth:
+            return None
+        directions = (True, False) if self.genome.missing_policy == "learned" else (self.genome.missing_policy == "left",)
+        for feature in features:
+            hist = histograms[feature]
+            total = [math.fsum(row) for row in hist]
+            n, G, H, R, U = total
+            if n < 2 * self.params.min_samples_leaf:
+                continue
+            fast = self.backend.fast_split(hist, total, depth, self.genome, self.params)
+            if fast is NotImplemented and self.genome.split_program == ("OBJECTIVE_GAIN",):
+                # NumPy's ambiguous-gain fallback keeps canonical arithmetic.
+                fast = PythonBackend().fast_split(hist, total, depth, self.genome, self.params)
+            if fast is not NotImplemented:
+                if fast is not None and (best is None or round(fast[0], 12) > round(best[0], 12)):
+                    best = (fast[0], feature, fast[1], fast[2])
+                continue
+            # Python float arithmetic is the admission/tie reference, including
+            # the narrowly requested NumPy fallback for ambiguous gains.
+            hist = [[float(v) for v in row] for row in hist]
+            # Without missing observations both routes have identical statistics.
+            # Preserve the historical first tie (missing_left=True), as NumPy does.
+            feature_directions = directions[:1] if len(directions) == 2 and not any(row[0] for row in hist) else directions
+            cumulative = PythonBackend().cumulative(hist)
+            parent_score = self.score(G, H, depth)
+            # Cut 0 isolates missing values. Final cut isolates observed from missing.
+            for cut in range(len(hist[0])):
+                observed = [row[cut - 1] if cut else 0.0 for row in cumulative]
+                for missing_left in feature_directions:
+                    left = [v + (hist[k][0] if missing_left else 0.0) for k, v in enumerate(observed)]
+                    ln, lg, lh, lr, lu = left
+                    rn, rg, rh, rr, ru = [v - vleft for v, vleft in zip(total, left)]
+                    if min(ln, rn) < self.params.min_samples_leaf or min(lh, rh) < self.params.min_hessian:
+                        continue
+                    objective = 0.5 * (self.score(lg, lh, depth + 1) + self.score(rg, rh, depth + 1) - parent_score)
+                    if self.genome.split_program == ("OBJECTIVE_GAIN",):
+                        gain = objective
+                    else:
+                        signals = {"OBJECTIVE_GAIN": objective,
+                                   "RESIDUAL_VARIANCE_GAIN": max(0.0, lr * lr / ln + rr * rr / rn - R * R / n),
+                                   "BALANCE": 2 * min(ln, rn) / n,
+                                   "HESSIAN_BALANCE": 2 * min(lh, rh) / max(H, 1e-12),
+                                   "UNCERTAINTY_GAIN": (lu / ln - ru / rn) ** 2 * ln * rn / n}
+                        gain = run_program(self.genome.split_program, signals, (self.params.signal_slot_0, self.params.signal_slot_1))
+                    if math.isfinite(gain) and gain > self.params.min_gain and (best is None or round(gain, 12) > round(best[0], 12)):
+                        best = (gain, feature, cut, missing_left)
+        return best
+
+    def _lookahead_split(self, Xb, ids, g, h, r, u, features, sizes, depth):
+        """Bounded two-level interaction probe; used only when greedy splitting stalls."""
+        if depth + 1 >= self.params.max_depth or len(ids) < 4 * self.params.min_samples_leaf:
+            return None
+        best = None
+        directions = (True, False) if self.genome.missing_policy == "learned" else (self.genome.missing_policy == "left",)
+        for feature in features[:4]:
+            observed = sorted({int(Xb[feature][i]) for i in ids if Xb[feature][i] > 0})
+            if not observed:
+                continue
+            cuts = sorted({observed[min(len(observed) - 1, k * len(observed) // 4)] for k in range(4)})
+            for cut in cuts:
+                for missing_left in directions:
+                    left, right = self.backend.partition(Xb[feature], ids, cut, missing_left)
+                    if min(len(left), len(right)) < self.params.min_samples_leaf:
+                        continue
+                    future_gain = 0.0
+                    for child in (left, right):
+                        if len(child) < 2 * self.params.min_samples_leaf:
+                            continue
+                        hist = self._histograms(Xb, child, g, h, r, u, features, sizes)
+                        split = self._best_split(hist, depth + 1, features)
+                        if split is not None:
+                            future_gain += split[0]
+                    G = math.fsum(g[i] for i in ids)
+                    H = math.fsum(h[i] for i in ids)
+                    lg = math.fsum(g[i] for i in left)
+                    lh = math.fsum(h[i] for i in left)
+                    rh = H - lh
+                    if min(lh, rh) < self.params.min_hessian:
+                        continue
+                    immediate = 0.5 * (self.score(lg, lh, depth + 1) + self.score(G - lg, rh, depth + 1) - self.score(G, H, depth))
+                    gain = immediate + future_gain
+                    if gain > self.params.min_gain and (best is None or round(gain, 12) > round(best[0], 12)):
+                        best = (gain, feature, cut, missing_left)
+        return best
+
+    def fit(self, Xb, g, h, r, u, rng, *, indices=None, sizes=None):
+        n_features = len(Xb)
+        features = sorted(rng.sample(range(n_features), max(1, math.ceil(n_features * self.params.feature_fraction))))
+        ids = list(range(len(g))) if indices is None else list(indices)
+        self.root_count = len(ids)
+        sizes = sizes or [max(column, default=0) + 1 for column in Xb]
+        hist = self._histograms(Xb, ids, g, h, r, u, features, sizes)
+
+        def make_node(node_ids, depth):
+            count = len(node_ids)
+            G, H, uncertainty, missing = self.backend.node_statistics(
+                Xb, node_ids, g, h, u, features, self.genome.local_policy == "missing_heavy", self.genome.leaf_policy == "uncertainty")
+            val = self.leaf_value(G, H, count, depth, uncertainty, missing)
+            return TreeNode(value=val, depth=depth)
+
+        nodes = [make_node(ids, 0)]
+        queue, serial = [], 0
+
+        def enqueue(node_id, node_ids, node_hist):
+            nonlocal serial
+            if len(nodes) >= 2 * self.params.max_leaves - 1:
+                return
+            split = self._best_split(node_hist, nodes[node_id].depth, features)
+            if split is None and self.genome.growth_policy == "lookahead":
+                split = self._lookahead_split(Xb, node_ids, g, h, r, u, features, sizes, nodes[node_id].depth)
+            if split is None:
+                return
+            priority = nodes[node_id].depth if self.genome.growth_policy == "depthwise" else -round(split[0], 12)
+            heapq.heappush(queue, (priority, serial, node_id, node_ids, node_hist, split))
+            serial += 1
+
+        enqueue(0, ids, hist)
+        leaves = 1
+        while queue and leaves < self.params.max_leaves:
+            _, _, node_id, node_ids, parent_hist, split = heapq.heappop(queue)
+            _, feature, cut, missing_left = split
+            left_ids, right_ids = self.backend.partition(Xb[feature], node_ids, cut, missing_left)
+            left_id, right_id = len(nodes), len(nodes) + 1
+            depth = nodes[node_id].depth + 1
+            nodes.extend((make_node(left_ids, depth), make_node(right_ids, depth)))
+            nodes[node_id] = replace(nodes[node_id], is_leaf=False, feature=feature, threshold_bin=cut,
+                                     missing_left=bool(missing_left), left=left_id, right=right_id)
+            leaves += 1
+            if leaves >= self.params.max_leaves:
+                break
+            small_ids = left_ids if len(left_ids) <= len(right_ids) else right_ids
+            small_hist = self._histograms(Xb, small_ids, g, h, r, u, features, sizes)
+            large_hist = {f: self.backend.subtract(parent_hist[f], small_hist[f]) for f in features}
+            self.histogram_subtractions += len(features)
+            left_hist, right_hist = (small_hist, large_hist) if small_ids is left_ids else (large_hist, small_hist)
+            enqueue(left_id, left_ids, left_hist)
+            enqueue(right_id, right_ids, right_hist)
+        self.nodes = tuple(nodes)
+        return self
+
+    def predict_binned(self, Xb):
+        return self.backend.predict_tree(self.nodes, Xb)
+
+    def to_dict(self):
+        return {"nodes": [asdict(node) for node in self.nodes]}

morphtree/tuning.py

@@ -0,0 +1,150 @@
+"""Small deterministic, conditional native tuner; never changes structural genes."""
+from __future__ import annotations
+
+from dataclasses import asdict, replace
+import time
+import math
+
+from .metrics import logloss, rmse
+from .control import RunControl, SearchInterrupted
+
+
+TUNABLE_ORDER = ("learning_rate", "l2", "min_samples_leaf", "max_leaves", "n_estimators", "feature_fraction", "row_fraction",
+                 "path_smooth", "max_delta_step", "depth_reg_strength", "error_weight", "update_decay", "gate_strength",
+                 "signal_slot_0", "signal_slot_1")
+
+
+def tunable_parameters(genome):
+    active = set(genome.active_parameters())
+    return tuple(name for name in TUNABLE_ORDER if name in active)
+
+
+def bounded_parameter(name, value):
+    integer_limits = {"min_samples_leaf": (1, 10**9), "max_leaves": (2, 4096), "n_estimators": (1, 4096)}
+    if name in integer_limits:
+        low, high = integer_limits[name]
+        return min(high, max(low, int(round(value))))
+    if name in ("feature_fraction", "row_fraction", "learning_rate"):
+        return min(1.0, max(0.001, value))
+    if name.startswith("signal_slot_"):
+        return min(10.0, max(0.0, value))
+    return max(1e-6, min(1e6, value))
+
+
+def tuning_record(genome, base_search, base_guard):
+    return {"attempted": True, "backend": "native", "completed": False, "accepted": False,
+            "reason": "no_completed_trials", "trials": [], "active_parameters": list(genome.active_parameters()),
+            "tunable_parameters": list(tunable_parameters(genome)), "frozen_fingerprint": genome.fingerprint(),
+            "search_loss_before": base_search, "guard_loss_before": base_guard}
+
+
+def prediction_loss(model, X, y):
+    if getattr(model, 'objective', 'binary_logloss') == 'squared_error':
+        return rmse(y, model.predict_raw(X))
+    return logloss(y, model.predict_proba(X))
+
+
+def decide_tuned_candidate(base, candidate, record, X_search, y_search, X_guard, y_guard, config, base_guard_limit):
+    record["completed"] = bool(record["trials"])
+    record["selected_parameters"] = asdict(candidate.params)
+    new_search = prediction_loss(candidate, X_search, y_search)
+    new_guard = prediction_loss(candidate, X_guard, y_guard)
+    record.update(search_loss_after=new_search, guard_loss_after=new_guard)
+    floor = 0.0 if getattr(base, 'objective', 'binary_logloss') == 'squared_error' else 1e-12
+    passes = math.isfinite(new_search) and math.isfinite(new_guard) and new_search < record["search_loss_before"] - floor and new_guard <= min(
+        record["guard_loss_before"] + config.guard_tolerance, base_guard_limit + config.global_guard_tolerance)
+    if passes:
+        record.update(accepted=True, reason="accepted")
+        result = candidate
+    else:
+        record["reason"] = "rejected_or_no_search_gain" if record["completed"] else "no_completed_trials"
+        result = base
+    record["effective_parameters"] = asdict(result.params)
+    assert result.genome.fingerprint() == record["frozen_fingerprint"]
+    return result, record
+
+
+class MorphTuner:
+    """Coarse coordinate probes, sensitivity ranking and local refinement."""
+    def optimize(self, base, evaluate, X_search, y_search, X_guard, y_guard, config, base_guard_limit):
+        start = time.monotonic()
+        before = logloss(y_search, base.predict_proba(X_search))
+        guard = logloss(y_guard, base.predict_proba(X_guard))
+        record = tuning_record(base.genome, before, guard)
+        control = RunControl(getattr(self, 'cancel', None), config.tune_timeout)
+        best, best_loss = base, before
+        tried, sensitivity = set(), {}
+        stale = 0
+        proposal_list = []
+        for name in tunable_parameters(base.genome):
+            value = getattr(base.params, name)
+            if value == 0:
+                value = 0.1
+            for factor in (0.7, 1.3):
+                proposal_list.append((name, bounded_parameter(name, value * factor), "coarse"))
+        # Reserve about half the budget for sensitivity-guided refinements.
+        coarse_budget = max(2, (config.tune_trials + 1) // 2)
+        for trial_index in range(config.tune_trials):
+            try:
+                control.check()
+            except SearchInterrupted as exc:
+                record['stop_reason'] = exc.reason
+                break
+            if config.tune_timeout and time.monotonic() - start >= config.tune_timeout:
+                record["stop_reason"] = "timeout"
+                break
+            if trial_index < coarse_budget and proposal_list:
+                name, value, phase = proposal_list.pop(0)
+            else:
+                if sensitivity:
+                    ranked = sorted(sensitivity, key=lambda k: (-sensitivity[k], k))
+                    name = ranked[((trial_index - coarse_budget) // 2) % len(ranked)]
+                else:
+                    name = tunable_parameters(base.genome)[(trial_index // 2) % len(tunable_parameters(base.genome))]
+                factor = 0.85 if trial_index % 2 == 0 else 1.15
+                value, phase = bounded_parameter(name, max(getattr(best.params, name), 1e-6) * factor), "local"
+            params = replace(best.params, **{name: value})
+            key = tuple(asdict(params).items())
+            if key in tried or params == best.params:
+                continue
+            tried.add(key)
+            def callback(iteration, loss):
+                control.check()
+                return True
+            try:
+                candidate = evaluate(base.genome, params, callback=callback, early_stopping_rounds=config.early_stopping_rounds)
+            except SearchInterrupted as exc:
+                record['stop_reason'] = exc.reason
+                break
+            except (ArithmeticError, ValueError) as exc:
+                record['trials'].append({'index': trial_index, 'state': 'FAIL', 'reason': type(exc).__name__})
+                continue
+            # n_estimators is a numerical parameter: choosing a retained prefix is allowed only here.
+            if len(candidate.trees) < params.n_estimators:
+                params = replace(params, n_estimators=len(candidate.trees))
+                try:
+                    candidate = evaluate(base.genome, params, callback=callback)
+                except SearchInterrupted as exc:
+                    record['stop_reason'] = exc.reason
+                    break
+            assert candidate.genome.fingerprint() == record["frozen_fingerprint"]
+            loss = logloss(y_search, candidate.predict_proba(X_search))
+            candidate_guard = logloss(y_guard, candidate.predict_proba(X_guard))
+            feasible = math.isfinite(loss) and math.isfinite(candidate_guard) and candidate_guard <= min(
+                logloss(y_guard, best.predict_proba(X_guard)) + config.guard_tolerance,
+                guard + config.guard_tolerance, base_guard_limit + config.global_guard_tolerance)
+            gain = best_loss - loss
+            sensitivity[name] = max(sensitivity.get(name, 0.0), abs(gain))
+            record["trials"].append({"index": trial_index, "phase": phase, "changed_parameter": name,
+                                     "value": value, "search_loss": loss, "guard_loss": candidate_guard,
+                                     "feasible": feasible, "parameters": asdict(candidate.params)})
+            if feasible and loss < best_loss - 1e-12:
+                best, best_loss, stale = candidate, loss, 0
+            else:
+                stale += 1
+            if stale >= config.tune_patience and trial_index + 1 >= coarse_budget:
+                record["stop_reason"] = "local_patience"
+                break
+        record.setdefault("stop_reason", "budget_exhausted")
+        record["sensitivity"] = sensitivity
+        return decide_tuned_candidate(base, best, record, X_search, y_search, X_guard, y_guard, config, base_guard_limit)

morphtree-2.1.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: morphtree
+Version: 2.1.0
+Summary: Adaptive tree learning for tabular data with diagnostic structural evolution
+Project-URL: Homepage, https://github.com/lucalullo/morph-tree
+Project-URL: Source, https://github.com/lucalullo/morph-tree
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <3.15,>=3.12
+Requires-Dist: numpy<3,>=1.26.0
+Requires-Dist: optuna==5.0.0
+Description-Content-Type: text/markdown
+
+# MorphTree
+
+**Adaptive tree learning for tabular data, with structural evolution and a simple Python API.**
+
+MorphTree 2.1.0 supports binary classification, multiclass classification and single-target regression. It screens applicable tree families, selects a parent, diagnoses training errors and evaluates structural changes to the executable learning program. A descendant replaces its parent only when the selection criteria are satisfied; otherwise the parent is retained.
+
+Automatic preprocessing, structural evolution, final numerical optimization and model persistence are available through `fit()` and `predict()`.
+
+Discovering a learning program involves more work than fitting a single fixed model: MorphTree compares families, diagnoses errors, evaluates descendants and tunes the retained program. This search happens during `fit()`. A saved model can then predict without repeating it, while an exported frozen program can train new weights without rerunning the search, within the advanced API's data and runtime requirements. These are different forms of reuse; their costs and predictive quality depend on the workload.
+
+## Installation
+
+```bash
+pip install morphtree
+```
+
+This command selects the latest compatible release available on PyPI. Compatible prebuilt wheels include the native components and require no C compiler. See the [installation guide](https://github.com/lucalullo/morph-tree/blob/main/docs/INSTALLATION.md) for supported environments, local wheel installation and source-build requirements.
+
+## Quick start
+
+These independent examples require the optional scikit-learn package: `pip install scikit-learn`.
+
+### Binary classification
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import train_test_split
+from morphtree import MorphTreeClassifier
+
+X, y = load_breast_cancer(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(
+    X, y, test_size=0.2, random_state=42, stratify=y
+)
+
+model = MorphTreeClassifier(random_state=42)
+model.fit(X_train, y_train)
+
+predictions = model.predict(X_test)
+probabilities = model.predict_proba(X_test)
+print("Test accuracy:", model.score(X_test, y_test))
+```
+
+### Multiclass classification
+
+```python
+from sklearn.datasets import load_iris
+from sklearn.model_selection import train_test_split
+from morphtree import MorphTreeClassifier
+
+X, y = load_iris(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(
+    X, y, test_size=0.2, random_state=42, stratify=y
+)
+
+model = MorphTreeClassifier(random_state=42)
+model.fit(X_train, y_train)
+
+predictions = model.predict(X_test)
+probabilities = model.predict_proba(X_test)
+print("Test accuracy:", model.score(X_test, y_test))
+```
+
+### Regression
+
+```python
+from sklearn.datasets import load_diabetes
+from sklearn.model_selection import train_test_split
+from morphtree import MorphTreeRegressor
+
+X, y = load_diabetes(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(
+    X, y, test_size=0.2, random_state=42
+)
+
+model = MorphTreeRegressor(random_state=42)
+model.fit(X_train, y_train)
+
+predictions = model.predict(X_test)
+print("Test R2:", model.score(X_test, y_test))
+```
+
+`predict()` returns a NumPy array of shape `(n_samples,)`. Classification `predict_proba()` returns a numeric NumPy array of shape `(n_samples, n_classes)`; column `j` follows `classes_[j]`. Probabilities are finite, lie in `[0, 1]` and sum to one within floating-point tolerance. NumPy slicing such as `probabilities[:, 1]` works directly; select the column for your intended class.
+
+Classifier `score()` reports accuracy; regressor `score()` reports R². Each example evaluates on its held-out TEST split.
+
+## Structural evolution
+
+MorphTree evaluates changes to its learning program as well as numerical parameters:
+
+```text
+Preprocess data and plan resources
+    -> Screen applicable tree families and select one parent
+    -> Diagnose errors from out-of-fold training evidence
+    -> Propose and train structural descendants
+    -> Evaluate on internal SEARCH data; accept or roll back
+    -> Continue from the retained parent when the budget permits
+    -> Freeze the learning program
+    -> Run final Optuna numerical tuning and refit
+```
+
+The current finite mutation grammar changes split-objective weighting and tree-growth policy. Mutations execute during descendant training; they are not merely annotations. Accepted descendants can become parents for subsequent proposals. Evolution never forces acceptance, and a completed fit may retain its initial parent after rejecting every proposal.
+
+Adaptive evolution and final Optuna tuning are enabled by default. `mode="baseline"` provides a control without structural evolution; `use_optuna=False` disables the final numerical search. These options change the scope of fitting. See the [API reference](https://github.com/lucalullo/morph-tree/blob/main/docs/API.md) and [architecture](https://github.com/lucalullo/morph-tree/blob/main/docs/ARCHITECTURE.md).
+
+## Data and resources
+
+The public estimators accept supported NumPy arrays, pandas DataFrames and row-based tabular input. Preprocessing handles numerical and categorical columns, including supported missing-value representations. Preserve the training feature schema when predicting. Missing-value and category handling are learned from the permitted training partition.
+
+Prediction uses internal batching, preserving row order. Training does not silently discard observations to pass resource admission. Memory, time, feature cardinality and model complexity still determine whether a workload can complete. See [data and resource limits](https://github.com/lucalullo/morph-tree/blob/main/docs/PUBLIC_API_LIMITS.md) for input contracts and qualified workloads.
+
+The Python learning program remains mutable. Compiled C kernels accelerate supported numerical operations and are selected automatically; normal use requires no backend configuration. Python retains the evolutionary controller and operations outside those kernels.
+
+## Capacity and defaults
+
+The default constructor is the recommended starting point. The initial screening/evolution capacity is two rounds; with `capacity=None`, the final numerical search uses a resource-dependent domain. The selected final round count is therefore not necessarily two. Automatic trial count currently resolves to two Optuna trials.
+
+An explicit eight-round profile is available through the same API:
+
+```python
+eight_round_classifier = MorphTreeClassifier(
+    random_state=42, capacity={"n_estimators": 8}
+)
+eight_round_regressor = MorphTreeRegressor(
+    random_state=42, capacity={"n_estimators": 8}
+)
+```
+
+This fixes the round capacity for the profile; it is not guaranteed to exceed the final capacity selected by the automatic policy. More rounds can improve accuracy and increase work, but can also worsen generalization. The [capacity comparison](https://github.com/lucalullo/morph-tree/blob/main/docs/CAPACITY.md) reports results for 2, 4 and 8 rounds across six datasets and explains why the defaults remain unchanged.
+
+Other controls include `max_mutations`, `n_trials`, `time_budget`, `memory_budget`, `n_jobs` and `mode`. Their semantics and resource limits are documented in the [API reference](https://github.com/lucalullo/morph-tree/blob/main/docs/API.md).
+
+## Inspect, save and reuse
+
+After fitting the binary classifier above:
+
+```python
+print(model.get_algorithm_program())
+print(model.get_recipe())
+print(model.get_mutation_history())
+print(model.get_search_report())
+print(model.cost_report())
+
+model.save("morphtree-model.json")
+restored = MorphTreeClassifier.load("morphtree-model.json")
+restored_predictions = restored.predict(X_test)
+```
+
+`get_algorithm_program()` describes the retained family's executable learning rules. `get_recipe()` also records its numerical parameters, fitted preprocessing and class ordering; inspecting a recipe does not train a model. `save()` and `load()` preserve the learned weights for inference on new observations with the same feature schema, without repeating discovery. Regression uses the same `save()` method and `MorphTreeRegressor.load()`.
+
+```python
+model.export_standalone("predictor.py", output_format="numpy")
+```
+
+The standalone predictor includes the fitted weights and performs inference without importing MorphTree; this explicit NumPy format requires NumPy. The default export format remains dependency-free Python lists.
+
+To export the learning program for a separate training operation:
+
+```python
+model.export_algorithm("training_program.py")
+```
+
+Exporting does not train. The generated `train_encoded()` function trains new weights for the frozen family, rules and numerical parameters, without repeating family screening, OOF diagnosis, mutations or Optuna. It requires the exact MorphTree runtime used for export, input encoded with the exported preprocessing, compatible task/class labels in compact numeric buffers and an explicit TRAIN identity. It is an advanced training fragment, not a raw-data `fit(X, y)` replacement or a standalone predictor. The [API reference](https://github.com/lucalullo/morph-tree/blob/main/docs/API.md) documents its encoded-data example and integrity requirements, alongside reports, genealogy and model variants.
+
+Calling the ordinary estimator's `fit()` again runs its configured learning process; loading a model does not turn `fit()` into frozen-program training. Evaluate a reused program on fresh held-out data before relying on it for a new problem: avoiding another search does not guarantee better accuracy or a particular speedup.
+
+## Supported environments
+
+The verified runtime scope is CPython 3.12–3.14 on Windows x86-64 and Ubuntu 24.04 WSL2 x86-64. Linux wheel ABI auditing is separate from full runtime qualification on other distributions. Python 3.15, macOS and other architectures are outside the established scope.
+
+Optuna and NumPy are core dependencies. pandas and scikit-learn are optional integrations. NumPy predictions support standard slicing, vectorized operations and compatible scikit-learn metrics; this does not imply support for every scikit-learn estimator protocol.
+
+## Evidence and limitations
+
+Predictive quality, training cost and memory use depend on the dataset, family, capacity and search budget. Local checks cover native dispatch, the three tasks, persistence, exported inference and structural decision handling within the [qualification scope](https://github.com/lucalullo/morph-tree/blob/main/docs/QUALIFICATION.md).
+
+- Accepted mutations do not by themselves prove better generalization; controlled comparisons are needed to isolate their contribution.
+- An independent predictive benefit from structural evolution has not been established across diverse real-world benchmarks.
+- Screening, OOF diagnostics, descendants and Optuna add work beyond a single fixed model fit.
+- Kernel acceleration does not imply an equivalent speedup for the complete pipeline.
+- Capacity comparisons show dataset-specific gains and regressions, not a universally optimal setting.
+
+Measured results and their limitations are recorded in the [comparison report](https://github.com/lucalullo/morph-tree/blob/main/docs/COMPARISON.md), [capacity study](https://github.com/lucalullo/morph-tree/blob/main/docs/CAPACITY.md) and [benchmark methodology](https://github.com/lucalullo/morph-tree/blob/main/BENCHMARKS.md).
+
+## Documentation
+
+- [Installation](https://github.com/lucalullo/morph-tree/blob/main/docs/INSTALLATION.md)
+- [API reference](https://github.com/lucalullo/morph-tree/blob/main/docs/API.md)
+- [Architecture](https://github.com/lucalullo/morph-tree/blob/main/docs/ARCHITECTURE.md)
+- [Examples](https://github.com/lucalullo/morph-tree/tree/main/examples/)
+- [Qualification](https://github.com/lucalullo/morph-tree/blob/main/docs/QUALIFICATION.md)
+- [Contributing](https://github.com/lucalullo/morph-tree/blob/main/CONTRIBUTING.md)
+
+## License
+
+MorphTree is created by Luca Lullo and released under the [MIT License](https://github.com/lucalullo/morph-tree/blob/main/LICENSE).
+
+## Author
+
+Created by [Luca Lullo](https://github.com/lucalullo).