Source development setup

Clone and select the documented release

git clone https://github.com/beatrice-b-m/model-auditor.git
cd model-auditor
git checkout v0.1.16

Confirm the commit:

git rev-parse HEAD

Expected:

9408be104264ef04115974a6ae4dc2ec357f1f95

Create an environment

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install pytest matplotlib build

The stable project has no development extra, so test and build tools are installed separately.

Repository layout

model_auditor/
  __init__.py
  core.py
  error_metrics.py
  metric_inputs.py
  metrics.py
  schemas.py
  utils.py
  plotting/
    __init__.py
    plotters.py
    schemas.py
tests/
  test_auditor_score_distribution_plotting.py
  test_bootstrap_confidence_intervals.py
  test_error_evaluation.py
  test_evaluate_metrics_correctness.py
  test_feature_level_ordering.py
  test_metric_inputs_correctness.py
  test_metrics_correctness.py
  test_result_styling.py
  test_score_evaluation_plotting.py
  test_threshold_optimization.py

Other important files:

File	Purpose
pyproject.toml	package metadata, dependencies, setuptools configuration
example.ipynb	interactive package example
.github/workflows/publish.yml	release-created build and PyPI publication
model_auditor/py.typed	typed-package marker

Architectural responsibilities

core.py

Owns Auditor, state registration, threshold resolution, metric/error evaluation, bootstrap loops, and score-distribution plotting.

metrics.py

Defines the ordinary metric protocol and all built-in performance/count metrics.

metric_inputs.py

Defines row-level confusion indicator calculators.

error_metrics.py

Defines the error-metric protocol and canonical odds ratio.

schemas.py

Defines configuration/result dataclasses, DataFrame exports, Styler behavior, and interval plotting.

plotting/

Defines hierarchy configuration, compilation, and output arrays.

Stable conventions

• Python 3.10+ type syntax is used.
• Dataclasses store configuration and result data.
• Protocol-shaped objects support metric extension.
• Public evaluation returns new result objects.
• Setup mutators return None.
• No asynchronous execution is present.
• Matplotlib is imported lazily.
• Ordinary feature evaluation and error analysis preserve categorical declarations.
• Private method names begin with _.

Tooling state

The stable pyproject.toml does not configure a formatter, linter, static type checker, pytest settings, or coverage settings. Do not invent mandatory source commands that the repository has not adopted.

A contribution can still use local tools, but formatting-only churn should be separated from behavioral changes.

Build

python -m build

The project uses setuptools and setuptools-scm. The resulting version depends on Git metadata.

Work from a branch

git switch -c fix/descriptive-change

Keep commits focused and include tests and documentation updates with the behavior they cover.