classifier-toolkit 0.2.4__tar.gz → 0.2.5__tar.gz

classifier_toolkit-0.2.5/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh && echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Deploy
+        run: uv run mkdocs gh-deploy --force

classifier_toolkit-0.2.5/.github/workflows/release.yaml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+env:
+  PYTHON_VERSION: "3.12.6"
+  UV_INDEX_URL: "https://${{ vars.NEXUS_READER_USERNAME }}:${{ secrets.NEXUS_READER_PASSWORD }}@package-registry.tooling-production.qonto.co/repository/pypi-proxies/simple"
+
+
+jobs:
+  build-and-publish:
+    runs-on: default
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential gcc g++ make
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: uv sync
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

{classifier_toolkit-0.2.4 → classifier_toolkit-0.2.5}/PKG-INFO

@@ -1,23 +1,24 @@
 Metadata-Version: 2.4
 Name: classifier-toolkit
-Version: 0.2.4
+Version: 0.2.5
+Project-URL: Documentation, http://classifier-toolkit.gh-pages.qonto.co/
 Author-email: "senih.yilmaz" <senih.yilmaz@qonto.com>, "jeremy.fraoua" <jeremy.fraoua@qonto.com>, "gauthier.marquand" <gauthier.marquand@qonto.com>, "arnaud.alepee" <arnaud.alepee@qonto.com>
 License-File: LICENSE
-Requires-Python: <3.13,>=3.9
+Requires-Python: <3.14,>=3.9
 Requires-Dist: catboost<2.0.0,>=1.2.2
 Requires-Dist: category-encoders<3.0.0,>=2.6.3
 Requires-Dist: colorama<0.5.0,>=0.4.6
 Requires-Dist: lightgbm<5.0.0,>=4.5.0
 Requires-Dist: matplotlib<4.0.0,>=3.9.2
 Requires-Dist: nbformat>=5.10.4
-Requires-Dist: numpy<2.0
+Requires-Dist: numpy<3.0,>=2.0
 Requires-Dist: optuna<4.0.0,>=3.5.0
 Requires-Dist: pandas<3.0.0,>=2.2.0
 Requires-Dist: polars<2.0.0,>=1.2.1
-Requires-Dist: pyarrow<19.0.0,>=18.0.0
+Requires-Dist: pyarrow>=18.0.0
 Requires-Dist: scikit-learn<2.0.0,>=1.4.0
-Requires-Dist: scipy<1.14
-Requires-Dist: shap<0.45.0,>=0.44.1
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: shap>=0.46.0
 Requires-Dist: statsmodels<0.15.0,>=0.14.2
 Requires-Dist: tabulate<0.10.0,>=0.9.0
 Requires-Dist: tqdm<5.0.0,>=4.66.0
@@ -39,8 +40,7 @@ pip install classifier-toolkit
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Code style - Black](https://img.shields.io/badge/Code%20Style-Black-000000.svg)](https://github.com/psf/black)
-
-This is a new project.
+[![Documentation](https://img.shields.io/badge/docs-gh--pages-blue)](http://classifier-toolkit.gh-pages.qonto.co/)
 
 -----
 
@@ -65,10 +65,10 @@ This library automates binary classification tasks in the finance domain, specif
 1. **EDA**: accessible via `EDA_Toolkit`. Provides EDA and feature engineering functionality with all necessary visualizations.
 2. **Feature Reduction**: filter-style pre-selection pipeline (expert rules, low variance, drift, predictive power, counter-intuitive direction, high correlation).
 3. **Feature Selection**: wrapper and embedded methods (RFE, Boruta, Sequential, Bayesian, ElasticNet, MetaSelector).
-4. Model fitting and hyperparameter tuning: To be implemented.
+4. **Model Training**: accessible via `Tuner`. Hyperparameter optimization (grid search, Bayesian via Optuna) for LightGBM and CatBoost with train/val/test evaluation.
 5. Evaluation and reporting: To be implemented.
 
-In the future, the package architectures will be included here. However, for now please consult the docstrings in the specific methods in the relevant modules.
+For detailed usage, refer to the documentation.
 
 **Note**: that this library does not contain data wrangling steps (although it contains feature engineering), it's an intermediate step between EDA and feature engineering where users should fix any data quality related issues. Therefore, conducting the EDA is crucial to mitigate any issues before moving onto the feature engineering and the subsequent steps.
 
@@ -131,9 +131,25 @@ In the future, the package architectures will be included here. However, for now
   - **Wrapper Methods**:
     - Recursive Feature Elimination (RFE) with support for various ensemble methods (Random Forest, XGBoost, LightGBM, CatBoost).
     - Sequential Feature Selection (forward, backward, floating, and bidirectional).
+    - **Recursive Feature Eliminator**: Adaptive two-phase elimination (batch drop + one-by-one) with overfitting-aware strategies, early stopping with rollback, temporal cross-validation, and sample weights.
+    - **Feature Combination Searcher**: Exhaustive combinatorial search over all subsets of a candidate pool, scoring each combination on train/val/test splits.
   - **Meta Selector**: Combines multiple feature selection methods to provide a robust selection.
   - **Utility Functions**: Includes scoring functions and plotting utilities for feature importance visualization.
 
+- **Model Training**: Hyperparameter optimization for LightGBM and CatBoost, with support for grid search and Bayesian optimization (via Optuna).
+
+  ```python
+  from classifier_toolkit.model_training.hyper_parameter_tuning import Tuner
+
+  tuner = Tuner(model_name="lightgbm", metric="auc", search_type="bayesian", n_trials=50)
+  tuner.fit(X_train, y_train, X_val, y_val, X_test=X_test, y_test=y_test)
+
+  best_model = tuner.best_model
+  tuner.results_df  # full trial results
+  ```
+
+  Custom parameter search spaces can be defined via `ModelParams` and `ParamRange`.
+
 ### Development & CI/CD
 
 This project uses modern tooling for fast and efficient development workflows:
@@ -172,6 +188,5 @@ uv build
 
 ### Future Work
 The next planned improvements and additions to the library include:
-* Adding model fitting and hyperparameter tuning functionalities.
 * Developing comprehensive evaluation and reporting tools to assist with model assessment.
 * Expanding documentation to include architecture diagrams and detailed usage examples.

{classifier_toolkit-0.2.4 → classifier_toolkit-0.2.5}/README.md

@@ -9,8 +9,7 @@ pip install classifier-toolkit
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Code style - Black](https://img.shields.io/badge/Code%20Style-Black-000000.svg)](https://github.com/psf/black)
-
-This is a new project.
+[![Documentation](https://img.shields.io/badge/docs-gh--pages-blue)](http://classifier-toolkit.gh-pages.qonto.co/)
 
 -----
 
@@ -35,10 +34,10 @@ This library automates binary classification tasks in the finance domain, specif
 1. **EDA**: accessible via `EDA_Toolkit`. Provides EDA and feature engineering functionality with all necessary visualizations.
 2. **Feature Reduction**: filter-style pre-selection pipeline (expert rules, low variance, drift, predictive power, counter-intuitive direction, high correlation).
 3. **Feature Selection**: wrapper and embedded methods (RFE, Boruta, Sequential, Bayesian, ElasticNet, MetaSelector).
-4. Model fitting and hyperparameter tuning: To be implemented.
+4. **Model Training**: accessible via `Tuner`. Hyperparameter optimization (grid search, Bayesian via Optuna) for LightGBM and CatBoost with train/val/test evaluation.
 5. Evaluation and reporting: To be implemented.
 
-In the future, the package architectures will be included here. However, for now please consult the docstrings in the specific methods in the relevant modules.
+For detailed usage, refer to the documentation.
 
 **Note**: that this library does not contain data wrangling steps (although it contains feature engineering), it's an intermediate step between EDA and feature engineering where users should fix any data quality related issues. Therefore, conducting the EDA is crucial to mitigate any issues before moving onto the feature engineering and the subsequent steps.
 
@@ -101,9 +100,25 @@ In the future, the package architectures will be included here. However, for now
   - **Wrapper Methods**:
     - Recursive Feature Elimination (RFE) with support for various ensemble methods (Random Forest, XGBoost, LightGBM, CatBoost).
     - Sequential Feature Selection (forward, backward, floating, and bidirectional).
+    - **Recursive Feature Eliminator**: Adaptive two-phase elimination (batch drop + one-by-one) with overfitting-aware strategies, early stopping with rollback, temporal cross-validation, and sample weights.
+    - **Feature Combination Searcher**: Exhaustive combinatorial search over all subsets of a candidate pool, scoring each combination on train/val/test splits.
   - **Meta Selector**: Combines multiple feature selection methods to provide a robust selection.
   - **Utility Functions**: Includes scoring functions and plotting utilities for feature importance visualization.
 
+- **Model Training**: Hyperparameter optimization for LightGBM and CatBoost, with support for grid search and Bayesian optimization (via Optuna).
+
+  ```python
+  from classifier_toolkit.model_training.hyper_parameter_tuning import Tuner
+
+  tuner = Tuner(model_name="lightgbm", metric="auc", search_type="bayesian", n_trials=50)
+  tuner.fit(X_train, y_train, X_val, y_val, X_test=X_test, y_test=y_test)
+
+  best_model = tuner.best_model
+  tuner.results_df  # full trial results
+  ```
+
+  Custom parameter search spaces can be defined via `ModelParams` and `ParamRange`.
+
 ### Development & CI/CD
 
 This project uses modern tooling for fast and efficient development workflows:
@@ -142,6 +157,5 @@ uv build
 
 ### Future Work
 The next planned improvements and additions to the library include:
-* Adding model fitting and hyperparameter tuning functionalities.
 * Developing comprehensive evaluation and reporting tools to assist with model assessment.
 * Expanding documentation to include architecture diagrams and detailed usage examples.

{classifier_toolkit-0.2.4 → classifier_toolkit-0.2.5}/classifier_toolkit/feature_selection/__init__.py

@@ -29,6 +29,9 @@ _EXPORTS: Dict[str, str] = {
     "RFESelector": "classifier_toolkit.feature_selection.wrapper_methods.rfe",
     "RFECatBoostSelector": "classifier_toolkit.feature_selection.wrapper_methods.rfe_catboost",
     "SequentialSelector": "classifier_toolkit.feature_selection.wrapper_methods.sequential_selection",
+    "FeatureCombinationSearcher": "classifier_toolkit.feature_selection.wrapper_methods.combination_search",
+    "RecursiveFeatureEliminator": "classifier_toolkit.feature_selection.wrapper_methods.recursive_feature_eliminator",
+    "fast_recursive_feature_elimination": "classifier_toolkit.feature_selection.wrapper_methods.recursive_feature_eliminator",
 }
 
 __all__ = list(_EXPORTS.keys())

classifier_toolkit-0.2.5/classifier_toolkit/feature_selection/utils/feature_type_constraints.py

@@ -0,0 +1,66 @@
+from typing import Dict, List, Union
+
+import pandas as pd
+
+
+def build_feature_type_map(
+    feature_type_mapping: Union[pd.DataFrame, Dict[str, str]],
+) -> Dict[str, str]:
+    """Normalize a feature_name/feature_type mapping into a ``{feature: type}`` dict.
+
+    Parameters
+    ----------
+    feature_type_mapping : pd.DataFrame or Dict[str, str]
+        Either a dict, or a DataFrame with ``feature_name`` and ``feature_type``
+        columns (e.g. built from an information_schema query grouping features
+        into business types such as ``balance_amount``, ``outflow_card``, ...).
+    """
+    if isinstance(feature_type_mapping, dict):
+        return dict(feature_type_mapping)
+
+    missing = {"feature_name", "feature_type"} - set(feature_type_mapping.columns)
+    if missing:
+        raise ValueError(
+            f"feature_type_mapping is missing required column(s): {sorted(missing)}"
+        )
+    return dict(
+        zip(
+            feature_type_mapping["feature_name"],
+            feature_type_mapping["feature_type"],
+        )
+    )
+
+
+def get_type_protected_features(
+    remaining_features: List[str], feature_type_map: Dict[str, str]
+) -> List[str]:
+    """Features that must not be removed to keep every required type covered.
+
+    A feature is protected once it is the *last* remaining representative of
+    its type within ``remaining_features``. Features absent from
+    ``feature_type_map`` are unconstrained and never protected.
+
+    Parameters
+    ----------
+    remaining_features : List[str]
+        Features still in play (not yet removed).
+    feature_type_map : Dict[str, str]
+        Mapping of feature name to feature type, as returned by
+        ``build_feature_type_map``.
+
+    Returns
+    -------
+    List[str]
+        Subset of ``remaining_features`` that are the sole survivor of their type.
+    """
+    type_counts: Dict[str, int] = {}
+    for feature in remaining_features:
+        feature_type = feature_type_map.get(feature)
+        if feature_type is not None:
+            type_counts[feature_type] = type_counts.get(feature_type, 0) + 1
+
+    return [
+        feature
+        for feature in remaining_features
+        if feature in feature_type_map and type_counts[feature_type_map[feature]] == 1
+    ]

classifier_toolkit-0.2.5/classifier_toolkit/feature_selection/wrapper_methods/__init__.py

@@ -0,0 +1,62 @@
+import logging
+
+from classifier_toolkit.feature_selection.wrapper_methods.combination_search import (
+    FeatureCombinationSearcher,
+)
+from classifier_toolkit.feature_selection.wrapper_methods.recursive_feature_eliminator import (
+    RecursiveFeatureEliminator,
+    fast_recursive_feature_elimination,
+)
+
+logger = logging.getLogger(__name__)
+
+try:
+    from classifier_toolkit.feature_selection.wrapper_methods.bayesian_search import (
+        BayesianFeatureSelector,
+    )
+except ImportError as e:
+    logger.warning("BayesianFeatureSelector not available: %s", e)
+    BayesianFeatureSelector = None  # type: ignore[assignment,misc]
+
+try:
+    from classifier_toolkit.feature_selection.wrapper_methods.boruta import (
+        BorutaSelector,
+    )
+except ImportError as e:
+    logger.warning("BorutaSelector not available: %s", e)
+    BorutaSelector = None  # type: ignore[assignment,misc]
+
+try:
+    from classifier_toolkit.feature_selection.wrapper_methods.rfe import (
+        RFESelector,
+    )
+except ImportError as e:
+    logger.warning("RFESelector not available: %s", e)
+    RFESelector = None  # type: ignore[assignment,misc]
+
+try:
+    from classifier_toolkit.feature_selection.wrapper_methods.rfe_catboost import (
+        RFECatBoostSelector,
+    )
+except ImportError as e:
+    logger.warning("RFECatBoostSelector not available: %s", e)
+    RFECatBoostSelector = None  # type: ignore[assignment,misc]
+
+try:
+    from classifier_toolkit.feature_selection.wrapper_methods.sequential_selection import (
+        SequentialSelector,
+    )
+except ImportError as e:
+    logger.warning("SequentialSelector not available: %s", e)
+    SequentialSelector = None  # type: ignore[assignment,misc]
+
+__all__ = [
+    "BayesianFeatureSelector",
+    "BorutaSelector",
+    "FeatureCombinationSearcher",
+    "RecursiveFeatureEliminator",
+    "RFESelector",
+    "RFECatBoostSelector",
+    "SequentialSelector",
+    "fast_recursive_feature_elimination",
+]