API Reference
Organised by subpackage. Each symbol has its own page with a signature, parameters, return value, a minimal snippet, and links back to the source and to the normative section of the artifact spec where one applies.
Integrating with the JSON document rather than the Python API? Start with the artifact JSON schema.
compileml
Top level. Re-exports the three things a deployment needs.
- compile_selectedCompile the whitebox whose target and configuration were chosen on Select.
- decideRun the complete decision for one row and return the payload dict.
- load_artifactLoad an artifact from JSON, verifying hash and structure by default.
- verify_artifactTrue iff the stored hash matches the recomputed canonical hash.
compileml.datasets
The data the documentation compiles against. One real credit panel, fetched and cached; one synthetic generator that needs no network.
compileml.select
Choose the target, the tree count and the depth on data the reported figure never sees, then report once.
- compile_selectedCompile the whitebox whose target and configuration were chosen on Select.
- SelectionResultWhat ``compile_selected`` returns: the artifact, the curve, and one report.
- make_partitionsSplit rows into Fit, Select and Report.
- default_gridThe default search space: five targets, four tree counts, two depths.
- chooseOne-SE-simplest: the simplest configuration statistically tied with the best.
compileml.batch
Score a whole matrix through the artifact with NumPy, learning-side. The same integers the row-at-a-time runtime produces.
compileml.compile
Teacher model to integer model. Everything here runs at compile time and never ships to production.
- ExtractedModelFloat-precision tree ensemble extracted from a source model.
- extract_treesExtract a fitted model into float tree arrays; dispatches on family.
- max_depthActual maximum tree depth, measured from the node arrays.
- normalize_constraintsNormalize to a list of -1/0/+1 per feature, or None if unconstrained.
- quantization_error_boundWorst-case |float_latent − int_latent/micro_scale| (latent units).
- quantize_modelQuantize an extracted float model into the integer artifact model.
- rhaRound half away from zero (spec §2.1).
- score_floatReference float scorer used for extraction validation only.
- scorecard_monotone_reportAggregate (necessary-and-sufficient) check on a depth ≤ 2 scorecard.
- train_whiteboxFit a whitebox GBM to a target.
- validate_extractionScore random rows through both paths; raise if they disagree.
- verify_monotone_constraintsCheck every quantized tree against the declared constraint signs.
compileml.artifact
Assemble the compiled model, calibration, bands and reasons into one hashed document.
- build_artifactCompile a fitted model into a complete, hashed decision artifact.
- fit_isotonic_tableIsotonic PD calibration frozen into integer thresholds.
- recalibrate_artifactRefit calibration on fresh outcomes; model and band edges unchanged.
- save_artifactWrite an artifact to JSON (hash already embedded; loaders verify it).
compileml.bands
Build the risk ladder, and measure what the ladder discards.
- BandSpecFloat-space band definition produced by the builders.
- band_efficiencyQuantify the discrimination cost of a band ladder.
- governance_bandsCommittee-facing bands: adjacent-band Welch t-test separation, a within-band residual-AUC cap, and (optionally) strictly monotone PDs.
- monotone_quantile_bandsQuantile bands with empirical bad rates and isotonic-smoothed semantics.
- quantile_bandsPlain quantile (or equal-width) bands; no outcome data required.
- semantic_bandsDiscover the maximum number of statistically separable risk bands.
compileml.reference
A weight-of-evidence logistic floor, so retention is read against a lower bound as well as a ceiling.
compileml.runtime
The deployment surface. Imports only the Python standard library, enforced by a test that parses every module's imports.
- decideRun the complete decision for one row and return the payload dict.
- load_artifactLoad an artifact from JSON, verifying hash and structure by default.
- verify_artifactTrue iff the stored hash matches the recomputed canonical hash.
- ArtifactErrorRaised for malformed, unsupported, or tampered artifacts.
compileml.runtime — primitives
The integer primitives a conforming runtime must reproduce. Pair each with its normative section of the artifact spec when porting to another language.
- score_microRaw ensemble score in micro units (may fall outside [0, micro_scale]).
- latent_from_rawClamp a raw score and convert to display scale (spec §4).
- band_indexIndex of the band containing ``latent_int``.
- band_label(index, label) for the band containing ``latent_int``.
- calibrate_ppmCalibrated probability of default in ppm for a clamped latent.
- contributions_half_microPer-feature contributions in half-micro units.
- display_impactsDisplay-scale impacts that sum exactly to the display-scale target (§7.5).
- format_reasonsAdverse and favorable reason blocks (§7.6).
- canonical_hashSHA-256 hex digest of the canonical serialization (spec §9).
- validate_structureCheap structural checks; raises ArtifactError on violation.
- ARTIFACT_TYPE
- 'compileml.decision_artifact'
- SCHEMA_VERSION
- 2
- PD_SCALE
- 1000000
- LEAF
- -2
compileml.scorecard
Collapse a depth ≤ 2 artifact into bin → points tables that re-derive any decision bit-for-bit.
compileml.tune
Measure the compilation choices instead of guessing them.
compileml.validate
Run the checks against the compiled artifact, through the same runtime production uses.
compileml.fairness
Audit compiled decisions by group: outcomes, predictive performance, and how the model behaves locally. Evidence for a validator, not a compliance certificate.
- FairnessAuditThree-layer fairness audit over compiled decisions.
- approval_rates§3 — approval rate per group, with the adverse impact ratio.
- attribution_concentration§8 — how many drivers it takes to explain a decision, per group.
- attribution_disparity§6 — decompose the mean group score gap by feature, exactly.
- boundary_fragility§9 — how close each group sits to the cutoff.
- calibration_by_group§4 — is the calibrated PD equally honest per group?
- counterfactual§11 — flip the protected attribute and see whether decisions move.
- error_rates§5 — FPR, FNR, precision and recall per group.
- feature_swing§7 — how far each feature *can* move a score, per group.
- model_interaction_structureModel-level context for §8: how much of the card is pairwise at all.
- reason_parity§10 — are the same reasons cited to both groups?
- representation§1 — who is in the population, and what their observed rates are.
- score_distribution§2 — group score distributions, KS and Wasserstein.
- wilson_intervalWilson score interval — behaves sanely on small groups, unlike normal.
compileml.monitor
Read decisions after they were made: which features moved the score, whether the bands are still calibrated, whether the baseline still describes anyone.
compileml.export
Emit the decision as standalone SQL or COBOL, with no model runtime at all.
compileml.viz
Plots driven by the decision payload, so a chart cannot disagree with the deployed decision.
- band_conditioned_decision_driversBand-conditioned decision drivers (faceted beeswarm by band).
- band_driversBand-conditioned decision drivers (faceted beeswarm by band).
- band_ladderObserved bad rate per band — the monotonicity picture.
- decision_driversGlobal decision drivers (deterministic SHAP-style beeswarm).
- waterfallSingle-decision waterfall: baseline → per-feature impacts → score.
- waterfall_svgRender one decision's waterfall as a self-contained SVG string.