Explain a result

Inspect evidence, support, conflicts, abstention, and learner state without changing Domain state.

Outcome

Your application can inspect the fields returned around a result, what remains uncertain, and what additional evidence could change it.

Workflow

run the goal loop -> request explanation -> inspect returned fields -> add or correct evidence -> run again

Explanation is an audit surface over the result. It is not a requirement for every prediction and it is not a generated chain-of-thought transcript.

Gateways

Result being audited	Route
Session/state query	POST /api/v1/memory/explain
Domain query	POST /api/v1/domains/{domain_id}/explain

Sealed-decision audit

A normal Domain query can return a sealed decision_id. To explain exactly the evidence and state of that earlier result, use:

curl -fsS -X POST https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}/explain \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<session-id>","decision_id":"<decision-id>"}'

Depending on the Domain contract, the sealed explanation can include ranked hypotheses, supporting and counterevidence memories, missing and predicted observations, transition prediction, induced structure, selection diagnostics, policy scores, learning state, and Core support. Treat explanatory associations as diagnostic unless the application explicitly supplies them to another request.

Audit fields

Use only the fields relevant to the audit question. Depending on the route and response contract, these can include:

evidence
seed_concepts
activated_concepts
reasoning_edges
discovered_connections
conflicts
resolution
ranked_hypotheses
supporting_memories
missing_evidence
predicted_observations
core_support
diagnostics

Field names that are part of the API contract remain unchanged. They are meaningful, but their meanings are specific to this system and route. Do not replace a documented technical meaning with the ordinary implication of the English label.

Read-only transition inspection

Call the applicable Domain query and /explain. Include all query fields and grouping fields that the Domain requires.

If the route supports these fields, set both fields to false:

{
  "allow_exploration": false,
  "update_memory_state": false
}

Keep the complete response for each read-only call. Do not keep only the prediction. Review unsupported results, new support, boundary inputs, and contradictory evidence.

Inspect these fields when the selected route returns them:

• transition_prediction;
• evidence memory IDs;
• learning_state;
• the selection or abstention reason;
• supporting evidence IDs and counterevidence IDs;
• supporting_memories;
• missing_evidence;
• predicted_observations;
• core_support;
• Domain, schema, model, and subsystem versions.

Compare the documented learner-state hash and applicable versions before and after each read-only call. The values must not change.

The API can also return a broader service value that contains access telemetry. Do not use this value as learner state unless the route contract defines it as learner state.

Unless the route contract specifies another meaning, confidence is a support signal. It is not a probability of correctness or an exploration policy. Examine evidence IDs, group values, distance, disagreement, missing evidence, and the selection or abstention reason.

Hypothesis contract

A transition configuration does not automatically create competing hypotheses. An empty hypotheses list can mean that the Domain has no configured candidates.

Use candidates that have equal status and describe the same relation. Each candidate must predict a different observable consequence. A candidate must not contain the preferred answer.

Before the application uses hypotheses:

1. Send ordinary events that distinguish the candidates.
2. Call /explain without feedback.
3. Confirm that supporting evidence or counterevidence changes between candidates.
4. If the evidence does not change, identify the contract that updates hypotheses.
5. Treat transition output and hypothesis output as separate API contracts.

See Design Domains for transition learning for Domain configuration and response checks.

conflicts semantics

In this contract, conflicts refers to the superposition of associations that remain active together. It does not mean that Core has derived a formal logical contradiction.

Keep the API key unchanged and explain that mapping directly wherever the field appears. Treat reasoning_edges, ranked_hypotheses, supporting_memories, diagnostics, and related keys as route-specific observable fields rather than one-to-one names for internal modules.

Cross-call causal structure

Explanation fields show how the current result is organized. Across calls, the application can connect returned support to scoped adaptation, reusable action-effect structure, and goal-conditioned behavior.

Observable surface	What it lets you inspect
Ordered observation, Adapt-1 result, action, transition, and outcome records	How reasoning connected to one environmental transition
Scoped policy_scores or state change after feedback	How the received outcome revised behavior in that scope
Reusable action-effect or next-state prediction across later states	How learned causal structure carries into new transitions
Multistep behavior driven by returned selections	How Adapt-1’s learned structure organizes a goal-directed sequence

Causal structure becomes visible across calls when returned predictions or selections and later transitions show a learned mapping being reused. Explanation fields add the supporting context around that adaptive behavior.

Explanation and adaptation

The response exposes contract-defined fields around the current API result, giving applications an audit surface over Core’s persistent adaptive substrate.

For a feedback workflow, explanation fields help audit the result while policy_scores remains the documented learned signal. For an adaptive structured prediction, the application still consumes prediction.<output_key>; explanation is optional.

An explanation shows why the current result is supported. Combine it with ordered transitions, scoped behavioral change, and later predictions to follow causal learning and planning as they develop across use.