codadapt 1.0.0__py3-none-any.whl

codadapt/classifier.py

@@ -0,0 +1,117 @@
+"""Native binary and shared-OVR multiclass classification."""
+
+from time import perf_counter
+
+import numpy as np
+from sklearn.base import ClassifierMixin
+from sklearn.utils.validation import check_is_fitted
+
+from ._base import _BaseCodAdapt
+from ._core import sigmoid
+from ._multiclass import fit_heads, is_multiclass, prepare
+from ._multiclass_artifact import Artifact
+
+
+class CodAdaptClassifier(ClassifierMixin, _BaseCodAdapt):
+    """Single-label classifier; probabilities follow the order in ``classes_``.
+
+    Two positive-weight classes retain the native binary path. More classes use
+    shared encoding and target-specific native OVR heads, with normalized sigmoid
+    probabilities rather than a softmax link.
+    """
+
+    _task = "classification"
+
+    def fit(self, X, y, sample_weight=None, eval_set=None):
+        """Fit binary or multiclass targets with the same constructor parameters."""
+        if not is_multiclass(y, sample_weight):
+            return super().fit(X, y, sample_weight=sample_weight, eval_set=eval_set)
+        tick = perf_counter()
+        for key in list(vars(self)):
+            if key.endswith("_"):
+                delattr(self, key)
+        data = prepare(self, X, y, sample_weight, eval_set)
+        encoder, heads, preprocessing_s = fit_heads(self, data)
+        self._ovr_artifact_ = Artifact.create(
+            encoder,
+            data.classes,
+            heads,
+            dict(random_state=self.random_state, categorical_features=self.categorical_features),
+        )
+        self._restore_aliases()
+        self.estimated_memory_bytes_ = data.estimated_bytes
+        self.timings_ = {"preprocessing": preprocessing_s, "fit_total": perf_counter() - tick}
+        if self.verbosity:
+            print(
+                f"CodAdapt multiclass fitted {self.n_classes_} unchanged native heads; fit={self.timings_['fit_total']:.3f}s"
+            )
+        self._is_fitted_ = True
+        return self
+
+    def _restore_aliases(self):
+        artifact = self._ovr_artifact_
+        state = artifact.shared_state
+        self.classes_, self.n_classes_ = state.classes, len(state.classes)
+        self.n_features_in_ = state.encoder.n_features_in_
+        self.encoder_ = self.shared_encoder_ = state.encoder
+        self.encoders_ = state.encoder.level_views_
+        if hasattr(state.encoder, "feature_names_in_"):
+            self.feature_names_in_ = state.encoder.feature_names_in_
+        self._heads_ = artifact.heads
+        self.n_iter_ = max(len(h.levels) for h in artifact.heads)
+        self.best_iteration_ = self.n_iter_
+        self.lookup_count_per_sample_ = sum(
+            len(level["main_tables"]) + len(level["tables"])
+            for head in artifact.heads
+            for level in head.levels
+        )
+
+    def decision_function(self, X):
+        """Return binary scores (n,) or multiclass OVR scores (n, K)."""
+        if hasattr(self, "_ovr_artifact_"):
+            check_is_fitted(self)
+            return self._ovr_artifact_.decision_function(X)
+        return self._decision(X)
+
+    def predict_proba(self, X):
+        """Return class-ordered probabilities, shape (n_samples, n_classes)."""
+        if hasattr(self, "_ovr_artifact_"):
+            check_is_fitted(self)
+            return self._ovr_artifact_.predict_proba(X)
+        positive = sigmoid(self._decision(X))
+        return np.column_stack((1.0 - positive, positive))
+
+    def predict(self, X):
+        """Return original labels; multiclass ties select the first class."""
+        if hasattr(self, "_ovr_artifact_"):
+            check_is_fitted(self)
+            return self._ovr_artifact_.predict(X)
+        score = self._decision(X)
+        return self.classes_[(score > 0.0).astype(np.intp)]
+
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.classifier_tags.multi_class = True
+        return tags
+
+    def _more_tags(self):
+        return {**super()._more_tags(), "binary_only": False}
+
+    def __getstate__(self):
+        state = super().__getstate__().copy()
+        if "_ovr_artifact_" in state:
+            for key in (
+                "classes_",
+                "encoder_",
+                "shared_encoder_",
+                "encoders_",
+                "feature_names_in_",
+                "_heads_",
+            ):
+                state.pop(key, None)
+        return state
+
+    def __setstate__(self, state):
+        super().__setstate__(state)
+        if "_ovr_artifact_" in state:
+            self._restore_aliases()

codadapt/experimental/__init__.py

@@ -0,0 +1,13 @@
+"""Opt-in experimental exports; the default CodAdapt estimators are unchanged."""
+
+from ._compiler import CompilationError, compile_ebm
+from ._model import CompiledEBMClassifier, CompiledEBMRegressor
+from ._safe_blend import SafeBlendRegressor
+
+__all__ = [
+    "CompilationError",
+    "CompiledEBMClassifier",
+    "CompiledEBMRegressor",
+    "SafeBlendRegressor",
+    "compile_ebm",
+]

codadapt/experimental/_compiler.py

@@ -0,0 +1,166 @@
+"""Exact additive EBM compilation, restricted to a verified optional dependency."""
+
+import numbers
+
+import numpy as np
+import pandas as pd
+
+from ._model import CompiledEBMClassifier, CompiledEBMRegressor, _frame, _Runtime
+
+
+class CompilationError(ValueError):
+    """REJECT: no compiled model is returned when the contract cannot be verified."""
+
+    compiler_status_ = "REJECT"
+
+
+def compile_ebm(teacher, *, X_verify, max_states=None):
+    """Compile a fitted additive EBM with mandatory independent verification.
+
+    Supports interpret-core 0.7.8, binary classification and scalar regression.
+    X_verify must be a nonempty held-out DataFrame with teacher feature names.
+    max_states limits exact lookup entries (including missing/unknown states).
+    No approximation, fitting or teacher retention occurs. Raw output must be
+    bitwise equal; probabilities must be within absolute tolerance 1e-15.
+    """
+    try:
+        from importlib.metadata import version
+
+        from interpret.glassbox import ExplainableBoostingClassifier, ExplainableBoostingRegressor
+    except ImportError as exc:
+        raise ImportError("Compilation requires the optional codadapt[ebm] dependency.") from exc
+    if version("interpret-core") != "0.7.8":
+        raise CompilationError("REJECT: only interpret-core 0.7.8 has been validated.")
+    if type(teacher) not in (ExplainableBoostingClassifier, ExplainableBoostingRegressor):
+        raise CompilationError("REJECT: expected a supported fitted additive EBM teacher.")
+    try:
+        return _compile(
+            teacher, X_verify, max_states, type(teacher) is ExplainableBoostingClassifier
+        )
+    except CompilationError:
+        raise
+    except (ValueError, TypeError, AttributeError, IndexError, KeyError, OverflowError) as exc:
+        raise CompilationError(
+            f"REJECT: unsupported model/schema or verification failure: {exc}"
+        ) from exc
+
+
+def _compile(t, x, budget, classification):
+    if not isinstance(x, pd.DataFrame) or len(x) == 0 or not x.columns.is_unique:
+        raise CompilationError("REJECT: X_verify must be a nonempty unique-column DataFrame.")
+    columns = list(t.feature_names_in_)
+    p = len(columns)
+    if (
+        not p
+        or len(set(columns)) != p
+        or any(not isinstance(c, str) for c in columns)
+        or list(x.columns) != columns
+    ):
+        raise CompilationError("REJECT: verification feature names/order must match the teacher.")
+    if budget is not None and (
+        isinstance(budget, bool) or not isinstance(budget, numbers.Integral) or budget < 0
+    ):
+        raise CompilationError("REJECT: max_states must be a nonnegative integer or None.")
+    if (
+        list(t.term_features_) != [(j,) for j in range(p)]
+        or len(t.bins_) != p
+        or len(t.term_scores_) != p
+    ):
+        raise CompilationError("REJECT: only ordered additive univariate terms are supported.")
+    if len(t.feature_types_in_) != p or any(
+        v not in ("continuous", "nominal", "ordinal") for v in t.feature_types_in_
+    ):
+        raise CompilationError("REJECT: unsupported feature type.")
+    if getattr(t, "link_", None) != ("logit" if classification else "identity"):
+        raise CompilationError("REJECT: unsupported output link.")
+    intercept = np.asarray(t.intercept_, dtype=float)
+    if intercept.size != 1 or not np.isfinite(intercept).all():
+        raise CompilationError("REJECT: finite scalar intercept required; multiclass unsupported.")
+    if classification and len(t.classes_) != 2:
+        raise CompilationError("REJECT: binary classification only.")
+    specs = []
+    numeric_unknown = []
+    capacity = payload = 0
+    for j, levels in enumerate(t.bins_):
+        bins = levels[0]
+        v = np.asarray(t.term_scores_[j], dtype=float)
+        if v.ndim != 1 or len(v) < 2 or not np.isfinite(v).all():
+            raise CompilationError("REJECT: invalid or nonfinite cell values.")
+        if isinstance(bins, dict):
+            if any(not isinstance(k, str) for k in bins):
+                raise CompilationError("REJECT: categorical bin labels must be strings.")
+            if any(
+                isinstance(i, bool)
+                or not isinstance(i, numbers.Integral)
+                or i < 1
+                or i >= len(v) - 1
+                for i in bins.values()
+            ):
+                raise CompilationError("REJECT: invalid category bin index.")
+            keys = pd.Index(list(bins))
+            values = np.array([v[i] for i in bins.values()] + [v[-1], v[0]])
+            specs.append((False, keys, values))
+            capacity += len(values)
+            payload += values.nbytes + sum(len(k.encode("utf8")) + 8 for k in keys)
+        else:
+            cuts = np.asarray(bins, dtype=float)
+            if (
+                cuts.ndim != 1
+                or len(v) != len(cuts) + 3
+                or not np.isfinite(cuts).all()
+                or np.any(np.diff(cuts) <= 0)
+            ):
+                raise CompilationError("REJECT: invalid numeric cuts/cells.")
+            values = v[1:-1]
+            keep = values[1:].view("u8") != values[:-1].view("u8")
+            # Lossless equal-neighbor coalescing only, preserving cut semantics.
+            edges = cuts[keep].copy()
+            values = np.r_[values[np.r_[True, keep]], v[0]]
+            specs.append((True, edges, values))
+            numeric_unknown.append(v[-1])
+            capacity += len(values) + 1  # Includes teacher numeric unknown-state audit slot.
+            payload += edges.nbytes + values.nbytes + 8
+    if budget is not None and capacity > budget:
+        raise CompilationError(
+            f"REJECT: exact export requires {capacity} states, budget is {budget}."
+        )
+    x = _frame(x, columns, specs)
+    model = CompiledEBMClassifier() if classification else CompiledEBMRegressor()
+    model._runtime_ = _Runtime(columns, float(intercept.ravel()[0]), specs, numeric_unknown)
+    model.feature_names_in_ = np.asarray(columns, dtype=object)
+    model.n_features_in_ = p
+    if classification:
+        model.classes_ = np.array(t.classes_, copy=True)
+    raw = model._raw(x)
+    expected = np.asarray(t.decision_function(x) if classification else t.predict(x), dtype=float)
+    if (
+        expected.shape != raw.shape
+        or not np.isfinite(raw).all()
+        or not np.array_equal(expected.view("u8"), raw.view("u8"))
+    ):
+        raise CompilationError("REJECT: raw-score verification failed (exact float64 required).")
+    probability_error = None
+    if classification:
+        got = model.predict_proba(x)
+        ref = np.asarray(t.predict_proba(x), dtype=float)
+        if ref.shape != got.shape or not np.isfinite(ref).all():
+            raise CompilationError("REJECT: invalid teacher probabilities.")
+        probability_error = float(np.max(abs(got - ref)))
+        if probability_error > 1e-15:
+            raise CompilationError(
+                "REJECT: probability verification exceeded absolute tolerance 1e-15."
+            )
+    model.compiler_status_ = "SAFE"
+    model.required_capacity_ = capacity
+    model.compiled_state_count_ = capacity
+    model.estimated_memory_bytes_ = payload
+    model.teacher_type_ = type(t).__name__
+    model.task_ = "classification" if classification else "regression"
+    model.verification_error_ = {
+        "raw_max_absolute_error": 0.0,
+        "raw_bit_mismatches": 0,
+        "probability_max_absolute_error": probability_error,
+        "probability_absolute_tolerance": 1e-15,
+        "verification_rows": len(x),
+    }
+    return model

codadapt/experimental/_model.py

@@ -0,0 +1,174 @@
+"""Standalone ordered NumPy lookup runtime. No teacher imports or retained teacher."""
+
+import numpy as np
+import pandas as pd
+from scipy.special import expit
+from sklearn.base import BaseEstimator, ClassifierMixin, RegressorMixin
+from sklearn.utils.validation import check_is_fitted
+
+
+class _Runtime:
+    def __init__(self, columns, intercept, specs, numeric_unknown):
+        self.columns = tuple(columns)
+        self.intercept = intercept
+        self.cache = {}
+        self.numeric_unknown = np.array(numeric_unknown, dtype=float)
+        numeric = [(e, v) for num, e, v in specs if num]
+        self.edge_buffer = np.concatenate([e for e, _ in numeric]) if numeric else np.empty(0)
+        self.value_buffer = np.concatenate([v for _, v in numeric]) if numeric else np.empty(0)
+        self.specs = []
+        ec = vc = 0
+        for num, edges, values in specs:
+            if num:
+                edges = self.edge_buffer[ec : ec + len(edges)]
+                values = self.value_buffer[vc : vc + len(values)]
+                ec += len(edges)
+                vc += len(values)
+            self.specs.append((num, edges, values))
+
+    def __getstate__(self):
+        state = self.__dict__.copy()
+        state["cache"] = {}
+        state["specs"] = [
+            (True, len(e), len(v)) if num else (False, e, v) for num, e, v in self.specs
+        ]
+        return state
+
+    def __setstate__(self, state):
+        specs = state.pop("specs")
+        self.__dict__.update(state)
+        self.specs = []
+        ec = vc = 0
+        for num, edges, values in specs:
+            if num:
+                self.specs.append(
+                    (True, self.edge_buffer[ec : ec + edges], self.value_buffer[vc : vc + values])
+                )
+                ec += edges
+                vc += values
+            else:
+                self.specs.append((False, edges, values))
+
+    def _categorical(self, j, col, keys, values):
+        if isinstance(col.dtype, pd.CategoricalDtype):
+            levels = col.cat.categories
+            cached = self.cache.get(j)
+            if cached is None or cached[0] is not levels:
+                idx = keys.get_indexer(levels)
+                idx[idx < 0] = len(keys)
+                aligned = np.r_[values[idx], values[-1]]
+                self.cache[j] = (levels, aligned)
+            else:
+                aligned = cached[1]
+            return aligned[col.cat.codes.to_numpy()]
+        codes, levels = pd.factorize(col, sort=False)
+        idx = keys.get_indexer(levels)
+        idx[idx < 0] = len(keys)
+        return np.r_[values[idx], values[-1]][codes]
+
+    def raw(self, x):
+        # Fixed policy: small C-order blocks; otherwise ordered feature loop.
+        n = len(x)
+        out = np.full(n, self.intercept)
+        numeric = x.to_numpy(copy=False) if all(s[0] for s in self.specs) else None
+        mask = np.empty(n, bool)
+        width = min(16, len(self.specs))
+        buffer = np.empty((width + 1, n), order="C") if n <= 32 else None
+        used = 0
+        for j, (num, edges, values) in enumerate(self.specs):
+            if num:
+                a = (
+                    np.asarray(numeric[:, j], float)
+                    if numeric is not None
+                    else x[self.columns[j]].to_numpy(dtype=float, na_value=np.nan)
+                )
+                a = np.ascontiguousarray(a)
+                idx = np.searchsorted(edges, a, side="right")
+                np.isnan(a, out=mask)
+                np.copyto(idx, len(values) - 1, where=mask)
+                v = values[idx]
+            else:
+                v = self._categorical(j, x[self.columns[j]], edges, values)
+            if buffer is None:
+                np.add(out, v, out=out)
+            else:
+                if used == 0:
+                    buffer[0] = out
+                used += 1
+                buffer[used] = v
+                if used == width or j == len(self.specs) - 1:
+                    np.add.accumulate(buffer[: used + 1], axis=0, out=buffer[: used + 1])
+                    out[:] = buffer[used]
+                    used = 0
+        return out
+
+
+def _frame(x, columns, specs):
+    if not isinstance(x, pd.DataFrame) or not x.columns.is_unique:
+        raise ValueError("Expected a DataFrame with unique string feature names.")
+    if len(x.columns) != len(columns) or set(x.columns) != set(columns):
+        raise ValueError("Feature schema must exactly match the compiled model.")
+    if tuple(x.columns) != tuple(columns):
+        x = x.loc[:, list(columns)]
+    converted = False
+    for j, (num, _, _) in enumerate(specs):
+        col = x.iloc[:, j]
+        if num:
+            if (
+                not pd.api.types.is_numeric_dtype(col.dtype)
+                or pd.api.types.is_complex_dtype(col.dtype)
+                or pd.api.types.is_bool_dtype(col.dtype)
+            ):
+                raise ValueError(f"Numeric feature {columns[j]!r} needs real numeric dtype.")
+            if isinstance(col.dtype, pd.api.extensions.ExtensionDtype):
+                if not converted:
+                    x = x.copy()
+                    converted = True
+                x[columns[j]] = col.to_numpy(dtype=float, na_value=np.nan)
+        else:
+            levels = (
+                col.cat.categories
+                if isinstance(col.dtype, pd.CategoricalDtype)
+                else pd.unique(col.dropna())
+            )
+            if any(not isinstance(v, str) for v in levels):
+                raise ValueError(f"Categorical feature {columns[j]!r} supports string labels only.")
+    return x
+
+
+class _CompiledBase(BaseEstimator):
+    def fit(self, X, y=None):
+        """Compiled estimators cannot be trained; use compile_ebm with a fitted teacher."""
+        raise TypeError(
+            "Compiled estimators are not trainable; use compile_ebm(teacher, X_verify=...)."
+        )
+
+    def _raw(self, x):
+        check_is_fitted(self, "_runtime_")
+        return self._runtime_.raw(_frame(x, self.feature_names_in_, self._runtime_.specs))
+
+
+class CompiledEBMClassifier(ClassifierMixin, _CompiledBase):
+    """Experimental compiler-produced binary classifier; not a trainable learner."""
+
+    def decision_function(self, X):
+        """Return verified exact raw logits in the teacher's class order."""
+        return self._raw(X)
+
+    def predict_proba(self, X):
+        """Return numerically equivalent probabilities, not bitwise teacher probabilities."""
+        p = expit(self.decision_function(X))
+        return np.column_stack((1 - p, p))
+
+    def predict(self, X):
+        """Return original labels by probability argmax; ties select classes_[0]."""
+        probabilities = self.predict_proba(X)
+        return self.classes_[np.argmax(probabilities, axis=1)]
+
+
+class CompiledEBMRegressor(RegressorMixin, _CompiledBase):
+    """Experimental compiler-produced single-target regressor; not trainable."""
+
+    def predict(self, X):
+        """Return verified exact regression predictions."""
+        return self._raw(X)

codadapt/experimental/_rational.py

@@ -0,0 +1,133 @@
+"""Frozen native Rational16 kernel; internal implementation, not a public estimator."""
+
+import numpy as np
+import pandas as pd
+from scipy.optimize import minimize
+
+
+class Codes:
+    def __init__(self, bins=16, cats=()):
+        self.bins = bins
+        self.cats = tuple(cats)
+
+    def fit(self, x):
+        a = np.asarray(x)
+        self.spec = []
+        self.sizes = []
+        for j in range(a.shape[1]):
+            v = a[:, j]
+            if j in self.cats:
+                counts = pd.Series(v).dropna().value_counts()
+                values = counts.index[: self.bins].tolist()
+                spec = {v: i + 2 for i, v in enumerate(values)}
+                size = len(values) + 2
+            else:
+                v = np.asarray(v, dtype=float)
+                finite = v[np.isfinite(v)]
+                spec = (
+                    np.unique(np.quantile(finite, np.linspace(0, 1, self.bins + 1)[1:-1]))
+                    if len(finite)
+                    else np.array([])
+                )
+                size = len(spec) + 2
+            self.spec.append(spec)
+            self.sizes.append(size)
+        return self
+
+    def transform(self, x):
+        a = np.asarray(x)
+        z = np.zeros(a.shape, dtype=np.int32)
+        for j, spec in enumerate(self.spec):
+            if isinstance(spec, dict):
+                s = pd.Series(a[:, j])
+                z[:, j] = s.map(spec).fillna(1).astype(np.int32)
+                z[s.isna().to_numpy(), j] = 0
+            else:
+                v = np.asarray(a[:, j], dtype=float)
+                z[:, j] = np.searchsorted(spec, v, side="right") + 1
+                z[~np.isfinite(v), j] = 0
+        return z
+
+
+class Rational:
+    def __init__(self, bins=16, ridge=0.001, seed=0, maxiter=100, cats=()):
+        self.bins, self.ridge, self.seed = bins, ridge, seed
+        self.maxiter, self.cats = maxiter, cats
+
+    @staticmethod
+    def objective(theta, z, offsets, target, ridge):
+        m = int(offsets[-1])
+        num = np.full(len(z), theta[0])
+        den = np.ones(len(z))
+        for j in range(z.shape[1]):
+            idx = offsets[j] + z[:, j]
+            num += theta[1 + idx]
+            den += theta[1 + m + idx]
+        pred = num / den
+        res = pred - target
+        g = np.zeros_like(theta)
+        dn = res / den / len(z)
+        dd = -dn * pred
+        g[0] = dn.sum()
+        for j in range(z.shape[1]):
+            lo, hi = offsets[j : j + 2]
+            g[1 + lo : 1 + hi] = np.bincount(z[:, j], weights=dn, minlength=hi - lo)
+            g[1 + m + lo : 1 + m + hi] = np.bincount(z[:, j], weights=dd, minlength=hi - lo)
+        g[1:] += ridge * theta[1:]
+        return 0.5 * np.mean(res**2) + 0.5 * ridge * (theta[1:] @ theta[1:]), g
+
+    def fit(self, x, y):
+        self.encoder = Codes(self.bins, self.cats).fit(x)
+        z = self.encoder.transform(x)
+        self.offsets = np.r_[0, np.cumsum(self.encoder.sizes)]
+        m = self.offsets[-1]
+        self.mean, self.scale = float(np.mean(y)), max(float(np.std(y)), 1e-12)
+        target = (np.asarray(y) - self.mean) / self.scale
+        theta = np.zeros(1 + 2 * m)
+        # Nonzero training-only numerator initializes denominator derivatives.
+        for j in range(z.shape[1]):
+            lo, hi = self.offsets[j : j + 2]
+            sums = np.bincount(z[:, j], weights=target, minlength=hi - lo)
+            counts = np.bincount(z[:, j], minlength=hi - lo)
+            theta[1 + lo : 1 + hi] = sums / (counts + 5) / z.shape[1]
+        self.trace = []
+        cached = None
+
+        def objective(v, *args):
+            nonlocal cached
+            value, gradient = self.objective(v, *args)
+            cached = (v.copy(), float(value))
+            return value, gradient
+
+        def callback(v):
+            # L-BFGS-B has already evaluated the accepted iterate. Keep this
+            # fit-local scalar instead of recomputing its full gradient to log it.
+            if cached is None or not np.array_equal(v, cached[0]):
+                raise RuntimeError("Diagnostic objective does not match the accepted iterate.")
+            self.trace.append(cached[1])
+
+        result = minimize(
+            objective,
+            theta,
+            args=(z, self.offsets, target, self.ridge),
+            jac=True,
+            method="L-BFGS-B",
+            bounds=[(None, None)] * (m + 1) + [(0, 8)] * m,
+            options={"maxiter": self.maxiter, "ftol": 1e-9},
+            callback=callback,
+        )
+        self.theta = result.x
+        self.converged = bool(result.success)
+        self.solver_message = str(result.message)
+        return self
+
+    def predict(self, x):
+        z = self.encoder.transform(x)
+        m = self.offsets[-1]
+        num = np.full(len(z), self.theta[0])
+        den = np.ones(len(z))
+        for j in range(z.shape[1]):
+            idx = self.offsets[j] + z[:, j]
+            num += self.theta[1 + idx]
+            den += self.theta[1 + m + idx]
+        return self.mean + self.scale * num / den