Classifier architecture

The classifier implementation uses a public façade and focused internal modules. The public estimator remains available from hugiml.classifier and from the package root.

Public contract

HUGIMLClassifier is the concrete estimator class. HUGIMLClassifierNative is an alternate public name for the same class. Both names therefore share the same constructor, fitted state, sklearn behavior, and serialization contract.

classifier.py contains:

  • the public module documentation;

  • native-extension availability state;

  • the estimator constructor and parameter assignments;

  • public helper and exception exports;

  • the mixin composition that defines the estimator.

Internal modules

_classifier_estimator.py

sklearn parameter handling, presets, estimator tags, object state, and model save/load methods.

_classifier_binning.py

input preparation, parameter validation, column metadata, adaptive binning, missing-value preparation, and pair-aware bin selection.

_classifier_training.py

native availability checks, fit orchestration, mining execution, fallback models, and probability/class prediction.

_classifier_features.py

original, pattern, and augmented-pair feature assembly; strict topK selection; downstream matrix construction; and feature-name alignment.

_classifier_interpretation.py

pattern provenance, RPTE rule and alias views, complexity delegation, standardization metadata, and augmented-pair effect explanations.

_classifier_prediction.py

transform-time pattern construction, schema and health checks, monitoring, drift APIs, and monitored cross-validation.

_classifier_inspection.py

pattern and downstream-feature inventories, model composition, coefficient summaries, adaptive-bin visualizations, and model summaries.

_classifier_tuning.py

cached and standard grid evaluation, scoring helpers, and tuning result data.

_classifier_support.py

numerical helpers, augmented-pair transformation state, fit metadata, memory tracking, transaction wrappers, and shared constants.

_classifier_runtime.py

runtime access to mutable native-extension and monitoring symbols exposed by hugiml.classifier.

Dependency rules

Internal modules do not import the concrete classifier class. Type annotations use deferred evaluation, and behavior is composed through self. This avoids cycles between the façade and the implementation modules.

Mutable native-extension and monitoring symbols are resolved through _classifier_runtime.py so test instrumentation and application-level substitution through hugiml.classifier remain effective.

The public façade re-exports classifier-specific helpers and support types used by package integrations. Public support types retain hugiml.classifier as their module path for stable pickle globals.

Adding functionality

Place new behavior in the module matching its responsibility. Cross-cutting state should be documented where it is created and consumed. Constructor parameters remain in HUGIMLClassifier.__init__ so sklearn introspection and cloning continue to derive the complete parameter contract from one location.

A new public method should be covered by tests for its owning module and, when it affects fitted state, by serialization and sklearn-cloning tests. Changes to feature construction should also cover DataFrame and ndarray inputs, binary and multiclass targets, and audit and production execution modes.