CE Notebook Audit

You are auditing notebooks in notebooks/ for policy compliance and API correctness. The key rules are defined in ADR-012 (gallery rendering: advisory on mainline, blocking on release branches).

Quick scan commands

# Scan for private-member usage in notebooks
make check-private-members

# Check agent instruction file consistency
make check-agent-instructions

# Run navigation tests (must pass before release)
pytest tests/docs/test_navigation.py -v

Notebook policy matrix

Scanning for private-member usage

# Dedicated scan script
python scripts/anti-pattern-analysis/scan_private_usage.py --check

# Direct grep across all notebooks
grep -r "\._[a-z]" notebooks/ --include="*.ipynb"

Allowed exceptions (implementation artefacts, not user APIs):

• None — all _private usage in notebooks is forbidden.

Scanning for direct core imports

grep -r "from calibrated_explanations.core" notebooks/ --include="*.ipynb"
grep -r "import calibrated_explanations.core" notebooks/ --include="*.ipynb"

Any match is a blocking violation; fix by replacing with the public top-level import:

# BAD
from calibrated_explanations.core.calibrated_explainer import CalibratedExplainer

# GOOD
from calibrated_explanations import CalibratedExplainer

Cell-level checks

For each notebook cell, verify:

1. Imports: only from calibrated_explanations import ... or import calibrated_explanations as ce.
2. Method calls: check against QUICK_API.md for valid public method names.
3. Parameters: filter_top=n not n_top_features=n on explanation calls.
4. No plt.show() without a guard block: notebooks should use %matplotlib inline and let plots render automatically.
5. Data loading: uses relative paths from workspace root or data/ directory.

Notebook execution audit

Run a notebook end-to-end and capture errors:

# Requires jupyter + nbconvert
jupyter nbconvert --to notebook --execute notebooks/core_demos/MyNotebook.ipynb \
    --output /tmp/test_run.ipynb \
    --ExecutePreprocessor.timeout=300

Check the exit code — non-zero means the notebook has a runtime error.

Automated notebook audit (make target)

make notebook-lint       # syntax + import checks
make notebook-execute    # execute all core_demos notebooks

If these targets are unavailable run individual nbconvert commands.

Known issues and resolution

Audit report template

## Notebook Audit Report

Notebook: notebooks/core_demos/<name>.ipynb
Date: YYYY-MM-DD

### Blocking violations
- [ ] (none)

### Non-blocking issues
- [ ] (none)

### API usage notes
- (e.g., uses deprecated parameter X — schedule migration)

### Verdict
PASS / FAIL
Recommended action: (merge as-is | fix blocking violations before merge | advisory follow-up)

Audit Checklist

• make check-private-members passes (exit code 0).
• make check-agent-instructions passes.
• grep for core imports returns no matches.
• Notebooks execute without error (nbconvert --execute).
• pytest tests/docs/test_navigation.py passes.
• All blocking violations resolved.
• Non-blocking issues logged for follow-up.