morphtree 2.1.0__py3-none-win_amd64.whl

morphtree/persistence.py

@@ -0,0 +1,414 @@
+"""Bounded JSON artifacts; strict graph validation, atomic writes, no pickle."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, fields, replace
+import json
+import math
+import os
+import stat
+from pathlib import Path
+import tempfile
+import uuid
+
+from .config import AlgorithmGenome, HyperParams, SPEC_VERSION, VERSION, validate_task_genome
+from .data import Binner, validate_names
+from .tree import HistogramTree, TreeNode
+from .booster import BinaryHistogramBooster
+from .public import learning_fingerprint, public_metadata, validate_recipe
+
+
+@dataclass(frozen=True)
+class LoadLimits:
+    max_bytes: int = 64 * 1024 * 1024
+    max_features: int = 4096
+    max_trees: int = 4096
+    max_nodes: int = 262144
+    max_thresholds: int = 1000000
+    max_json_depth: int = 256
+
+    def __post_init__(self):
+        for field in fields(self):
+            value = getattr(self, field.name)
+            if type(value) is not int or value < 1:
+                raise ValueError("Loader limits must be positive integers")
+
+
+def _unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError('Duplicate JSON key')
+        result[key] = value
+    return result
+
+
+def _reject_constant(value):
+    raise ValueError(f"Nonfinite JSON constant: {value}")
+
+
+def regular_file_size(path):
+    info = Path(path).stat()
+    if not stat.S_ISREG(info.st_mode):
+        raise ValueError('Model artifact must be a regular file')
+    return info.st_size
+
+
+def read_regular_bytes(path, max_bytes):
+    """Read one bounded regular-file snapshot, never wait for a FIFO writer.
+
+    POSIX nonblocking open also covers a regular-path/FIFO replacement between
+    stat and open. Descriptor validation precedes reading on every platform.
+    Caller-supplied regular-file symlinks remain supported; checksum custody
+    and typed JSON validation still apply to the exact bytes returned.
+    """
+    if type(max_bytes) is not int or max_bytes < 1:
+        raise ValueError('Positive immutable snapshot allowance required')
+    regular_file_size(path)
+    flags = os.O_RDONLY | getattr(os, 'O_BINARY', 0) | getattr(os, 'O_NONBLOCK', 0)
+    descriptor = os.open(path, flags)
+    try:
+        info = os.fstat(descriptor)
+        if not stat.S_ISREG(info.st_mode):
+            raise ValueError('Model artifact descriptor must be a regular file')
+        if info.st_size > max_bytes:
+            raise ValueError('Artifact exceeds max_bytes')
+        with os.fdopen(descriptor, 'rb') as handle:
+            descriptor = None
+            # The file ceiling is admission, not the buffer size. BufferedReader
+            # may reserve its requested length even for a tiny regular file.
+            # One extra byte detects growth without ceiling-sized allocation.
+            raw = handle.read(info.st_size + 1)
+            after = os.fstat(handle.fileno())
+        if len(raw) > max_bytes or after.st_size > max_bytes:
+            raise ValueError('Artifact exceeds max_bytes')
+        if (info.st_size, info.st_mtime_ns) != (after.st_size, after.st_mtime_ns) or len(raw) != info.st_size:
+            raise ValueError('Artifact changed while reading immutable snapshot')
+        return raw
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+
+
+def read_json(path, limits=None):
+    limits = limits or LoadLimits()
+    return decode_json_bytes(read_regular_bytes(path, limits.max_bytes), limits)
+
+
+def _admit_json_workspace(raw, limits, reserve):
+    """Conservative topology forecast before stdlib parsing, constant space.
+
+    This is resource admission, not a replacement JSON parser or an absolute
+    process-memory ceiling. Syntax, duplicate keys and finite values still go
+    through the strict decoder below. Charges include pairs-hook and validation
+    workspace; dense containers must not hide behind a file-byte multiplier.
+    """
+    estimate = 4096 + len(raw) * 12
+    if reserve is not None:
+        reserve(estimate, 'JSON decoding workspace before parsing')
+    depth = 0
+    quoted = escaped = atom = False
+    for position, byte in enumerate(raw):
+        if quoted:
+            estimate += 8
+            if escaped:
+                escaped = False
+            elif byte == 92:
+                escaped = True
+            elif byte == 34:
+                quoted = False
+        elif byte == 34:
+            if depth > limits.max_json_depth:
+                raise ValueError('JSON nesting depth exceeds supported limit')
+            estimate += 256
+            quoted = True
+            atom = False
+        elif byte in (123, 91):
+            if depth > limits.max_json_depth:
+                raise ValueError('JSON nesting depth exceeds supported limit')
+            depth += 1
+            estimate += 1024 if byte == 123 else 128
+            atom = False
+        elif byte in (125, 93):
+            depth -= 1
+            atom = False
+        elif byte in (44, 58):
+            estimate += 128
+            atom = False
+        elif byte in (9, 10, 13, 32):
+            atom = False
+        elif not atom:
+            if depth > limits.max_json_depth:
+                raise ValueError('JSON nesting depth exceeds supported limit')
+            estimate += 128
+            atom = True
+        if reserve is not None and position % 4096 == 0:
+            reserve(estimate, 'JSON topology workspace before parsing')
+    if reserve is not None:
+        reserve(estimate, 'JSON topology workspace before parsing')
+    return estimate
+
+
+def decode_json_bytes(raw, limits=None, *, reserve=None):
+    """Validate one byte snapshot; checksum and decoder see identical bytes."""
+    limits = limits or LoadLimits()
+    if type(raw) is not bytes:
+        raise ValueError('Immutable JSON bytes required')
+    if len(raw) > limits.max_bytes:
+        raise ValueError("Artifact exceeds max_bytes")
+    _admit_json_workspace(raw, limits, reserve)
+    try:
+        value = json.loads(raw, object_pairs_hook=_unique_object, parse_constant=_reject_constant)
+    except (UnicodeError, json.JSONDecodeError, RecursionError) as exc:
+        raise ValueError("Malformed or excessively nested JSON artifact") from exc
+    if not isinstance(value, dict):
+        raise ValueError("Artifact must be a JSON object")
+    # Keep iterators on the current ancestry only: a wide array must not create
+    # a second width-sized list of (child,depth) tuples during validation.
+    pending = [(iter((value,)), 0)]
+    while pending:
+        children, depth = pending[-1]
+        try:
+            node = next(children)
+        except StopIteration:
+            pending.pop()
+            continue
+        if depth > limits.max_json_depth:
+            raise ValueError('JSON nesting depth exceeds supported limit')
+        if isinstance(node, dict):
+            pending.append((iter(node.values()), depth + 1))
+        elif isinstance(node, list):
+            pending.append((iter(node), depth + 1))
+        elif isinstance(node, float) and not math.isfinite(node):
+            raise ValueError("Nonfinite JSON number")
+    if reserve is not None:
+        reserve(0, 'JSON decoding completed')
+    return value
+
+
+def atomic_text(path, text):
+    path = Path(path)
+    # The directory must already exist. Never create arbitrary parent paths from artifact content.
+    # CPython's Windows mkstemp may retry PermissionError as a name collision
+    # when os.access reports writable. Do not spin through TMP_MAX candidates:
+    # one unpredictable O_EXCL name, and preserve the actual filesystem error.
+    temporary = path.parent / ('.morphtree-' + uuid.uuid4().hex + '.tmp')
+    if os.name == 'nt':
+        # A valid final path can have insufficient suffix room for a secure
+        # temporary name. Extend only the owned temporary OS path; leave the
+        # user destination semantics and ordinary load paths unchanged.
+        temporary = os.path.abspath(temporary)
+        if not temporary.startswith('\\\\?\\'):
+            temporary = '\\\\?\\UNC\\' + temporary[2:] if temporary.startswith('\\\\') else '\\\\?\\' + temporary
+    flags = os.O_RDWR | os.O_CREAT | os.O_EXCL | getattr(os, 'O_BINARY', 0) | getattr(os, 'O_NOFOLLOW', 0)
+    fd = os.open(temporary, flags, 0o600)
+    primary = None
+    try:
+        try:
+            handle = os.fdopen(fd, "w", encoding="utf-8", newline="\n")
+        except BaseException:
+            os.close(fd)
+            raise
+        with handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except BaseException as error:
+        primary = error
+        raise
+    finally:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+        except OSError as cleanup_error:
+            if primary is None:
+                raise
+            BaseException.add_note(primary, 'Owned temporary cleanup also failed: ' + type(cleanup_error).__name__)
+
+
+def write_json(path, data):
+    atomic_text(path, json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True, allow_nan=False) + "\n")
+
+
+def require_keys(data, required, optional=()):
+    if not isinstance(data, dict) or not set(required) <= set(data) or set(data) - set(required) - set(optional):
+        raise ValueError("Unexpected or missing artifact fields")
+
+
+def finite(value, name):
+    if type(value) not in (float, int):
+        raise ValueError(f"{name} must be finite")
+    try:
+        normalized = float(value)
+    except (OverflowError, ValueError) as exc:
+        raise ValueError(f"{name} must be representable as a finite float") from exc
+    if not math.isfinite(normalized):
+        raise ValueError(f"{name} must be finite")
+    return normalized
+
+
+def integer(value, name, low, high):
+    if type(value) is not int or not low <= value <= high:
+        raise ValueError(f"Invalid {name}")
+    return value
+
+
+def species_payload(genome, params, metadata=None):
+    metadata = public_metadata(metadata or {})
+    recipe = metadata.pop('learning_recipe', None)
+    payload = {"format": "MorphTreeSpecies", "spec_version": 2 if recipe is not None else 1, "producer_version": VERSION,
+            "task": "binary_classification", "capabilities": ["numeric_dense", "missing", "split_dsl_v1", "local_gates_v1"],
+            "genome": genome.to_dict(), "parameters": asdict(params), "structural_fingerprint": genome.fingerprint(),
+            "active_parameters": list(genome.active_parameters()), "metadata": metadata}
+    if recipe is not None:
+        payload.update(learning_recipe=recipe, learning_fingerprint=learning_fingerprint(genome, params, recipe))
+    return payload
+
+
+def decode_species(data):
+    require_keys(data, ("format", "spec_version", "producer_version", "task", "capabilities", "genome", "parameters",
+                        "structural_fingerprint", "active_parameters", "metadata"), ('learning_recipe', 'learning_fingerprint'))
+    if data["format"] != "MorphTreeSpecies" or type(data["spec_version"]) is not int or data["spec_version"] not in (1, 2):
+        raise ValueError("Unsupported species format/version; 0.2 artifacts require retraining")
+    if data["task"] != "binary_classification":
+        raise ValueError("Unsupported task")
+    if data["capabilities"] != ["numeric_dense", "missing", "split_dsl_v1", "local_gates_v1"]:
+        raise ValueError("Unsupported species capabilities")
+    try:
+        require_keys(data["genome"], [field.name for field in fields(AlgorithmGenome)])
+        require_keys(data["parameters"], [field.name for field in fields(HyperParams)])
+        genome, params = AlgorithmGenome(**data["genome"]), HyperParams(**data["parameters"])
+    except (TypeError, KeyError) as exc:
+        raise ValueError("Invalid species genes/parameters") from exc
+    if data["structural_fingerprint"] != genome.fingerprint() or data["active_parameters"] != list(genome.active_parameters()):
+        raise ValueError("Species fingerprint or active parameters mismatch")
+    if not isinstance(data["metadata"], dict):
+        raise ValueError("Species metadata must be an object")
+    metadata = public_metadata(data['metadata'])
+    metadata.pop('learning_recipe', None)
+    if data['spec_version'] == 2:
+        recipe = validate_recipe(data.get('learning_recipe'))
+        if data.get('learning_fingerprint') != learning_fingerprint(genome, params, recipe):
+            raise ValueError('Learning fingerprint mismatch')
+        metadata['learning_recipe'] = recipe
+    elif 'learning_recipe' in data or 'learning_fingerprint' in data:
+        raise ValueError('Version 1 cannot contain version 2 learning fields')
+    return genome, params, metadata
+
+
+def decode_booster(data, genome, params, backend, limits=None, *, objective='binary_logloss', _aggregate_tree_count=None):
+    limits = limits or LoadLimits()
+    require_keys(data, ("base_score", "n_features", "binner", "steps", "trees"))
+    n_features = integer(data["n_features"], "n_features", 1, limits.max_features)
+    base_score = finite(data["base_score"], "base_score")
+    if objective not in ('binary_logloss', 'squared_error'):
+        raise ValueError('Unsupported booster objective')
+    if abs(base_score) > (1e100 if objective == 'squared_error' else 100):
+        raise ValueError("Implausible base score")
+    bd = data["binner"]
+    require_keys(bd, ("max_bins", "policy", "thresholds"))
+    if integer(bd["max_bins"], "max_bins", 2, 4096) != params.max_bins or bd["policy"] != genome.binning_policy:
+        raise ValueError("Binner/species mismatch")
+    cuts = bd["thresholds"]
+    if not isinstance(cuts, list) or len(cuts) != n_features:
+        raise ValueError("Binner feature count mismatch")
+    if any(not isinstance(row, list) for row in cuts) or sum(map(len, cuts)) > limits.max_thresholds:
+        raise ValueError("Threshold budget exceeded")
+    cuts = [[finite(v, "threshold") for v in row] for row in cuts]
+    for feature,row in enumerate(cuts):
+        nominal = getattr(backend, 'nominal_sizes', {}).get(feature)
+        if nominal is not None:
+            if row != list(range(nominal + 1)):
+                raise ValueError('Nominal thresholds must match the validated TRAIN vocabulary')
+        elif len(row) >= params.max_bins:
+            raise ValueError("Too many thresholds for max_bins")
+        if any(a >= b for a, b in zip(row, row[1:])):
+            raise ValueError("Binning thresholds must be strictly increasing")
+    trees, steps = data["trees"], data["steps"]
+    if not isinstance(trees, list) or not isinstance(steps, list) or not 1 <= len(trees) <= limits.max_trees:
+        raise ValueError("Invalid tree count")
+    tree_allowance=min(params.n_estimators,limits.max_trees) if _aggregate_tree_count is None else _aggregate_tree_count
+    if type(tree_allowance) is not int or not 1<=tree_allowance<=limits.max_trees:raise ValueError('Invalid aggregate tree allowance')
+    if len(trees) != len(steps) or len(trees) > tree_allowance:
+        raise ValueError("Tree/update count mismatch")
+    steps = [finite(step, "step") for step in steps]
+    for step in steps:
+        if not 0 < step <= 1:
+            raise ValueError("Invalid update weight")
+    decoded, total_nodes = [], 0
+    required_nodes = [field.name for field in fields(TreeNode)]
+    for td in trees:
+        require_keys(td, ("nodes",))
+        nodes = td["nodes"]
+        if not isinstance(nodes, list) or not nodes or len(nodes) > 2 * params.max_leaves - 1:
+            raise ValueError("Invalid tree size")
+        total_nodes += len(nodes)
+        if total_nodes > limits.max_nodes:
+            raise ValueError("Total node budget exceeded")
+        for node in nodes:
+            require_keys(node, required_nodes)
+            if type(node["is_leaf"]) is not bool or type(node["missing_left"]) is not bool:
+                raise ValueError("Node flags must be boolean")
+            if abs(finite(node["value"], "leaf value")) > 1e100:
+                raise ValueError("Leaf magnitude exceeds supported limit")
+            integer(node["depth"], "depth", 0, params.max_depth)
+            if node["is_leaf"]:
+                if any(type(node[k]) is not int or node[k] != -1 for k in ("feature", "threshold_bin", "left", "right")):
+                    raise ValueError("Leaf must not contain split fields")
+            else:
+                f = integer(node["feature"], "feature", 0, n_features - 1)
+                integer(node["threshold_bin"], "threshold_bin", 0, len(cuts[f]) + 1)
+                integer(node["left"], "left child", 0, len(nodes) - 1)
+                integer(node["right"], "right child", 0, len(nodes) - 1)
+                if node["left"] == node["right"]:
+                    raise ValueError("A split must have two distinct children")
+        visited, stack = set(), [(0, 0)]
+        while stack:
+            index, depth = stack.pop()
+            if index in visited:
+                raise ValueError("Cyclic tree or shared child")
+            visited.add(index)
+            node = nodes[index]
+            if node["depth"] != depth:
+                raise ValueError("Inconsistent tree depth")
+            if not node["is_leaf"]:
+                stack.extend(((node["left"], depth + 1), (node["right"], depth + 1)))
+        if len(visited) != len(nodes):
+            raise ValueError("Unreachable tree nodes")
+        tree = HistogramTree(genome, params, backend)
+        tree.nodes = tuple(TreeNode(**{**node, "value": finite(node["value"], "leaf value")}) for node in nodes)
+        decoded.append(tree)
+    booster = BinaryHistogramBooster(genome, params, backend=backend,
+                                     memory_enabled=objective != 'squared_error', objective=objective)
+    booster.base_score, booster.n_features_ = base_score, n_features
+    booster.binner = Binner(params.max_bins, genome.binning_policy)
+    booster.binner.thresholds = tuple(tuple(row) for row in cuts)
+    booster.trees, booster.steps = decoded, list(steps)
+    return booster
+
+
+def decode_multiclass_booster(data, params, backend, n_classes, strategy, limits=None, *, genome=None):
+    """Reuse the scalar graph validator with a single aggregate tree/node budget."""
+    limits = limits or LoadLimits()
+    if type(n_classes) is not int or n_classes<2:raise ValueError('Typed multiclass dimension required')
+    require_keys(data, ('base_score', 'n_features', 'binner', 'steps', 'trees'))
+    priors = data['base_score']
+    if not isinstance(priors, list) or len(priors) != n_classes:
+        raise ValueError('Multiclass prior dimensions disagree')
+    priors = [finite(value, 'class prior score') for value in priors]
+    if any(abs(value) > 100 for value in priors):
+        raise ValueError('Implausible class prior score')
+    trees = data['trees']
+    if not isinstance(trees, list) or not trees or len(trees) % n_classes or len(trees) > limits.max_trees:
+        raise ValueError('Multiclass requires complete rounds within the aggregate tree budget')
+    if len(trees)//n_classes > params.n_estimators:
+        raise ValueError('Multiclass round count exceeds parameters')
+    # Validate once, not once per class (which would multiply the load budgets).
+    genome=validate_task_genome('multiclass',AlgorithmGenome() if genome is None else genome)
+    booster = decode_booster({**data, 'base_score': 0.}, genome,
+        params, backend, limits, objective='squared_error', _aggregate_tree_count=len(trees))
+    if any(step != params.learning_rate for step in booster.steps):
+        raise ValueError('Multiclass steps must match the declared fixed learning rate')
+    booster.params, booster.objective, booster.n_classes, booster.base_score = params, strategy, n_classes, priors
+    return booster

morphtree/prediction_output.py

@@ -0,0 +1,35 @@
+"""Public NumPy output boundary; no learning, clipping or renormalization."""
+
+def prediction_array(values, *, regression=False):
+    import numpy as np
+    result=np.asarray(values,dtype=np.float64 if regression else object if len(values) and isinstance(values[0],str) else None)
+    if result.ndim!=1:raise ValueError('One-dimensional scalar predictions required')
+    if not regression and any((v.item() if hasattr(v,'item') else v)!=old for v,old in zip(result,values)):
+        # Never round large/mixed integer class IDs to binary64 or stringify them.
+        result=np.asarray(values,dtype=object)
+    if regression and not np.isfinite(result).all():raise ValueError('Finite regression predictions required')
+    return result
+
+def probability_array(values, n_classes, *, n_samples=None, check=None):
+    import numpy as np
+    result=np.asarray(values,dtype=np.float64)
+    if result.ndim!=2 or result.shape[1]!=n_classes or n_classes<2 or n_samples is not None and result.shape[0]!=n_samples:
+        raise ValueError('Probability shape must be (n_samples,n_classes)')
+    for start in range(0,len(result),4096):
+        if check:check()
+        block=result[start:start+4096]
+        if not np.isfinite(block).all() or np.any(block<0) or np.any(block>1):raise ValueError('Probabilities must be finite and in [0,1]')
+        if not np.allclose(block.sum(axis=1),1.,rtol=0.,atol=1e-10):raise ValueError('Probability rows must sum to one')
+    if check:check()
+    return result
+
+def numpy_export_source(source, classes, regression):
+    """Wrap explicit NumPy exports while retaining the standalone list default."""
+    import inspect
+    extra='\n# Explicit NumPy output adapter; requires NumPy, not morphtree.\n'
+    extra+='OUTPUT_FORMAT = "numpy"\nclasses_ = '+repr(list(classes))+'\n'
+    extra+=inspect.getsource(prediction_array)+'\n'+inspect.getsource(probability_array)
+    extra+='\n_morphtree_python_predict = predict\ndef predict(X):\n    return prediction_array(_morphtree_python_predict(X), regression='+repr(regression)+')\n'
+    if not regression:
+        extra+='\n_morphtree_python_predict_proba = predict_proba\ndef predict_proba(X):\n    return probability_array(_morphtree_python_predict_proba(X), len(classes_), n_samples=len(X))\n'
+    return source+extra

morphtree/prepared_bins.py

@@ -0,0 +1,82 @@
+"""Bounded, call-local reuse of exact TRAIN preprocessing, never learner fits.
+
+The facade supplies identities from its owned copied buffers. Tokens are bound
+to one encoded input object. Source, ordered sample, labels, schema, encoder,
+role, engine, bin policy and bin count all participate in the reuse key.
+Entries are private and not persisted. The cap covers retained bins/thresholds
+and conservative entry overhead, not all fit/process allocations.
+"""
+from array import array
+from collections import OrderedDict
+import hashlib
+import sys
+import time
+from .data import Binner
+
+
+IDENTITIES=('source_sha256','schema_sha256','effective_rows_sha256',
+            'effective_labels_sha256','preprocessing_sha256','engine_sha256')
+
+
+def fingerprint(binner, bins):
+    h=hashlib.sha256()
+    h.update(binner.policy.encode('ascii'));h.update(binner.max_bins.to_bytes(8,'little'))
+    for cuts in binner.thresholds:
+        h.update(len(cuts).to_bytes(8,'little'));h.update(memoryview(array('d',cuts)))
+    for column in bins:
+        h.update(column.typecode.encode('ascii'));h.update(bytes((bool(getattr(column,'nominal',False)),)))
+        h.update(len(column).to_bytes(8,'little'));h.update(memoryview(column))
+    return h.hexdigest()
+
+
+def retained_bytes(binner,bins,key):
+    # Counting shared small integers more than once is deliberately conservative.
+    def size(v):return sys.getsizeof(v)+(sum(size(x) for x in v) if type(v) is tuple else 0)
+    return (2048+size(key)
+            +sys.getsizeof(binner)+sys.getsizeof(binner.__dict__)
+            +sys.getsizeof(binner.thresholds)
+            +sum(sys.getsizeof(cuts)+sum(sys.getsizeof(v) for v in cuts) for cuts in binner.thresholds)
+            +sys.getsizeof(bins)+sum(sys.getsizeof(c)+sys.getsizeof(c.__dict__) for c in bins))
+
+
+class BinCache:
+    def __init__(self,limit_bytes,check):
+        if type(limit_bytes) is not int or limit_bytes<0 or not callable(check):raise ValueError('Finite cache allowance/check')
+        self.limit_bytes=limit_bytes;self.check=check;self.entries=OrderedDict();self.bytes=0
+        self.counts=dict(hits=0,misses=0,bypassed=0,evictions=0,peak_retained_bytes=0,reused_rows=0,preparation_seconds=0.,integrity_seconds=0.)
+    def bind(self,X,identity,role):
+        if type(identity) is not dict or set(identity)!=set(IDENTITIES):raise ValueError('Exact owned-source identity')
+        if any(type(v) is not str or len(v)!=64 or any(c not in '0123456789abcdef' for c in v) for v in identity.values()):raise ValueError('SHA256 identity fields')
+        if role not in ('TRAIN','OOF_TRAIN','TRAIN_FULL'):raise ValueError('Learning role required; no SEARCH/EXTERNAL preparation')
+        if not getattr(X,'_compact_columns',False):raise ValueError('Owned compact encoded input required')
+        return _Bound(self,X,tuple(identity[n] for n in IDENTITIES)+(role,))
+    def _get(self,X,base,genome,params,backend):
+        self.check()
+        nominal=tuple(sorted(X._nominal_sizes.items()))
+        if nominal!=tuple(sorted(backend.nominal_sizes.items())):raise ValueError('Prepared bins/backend nominal schema mismatch')
+        key=base+(len(X),X.width,genome.binning_policy,params.max_bins,nominal)
+        if key in self.entries:
+            binner,bins,size,stamp=self.entries[key];tick=time.perf_counter()
+            if fingerprint(binner,bins)!=stamp:raise ValueError('Changed call-local prepared buffers')
+            self.counts['integrity_seconds']+=time.perf_counter()-tick
+            self.entries.move_to_end(key);self.counts['hits']+=1;self.counts['reused_rows']+=len(X)
+            self.check();return binner,bins
+        self.counts['misses']+=1;tick=time.perf_counter()
+        binner=Binner(params.max_bins,genome.binning_policy).fit(X);bins=backend.bin(binner,X)
+        self.counts['preparation_seconds']+=time.perf_counter()-tick;self.check()
+        size=retained_bytes(binner,bins,key)
+        if size>self.limit_bytes:
+            self.counts['bypassed']+=1;return binner,bins
+        while self.bytes+size>self.limit_bytes:
+            _,(_,_,removed,_)=self.entries.popitem(last=False);self.bytes-=removed;self.counts['evictions']+=1
+        self.entries[key]=(binner,bins,size,fingerprint(binner,bins));self.bytes+=size
+        self.counts['peak_retained_bytes']=max(self.bytes,self.counts['peak_retained_bytes']);self.check();return binner,bins
+    def report(self):return dict(limit_bytes=self.limit_bytes,retained_bytes=self.bytes,entries=len(self.entries),**self.counts)
+    def clear(self):self.entries.clear();self.bytes=0
+
+
+class _Bound:
+    def __init__(self,owner,X,base):self.owner,self.X,self.base=owner,X,base
+    def get(self,X,genome,params,backend):
+        if X is not self.X:raise ValueError('Prepared-data token belongs to a different input object')
+        return self.owner._get(X,self.base,genome,params,backend)

morphtree/public.py

@@ -0,0 +1,106 @@
+"""Public artifact boundary. Runtime connection settings are never serializable."""
+from dataclasses import asdict
+import math
+from .config import MorphTreeConfig, canonical_hash
+
+PUBLIC_CONFIG_FIELDS = (
+    'seed', 'search_fraction', 'guard_fraction', 'enable_morphing', 'enable_tuning',
+    'structural_rounds', 'structural_mutants', 'structural_patience', 'structural_evaluations',
+    'search_timeout', 'freeze_on_budget', 'diagnostic_guidance', 'memory_enabled',
+    'min_morph_improvement', 'guard_tolerance', 'global_guard_tolerance', 'complexity_penalty',
+    'confidence_z', 'probe_fraction', 'probe_margin', 'tuner', 'tune_trials', 'tune_patience',
+    'tune_timeout', 'early_stopping_rounds', 'refit_full', 'optuna_startup_trials')
+RECIPE_FIELDS = ('seed', 'memory_enabled', 'refit_full', 'search_fraction', 'guard_fraction')
+
+def public_config(config):
+    return {name: getattr(config, name) for name in PUBLIC_CONFIG_FIELDS if hasattr(config, name)}
+
+def validate_recipe(recipe):
+    if not isinstance(recipe, dict) or set(recipe) != set(RECIPE_FIELDS) | {'partition'}:
+        raise ValueError('Invalid learning recipe fields')
+    config = MorphTreeConfig(**{name: recipe[name] for name in RECIPE_FIELDS})
+    if recipe['partition'] not in ('automatic', 'explicit', 'all'):
+        raise ValueError('Invalid learning partition')
+    return {**{name: getattr(config, name) for name in RECIPE_FIELDS}, 'partition': recipe['partition']}
+
+def recipe_settings(recipe, config=None):
+    if recipe is None:
+        return config or MorphTreeConfig()
+    recipe = validate_recipe(recipe)
+    if config is not None:
+        if config.memory_enabled != recipe['memory_enabled']:
+            raise ValueError('config.memory_enabled conflicts with the frozen learning recipe')
+        return config
+    return MorphTreeConfig(**{name: recipe[name] for name in RECIPE_FIELDS})
+
+def learning_fingerprint(genome, params, recipe):
+    return canonical_hash({'genome': genome.to_dict(), 'parameters': asdict(params),
+                           'learning_recipe': validate_recipe(recipe), 'semantics': 2})
+
+def imported_report(data):
+    """Imported annotations are untrusted. Preserve only typed, known numeric metrics.
+
+    Operational histories/free text are deliberately not carried across artifact boundaries.
+    Predictions and the explicit learning recipe are independent of this diagnostic subset.
+    """
+    result = {}
+    for name in ('base_search_loss', 'base_guard_loss', 'structure_search_loss', 'structure_guard_loss',
+                 'final_search_loss', 'final_guard_loss', 'structural_gain', 'tuning_gain'):
+        value = data.get(name)
+        if type(value) in (int, float):
+            try:
+                normalized = float(value)
+            except OverflowError:
+                continue
+            if math.isfinite(normalized):
+                result[name] = normalized
+    return result
+
+def public_metadata(metadata):
+    result = {}
+    if 'learning_recipe' in metadata:
+        result['learning_recipe'] = validate_recipe(metadata['learning_recipe'])
+    if isinstance(metadata.get('discovery_report'), dict):
+        result['discovery_report'] = imported_report(metadata['discovery_report'])
+    return result
+
+
+def imported_regression_report(data):
+    """Regression diagnostics only; never trust free-form operational annotations."""
+    result = {'task': 'regression', 'objective': 'squared_error', 'imported': True}
+    for group in ('train_metrics', 'validation_metrics'):
+        values = data.get(group)
+        if not isinstance(values, dict):
+            continue
+        kept = {}
+        for name in ('rmse', 'mae', 'r2'):
+            value = values.get(name)
+            if type(value) in (int, float):
+                try:
+                    number = float(value)
+                except OverflowError:
+                    continue
+                if math.isfinite(number) and (name == 'r2' or number >= 0):
+                    kept[name] = number
+        result[group] = kept
+    return result
+
+
+def imported_multiclass_report(data):
+    result = {'task': 'multiclass', 'imported': True}
+    for group in ('train_metrics', 'validation_metrics'):
+        values = data.get(group)
+        if not isinstance(values, dict):
+            continue
+        kept = {}
+        for name in ('logloss', 'accuracy', 'macro_f1'):
+            value = values.get(name)
+            if type(value) in (int, float):
+                try:
+                    number = float(value)
+                except OverflowError:
+                    continue
+                if math.isfinite(number) and 0 <= number and (name == 'logloss' or number <= 1):
+                    kept[name] = number
+        result[group] = kept
+    return result