[JGagacheva]

Summary

Enable gradient explanations for kumo-tabular and kumo-relational, one per scored row.

• explanation in outputs is accepted on both models with no row limit. The one-row/one-entity checks and the old 1,000-row context rule for relational explanations are removed; the SDM NIM
  (structured-data-nims 0a8230d) explains every predict row.
• result.explanations maps each row's key (id; (id, forecast_step) for forecasts;
  row_index when the request has no id column) to its explanation, kept out of to_pandas().
  Replaces result.explanation and {'by_forecast_step': ...}.
• An entry is the NIM's sdm_gradient_v1 record with row positions resolved: kumo-tabular gives
  {'outputs', 'instance'}; kumo-relational gives {'outputs', 'related'} with one block per
  table (the entity's own included), each row carrying its primary key when the table has one and
  its values as sent. The engine's question-row block is dropped. Positions are resolved per call,
  so split requests are correct.
• result.explanations.to_pandas() flattens to one line per (row, table, hop, key, row, output,
  column, gradient); hop is computed from the relationships and keys sent.
• Docs, skills, changelog and QA probes updated; unit tests with mocked NIM replies; live tests
  (-m live_nim) for both models pass.

API

Relational

result = client.predict(request, model=KumoRelational(),
                        outputs=['prediction', 'probabilities', 'explanation'])
result.explanations['user_5']
{'outputs': [...],
 'related': {'users':  {'keys': [...], 'rows': [...], 'columns': [...], 'gradients': [...]},  # [output][row][column]
             'orders': {'rows': [...], 'columns': [...], 'gradients': [...]}}}

As one table

result.explanations.to_pandas() gives one line per (row, output, column), across all entities:

id      table   hop  key     row  output           column       gradient
user_5  users   0    user_5  0    probability_yes  tenure_days   0.05
user_5  orders  1    None    0    probability_yes  amount        0.02
user_5  events  1    None    1    probability_yes  kind_login   -0.02

Tabular

result = client.predict(request, model=KumoTabular(),
                        outputs=['prediction', 'probabilities', 'explanation'])

result.explanations[901]            # keyed by the request's id column; by row_index if it has none
{
  'outputs':  [{'kind': 'probability', 'class': 0},
               {'kind': 'probability', 'class': 1}],
  'instance': {
      'columns':   ['age', 'spend'],
      'gradients': [[ 0.012, -0.004],   # probability_0 per unit age, spend
                    [-0.012,  0.004]],  # probability_1
  },
}

result.explanations.to_pandas()

id   table     hop  key  row  output         column  gradient
901  instance  0    901  0    probability_0  age      0.012
901  instance  0    901  0    probability_0  spend   -0.004
901  instance  0    901  0    probability_1  age     -0.012
901  instance  0    901  0    probability_1  spend    0.004

[adi-kumo]

P2: Missing IDs omit row positions from flattened explanations

Question: Should explanations fall back to row-index keys when any scored row lacks an ID? With accepted IDs [None, 90], one explanation is keyed by None and the flattened frame has no row_index column, so callers cannot join that row by position directly. The documentation does not specify mixed null IDs; using row-index keys would preserve that join.

[adi-kumo]

P2: Native forecasts overwrite earlier normalized explanations

When a materialized forecast receives several steps for one row, result.explanations keeps only the last step. Predictions and raw item explanations survive, but normalized access cannot retrieve earlier steps. Include forecast_step in the explanation keys and position metadata, and preserve those pairs when renumbering and merging batches.

[Manushpm8]

All three earlier comments look fixed, thanks. One blocker: 9 commits lack a Signed-off-by, and AGENTS.md says unsigned PRs can't merge; git rebase --signoff main fixes it.