CE Onboard

This is your session primer. Read it in full before touching any CE code. Nothing here requires running code or calling tools — just read and confirm you understand the invariants.

1. Project identity

calibrated_explanations is a scikit-learn-compatible Python XAI library. It extracts calibrated factual rules, alternative rules, and prediction intervals from any model.

• Current version: v0.10.4
• Target milestone: v0.11.0 (see docs/improvement/RELEASE_PLAN_v1.md)
• Core entry points: CalibratedExplainer, WrapCalibratedExplainer
• Public install: pip install calibrated-explanations

2. The CE-First invariants (memorise these)

1. Always use WrapCalibratedExplainer — never subclass or bypass it.
2. Fit → Calibrate → Explain — that is the only valid lifecycle order.
3. Never access _private members — if you need it, there is a public accessor or the feature does not exist yet.
4. Lazy imports — do not add eager top-level imports for heavy libraries (matplotlib, pandas, catboost…) in __init__.py.
5. Plugin-first — new functionality belongs in plugins/, not core/.
6. ADR wins — if a plan and an ADR conflict, the ADR takes precedence.
7. Fallback visibility — every fallback emits _LOGGER.info() AND warnings.warn(..., UserWarning). No silent fallbacks ever.
8. Numpy docstrings — all public functions and classes use numpy-style.
9. Coverage gate — pytest --cov=... --cov-fail-under=90 must pass.
10. Test naming — test_should_<behavior>_when_<condition>.

3. Key files to read on first touch

4. Skill catalogue (when to use which skill)

5. Module layout (ADR-001 boundary)

src/calibrated_explanations/
├── core/           # CalibratedExplainer, WrapCalibratedExplainer — do NOT modify unless necessary
├── plugins/        # All extensible functionality — registry, calibrators, plotters, explanations
├── calibration/    # Venn-Abers and conformal calibration logic
├── viz/            # PlotSpec IR + matplotlib adapter (ADR-007, ADR-016, ADR-023)
├── utils/          # Shared helpers, deprecation, logging
└── ce_agent_utils.py  # CE-first pipeline helpers for agents

Rule: Code in core/ must not import from plugins/. Plugins import from core/, never the reverse.

6. Check your environment

Before coding, verify the install:

python -c "import calibrated_explanations; print(calibrated_explanations.__version__)"
python -m pytest -q --co -q   # list tests without running
make local-checks-pr           # fast gates (lint + type + quick tests)

7. Frequent agent mistakes (recorded in .github/copilot-feedback-log.md)

• Using n_top_features=n → correct param is filter_top=n on explain calls.
• Importing from calibrated_explanations.core.* directly → use top-level import.
• Adding a new fallback without warnings.warn(UserWarning) → always warn.
• Writing tests without test_should_<behavior>_when_<condition> naming.
• Adding eager import matplotlib at module top level → always import lazily.

8. Proceed

Once you have read sections 1–7, you are ready. Select the appropriate skill from section 4 and begin.