> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reilabs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Inspect learning and troubleshoot

> Check forecast resolution, compare issued forecasts with the prior, and diagnose abstentions.

Use `POST /domains/{id}/explain` to inspect current learning state:

```json theme={null}
{
  "session_id": "my-stable-session",
  "question": "Inspect learning state",
  "context": {"values": {}},
  "update_memory_state": false
}
```

Omit `decision_id` for current state. Supplying it explains the saved decision
snapshot instead. This inspection does not issue a new forecast receipt: use
`/query` for a prediction you intend to resolve later. `GET /domains/{id}` returns
the declaration and event count, not this live learning-state block.

Inspect these response paths:

```text theme={null}
learning_state.subsystems.structured_transition
learning_state.subsystems.structured_transition.futures
learning_state.subsystems.feedback_policy   (if separately enabled)
```

The futures state includes:

* `resolved_count`: completed forecast targets that have been scored.
* `pending_forecasts`: issued receipts still awaiting an outcome.
* `calibration_groups`: retained conditioning histories.
* `mean_energy_score`: score of the issued distributions; lower is better.
* `mean_prior_energy_score`: score of the corresponding unconditioned forecasts
  on the same outcomes; also lower is better.

Interpret the signal in context. A growing transition sample count proves that
eligible observations were ingested; it does not prove useful prediction. A
growing `resolved_count` proves forecast/outcome linkage. Useful prediction is
demonstrated by held-out or prediction-before-update scores, and useful planning
by the actual outcomes or costs of the executed decisions.

For a fair application test:

1. Fix the data split, target, metrics and action costs before comparing settings.
2. Start separate fresh Domains with identical observations for each setting.
3. Compare `conditioning: "adaptive"`, `"prior"` and `"kernel"`; compare numeric
   transport on/off separately when the task has numeric targets.
4. In an online test, save the prediction before exposing its outcome, then learn.
5. In a frozen test, train on an earlier partition and issue forecasts on a new
   partition without sending its outcomes, rewards or configuration changes to
   the learner. Score externally.
6. Compare the same targets with the same scaling. Use energy score for joint
   distributions, Brier/log loss for categorical probabilities, numeric forecast
   error and interval coverage, and realized utility/cost for action decisions.

For a frozen test, unresolved receipts still occupy capacity even though labels
are withheld. Configure sufficient `max_pending_forecasts` in advance, within
its limit. Do not resolve test targets during the frozen run merely to free space:
resolution changes calibration. Query bookkeeping is distinct from learning.

## Troubleshooting

| Symptom | Check or action |
| - | - |
| `401` / `403` | Correct UAT key and Bearer header; confirm access to that deployment. |
| Domain `404` | Same key, owner/session and Domain ID as creation. |
| `422` for `futures`, `probabilistic` or `numeric_transport` | Verify payload nesting and that your deployment supports those fields. |
| No `futures` output | Enable it under `learning.transition`, request `transition_prediction`, and read back the effective configuration. |
| Point forecast abstains but futures predicts | Read the nested futures status; partial-input support differs. |
| Sample count stays zero | Inspect event eligibility, declared event types, input/group paths and actual target types. Memory storage alone is not transition ingestion. |
| Many samples but forecast still abstains | Check matching action/group support and evidence distance, not just total records. |
| Samples grow but `resolved_count` does not | Outcomes are not resolving issued forecasts. Send the actual returned decision ID and matching future/group/action. |
| `future_context_mismatch` | The outcome action or grouping differs from the recorded forecast. Do not relabel another execution to make it match. |
| `future_id_mismatch` | The supplied future ID differs from the issued forecast. |
| `not_linked_or_already_resolved` | Unknown/missing decision link or a previously completed target. Check the request trace before resubmitting. |
| Pending forecast capacity reached | Resolve genuine outstanding outcomes or increase the declared bounded capacity. Do not fabricate outcomes to clear it. |
| An already resolved future ID is rejected | Generate a new ID for a new eventual outcome; never recycle completed target IDs. |
| Numeric transport is not active | Check numeric input availability, sufficient varied support, `numeric_min_skill`, and transport validation diagnostics. |
| Probabilities barely change | Check whether the new evidence is actually supplied, whether it distinguishes outcomes, and whether linked outcomes have validated conditioning. |
| Planner abstains | Inspect rejected sequences, modeled constraint failure, unresolved mass and rollout budget. Fix missing support before relaxing safety limits. |
| Planner says `probabilistic_rollout_budget_reached` | Reduce horizon/branching or increase `max_rollouts` within the supported bound. |
| Correct plan, wrong application action | Consume `transition_plan.selected_action`; do not accidentally use the separate `selection.selected_policy`. |
| Repeated outcome affects counts unexpectedly | Resolve once and maintain application-level execution IDs. Duplicate suppression is bounded, not an unlimited historical deduplication service. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.