catfishml 0.4.0__tar.gz

catfishml-0.4.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.pyd
+*.so
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/

catfishml-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CatfishML Contributors
+
+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.

catfishml-0.4.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: catfishml
+Version: 0.4.0
+Summary: NeuroSplit Boosting for tabular data with differentiable soft trees and neural gating.
+Project-URL: Homepage, https://github.com/catfishml/catfishml
+Project-URL: Repository, https://github.com/catfishml/catfishml
+Project-URL: Issues, https://github.com/catfishml/catfishml/issues
+Author: CatfishML Contributors
+License: MIT
+License-File: LICENSE
+Keywords: gradient-boosting,machine-learning,pytorch,soft-decision-tree,tabular
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.10
+Requires-Dist: torch>=2.1
+Requires-Dist: typing-extensions>=4.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# catfishml
+
+`catfishml` is a Python library for **OmniBoost++**: generalized boosting with adaptive routing across heterogeneous weak learners (linear, spline/GAM-like, adaptive-depth MLP, differentiable soft tree).
+
+## Why catfishml
+
+- Adaptive residual router with complexity/redundancy penalties.
+- Additive boosting in natural predictor space with Newton-style targets.
+- Numeric + categorical support (categorical embeddings).
+- Missing value handling with `SimpleImputer` or MICE-style `IterativeImputer`.
+- Adaptive behavior:
+  - automatic objective/distribution and metric selection,
+  - linearity probe (auto linear vs nonlinear mode),
+  - adaptive MLP depth + adaptive tree depth.
+- CPU/GPU via PyTorch.
+- Automatic dependency install for missing core libraries (can be disabled).
+
+## Install
+
+```bash
+pip install catfishml
+```
+
+For development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from catfishml import FishyCatClassifier
+
+X = pd.DataFrame(
+    {
+        "age": [25, 31, 45, None, 39, 22, 55],
+        "income": [2200, 3400, 7600, 5100, None, 1900, 8800],
+        "city": ["A", "B", "A", "C", "B", None, "A"],
+    }
+)
+y = [0, 0, 1, 1, 0, 0, 1]
+
+model = FishyCatClassifier(
+    n_estimators=40,
+    tree_depth=3,
+    metrics="auto",
+    auto_metric=True,
+    impute_strategy="auto",
+    candidate_families="auto",
+    install_missing_libraries=True,
+    n_jobs=4,
+    verbose=1,
+)
+
+model.fit(X, y)
+print(model.evaluate(X, y))
+print(model.predict_proba(X)[:3])
+fig = model.plot_visualization(kind="overview")
+print(model.get_statistics())
+print(model.get_history(as_dataframe=True).head())
+```
+
+## Main API
+
+- `FishyCatBooster`
+- `FishyCatClassifier`
+
+For regression, use `FishyCatBooster(task="regression", ...)`.
+
+Common parameters:
+
+- `metrics`: metric name (`"auto"`, `"accuracy"`, `"auc"`, `"logloss"`, `"rmse"`, `"mae"`, `"r2"`) or callable.
+- `auto_metric`: if `True`, metric and training validation feedback are auto-selected by task/data.
+- `impute_strategy`: `"auto"`, `"simple"`, `"iterative"`, or `"none"`.
+- `structure_mode`: `"auto"`, `"linear"`, `"nonlinear"`.
+- `boosting_order`: `1` (gradient) or `2` (Newton-like weighted residuals).
+- `candidate_families`: `"auto"` or subset of `["linear", "spline", "adaptive_mlp", "soft_tree"]`.
+- `plot_visualization(kind=...)`: loss/routing/depth/overview diagnostics.
+- `get_statistics()`: full training + data summary.
+- `get_history(as_dataframe=True)`: per-iteration history (loss, metric, ETA, routing).
+- `view_data(X, transformed=True/False)`: inspect raw or transformed data.
+- `auto_install_dependencies`: auto-installs missing libs using pip at runtime.
+- `install_plot_dependencies`: if `True`, auto-installs plotting dependencies too.
+- `full_report(X, y)`: one-shot report (statistics + history + evaluation).
+- `available_components()`: list of all integrated learner families/features.
+
+## Notes
+
+- This repository provides a practical implementation of OmniBoost++ ideas; it is not a strict reproduction of a specific paper.
+- For larger datasets, run on GPU: `device="cuda"`.
+
+## License
+
+MIT

catfishml-0.4.0/README.md

@@ -0,0 +1,96 @@
+# catfishml
+
+`catfishml` is a Python library for **OmniBoost++**: generalized boosting with adaptive routing across heterogeneous weak learners (linear, spline/GAM-like, adaptive-depth MLP, differentiable soft tree).
+
+## Why catfishml
+
+- Adaptive residual router with complexity/redundancy penalties.
+- Additive boosting in natural predictor space with Newton-style targets.
+- Numeric + categorical support (categorical embeddings).
+- Missing value handling with `SimpleImputer` or MICE-style `IterativeImputer`.
+- Adaptive behavior:
+  - automatic objective/distribution and metric selection,
+  - linearity probe (auto linear vs nonlinear mode),
+  - adaptive MLP depth + adaptive tree depth.
+- CPU/GPU via PyTorch.
+- Automatic dependency install for missing core libraries (can be disabled).
+
+## Install
+
+```bash
+pip install catfishml
+```
+
+For development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from catfishml import FishyCatClassifier
+
+X = pd.DataFrame(
+    {
+        "age": [25, 31, 45, None, 39, 22, 55],
+        "income": [2200, 3400, 7600, 5100, None, 1900, 8800],
+        "city": ["A", "B", "A", "C", "B", None, "A"],
+    }
+)
+y = [0, 0, 1, 1, 0, 0, 1]
+
+model = FishyCatClassifier(
+    n_estimators=40,
+    tree_depth=3,
+    metrics="auto",
+    auto_metric=True,
+    impute_strategy="auto",
+    candidate_families="auto",
+    install_missing_libraries=True,
+    n_jobs=4,
+    verbose=1,
+)
+
+model.fit(X, y)
+print(model.evaluate(X, y))
+print(model.predict_proba(X)[:3])
+fig = model.plot_visualization(kind="overview")
+print(model.get_statistics())
+print(model.get_history(as_dataframe=True).head())
+```
+
+## Main API
+
+- `FishyCatBooster`
+- `FishyCatClassifier`
+
+For regression, use `FishyCatBooster(task="regression", ...)`.
+
+Common parameters:
+
+- `metrics`: metric name (`"auto"`, `"accuracy"`, `"auc"`, `"logloss"`, `"rmse"`, `"mae"`, `"r2"`) or callable.
+- `auto_metric`: if `True`, metric and training validation feedback are auto-selected by task/data.
+- `impute_strategy`: `"auto"`, `"simple"`, `"iterative"`, or `"none"`.
+- `structure_mode`: `"auto"`, `"linear"`, `"nonlinear"`.
+- `boosting_order`: `1` (gradient) or `2` (Newton-like weighted residuals).
+- `candidate_families`: `"auto"` or subset of `["linear", "spline", "adaptive_mlp", "soft_tree"]`.
+- `plot_visualization(kind=...)`: loss/routing/depth/overview diagnostics.
+- `get_statistics()`: full training + data summary.
+- `get_history(as_dataframe=True)`: per-iteration history (loss, metric, ETA, routing).
+- `view_data(X, transformed=True/False)`: inspect raw or transformed data.
+- `auto_install_dependencies`: auto-installs missing libs using pip at runtime.
+- `install_plot_dependencies`: if `True`, auto-installs plotting dependencies too.
+- `full_report(X, y)`: one-shot report (statistics + history + evaluation).
+- `available_components()`: list of all integrated learner families/features.
+
+## Notes
+
+- This repository provides a practical implementation of OmniBoost++ ideas; it is not a strict reproduction of a specific paper.
+- For larger datasets, run on GPU: `device="cuda"`.
+
+## License
+
+MIT

catfishml-0.4.0/examples/basic_usage.py

@@ -0,0 +1,65 @@
+"""Minimal example for catfishml."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from catfishml import FishyCatClassifier
+
+
+def main() -> None:
+    rng = np.random.default_rng(42)
+    n = 400
+
+    data = pd.DataFrame(
+        {
+            "age": rng.integers(18, 70, size=n),
+            "income": rng.normal(5000, 1800, size=n),
+            "click_rate": rng.uniform(0, 1, size=n),
+            "city": rng.choice(["B", "C", "D", "A"], size=n),
+            "device": rng.choice(["ios", "android", "web"], size=n),
+        }
+    )
+
+    data.loc[::17, "income"] = np.nan
+    data.loc[::23, "city"] = None
+
+    logits = (
+        0.04 * (data["age"].fillna(40) - 35)
+        + 0.0003 * (data["income"].fillna(5000) - 5000)
+        + 1.4 * (data["click_rate"] - 0.4)
+        + 0.5 * (data["device"] == "ios").astype(float)
+        - 0.3 * (data["city"].fillna("A") == "D").astype(float)
+    )
+    probs = 1.0 / (1.0 + np.exp(-logits.to_numpy()))
+    y = (rng.random(n) < probs).astype(int)
+
+    model = FishyCatClassifier(
+        n_estimators=50,
+        tree_depth=3,
+        boosting_order=2,
+        metrics="auto",
+        auto_metric=True,
+        impute_strategy="auto",
+        structure_mode="auto",
+        neural_epochs=12,
+        batch_size=128,
+        candidate_families="auto",
+        install_missing_libraries=True,
+        n_jobs=4,
+        verbose=1,
+    )
+
+    model.fit(data, y)
+    metrics = model.evaluate(data, y)
+    print("Training metrics:", metrics)
+    print("Proba preview:\n", model.predict_proba(data.head(5)))
+    print("Statistics:", model.get_statistics())
+    print("History preview:\n", model.get_history(as_dataframe=True).head())
+    # Requires matplotlib
+    # model.plot_visualization(kind="overview")
+
+
+if __name__ == "__main__":
+    main()

catfishml-0.4.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "catfishml"
+version = "0.4.0"
+description = "NeuroSplit Boosting for tabular data with differentiable soft trees and neural gating."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+  { name = "CatfishML Contributors" }
+]
+keywords = ["machine-learning", "gradient-boosting", "tabular", "pytorch", "soft-decision-tree"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence"
+]
+dependencies = [
+  "numpy>=1.23",
+  "scipy>=1.10",
+  "torch>=2.1",
+  "scikit-learn>=1.3",
+  "pandas>=1.5",
+  "typing-extensions>=4.8"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.6",
+  "mypy>=1.11"
+]
+viz = [
+  "matplotlib>=3.8"
+]
+
+[project.urls]
+Homepage = "https://github.com/catfishml/catfishml"
+Repository = "https://github.com/catfishml/catfishml"
+Issues = "https://github.com/catfishml/catfishml/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/catfishml"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"

catfishml-0.4.0/src/catfishml/__init__.py

@@ -0,0 +1,13 @@
+"""catfishml public API."""
+
+from ._autoinstall import ensure_runtime_dependencies
+
+ensure_runtime_dependencies(auto_install=True, include_plot=False, quiet=True)
+
+from .model import FishyCatBooster, FishyCatClassifier
+
+__all__ = [
+    "FishyCatBooster",
+    "FishyCatClassifier",
+]
+__version__ = "0.4.0"

catfishml-0.4.0/src/catfishml/_adaptive_mlp.py

@@ -0,0 +1,126 @@
+"""Adaptive-depth MLP weak learner for OmniBoost++."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+
+class TabularEncoder(nn.Module):
+    """Builds dense input from numeric features and categorical embeddings."""
+
+    def __init__(
+        self,
+        *,
+        num_numeric_features: int,
+        categorical_cardinalities: Sequence[int],
+        embedding_dropout: float = 0.0,
+    ) -> None:
+        super().__init__()
+        self.num_numeric_features = num_numeric_features
+        self.embed_layers = nn.ModuleList()
+        embed_dims: list[int] = []
+
+        for cardinality in categorical_cardinalities:
+            dim = _default_embedding_dim(cardinality)
+            self.embed_layers.append(nn.Embedding(cardinality, dim))
+            embed_dims.append(dim)
+
+        self.output_dim = num_numeric_features + sum(embed_dims)
+        self.embedding_dropout = nn.Dropout(embedding_dropout) if embedding_dropout > 0 else nn.Identity()
+
+    def forward(self, x_num: torch.Tensor, x_cat: torch.Tensor | None) -> torch.Tensor:
+        parts = [x_num] if self.num_numeric_features > 0 else []
+
+        if self.embed_layers:
+            if x_cat is None:
+                raise ValueError("x_cat is required because categorical embeddings are enabled.")
+            embedded = [layer(x_cat[:, idx]) for idx, layer in enumerate(self.embed_layers)]
+            cat_vec = torch.cat(embedded, dim=1)
+            parts.append(self.embedding_dropout(cat_vec))
+
+        if not parts:
+            raise ValueError("AdaptiveDepthMLP requires at least one input feature.")
+
+        return torch.cat(parts, dim=1) if len(parts) > 1 else parts[0]
+
+
+class AdaptiveDepthMLP(nn.Module):
+    """MLP template with differentiable per-layer depth gates."""
+
+    def __init__(
+        self,
+        *,
+        num_numeric_features: int,
+        categorical_cardinalities: Sequence[int],
+        output_dim: int,
+        hidden_dim: int = 128,
+        max_layers: int = 4,
+        dropout: float = 0.1,
+        embedding_dropout: float = 0.0,
+    ) -> None:
+        super().__init__()
+        if max_layers < 1:
+            raise ValueError("max_layers must be >= 1")
+
+        self.max_layers = max_layers
+        self.hidden_dim = hidden_dim
+        self.output_dim = output_dim
+
+        self.encoder = TabularEncoder(
+            num_numeric_features=num_numeric_features,
+            categorical_cardinalities=categorical_cardinalities,
+            embedding_dropout=embedding_dropout,
+        )
+        if self.encoder.output_dim == 0:
+            raise ValueError("AdaptiveDepthMLP requires at least one numeric or categorical feature.")
+
+        self.input_proj = nn.Linear(self.encoder.output_dim, hidden_dim)
+        self.blocks = nn.ModuleList(
+            [
+                nn.Sequential(
+                    nn.Linear(hidden_dim, hidden_dim),
+                    nn.SiLU(),
+                    nn.Dropout(dropout) if dropout > 0 else nn.Identity(),
+                )
+                for _ in range(max_layers)
+            ]
+        )
+        self.depth_logits = nn.Parameter(torch.zeros(max_layers))
+        self.output_head = nn.Linear(hidden_dim, output_dim)
+
+    def forward(
+        self,
+        x_num: torch.Tensor,
+        x_cat: torch.Tensor | None = None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        x = self.encoder(x_num, x_cat)
+        h = F.silu(self.input_proj(x))
+        gates = torch.sigmoid(self.depth_logits)
+
+        for layer_idx, block in enumerate(self.blocks):
+            proposal = block(h)
+            gate = gates[layer_idx]
+            h = gate * proposal + (1.0 - gate) * h
+
+        out = self.output_head(h)
+        return out, gates
+
+    def depth_penalty(self) -> torch.Tensor:
+        return torch.sigmoid(self.depth_logits).sum()
+
+    def sharpness_penalty(self) -> torch.Tensor:
+        gates = torch.sigmoid(self.depth_logits)
+        return (gates * (1.0 - gates)).sum()
+
+    def effective_depth(self) -> float:
+        return float(torch.sigmoid(self.depth_logits).sum().detach().cpu().item())
+
+
+
+def _default_embedding_dim(cardinality: int) -> int:
+    cardinality = max(2, int(cardinality))
+    return min(32, max(4, int(round(cardinality**0.25 * 4))))

catfishml-0.4.0/src/catfishml/_autoinstall.py

@@ -0,0 +1,93 @@
+"""Runtime dependency auto-installer for catfishml."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import subprocess
+import sys
+from typing import Iterable
+
+_CORE_REQUIREMENTS = {
+    "numpy": "numpy>=1.23",
+    "scipy": "scipy>=1.10",
+    "pandas": "pandas>=1.5",
+    "sklearn": "scikit-learn>=1.3",
+    "torch": "torch>=2.1",
+}
+
+_OPTIONAL_REQUIREMENTS = {
+    "matplotlib": "matplotlib>=3.8",
+}
+
+_ENSURED = False
+
+
+def _is_installed(module_name: str) -> bool:
+    return importlib.util.find_spec(module_name) is not None
+
+
+def _missing_modules(module_names: Iterable[str]) -> list[str]:
+    missing: list[str] = []
+    for module_name in module_names:
+        if not _is_installed(module_name):
+            missing.append(module_name)
+    return missing
+
+
+def ensure_runtime_dependencies(
+    *,
+    auto_install: bool = True,
+    include_plot: bool = False,
+    quiet: bool = True,
+) -> None:
+    """Ensure core runtime dependencies exist; optionally auto-install them."""
+
+    global _ENSURED
+    if _ENSURED:
+        return
+
+    required = dict(_CORE_REQUIREMENTS)
+    if include_plot:
+        required.update(_OPTIONAL_REQUIREMENTS)
+
+    missing_modules = _missing_modules(required.keys())
+    if not missing_modules:
+        _ENSURED = True
+        return
+
+    if not auto_install:
+        pkgs = [required[name] for name in missing_modules]
+        raise ImportError(
+            "Missing dependencies: "
+            + ", ".join(pkgs)
+            + ". Enable auto_install_dependencies=True or install manually."
+        )
+
+    if os.environ.get("CATFISHML_DISABLE_AUTO_INSTALL", "0") in {"1", "true", "True"}:
+        pkgs = [required[name] for name in missing_modules]
+        raise ImportError(
+            "Automatic dependency install is disabled via CATFISHML_DISABLE_AUTO_INSTALL. "
+            + "Missing: "
+            + ", ".join(pkgs)
+        )
+
+    pkgs_to_install = [required[name] for name in missing_modules]
+    cmd = [sys.executable, "-m", "pip", "install"]
+    if quiet:
+        cmd.append("-q")
+    cmd.extend(pkgs_to_install)
+
+    try:
+        subprocess.check_call(cmd)
+    except subprocess.CalledProcessError as exc:  # pragma: no cover
+        raise ImportError(
+            "Failed to auto-install dependencies: " + ", ".join(pkgs_to_install)
+        ) from exc
+
+    still_missing = _missing_modules(required.keys())
+    if still_missing:
+        pkgs = [required[name] for name in still_missing]
+        raise ImportError("Dependencies still missing after install: " + ", ".join(pkgs))
+
+    _ENSURED = True