API Reference
Artifact JSON schema
The artifact spec is normative about algorithms. This page is the document view: every field of the JSON, its type, whether it is required, and the invariant a reader must enforce. If you are writing an integration that only reads the artifact, this is the page you need.
Document root
Every artifact is a single JSON object with these top-level keys.
| Field | Type | Required | Description |
|---|---|---|---|
| artifact_type | string | yes | Always "compileml.decision_artifact". |
| schema_version | integer | yes | Document version. Current: 2.Invariant: Readers must reject versions they do not implement. |
| scale | integer | yes | Display scale for the integer latent score and band edges.Invariant: Typically 1000. |
| model | object | yes | The quantized integer tree ensemble. |
| calibration | object | null | optional | Isotonic latent → probability table. null means the artifact scores and bands but does not emit pd. |
| bands | object | yes | The risk band ladder in display-scale integers. |
| features | object | yes | Feature order, baseline values and missing-value policy. |
| reasons | object | optional | Reason dictionary keyed by feature name. |
| runtime | object | yes | Attribution mode and display settings. |
| metadata | object | optional | Free-form provenance (training run, recalibration lineage, owner). |
| artifact_hash | string | yes | SHA-256 hex over the canonical form of every other key.Invariant: Loaders verify this by default and reject a mismatch. |
model
The scoring core. All payload values are integers in micro units.
| Field | Type | Required | Description |
|---|---|---|---|
| model.kind | string | yes | Always "tree_ensemble_int". |
| model.micro_scale | integer | yes | Internal accumulation scale. 1_000_000. |
| model.base_micro | integer | yes | Baseline latent in micro units, before any tree contribution. |
| model.n_features | integer | yes | Input arity.Invariant: Must equal len(features.names). |
| model.input_precision | string | yes | "float64" or "float32" — how a conforming runtime must compare thresholds. |
| model.trees | array<object> | yes | One entry per tree; all arrays share the node index space. |
| model.trees[].feature | array<int> | yes | Split feature per node.Invariant: -2 marks a leaf. |
| model.trees[].threshold | array<float> | yes | Split threshold per node.Invariant: float64, must round-trip exactly through JSON. |
| model.trees[].left | array<int> | yes | Left child index; -1 at leaves. |
| model.trees[].right | array<int> | yes | Right child index; -1 at leaves. |
| model.trees[].value_micro | array<int> | yes | Leaf payload in micro units.Invariant: Interior nodes are 0. |
calibration
An integer lookup table. No floating-point model is evaluated at decision time.
| Field | Type | Required | Description |
|---|---|---|---|
| calibration.mode | string | yes | "linear_int" (interpolated) or "step". |
| calibration.f_micro | array<int> | yes | Latent knots in micro units.Invariant: Strictly increasing. |
| calibration.pd_ppm | array<int> | yes | Probability of default in parts per million.Invariant: Non-decreasing; same length as f_micro. |
bands
The ladder, expressed in display-scale integers so band assignment is an integer comparison.
| Field | Type | Required | Description |
|---|---|---|---|
| bands.edges_int | array<int> | yes | Band boundaries at display scale.Invariant: Strictly increasing. |
| bands.labels | array<string> | yes | Band names in ascending order.Invariant: len(labels) == len(edges_int) - 1. |
| bands.boundary | string | yes | "left_closed_right_open" — an edge value belongs to the band above it. |
features
Input contract. The order of names is the scoring order for every runtime and every export.
| Field | Type | Required | Description |
|---|---|---|---|
| features.names | array<string> | yes | Feature names in scoring order. |
| features.baseline | array<float> | yes | float64 reference row: imputation value and attribution reference.Invariant: Same length as names. |
| features.missing_policy | string | yes | "baseline" imputes from baseline; "reject" raises instead. |
| features.display_names | object | optional | Optional human-facing labels keyed by feature name. |
| features.meta | array | optional | Optional per-feature metadata carried for governance. |
reasons
Policy language owned by the institution, not by the library.
| Field | Type | Required | Description |
|---|---|---|---|
| reasons.<feature>.code | string | yes | Reason code emitted in the payload. |
| reasons.<feature>.negative | string | yes | Message shown when the feature increased risk. |
| reasons.<feature>.positive | string | yes | Message shown when the feature decreased risk. |
| reasons.<feature>.suppress | boolean | optional | Policy mask: compute the impact but never display it. |
runtime
Declares how explanations are produced and how many are shown.
| Field | Type | Required | Description |
|---|---|---|---|
| runtime.attribution | string | yes | "pairwise_interaction_int". |
| runtime.top_k | integer | yes | Default number of reasons returned per direction. |
| runtime.whitebox_max_depth | integer | yes | Measured depth of the compiled model. |
| runtime.exact_attribution | boolean | yes | Recorded claim.Invariant: true if and only if whitebox_max_depth ≤ 2. |