POST /domains/{id}/explain to inspect current learning state:
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:
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.
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:
- Fix the data split, target, metrics and action costs before comparing settings.
- Start separate fresh Domains with identical observations for each setting.
- Compare
conditioning: "adaptive","prior"and"kernel"; compare numeric transport on/off separately when the task has numeric targets. - In an online test, save the prediction before exposing its outcome, then learn.
- 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.
- 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.
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
- 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 eachdecision_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. - 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. - 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_supportfor 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 show the request order. - Inspect the response before scaling up. Look for
predictedorplannedand the expectedobserved_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 fornumeric_transport.status: "active"and verify the intended paths intarget_paths. For planning, inspectunresolved_probabilityandfailure_probability_upper. For multiple steps, confirm thatcandidate_sequencesranks a known better sequence ahead of a known worse one. This checks support, bindings, and objective scoring together. - Check resolution. Confirm that the update accepted your linked outcome, the expected revisions were resolved, and read-only
/explainshows the expected pending count. Delete the disposable Domain when the probe is complete.
Check conditioning early
Save the issuedprobability, prior, and conditional weights from the joint receipt. 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, and504responses, use bounded exponential backoff with jitter where retry is appropriate. HonorRetry-Afterwhen returned. Reconcile ambiguous/eventswrites against your recorded identifiers and available learner state before resubmitting, including unexpected500responses. Correct invalid400or422requests before retrying. Operations and retries. - For a disposable Domain, arrange
DELETE /domains/{id}in cleanup code. On a transient delete response such as503 engine_checkpoint_busy, reconcile or retry with a bounded policy. Verify deletion with a laterGET /domains/{id}returning404under the same authenticated identity, and retain the delete response in the run log. - At the end of an online run, call
/explainwithupdate_memory_state: false. Confirmpending_forecastsis 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.
