slatex 0.1.0__py3-none-any.whl

slatex/__init__.py

@@ -0,0 +1,18 @@
+"""slatex — Sparse Lightweight Additive Threshold Ensemble.
+
+A small, fast, interpretable classifier for constrained hardware (edge devices,
+microcontrollers, TinyML). SLATE is an additive model (a GAM) built from simple
+threshold rules of the form "1 if a feature is at or below a learned cut, else 0",
+trained by budgeted, L1-regularized Newton boosting.
+
+Basic usage
+-----------
+>>> from slatex import SlateClassifier
+>>> clf = SlateClassifier(budget=32).fit(X_train, y_train)
+>>> clf.predict(X_test)
+>>> clf.predict_proba(X_test)
+"""
+from .classifier import NotFittedError, SlateClassifier
+
+__all__ = ["SlateClassifier", "NotFittedError", "__version__"]
+__version__ = "0.1.0"

slatex/_core.py

@@ -0,0 +1,233 @@
+"""Binary SLATE engine: budgeted, fully-corrective, L1-regularized Newton
+boosting over axis-aligned threshold indicator atoms ``h_{j,t}(x) = 1[x_j <= t]``.
+
+This module is internal. Users should use :class:`slatex.SlateClassifier`, which
+wraps this engine with label encoding, input validation, and multiclass support.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["_BinarySlate", "_sigmoid"]
+
+
+def _sigmoid(z):
+    """Numerically stable logistic sigmoid."""
+    z = np.asarray(z, dtype=np.float64)
+    out = np.empty_like(z)
+    pos = z >= 0
+    out[pos] = 1.0 / (1.0 + np.exp(-z[pos]))
+    ez = np.exp(z[~pos])
+    out[~pos] = ez / (1.0 + ez)
+    return out
+
+
+class _BinarySlate:
+    """Binary additive threshold ensemble trained by budgeted Newton boosting.
+
+    Operates on a pre-validated, finite, float64 design matrix ``X`` and a label
+    vector ``y`` with values in ``{0, 1}``. All user-facing concerns (label
+    encoding, validation, multiclass) are handled one layer up.
+    """
+
+    def __init__(self, budget=64, n_bins=32, max_iter=400, learning_rate=0.5,
+                 l2=2.0, l1=1e-3, corrective_every=5, corrective_passes=2,
+                 tol=1e-7):
+        self.budget = budget
+        self.n_bins = n_bins
+        self.max_iter = max_iter
+        self.learning_rate = learning_rate
+        self.l2 = l2
+        self.l1 = l1
+        self.corrective_every = corrective_every
+        self.corrective_passes = corrective_passes
+        self.tol = tol
+
+    # ------------------------------------------------------------------ #
+    def _bin_features(self, X):
+        """Quantile-bin every feature; store per-feature threshold grids."""
+        n, d = X.shape
+        self.thresholds_ = []
+        codes = np.empty((n, d), dtype=np.int32)
+        qs = np.linspace(0, 1, self.n_bins + 1)[1:-1]
+        for j in range(d):
+            col = X[:, j]
+            if qs.size:
+                t = np.unique(np.quantile(col, qs))
+            else:
+                t = np.empty(0, dtype=np.float64)
+            # drop degenerate thresholds (>= max never splits anything off)
+            if t.size and t[-1] >= col.max():
+                t = t[t < col.max()]
+            self.thresholds_.append(t.astype(np.float64))
+            # searchsorted maps each value to its bin index in [0, len(t)]
+            codes[:, j] = np.searchsorted(t, col, side="left")
+        return codes
+
+    # ------------------------------------------------------------------ #
+    def fit(self, X, y):
+        n, d = X.shape
+        codes = self._bin_features(X)
+        nthr = np.array([t.size for t in self.thresholds_], dtype=np.int64)
+
+        # model state -------------------------------------------------- #
+        p0 = float(np.clip(y.mean(), 1e-6, 1 - 1e-6))
+        self.intercept_ = float(np.log(p0 / (1 - p0)))
+        F = np.full(n, self.intercept_)
+        atoms: dict[tuple[int, int], float] = {}       # (j, bin) -> alpha
+        masks: dict[tuple[int, int], np.ndarray] = {}  # cached indicator vectors
+
+        ll_prev = np.inf
+        for it in range(self.max_iter):
+            p = _sigmoid(F)
+            g = p - y                              # gradient of logloss
+            h = np.maximum(p * (1 - p), 1e-12)     # Hessian diagonal
+
+            # --- greedy atom selection via per-feature histograms ----- #
+            best_gain, best = -1.0, None
+            for j in range(d):
+                k = int(nthr[j])
+                if k == 0:
+                    continue
+                Gh = np.bincount(codes[:, j], weights=g, minlength=k + 1)
+                Hh = np.bincount(codes[:, j], weights=h, minlength=k + 1)
+                Gc = np.cumsum(Gh)[:k]             # sum of g over {x_j <= t_b}
+                Hc = np.cumsum(Hh)[:k]
+                gains = Gc * Gc / (Hc + self.l2)
+                b = int(np.argmax(gains))
+                if gains[b] > best_gain:
+                    best_gain, best = float(gains[b]), (j, b, Gc[b], Hc[b])
+
+            if best is None or best_gain < self.tol:
+                break
+            j, b, G, H = best
+            key = (j, b)
+            if key not in atoms and len(atoms) >= self.budget:
+                # budget full: restrict the greedy step to existing atoms
+                key, G, H = self._best_existing(masks, g, h)
+                if key is None:
+                    break
+            if key not in masks:
+                masks[key] = (codes[:, key[0]] <= key[1])
+                atoms.setdefault(key, 0.0)
+                G = g[masks[key]].sum()
+                H = h[masks[key]].sum()
+            step = -self.learning_rate * G / (H + self.l2)
+            atoms[key] += step
+            F += step * masks[key]
+
+            # --- intercept Newton update ------------------------------ #
+            p = _sigmoid(F)
+            db = -(p - y).sum() / (np.maximum(p * (1 - p), 1e-12).sum() + self.l2)
+            self.intercept_ += db
+            F += db
+
+            # --- fully-corrective proximal phase ---------------------- #
+            if (it + 1) % self.corrective_every == 0:
+                F = self._corrective(F, y, atoms, masks)
+                ll = self._logloss(F, y)
+                if ll_prev - ll < 1e-6 and len(atoms) >= self.budget:
+                    break
+                ll_prev = ll
+
+        # final corrective polish
+        F = self._corrective(F, y, atoms, masks)
+        self._pack(atoms)
+        return self
+
+    # ------------------------------------------------------------------ #
+    def _best_existing(self, masks, g, h):
+        best_gain, best_key, bG, bH = -1.0, None, 0.0, 0.0
+        for key, m in masks.items():
+            G = g[m].sum()
+            H = h[m].sum()
+            gain = G * G / (H + self.l2)
+            if gain > best_gain:
+                best_gain, best_key, bG, bH = gain, key, G, H
+        return best_key, bG, bH
+
+    def _corrective(self, F, y, atoms, masks):
+        """Cyclic Newton + soft-threshold (prox of l1) on the active set."""
+        for _ in range(self.corrective_passes):
+            for key in list(atoms.keys()):
+                m = masks[key]
+                p = _sigmoid(F)
+                g = p - y
+                h = np.maximum(p * (1 - p), 1e-12)
+                G = g[m].sum()
+                H = h[m].sum() + self.l2
+                anew = atoms[key] - G / H
+                anew = np.sign(anew) * max(abs(anew) - self.l1 / H, 0.0)  # prox_{l1/H}
+                dF = anew - atoms[key]
+                if dF != 0.0:
+                    F = F + dF * m
+                    atoms[key] = anew
+                if atoms[key] == 0.0:
+                    del atoms[key]
+                    del masks[key]
+            # intercept
+            p = _sigmoid(F)
+            db = -(p - y).sum() / (np.maximum(p * (1 - p), 1e-12).sum() + self.l2)
+            self.intercept_ += db
+            F = F + db
+        return F
+
+    @staticmethod
+    def _logloss(F, y):
+        if F.size == 0:
+            return 0.0
+        return float(np.mean(np.log1p(np.exp(-np.where(y == 1, F, -F)))))
+
+    def _pack(self, atoms):
+        """Pack model into flat arrays for O(B) vectorized inference.
+
+        After packing, the per-feature quantile grids in ``thresholds_`` are no
+        longer needed (every inference and interpretability path uses the packed
+        ``atom_threshold_`` array instead), so they are dropped to keep the
+        serialized model as small as the live inference footprint.
+        """
+        keys = sorted(atoms.keys())
+        self.atom_feature_ = np.array([k[0] for k in keys], dtype=np.int32)
+        self.atom_threshold_ = np.array(
+            [self.thresholds_[k[0]][k[1]] for k in keys], dtype=np.float64)
+        self.atom_coef_ = np.array([atoms[k] for k in keys], dtype=np.float64)
+        self.n_atoms_ = len(keys)
+        # free training-only scaffolding so a pickled model matches its true
+        # deployment footprint (~1 KB instead of tens of KB)
+        del self.thresholds_
+
+    # ------------------------------------------------------------------ #
+    def decision_function(self, X):
+        """Raw additive margin F(x). Vectorized: O(n * B)."""
+        n = X.shape[0]
+        if self.n_atoms_ == 0:
+            return np.full(n, self.intercept_)
+        # (n, B) indicator matrix @ (B,) coefficients
+        ind = X[:, self.atom_feature_] <= self.atom_threshold_
+        return self.intercept_ + ind @ self.atom_coef_
+
+    def predict_proba_pos(self, X):
+        """P(y = 1 | x) as a 1-D array."""
+        return _sigmoid(self.decision_function(X))
+
+    # ----------------------- interpretability ------------------------- #
+    def shape_function(self, j, grid):
+        """Exact additive contribution of feature ``j`` over a grid of values."""
+        grid = np.asarray(grid, dtype=np.float64)
+        out = np.zeros_like(grid)
+        sel = self.atom_feature_ == j
+        for t, a in zip(self.atom_threshold_[sel], self.atom_coef_[sel]):
+            out += a * (grid <= t)
+        return out
+
+    def shapley_values(self, X, X_background):
+        """Exact Shapley attributions (closed form for additive models):
+        ``phi_j(x) = f_j(x_j) - E[f_j(X_j)]`` against a background set."""
+        X = np.asarray(X, dtype=np.float64)
+        B = np.asarray(X_background, dtype=np.float64)
+        phi = np.zeros((X.shape[0], X.shape[1]))
+        for jf, t, a in zip(self.atom_feature_, self.atom_threshold_,
+                            self.atom_coef_):
+            mean_bg = a * (B[:, jf] <= t).mean()
+            phi[:, jf] += a * (X[:, jf] <= t) - mean_bg
+        return phi

slatex/classifier.py

@@ -0,0 +1,355 @@
+"""Public SLATE estimator: a sparse, lightweight, interpretable classifier."""
+from __future__ import annotations
+
+import inspect
+
+import numpy as np
+
+from ._core import _BinarySlate, _sigmoid
+
+__all__ = ["SlateClassifier", "NotFittedError"]
+
+
+class NotFittedError(ValueError, AttributeError):
+    """Raised when prediction is attempted on an unfitted estimator."""
+
+
+def _check_X(X, *, ensure_2d=True):
+    """Validate a design matrix: finite float64, 2-D, non-empty."""
+    X = np.asarray(X, dtype=np.float64)
+    if ensure_2d:
+        if X.ndim == 1:
+            raise ValueError(
+                "Expected a 2-D array, got 1-D. Reshape your data with "
+                "X.reshape(-1, 1) for a single feature or X.reshape(1, -1) "
+                "for a single sample."
+            )
+        if X.ndim != 2:
+            raise ValueError(f"Expected a 2-D array, got {X.ndim}-D.")
+    if X.size == 0:
+        raise ValueError("Found an empty array with 0 sample(s) or feature(s).")
+    if not np.all(np.isfinite(X)):
+        raise ValueError(
+            "Input X contains NaN or infinity. SLATE requires finite inputs; "
+            "impute or clean your data first (e.g. sklearn SimpleImputer)."
+        )
+    return X
+
+
+class SlateClassifier:
+    """Sparse Lightweight Additive Threshold Ensemble.
+
+    A small, fast, interpretable classifier built from simple threshold rules
+    of the form ``1 if a feature is at or below a learned cut, else 0``. It is
+    a Generalized Additive Model trained by budgeted, L1-regularized Newton
+    boosting, designed for constrained hardware (edge devices, microcontrollers,
+    TinyML).
+
+    Binary and multiclass targets are both supported; multiclass is handled
+    internally via one-vs-rest. Labels may be of any type (ints, strings, etc.)
+    and are encoded automatically.
+
+    Parameters
+    ----------
+    budget : int, default=64
+        Hard cap ``B`` on the number of distinct threshold atoms per binary
+        model (controls model size and inference cost).
+    n_bins : int, default=32
+        Maximum number of quantile bins per feature (dictionary granularity).
+    max_iter : int, default=400
+        Maximum number of boosting iterations per binary model.
+    learning_rate : float, default=0.5
+        Shrinkage applied to each greedy Newton step.
+    l2 : float, default=2.0
+        Hessian ridge (Newton damping) per atom.
+    l1 : float, default=1e-3
+        Soft-threshold level in the fully-corrective proximal passes (drives
+        exact sparsity / prunes weak atoms).
+    corrective_every : int, default=5
+        Run a fully-corrective cyclic Newton + prox pass every ``k`` iterations.
+    corrective_passes : int, default=2
+        Number of cyclic passes per corrective phase.
+    tol : float, default=1e-7
+        Stop when the best available Newton gain falls below ``tol``.
+    random_state : int or None, default=0
+        Accepted for API compatibility. Training is deterministic, so this has
+        no effect on results.
+
+    Attributes
+    ----------
+    classes_ : ndarray
+        The class labels seen during :meth:`fit`, in sorted order.
+    n_features_in_ : int
+        Number of features seen during :meth:`fit`.
+    n_atoms_ : int
+        Total number of threshold atoms across all internal binary models.
+    n_parameters_ : int
+        Total parameter count (coefficients + thresholds + intercepts).
+    memory_bytes_ : int
+        Approximate size of the packed model in bytes.
+
+    Examples
+    --------
+    >>> from slatex import SlateClassifier
+    >>> import numpy as np
+    >>> X = np.random.RandomState(0).randn(200, 5)
+    >>> y = (X[:, 0] + X[:, 1] > 0).astype(int)
+    >>> clf = SlateClassifier(budget=16).fit(X, y)
+    >>> clf.predict(X[:3])
+    array([...])
+    """
+
+    _estimator_type = "classifier"
+
+    def __init__(self, budget=64, n_bins=32, max_iter=400, learning_rate=0.5,
+                 l2=2.0, l1=1e-3, corrective_every=5, corrective_passes=2,
+                 tol=1e-7, random_state=0):
+        self.budget = budget
+        self.n_bins = n_bins
+        self.max_iter = max_iter
+        self.learning_rate = learning_rate
+        self.l2 = l2
+        self.l1 = l1
+        self.corrective_every = corrective_every
+        self.corrective_passes = corrective_passes
+        self.tol = tol
+        self.random_state = random_state
+
+    # ----------------------- sklearn-style params --------------------- #
+    @classmethod
+    def _param_names(cls):
+        sig = inspect.signature(cls.__init__)
+        return sorted(p for p in sig.parameters if p != "self")
+
+    def __sklearn_tags__(self):
+        """Lazy scikit-learn (>=1.6) tag hook.
+
+        Defined so the estimator integrates with cross-validation, pipelines,
+        and grid search on modern scikit-learn, while keeping scikit-learn an
+        *optional* dependency (the import only happens if sklearn calls this).
+        Construction is delegated to scikit-learn's own ``BaseEstimator`` so it
+        stays correct across versions.
+        """
+        from sklearn.base import BaseEstimator
+        from sklearn.utils import ClassifierTags
+        tags = BaseEstimator.__sklearn_tags__(self)
+        tags.estimator_type = "classifier"
+        tags.classifier_tags = ClassifierTags()
+        return tags
+
+    def get_params(self, deep=True):
+        """Return estimator parameters (scikit-learn compatible)."""
+        return {k: getattr(self, k) for k in self._param_names()}
+
+    def set_params(self, **params):
+        """Set estimator parameters (scikit-learn compatible)."""
+        valid = set(self._param_names())
+        for k, v in params.items():
+            if k not in valid:
+                raise ValueError(
+                    f"Invalid parameter {k!r} for SlateClassifier. "
+                    f"Valid parameters are: {sorted(valid)}."
+                )
+            setattr(self, k, v)
+        return self
+
+    # --------------------------- validation --------------------------- #
+    def _validate_params(self):
+        if not (isinstance(self.budget, (int, np.integer)) and self.budget >= 1):
+            raise ValueError(f"budget must be a positive int, got {self.budget!r}.")
+        if not (isinstance(self.n_bins, (int, np.integer)) and self.n_bins >= 2):
+            raise ValueError(f"n_bins must be an int >= 2, got {self.n_bins!r}.")
+        if not (isinstance(self.max_iter, (int, np.integer)) and self.max_iter >= 1):
+            raise ValueError(f"max_iter must be a positive int, got {self.max_iter!r}.")
+        if not (self.learning_rate > 0):
+            raise ValueError(
+                f"learning_rate must be > 0, got {self.learning_rate!r}.")
+        if self.l2 < 0 or self.l1 < 0:
+            raise ValueError("l1 and l2 must be non-negative.")
+        if not (isinstance(self.corrective_every, (int, np.integer))
+                and self.corrective_every >= 1):
+            raise ValueError("corrective_every must be a positive int.")
+        if not (isinstance(self.corrective_passes, (int, np.integer))
+                and self.corrective_passes >= 0):
+            raise ValueError("corrective_passes must be a non-negative int.")
+
+    def _core_kwargs(self):
+        return dict(budget=int(self.budget), n_bins=int(self.n_bins),
+                    max_iter=int(self.max_iter),
+                    learning_rate=float(self.learning_rate),
+                    l2=float(self.l2), l1=float(self.l1),
+                    corrective_every=int(self.corrective_every),
+                    corrective_passes=int(self.corrective_passes),
+                    tol=float(self.tol))
+
+    def _check_is_fitted(self):
+        if not hasattr(self, "estimators_"):
+            raise NotFittedError(
+                "This SlateClassifier instance is not fitted yet. Call 'fit' "
+                "with appropriate arguments before using this estimator."
+            )
+
+    # ------------------------------ fit ------------------------------- #
+    def fit(self, X, y):
+        """Fit the model.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Finite numeric training data.
+        y : array-like of shape (n_samples,)
+            Target labels (any hashable type; encoded automatically).
+        """
+        self._validate_params()
+        X = _check_X(X)
+        y = np.asarray(y).ravel()
+        if y.shape[0] != X.shape[0]:
+            raise ValueError(
+                f"X and y have inconsistent lengths: {X.shape[0]} vs {y.shape[0]}.")
+
+        self.classes_, y_enc = np.unique(y, return_inverse=True)
+        if self.classes_.shape[0] < 2:
+            raise ValueError(
+                "Classifier can't train when only one class is present. "
+                f"Found classes: {self.classes_.tolist()}."
+            )
+        self.n_features_in_ = X.shape[1]
+        kw = self._core_kwargs()
+
+        if self.classes_.shape[0] == 2:
+            target = (y_enc == 1).astype(np.float64)
+            self.estimators_ = [_BinarySlate(**kw).fit(X, target)]
+            self._multiclass = False
+        else:
+            self.estimators_ = [
+                _BinarySlate(**kw).fit(X, (y_enc == c).astype(np.float64))
+                for c in range(self.classes_.shape[0])
+            ]
+            self._multiclass = True
+        return self
+
+    # --------------------------- inference ---------------------------- #
+    def _check_predict_X(self, X):
+        self._check_is_fitted()
+        X = _check_X(X)
+        if X.shape[1] != self.n_features_in_:
+            raise ValueError(
+                f"X has {X.shape[1]} features, but SlateClassifier was fitted "
+                f"with {self.n_features_in_} features."
+            )
+        return X
+
+    def decision_function(self, X):
+        """Confidence scores.
+
+        Returns a 1-D margin array for binary problems, or a 2-D array of
+        per-class margins of shape ``(n_samples, n_classes)`` for multiclass.
+        """
+        X = self._check_predict_X(X)
+        if not self._multiclass:
+            return self.estimators_[0].decision_function(X)
+        return np.column_stack([e.decision_function(X) for e in self.estimators_])
+
+    def predict_proba(self, X):
+        """Probability estimates of shape ``(n_samples, n_classes)``."""
+        X = self._check_predict_X(X)
+        if not self._multiclass:
+            p = self.estimators_[0].predict_proba_pos(X)
+            return np.column_stack([1.0 - p, p])
+        P = np.column_stack([e.predict_proba_pos(X) for e in self.estimators_])
+        # one-vs-rest normalization into a proper distribution
+        denom = np.clip(P.sum(axis=1, keepdims=True), 1e-12, None)
+        return P / denom
+
+    def predict_log_proba(self, X):
+        """Log of :meth:`predict_proba`."""
+        return np.log(np.clip(self.predict_proba(X), 1e-12, None))
+
+    def predict(self, X):
+        """Predict class labels for ``X``."""
+        proba = self.predict_proba(X)
+        idx = np.argmax(proba, axis=1)
+        return self.classes_[idx]
+
+    def score(self, X, y):
+        """Mean accuracy on the given test data and labels."""
+        y = np.asarray(y).ravel()
+        return float(np.mean(self.predict(X) == y))
+
+    # ----------------------- interpretability ------------------------- #
+    def _resolve_target(self, target):
+        """Map a user-supplied class label/index to an internal estimator index."""
+        if not self._multiclass:
+            if target is not None and target not in (None, 1, self.classes_[1]):
+                raise ValueError(
+                    "For binary problems, interpretability is reported for the "
+                    "positive class; leave target=None."
+                )
+            return 0
+        if target is None:
+            raise ValueError(
+                "target is required for multiclass models. Pass one of "
+                f"classes_={self.classes_.tolist()}."
+            )
+        matches = np.where(self.classes_ == target)[0]
+        if matches.size == 0:
+            raise ValueError(
+                f"Unknown target {target!r}. Valid classes: {self.classes_.tolist()}.")
+        return int(matches[0])
+
+    def shape_function(self, feature, grid, target=None):
+        """Exact additive contribution of one feature over a grid of values.
+
+        Parameters
+        ----------
+        feature : int
+            Feature index.
+        grid : array-like
+            Values of the feature to evaluate.
+        target : label, optional
+            Required for multiclass: which class's additive model to inspect.
+            Ignored for binary (the positive class is used).
+        """
+        self._check_is_fitted()
+        if not (0 <= feature < self.n_features_in_):
+            raise ValueError(
+                f"feature must be in [0, {self.n_features_in_}), got {feature}.")
+        est = self.estimators_[self._resolve_target(target)]
+        return est.shape_function(int(feature), grid)
+
+    def shapley_values(self, X, X_background, target=None):
+        """Exact per-feature Shapley attributions against a background set.
+
+        For multiclass, pass ``target`` to select the class model; the returned
+        array has shape ``(n_samples, n_features)``.
+        """
+        X = self._check_predict_X(X)
+        X_background = _check_X(X_background)
+        if X_background.shape[1] != self.n_features_in_:
+            raise ValueError(
+                f"X_background has {X_background.shape[1]} features, expected "
+                f"{self.n_features_in_}.")
+        est = self.estimators_[self._resolve_target(target)]
+        return est.shapley_values(X, X_background)
+
+    # ------------------------- model size ----------------------------- #
+    @property
+    def n_atoms_(self):
+        self._check_is_fitted()
+        return int(sum(e.n_atoms_ for e in self.estimators_))
+
+    @property
+    def n_parameters_(self):
+        self._check_is_fitted()
+        # per binary model: 2 * n_atoms (coef + threshold) + 1 intercept
+        return int(sum(2 * e.n_atoms_ + 1 for e in self.estimators_))
+
+    @property
+    def memory_bytes_(self):
+        self._check_is_fitted()
+        # per atom: 8 (coef) + 8 (threshold) + 4 (feature id); + 8 per intercept
+        return int(sum(e.n_atoms_ * (8 + 8 + 4) + 8 for e in self.estimators_))
+
+    def __repr__(self):
+        params = ", ".join(f"{k}={getattr(self, k)!r}" for k in self._param_names())
+        return f"SlateClassifier({params})"

slatex-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: slatex
+Version: 0.1.0
+Summary: Sparse Lightweight Additive Threshold Ensemble — a small, fast, interpretable classifier for edge devices and TinyML.
+Project-URL: Homepage, https://github.com/saikirangogineni/slatex
+Project-URL: Repository, https://github.com/saikirangogineni/slatex
+Project-URL: Issues, https://github.com/saikirangogineni/slatex/issues
+Author-email: Saikiran Gogineni <goginenisaikiran31677@gmail.com>
+Maintainer-email: Saikiran Gogineni <goginenisaikiran31677@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Saikiran Gogineni
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: boosting,classifier,edge-ai,explainable-ai,gam,generalized-additive-model,interpretable-ml,machine-learning,sparse-models,tinyml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: scikit-learn>=1.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: scikit-learn>=1.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# slatex
+
+**Sparse Lightweight Additive Threshold Ensemble** — a small, fast, interpretable
+classifier for constrained hardware (edge devices, microcontrollers, TinyML).
+
+SLATE is an additive model (a Generalized Additive Model) built from simple
+threshold rules of the form *"1 if a feature is at or below a learned cut, else 0"*.
+It is trained by L1-regularized Newton boosting: rules are selected one at a time,
+then all active rules are refit together in a corrective pass, while a hard budget
+keeps the model tiny.
+
+- **Tiny.** A hard budget caps the number of rules, so a trained model is on the
+  order of a kilobyte and inference is a handful of comparisons and adds. The
+  fitted model drops its training-time scaffolding, so a pickled/joblib-saved
+  estimator is just ~1-2 KB — the same as its live inference footprint.
+- **Interpretable.** Because the model is additive, you get exact per-feature shape
+  functions and exact Shapley attributions in closed form.
+- **Lightweight to install.** Pure NumPy at runtime — no heavy ML stack required.
+- **Familiar API.** `fit` / `predict` / `predict_proba`, drops into scikit-learn
+  pipelines and grid search. Binary *and* multiclass are supported.
+
+## Installation
+
+```bash
+pip install slatex
+```
+
+Requires Python 3.9+ and NumPy. To run the test suite you also need
+scikit-learn (`pip install "slatex[test]"`).
+
+## Quickstart
+
+```python
+import numpy as np
+from slatex import SlateClassifier
+
+rng = np.random.RandomState(0)
+X = rng.randn(500, 8)
+y = (X[:, 0] + 0.5 * X[:, 3] > 0).astype(int)
+
+clf = SlateClassifier(budget=32).fit(X, y)
+
+clf.predict(X[:5])           # class labels
+clf.predict_proba(X[:5])     # (n_samples, n_classes) probabilities
+clf.score(X, y)              # mean accuracy
+
+print(clf.n_atoms_)          # number of threshold rules used
+print(clf.memory_bytes_)     # approximate packed model size in bytes
+```
+
+Multiclass works the same way (handled internally via one-vs-rest), and labels
+can be any type — integers, strings, etc.:
+
+```python
+y = np.array(["low", "mid", "high"])[rng.randint(0, 3, size=500)]
+clf = SlateClassifier(budget=24).fit(X, y)
+clf.classes_                 # array(['high', 'low', 'mid'], dtype='<U4')
+```
+
+## Interpretability
+
+Because SLATE is additive, the contribution of each feature is exact and cheap to
+compute.
+
+```python
+# Shape function: how feature 0 contributes to the score across a range of values
+grid = np.linspace(-3, 3, 50)
+contribution = clf.shape_function(feature=0, grid=grid)   # binary
+# contribution = clf.shape_function(0, grid, target="high")  # multiclass
+
+# Exact Shapley attributions against a background sample
+phi = clf.shapley_values(X[:10], X_background=X)           # (10, n_features)
+```
+
+## Hyperparameters
+
+| Parameter | Default | Meaning |
+|---|---|---|
+| `budget` | 64 | Hard cap on the number of threshold rules per binary model |
+| `n_bins` | 32 | Max quantile bins per feature (candidate-cut granularity) |
+| `max_iter` | 400 | Max boosting iterations |
+| `learning_rate` | 0.5 | Shrinkage on each Newton step |
+| `l2` | 2.0 | Newton damping (ridge on the Hessian) |
+| `l1` | 1e-3 | Soft-threshold level for pruning weak rules |
+| `corrective_every` | 5 | Run a fully-corrective refit pass every *k* iterations |
+| `corrective_passes` | 2 | Cyclic passes per corrective phase |
+| `tol` | 1e-7 | Stop when the best Newton gain falls below this |
+
+Smaller `budget` → smaller, faster, more interpretable model. Increase `n_bins`
+for finer cuts on continuous features.
+
+## scikit-learn compatibility
+
+`SlateClassifier` implements `get_params` / `set_params` and follows the standard
+estimator API, so it composes with scikit-learn tools:
+
+```python
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.model_selection import GridSearchCV
+
+pipe = make_pipeline(StandardScaler(), SlateClassifier())
+grid = GridSearchCV(pipe, {"slateclassifier__budget": [16, 32, 64]}, cv=3)
+grid.fit(X, y)
+```
+
+(scikit-learn is optional and only needed if you use these helpers.)
+
+## Notes and requirements
+
+- Inputs must be **finite numeric arrays** (no NaN/inf). Impute or clean first.
+- Training is **deterministic**; `random_state` is accepted for API compatibility
+  but does not change results.
+- This is research-grade software released under the MIT License.
+
+## License
+
+MIT © Saikiran Gogineni

slatex-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+slatex/__init__.py,sha256=--f_5NDQFC9O2PfAoUwxavN7rPsPYAJIRMAHTbfgnI0,682
+slatex/_core.py,sha256=IzA1Mw49IuTSANeAYARNLTn9jEVwLRcRYCzGQlMiipQ,9583
+slatex/classifier.py,sha256=YFqxgrAmWim7KBJOp_YfSdKiA76-BYNLbrO0cuFFsFM,14438
+slatex-0.1.0.dist-info/METADATA,sha256=0ghTU0HFepQTfataIladqW8-YfYgyu1rN5AaEbegtNY,7311
+slatex-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+slatex-0.1.0.dist-info/licenses/LICENSE,sha256=62RL162QqdY58OxqUmFhBwG-drDX48i8ZlrSj3RWnNk,1074
+slatex-0.1.0.dist-info/RECORD,,

slatex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

slatex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saikiran Gogineni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.