English quick docs: README.en.md

CI Release License Python

model-debugger — инструмент для пост-тренировочной диагностики моделей классификации.

Он помогает быстро ответить на вопросы:

• Где модель ошибается чаще всего?
• В каких сегментах данных качество заметно проседает?
• Есть ли перекосы между группами (fairness-риски)?
• Насколько хорошо откалиброваны вероятности?

Проект ориентирован на русскоязычную ML-аудиторию и стек Python + Pandas + scikit-learn + Matplotlib/Seaborn.

• Глобальные метрики: accuracy, precision, recall, f1, error_rate
• Вероятностные метрики (если есть proba): roc_auc, log_loss, brier_score
• Диагностика по срезам (region, device, age_group, ...)
• Рейтинг проблемных срезов (error_gap_vs_global)
• Fairness-диагностика для бинарной классификации (selection_rate, TPR, FPR, FNR, precision)
• Калибровка (ECE, MCE) и calibration curve
• Генерация артефактов: summary.json, CSV-таблицы, PNG-графики, report.md

Top Failure Slices

Calibration Curve

Confusion Matrix

cd model-debugger
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Для разработки:

pip install -e .[dev]

python3 examples/generate_synthetic_data.py --rows 4000 --seed 42 --output examples/sample_predictions.csv

python3 -m model_debugger \
 --input examples/sample_predictions.csv \
 --target y_true \
 --pred y_pred \
 --proba y_proba \
 --positive-label 1 \
 --segments gender,region,device,age_group \
 --fairness-groups gender,region \
 --min-segment-size 50 \
 --top-k-failures 10 \
 --output artifacts

• artifacts/summary.json
• artifacts/report.md
• artifacts/segment_metrics.csv
• artifacts/top_failure_slices.csv
• artifacts/fairness_*.csv
• artifacts/calibration_table.csv
• artifacts/plots/*.png

Обязательно:

• колонка target (истинные метки)
• либо pred (предсказанный класс), либо proba (вероятность положительного класса)

Опционально:

• любые колонки сегментов/групп для slice/fairness анализа

Пример:

• y_true, y_pred, y_proba, gender, region, device, age_group

import pandas as pd
from model_debugger import AnalysisConfig, ModelDebugger
df = pd.read_csv("examples/sample_predictions.csv")
config = AnalysisConfig(
 target_col="y_true",
 pred_col="y_pred",
 proba_col="y_proba",
 positive_label=1,
 segment_cols=("gender", "region", "device", "age_group"),
 fairness_group_cols=("gender", "region"),
 min_segment_size=50,
)
result = ModelDebugger(df, config).run("artifacts")
print(result["summary"]["overall"])

python3 -m model_debugger --help

Ключевые флаги:

• --input: путь к CSV
• --target: колонка истинных меток
• --pred: колонка предсказанного класса
• --proba: колонка вероятности положительного класса
• --positive-label: значение положительного класса
• --threshold: порог преобразования вероятности в класс
• --segments: срезы через запятую
• --fairness-groups: fairness-группы через запятую
• --min-segment-size: минимальный размер сегмента
• --top-k-failures: число проблемных срезов
• --calibration-bins: число бинов для калибровки
• --output: директория артефактов

В репозитории настроены:

• GitHub Actions CI: линт, тесты, smoke-run CLI
• Dependabot для обновления зависимостей
• Шаблоны Issues/PR и community-файлы

• Правила контрибуции: CONTRIBUTING
• Кодекс поведения: CODE_OF_CONDUCT
• Политика безопасности: SECURITY
• Поддержка: SUPPORT

• История изменений: CHANGELOG
• Чеклист публикации: PUBLISH_CHECKLIST

• Основной фокус — классификация; fairness/calibration детально реализованы для бинарного кейса.
• В multiclass-задачах бинарные fairness/calibration метрики пропускаются.

MIT