Explanations

Attributions for one input: why the model produced this output, and the smallest change that would flip it.

An explanation answers why this prediction: for one input it gives the model's output, an attribution per feature, the ranked top_features and, if asked, the smallest change that would flip the decision. Image models get a heatmap, named regions and a sentence. Kaimei computes attributions by querying the model, or stores attributions you computed yourself.

#The Explanation object

attributions covers every feature; top_features ranks the top_k strongest with their share of the total absolute attribution. For Shapley methods the attributions sum to output.value − base_value.

Attributes

idstring

exp_ identifier.

model_idstring

prediction_idstring | null

The prediction this explains: the one you named, or the one recorded by log_prediction.

methodstring

shap, shapley, lime, gradcam, occlusion, or provided for attributions you sent.

inputobject

The explained row.

outputobject

The model's output for it. Classifiers: label, class_index, probability (of the predicted class), probabilities, target_label, target_index and value (probability of the explained class), name. Regressions: value, name, unit.

attributionsobject

Feature name → contribution to output.value. Image methods key by region name (top left, centre 3).

base_valuenumber | null

The expected output over the background population; the waterfall starts here.

top_featuresarray

{feature, attribution, value, share, direction, rank}, strongest first; permutation Shapley adds stderr. value is the input's value (null for an omitted feature or an image region).

counterfactualobject | null

Present when options.counterfactual was true. See below.

n_evalsinteger

Model evaluations spent.

latency_msnumber

Wall-clock time of the explanation.

optionsobject

The options used, completed with what the method decided: estimator, exact, n_coalitions, background_rows, background_source, kernel_width, local_r2, and for images the fields under image explanations.

metadataobject

Yours, plus api_key (the prefix of the key that created it).

created_attimestamp

The counterfactual object

foundbooleanoptional

Whether a counterfactual was found within max_changes changes.

changesarrayoptional

{feature, from, to, output_after} per step, with label_after for binary models. Applied in order.

output_before / output_afternumberoptional

The explained output before and after the changes.

targetobjectoptional

{kind: "flip_decision", threshold} for classifiers; {kind: "reach_value", target_value} for regressions.

n_evalsintegeroptional

Evaluations the search spent.

The Explanation object

{
  "object": "explanation",
  "id": "exp_7d7add16c796eafac087",
  "model_id": "mdl_390bd6d9568f626851ef",
  "prediction_id": "pred_8f2a19",
  "method": "shap",
  "input": {
    "income": 72000,
    "credit_score": 681,
    "utilization": 0.41,
    "debt_to_income": 0.38,
    "loan_amount": 18000,
    "employment_years": 4,
    "num_delinquencies": 1,
    "age": 34,
    "home_ownership": "rent"
  },
  "output": {
    "label": "decline",
    "class_index": 1,
    "probability": 0.5947,
    "probabilities": {"approve": 0.4053, "decline": 0.5947},
    "target_label": "decline",
    "target_index": 1,
    "value": 0.5947,
    "name": "decision"
  },
  "attributions": {
    "income": -0.052572,
    "credit_score": 0.02092,
    "utilization": -0.062237,
    "debt_to_income": 0.079706,
    "loan_amount": -0.022242,
    "employment_years": 0.007327,
    "num_delinquencies": 0.07484,
    "age": 0.012778,
    "home_ownership": 0.045748
  },
  "base_value": 0.4904,
  "top_features": [
    {
      "feature": "debt_to_income",
      "attribution": 0.079706,
      "value": 0.38,
      "share": 0.2107,
      "direction": "positive",
      "rank": 1
    },
    {
      "feature": "num_delinquencies",
      "attribution": 0.07484,
      "value": 1,
      "share": 0.1978,
      "direction": "positive",
      "rank": 2
    },
    {
      "feature": "utilization",
      "attribution": -0.062237,
      "value": 0.41,
      "share": 0.1645,
      "direction": "negative",
      "rank": 3
    },
    {
      "feature": "income",
      "attribution": -0.052572,
      "value": 72000,
      "share": 0.1389,
      "direction": "negative",
      "rank": 4
    },
    {
      "feature": "home_ownership",
      "attribution": 0.045748,
      "value": "rent",
      "share": 0.1209,
      "direction": "positive",
      "rank": 5
    }
  ],
  "counterfactual": {
    "found": true,
    "changes": [
      {
        "feature": "credit_score",
        "from": 681,
        "to": 850,
        "output_after": 0.0834,
        "label_after": "approve"
      }
    ],
    "output_before": 0.5947,
    "output_after": 0.0834,
    "n_evals": 95,
    "target": {"kind": "flip_decision", "threshold": 0.5}
  },
  "n_evals": 32865,
  "latency_ms": 417.82,
  "options": {
    "seed": 0,
    "counterfactual": true,
    "max_changes": 3,
    "frozen_features": ["age"],
    "log_prediction": true,
    "top_k": 5,
    "estimator": "kernel",
    "exact": true,
    "n_coalitions": 510,
    "n_samples": 510,
    "background_rows": 64,
    "background_source": "reference_data"
  },
  "metadata": {"reviewer": "ops", "api_key": "km_live_fPaB"},
  "created_at": "2026-10-31T22:40:23.705348Z"
}

#Explain a prediction

POST/v1/explanationsAPI key or session

Compute attributions for one input by the chosen method, or store the attributions you pass. The explained instance is also recorded as a prediction (log_prediction) unless you link an existing one with prediction_id.

Counts against the monthly explanations quota and the 120-per-hour limit. A model-querying method needs a runnable model and a population.

Body parameters

modelstringrequired

Model id or slug.

inputobjectrequired

The feature row. Omitted features take their baseline.

methodstringoptionaldefault "shapley"

shap, shapley, lime, gradcam, occlusion or auto.

prediction_idstringoptional

Link to a logged prediction instead of recording a new one.

optionsobjectoptional

See below.

counterfactualbooleanoptionaldefault false

Also search for a minimal counterfactual.

max_changesintegeroptionaldefault 3

Features the counterfactual may change, 1 to 8.

frozen_featuresarray of stringsoptional

Features the counterfactual must not touch.

target_valuenumberoptional

Regression counterfactuals: the output to reach. Default: +0.5 standard deviations of the population.

top_kintegeroptionaldefault 8

Rows in top_features, 1 to 100.

log_predictionbooleanoptionaldefault true

Record the explained instance as a prediction.

seedintegeroptional

Makes sampling methods reproducible.

target_classstringoptional

Explain this class instead of the predicted one (multiclass, and every image method).

n_permutationsintegeroptionaldefault 128

shapley: permutation samples, 8 to 2048.

n_samplesintegeroptional

32 to 5000. shap: coalition budget (default 256; exact SHAP is used when the budget covers the power set). lime: perturbed samples (default the larger of 512 and 4 × the feature count for tables, of 256 and 4 × the region count for images).

background_sizeintegeroptionaldefault 64

Background rows drawn from the population, 1 to 1000.

background_rowsintegeroptional

shap: background rows averaged inside each coalition, 1 to 64. Default: a budget-sized subset.

gridintegeroptional

Images: patches per side of the grid segmentation, 2 to 32. Default 4, or 8 from 64 px.

segmentationstringoptional

Images: superpixels (follows edges) or grid. Default: superpixels for photos at least 64 px on the short side.

n_segmentsintegeroptional

Images: superpixels to aim for, 4 to 256. Default: about one per 35×35 px, between 12 and 64.

layerstringoptional

gradcam: node id of the spatial layer to read. Default: the last convolutional feature map.

attributionsobjectoptional

Pre-computed {feature: contribution}. When present the model is not queried and method is recorded as provided.

outputanyoptional

With attributions: the model's output for the row.

base_valuenumberoptional

With attributions: the expected output.

metadataobjectoptional

Free-form.

Returns

The Explanation. 201.

explanation = client.explanations.create(
    model="credit-risk-v3",
    prediction_id="pred_8f2a19",
    input={"income": 72000, "credit_score": 681, "utilization": 0.41, "debt_to_income": 0.38,
           "loan_amount": 18000, "employment_years": 4, "num_delinquencies": 1, "age": 34,
           "home_ownership": "rent"},
    method="shap",
    options={"counterfactual": True, "frozen_features": ["age"], "max_changes": 3, "seed": 0, "top_k": 5},
    metadata={"reviewer": "ops"},
)
print(explanation.output["label"], explanation.output["value"], explanation.base_value)
print(explanation.counterfactual["changes"])

# other methods
client.explanations.create(model="credit-risk-v3", input=row, method="shapley", options={"n_permutations": 256})
client.explanations.create(model="credit-risk-v3", input=row, method="lime", options={"n_samples": 1000})
client.explanations.create(model="cats-dogs-v1", input={"image": pixels}, method="gradcam", options={"target_class": "dog"})

curl -X POST https://api.kaimei.ai/v1/explanations \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "credit-risk-v3",
    "prediction_id": "pred_8f2a19",
    "input": {"income": 72000, "credit_score": 681, "utilization": 0.41, "debt_to_income": 0.38, "loan_amount": 18000,
              "employment_years": 4, "num_delinquencies": 1, "age": 34, "home_ownership": "rent"},
    "method": "shap",
    "options": {"counterfactual": true, "frozen_features": ["age"], "max_changes": 3, "seed": 0, "top_k": 5},
    "metadata": {"reviewer": "ops"}
  }'

201 CreatedResponse

{
  "object": "explanation",
  "id": "exp_7d7add16c796eafac087",
  "model_id": "mdl_390bd6d9568f626851ef",
  "prediction_id": "pred_8f2a19",
  "method": "shap",
  "input": {
    "income": 72000,
    "credit_score": 681,
    "utilization": 0.41,
    "debt_to_income": 0.38,
    "loan_amount": 18000,
    "employment_years": 4,
    "num_delinquencies": 1,
    "age": 34,
    "home_ownership": "rent"
  },
  "output": {
    "label": "decline",
    "class_index": 1,
    "probability": 0.5947,
    "probabilities": {"approve": 0.4053, "decline": 0.5947},
    "target_label": "decline",
    "target_index": 1,
    "value": 0.5947,
    "name": "decision"
  },
  "attributions": {
    "income": -0.052572,
    "credit_score": 0.02092,
    "utilization": -0.062237,
    "debt_to_income": 0.079706,
    "loan_amount": -0.022242,
    "employment_years": 0.007327,
    "num_delinquencies": 0.07484,
    "age": 0.012778,
    "home_ownership": 0.045748
  },
  "base_value": 0.4904,
  "top_features": [
    {
      "feature": "debt_to_income",
      "attribution": 0.079706,
      "value": 0.38,
      "share": 0.2107,
      "direction": "positive",
      "rank": 1
    },
    {
      "feature": "num_delinquencies",
      "attribution": 0.07484,
      "value": 1,
      "share": 0.1978,
      "direction": "positive",
      "rank": 2
    },
    {
      "feature": "utilization",
      "attribution": -0.062237,
      "value": 0.41,
      "share": 0.1645,
      "direction": "negative",
      "rank": 3
    },
    {
      "feature": "income",
      "attribution": -0.052572,
      "value": 72000,
      "share": 0.1389,
      "direction": "negative",
      "rank": 4
    },
    {
      "feature": "home_ownership",
      "attribution": 0.045748,
      "value": "rent",
      "share": 0.1209,
      "direction": "positive",
      "rank": 5
    }
  ],
  "counterfactual": {
    "found": true,
    "changes": [
      {
        "feature": "credit_score",
        "from": 681,
        "to": 850,
        "output_after": 0.0834,
        "label_after": "approve"
      }
    ],
    "output_before": 0.5947,
    "output_after": 0.0834,
    "n_evals": 95,
    "target": {"kind": "flip_decision", "threshold": 0.5}
  },
  "n_evals": 32865,
  "latency_ms": 417.82,
  "options": {
    "seed": 0,
    "counterfactual": true,
    "max_changes": 3,
    "frozen_features": ["age"],
    "log_prediction": true,
    "top_k": 5,
    "estimator": "kernel",
    "exact": true,
    "n_coalitions": 510,
    "n_samples": 510,
    "background_rows": 64,
    "background_source": "reference_data"
  },
  "metadata": {"reviewer": "ops", "api_key": "km_live_fPaB"},
  "created_at": "2026-10-31T22:40:23.705348Z"
}

201 Createda regression model

{
  "object": "explanation",
  "id": "exp_ff2c68553239e0c1fc24",
  "model_id": "mdl_c7a1a5c913dfba75c832",
  "prediction_id": "pred_c19d756a3eb6e72423d5",
  "method": "shap",
  "input": {
    "temperature": 31.5,
    "hour": 17,
    "day_type": "weekday",
    "humidity": 0.62,
    "wind_speed": 3.1,
    "solar_irradiance": 410,
    "industrial_index": 1.08
  },
  "output": {
    "value": 3072.56,
    "name": "demand_mw",
    "unit": "MW"
  },
  "attributions": {
    "temperature": 232.35,
    "hour": 81.11,
    "day_type": 32.99,
    "humidity": -16.76,
    "wind_speed": 2.02,
    "solar_irradiance": -77.07,
    "industrial_index": -396.71
  },
  "base_value": 3214.64,
  "top_features": [
    {
      "feature": "industrial_index",
      "attribution": -396.708437,
      "value": 1.08,
      "share": 0.4728,
      "direction": "negative",
      "rank": 1
    },
    {
      "feature": "temperature",
      "attribution": 232.346286,
      "value": 31.5,
      "share": 0.2769,
      "direction": "positive",
      "rank": 2
    },
    …
  ],
  "counterfactual": {
    "found": true,
    "changes": [
      {
        "feature": "industrial_index",
        "from": 1.08,
        "to": 121.43,
        "output_after": 3715.4
      }
    ],
    "output_before": 3072.56,
    "output_after": 3715.4,
    "n_evals": 86,
    "target": {"kind": "reach_value", "target_value": 3220.65}
  },
  "n_evals": 8344,
  "latency_ms": 88.59,
  "options": {
    "seed": 0,
    "counterfactual": true,
    "top_k": 4,
    "estimator": "kernel",
    "exact": true,
    "n_coalitions": 126,
    "background_rows": 64,
    "background_source": "reference_data"
  },
  "metadata": {"api_key": "km_live_fPaB"},
  "created_at": "2026-10-31T22:40:25.499855Z"
}

#Image explanations

For an image feature the attributions are per region, and options carries everything needed to draw the answer the way the dashboard does. kaimei.images renders these fields byte for byte.

Fields in options

heatmaparray of arrays

A grid covering the image, at most 64 cells a side. Occlusion and LIME values are in [-1, 1] (negative is evidence against the target); Grad-CAM in [0, 1].

segmentsarray of arrays

Region id per heatmap cell.

regionsarray

{id, name, attribution, area, centroid, bbox, anchor} per region. Names follow position (upper left, centre 3); anchor is a point inside the region for a number badge; coordinates are fractions of the image.

focusobject

The smallest region holding half of the evidence: threshold, share, area, centroid, bbox, position, anchor.

evidenceobject

P(target) for the full photo (full), with the focus hidden (without_focus) and with only the focus kept (focus_only); fill is blur (with blur_sigma) for photos, gray for thumbnails.

summarystring

A plain-English sentence about where the model looked and how much that region alone decides.

target, target_classstring

The class the attributions are for.

segmentation, n_segments, grid

How the image was cut. grid_requested / n_samples_requested and budget_seconds appear when the explanation was coarsened to fit the time budget.

layer, channel_weights, gradient

Grad-CAM: the feature map read, the per-channel weights and how the gradient was taken (analytic).

score_space, background, occluder

Occlusion: attributions are changes in log_odds; regions were hidden by blur or gray.

201 CreatedGrad-CAM on the cats-dogs demo

{
  "object": "explanation",
  "id": "exp_e0b444d4c9fc6e527a6e",
  "model_id": "mdl_8f795e8afd954a787785",
  "method": "gradcam",
  "input": {
    "image": [
      [[0.13, 0.85, 0.76], [0.26, 0.5, 0.45], …],
      …
    ]
  },
  "output": {
    "label": "dog",
    "class_index": 1,
    "probability": 0.9042,
    "probabilities": {"cat": 0.0958, "dog": 0.9042},
    "target_label": "dog",
    "target_index": 1,
    "value": 0.9042,
    "name": "species"
  },
  "attributions": {
    "top left": 0.221786,
    "top mid-left": 0.196378,
    "top mid-right": 0.0,
    "top right": 0.435271,
    "upper left": 0.267341,
    …: …
  },
  "base_value": 0.0,
  "top_features": [
    {
      "feature": "top right",
      "attribution": 0.435271,
      "value": null,
      "share": 0.2959,
      "direction": "positive",
      "rank": 1
    },
    …
  ],
  "counterfactual": null,
  "n_evals": 3,
  "latency_ms": 5.52,
  "options": {
    "target_class": "dog",
    "target": "dog",
    "layer": "conv2",
    "channel_weights": [0.171488, -0.032645, …],
    "gradient": "analytic",
    "segmentation": "grid",
    "n_segments": 16,
    "grid": 4,
    "heatmap": [[0.8871, 0.8871, …], …],
    "segments": [[0, 0, …], …],
    "regions": [
      {
        "id": 3,
        "name": "top right",
        "attribution": 0.435271,
        "area": 0.0625,
        "centroid": [0.875, 0.125],
        "bbox": [0.75, 0.0, 1.0, 0.25],
        "anchor": [0.8438, 0.0938]
      },
      …
    ],
    "focus": {
      "threshold": 0.7637,
      "share": 0.5,
      "area": 0.0625,
      "centroid": [0.2812, 0.375],
      "bbox": [0.0, 0.0, 1.0, 0.5],
      "position": "upper right",
      "anchor": [0.9375, 0.0625]
    },
    "evidence": {
      "label": "dog",
      "full": 0.904212,
      "without_focus": 0.845568,
      "focus_only": 0.976017,
      "fill": "gray"
    },
    "summary": "The model looks mostly at the upper right of the photo: half of its evidence for dog sits in 6% of the picture. That region alone is enough to say dog (P(dog) = 97.6%), and so is the rest of the photo (P(dog) = 84.6% with the region hidden).",
    "top_k": 8,
    "log_prediction": true
  },
  "created_at": "2026-10-31T22:40:23.801563Z"
}

#List explanations

GET/v1/explanationsAPI key or session

Explanations in your organization, newest first.

Query parameters

modelstringoptional

Model id or slug.

prediction_idstringoptional

Explanations of one prediction.

methodstringoptional

One method name, or provided.

limitintegeroptionaldefault 20

1 to 200.

offsetintegeroptionaldefault 0

Returns

A page of Explanations.

page = client.explanations.list(model="credit-risk-v3", method="shap", limit=50)
for explanation in page.data:
    print(explanation.id, explanation.output["label"], explanation.top_features[0]["feature"])

curl "https://api.kaimei.ai/v1/explanations?model=credit-risk-v3&limit=2" \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "object": "list",
  "data": [
    {
      "object": "explanation",
      "id": "exp_7d7add16c796eafac087",
      "model_id": "mdl_390bd6d9568f626851ef",
      "prediction_id": "pred_8f2a19",
      "method": "shap",
      "input": …,
      "output": {
        "label": "decline",
        "class_index": 1,
        "probability": 0.5947,
        "probabilities": {"approve": 0.4053, "decline": 0.5947},
        "target_label": "decline",
        "target_index": 1,
        "value": 0.5947,
        "name": "decision"
      },
      "attributions": …,
      "base_value": 0.4904,
      "top_features": …,
      "counterfactual": {
        "found": true,
        "changes": [
          {
            "feature": "credit_score",
            "from": 681,
            "to": 850,
            "output_after": 0.0834,
            "label_after": "approve"
          }
        ],
        "output_before": 0.5947,
        "output_after": 0.0834,
        "n_evals": 95,
        "target": {"kind": "flip_decision", "threshold": 0.5}
      },
      "n_evals": 32865,
      "latency_ms": 417.82,
      "options": …,
      "metadata": {"reviewer": "ops", "api_key": "km_live_fPaB"},
      "created_at": "2026-10-31T22:40:23.705348Z"
    },
    …
  ],
  "total": 16,
  "limit": 2,
  "offset": 0,
  "has_more": true
}

#Retrieve an explanation

GET/v1/explanations/{explanation_id}API key or session

One explanation by id.

Path parameters

explanation_idstringrequired

Returns

An Explanation.

explanation = client.explanations.retrieve("exp_7d7add16c796eafac087")

curl https://api.kaimei.ai/v1/explanations/exp_7d7add16c796eafac087 \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "object": "explanation",
  "id": "exp_7d7add16c796eafac087",
  "model_id": "mdl_390bd6d9568f626851ef",
  "prediction_id": "pred_8f2a19",
  "method": "shap",
  "input": {
    "income": 72000,
    "credit_score": 681,
    "utilization": 0.41,
    "debt_to_income": 0.38,
    "loan_amount": 18000,
    "employment_years": 4,
    "num_delinquencies": 1,
    "age": 34,
    "home_ownership": "rent"
  },
  "output": {
    "label": "decline",
    "class_index": 1,
    "probability": 0.5947,
    "probabilities": {"approve": 0.4053, "decline": 0.5947},
    "target_label": "decline",
    "target_index": 1,
    "value": 0.5947,
    "name": "decision"
  },
  "attributions": {
    "income": -0.052572,
    "credit_score": 0.02092,
    "utilization": -0.062237,
    "debt_to_income": 0.079706,
    "loan_amount": -0.022242,
    "employment_years": 0.007327,
    "num_delinquencies": 0.07484,
    "age": 0.012778,
    "home_ownership": 0.045748
  },
  "base_value": 0.4904,
  "top_features": [
    {
      "feature": "debt_to_income",
      "attribution": 0.079706,
      "value": 0.38,
      "share": 0.2107,
      "direction": "positive",
      "rank": 1
    },
    {
      "feature": "num_delinquencies",
      "attribution": 0.07484,
      "value": 1,
      "share": 0.1978,
      "direction": "positive",
      "rank": 2
    },
    {
      "feature": "utilization",
      "attribution": -0.062237,
      "value": 0.41,
      "share": 0.1645,
      "direction": "negative",
      "rank": 3
    },
    {
      "feature": "income",
      "attribution": -0.052572,
      "value": 72000,
      "share": 0.1389,
      "direction": "negative",
      "rank": 4
    },
    {
      "feature": "home_ownership",
      "attribution": 0.045748,
      "value": "rent",
      "share": 0.1209,
      "direction": "positive",
      "rank": 5
    }
  ],
  "counterfactual": {
    "found": true,
    "changes": [
      {
        "feature": "credit_score",
        "from": 681,
        "to": 850,
        "output_after": 0.0834,
        "label_after": "approve"
      }
    ],
    "output_before": 0.5947,
    "output_after": 0.0834,
    "n_evals": 95,
    "target": {"kind": "flip_decision", "threshold": 0.5}
  },
  "n_evals": 32865,
  "latency_ms": 417.82,
  "options": {
    "seed": 0,
    "counterfactual": true,
    "max_changes": 3,
    "frozen_features": ["age"],
    "log_prediction": true,
    "top_k": 5,
    "estimator": "kernel",
    "exact": true,
    "n_coalitions": 510,
    "n_samples": 510,
    "background_rows": 64,
    "background_source": "reference_data"
  },
  "metadata": {"reviewer": "ops", "api_key": "km_live_fPaB"},
  "created_at": "2026-10-31T22:40:23.705348Z"
}