MLGuard: Model Diagnostic Tool

Why MLGuard?

MLGuard is a diagnostic toolkit for machine learning practitioners. It provides automated analysis of critical issues such as multicollinearity, class imbalance, overfitting, and fairness bias—common pitfalls that often silently degrade model performance.

Use MLGuard when you need:

• Automated sanity checks before deploying a model
• Human-readable summaries of data/model quality
• Direct labels like "Overfitting" or "Bias Detected" instead of interpreting raw scores or plots

Installation

Install the MLGuard library using pip:

pip install mlguard

Then import the checkers you need:

from mlguard.multicollinearitychecker import MulticollinearityChecker
from mlguard.class_imbalance import ClassImbalanceChecker
from mlguard.overfitting import OverfittingChecker
from mlguard.bias_detecter import BiasDetectionChecker

MulticollinearityChecker

Detects multicollinearity among numeric features using Variance Inflation Factor (VIF).

Method

Parameters

• X (DataFrame or ndarray): Numeric feature matrix
• vif_threshold (float): Threshold above which features are considered collinear (default=5.0)

Returns

{
  "vif_scores": dict,
  "high_vif_features": list,
  "vif_threshold": float,
  "collinearity_status": str
}

ClassImbalanceChecker

Evaluates label distribution and identifies imbalance issues in classification datasets.

Method

Parameters

• y (array-like): Target array
• imbalance_threshold (float): Max allowed class frequency gap (default=0.2)
• plot (bool): Show distribution chart (default=True)

Returns

{
  "class_counts": dict,
  "class_frequencies": dict,
  "imbalance_ratio": float,
  "imbalance_threshold": float,
  "imbalance_status": str
}

OverfittingChecker

Direct output of "fit_status" (e.g., "Overfitting") makes this ideal for automation.

Analyzes learning curves and returns programmatic status based on performance trends.

Method

Parameters

• model: Scikit-learn compatible model
• X, y: Features and labels
• cv: Number of cross-validation splits (default=5)
• scoring: Metric like 'accuracy', 'r2' etc. (default=None, auto-selected)
• plot: Show learning curve plot (default=True)

Returns

{
  "train_sizes": list,
  "train_scores_mean": list,
  "test_scores_mean": list,
  "final_train_score": float,
  "final_test_score": float,
  "train_test_gap": float,
  "fit_status": str,
  "scoring_metric": str
}

Example

from mlguard.overfitting import OverfittingChecker
from sklearn.linear_model import LogisticRegression
from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split

X, y = make_classification(n_samples=1000, n_features=10, n_informative=5, random_state=42)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

model = LogisticRegression(C=1000, max_iter=1000)
result = OverfittingChecker.check_learning_curve(model, X_train, y_train, scoring='accuracy', plot=False)

print("Model Fit Status:", result['fit_status'])
print("Train Score:", result['final_train_score'])
print("Test Score:", result['final_test_score'])
print("Gap:", result['train_test_gap'])
      

BiasDetectionChecker

Detects performance bias across values in a sensitive feature (e.g. gender).

Method

Parameters

• model: Trained classification model
• X: Feature data (must include the sensitive column)
• y: Target labels
• sensitive_feature: Column name (or index) to group on
• metric: Supported: 'accuracy'
• threshold: Max acceptable performance gap (default=0.1)

Returns

{
  "group_performance": dict,
  "bias_gap": float,
  "bias_threshold": float,
  "bias_status": str,
  "metric_used": str
}