model-debugger

English quick docs: README.en.md

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]

Быстрый старт

1. Сгенерировать демо-данные

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

2. Запустить диагностику

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

3. Артефакты

• 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

Формат входного CSV

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

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

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

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

Пример:

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

Python API

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"])

CLI-параметры

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: директория артефактов

Качество и CI

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

• 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