> ## 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.

## Check a Domain before streaming

1. **Verify the observation clock.** Define the target horizon and the timestamp at which the measured outcome becomes available, including timezone and settlement boundaries. Save the issue-time inputs, `future_id`, and each `decision_id`. During live runs and replays, release completed observations in availability order after their forecasts. Apply any scaling or lagged feature calculation with data available at that issue time.
2. **Check the rows locally.** Inspect the standardized feature matrix for collinearity. Check that numeric targets are on comparable scales for joint scoring and that the serialized payload contains finite values. Python's `json.dumps(payload, allow_nan=False)` catches non-finite numbers before a request.
3. **Probe a disposable Domain.** Create it with the intended declaration. Send a small batch of synthetic or representative completed observations, for example 16 to 32 for a compact forecast with modest support requirements. For planning, use enough observations to meet `required_support` for each reachable group and action. Check admission before querying. Issue a forecast and any revision you want to exercise, then resolve it with a later observation. The [runnable examples](https://docs.reilabs.org/docs/neuroadapt/futures/examples.md) show the request order.
4. **Inspect the response before scaling up.** Look for `predicted` or `planned` and the expected `observed_paths`. Sum the forecast receipt's issued atom probabilities and check that the mass is one within rounding tolerance. If you expect numeric transport, check for `numeric_transport.status: "active"` and verify the intended paths in `target_paths`. For planning, inspect `unresolved_probability` and `failure_probability_upper`. For multiple steps, confirm that `candidate_sequences` ranks a known better sequence ahead of a known worse one. This checks support, bindings, and objective scoring together.
5. **Check resolution.** Confirm that the update accepted your linked outcome, the expected revisions were resolved, and read-only `/explain` shows the expected pending count. Delete the disposable Domain when the probe is complete.

## Check conditioning early

Save the issued `probability`, `prior`, and `conditional` weights from [the joint receipt](https://docs.reilabs.org/docs/neuroadapt/futures/distribution.md#read-the-joint-atoms). As outcomes arrive, score all three on the same observations and scale. Review an initial window of resolved forecasts, for example the first 50 to 100, and break down scores by evidence mask, group, and action where support permits. The `/explain` aggregates compare issued and prior forecasts. Scoring the receipt's conditional weights separately tells you whether the evidence weighting itself improves on the prior. If it does not, compare a pruned input set, a different bandwidth, or numeric transport settings on the same sequence.

## Operate the stream

* For transient `429`, `502`, `503`, and `504` responses, use bounded exponential backoff with jitter where retry is appropriate. Honor `Retry-After` when returned. Reconcile ambiguous `/events` writes against your recorded identifiers and available learner state before resubmitting, including unexpected `500` responses. Correct invalid `400` or `422` requests before retrying. [Operations and retries](https://docs.reilabs.org/docs/neuroadapt/operational-behavior-and-retries.md).
* For a disposable Domain, arrange `DELETE /domains/{id}` in cleanup code. On a transient delete response such as `503 engine_checkpoint_busy`, reconcile or retry with a bounded policy. Verify deletion with a later `GET /domains/{id}` returning `404` under the same authenticated identity, and retain the delete response in the run log.
* At the end of an online run, call `/explain` with `update_memory_state: false`. Confirm `pending_forecasts` is zero once the last outcome is available, or reconcile the outstanding receipts with your outcome queue. In a frozen run, budget for intentionally pending receipts.
* Compare configurations in fresh Domains on the same deployment and API version, with the same observation order and concurrency. Use fresh Domain IDs for isolation. Use separate authorized identities when you also need to isolate owner-scoped state.

## Troubleshooting

| Symptom | Check or action |
| - | - |
| `401` / `403` | Check the API key and Bearer header, and confirm the key has access to the 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.