Tuning sweeps, band efficiency, exact scorecards, tuning guide + FAQ

[orgoca]

The configuration questions users face, answered with measured tools instead of rules of thumb.

The organizing idea

The two whitebox knobs are not symmetric. n_estimators buys fidelity at a linear cost in size and explain time and never costs a guarantee; max_depth is the knob that takes exact attribution (and the scorecard) away above 2. Spend on trees, be stingy with depth — and the new tooling turns that from advice into tables.

What's in

compileml.tune — sweep_whitebox (trees × depth grid: holdout Gini retention, Spearman vs teacher, exact_attribution, quantized size, measured per-row explain cost) and sweep_bands (K grid: ordinal-Gini retention, Gini gap, worst within-band AUC + verdict, min volume, monotonicity violations, integer-edge collisions).

compileml.bands.band_efficiency — the money-on-the-table diagnostic: the Gini gap your ladder discards, plus per-band within-band AUC with bootstrap CIs and refinable / exhausted / inconclusive verdicts. Validation check 4 now carries banding_gini_gap and worst_within_band_auc whenever outcomes are supplied — advisory by default, hard-gateable via max_within_band_auc=.

compileml.scorecard (stdlib-only) — at depth ≤ 2 the artifact collapses into an exact points scorecard: bin → points tables plus pairwise interaction grids whose integers re-sum to every decision's raw_micro bit-for-bit. score_from_scorecard re-derives any decision from the printed tables alone — asserted on 300 rows at depths 1 and 2 — so a validator can reproduce production scores in a spreadsheet. Markdown/CSV renderers and a compileml scorecard CLI subcommand; refuses above depth 2 rather than approximating (the same boundary as exact attribution, same reason).

One math subtlety the tests caught: a depth-2 tree can reference three features (root + a different one per child). Exactness survives — depth-2 leaves are products of at most two indicators — but the collapse must split such trees at the root into two ≤2-feature halves. Implemented and covered.

Docs — howto/tuning.md walks all eight questions (tree count, depth, the asymmetry, the "doesn't it just become the teacher?" concern, band count, within-band AUC reading guide, scorecards); faq.md adds fourteen Q&As from configuration through determinism. Both in nav; API reference extended.

Gate

Full local suite (110 tests), ruff/black, mkdocs build --strict — all green.

Release note: main is at v0.1.0 — if this should ride the first release, merge before tagging; otherwise it lands cleanly in the next.

[orgoca]

Added to this PR: version single-sourced at 0.1.1. Root cause of the "still appeared as dev" mystery: PyPI's 0.1.0 metadata was actually correct — the stale value was the hardcoded compileml.__version__ = "0.1.0.dev0" in __init__.py, a second declaration never wired to pyproject. That's what import compileml, compileml inspect, and every artifact's compileml_version displayed.

Fix is structural: __init__.py is now the only version declaration and pyproject reads it at build time (dynamic = ["version"]). Verified locally: wheel metadata == module attribute == 0.1.1, twine check passed. RELEASING.md updated to point at the new single source.

Merging this PR leaves main tag-ready: git tag v0.1.1, push, publish the GitHub release.