hugiml-core documentation

hugiml-core is a high-performance implementation of the HUG-IML framework for intrinsic interpretable machine learning on tabular data. It learns High Utility Gain patterns, converts input rows into a binary pattern-presence representation, and fits an interpretable downstream classifier on top of those patterns.

The package is designed for teams that need competitive tabular classification with explanations that can be reviewed as intervals, categories, supports, utilities, information gain values, and coefficients rather than as post-hoc approximations of a black-box model.

HUGIML interpretable tabular machine learning

Why HUGIML?

  • Intrinsic interpretability: learned HUG patterns are the model representation, not an after-the-fact explanation.

  • Regulated-domain fit: model cards, audit artifacts, pruning trails, calibration, drift monitoring, and deployment helpers are included.

  • Native performance: computationally intensive mining, transaction construction, and matrix-building stages are C++ accelerated with optional OpenMP support. Version 1.1.8 adds fast tuning for eligible adaptive-binning hyperparameter searches, improves higher-order interaction selection for feature_mode="original_plus_interactions", and introduces a Streamlit Governance Studio dashboard for validation and audit workflows. Earlier 1.1.x capabilities remain available, including the native L=2 hot path, augmented-pair operations, strict global topK budgeting, compact native transaction memory, and fused adaptive L=1 execution.

  • Python ergonomics: the estimator follows the scikit-learn API and works with pandas DataFrames or NumPy arrays.

Current release focus

The 1.1.9 release keeps the v1.1.8 modeling workflow stable while adding deployment-oriented controls and memory improvements:

  • HUGIMLClassifier is now the cleaner primary class name; HUGIMLClassifierNative remains backward-compatible.

  • execution_mode="audit" keeps full traceability by default, while execution_mode="production" retains prediction and save/load state with a smaller memory footprint.

  • Strict and hybrid feature modes use earlier feature selection, compact native storage, CSR-returning paths, and improved fixed-B numeric handling.

Installation

pip install hugiml-core
pip install "hugiml-core[plots]"       # optional Plotly dashboards
pip install "hugiml-core[benchmarks]"  # optional comparison suite
pip install "hugiml-core[dashboard]"   # optional Streamlit dashboard

Paper reference

The implementation is based on:

Krishnamoorthy, S. (2024). Interpretable Classifier Models for Decision Support Using High Utility Gain Patterns. IEEE Access, 12, 126088–126107. DOI: 10.1109/ACCESS.2024.3455563.

User guide

API reference

Project