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

# Explain a result

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

export const AuditSurface = () => {
  const areas = [{
    label: "Support",
    field: "supporting_memories · core_support",
    detail: "Evidence and learned structure returned in support of the current result.",
    tone: "border-emerald-200 bg-emerald-50 dark:border-emerald-900 dark:bg-emerald-950"
  }, {
    label: "Co-active associations",
    field: "conflicts · selected route contract",
    detail: "Here, conflicts names associations that remain active together; it does not mean logical contradiction.",
    tone: "border-violet-200 bg-violet-50 dark:border-violet-900 dark:bg-violet-950"
  }, {
    label: "Missing evidence",
    field: "missing_evidence",
    detail: "Information whose absence limits confidence or separates currently active alternatives.",
    tone: "border-amber-200 bg-amber-50 dark:border-amber-900 dark:bg-amber-950"
  }, {
    label: "Predicted observations",
    field: "predicted_observations",
    detail: "Observations the current result says could be encountered next.",
    tone: "border-sky-200 bg-sky-50 dark:border-sky-900 dark:bg-sky-950"
  }];
  return <figure className="not-prose my-8 overflow-hidden rounded-2xl border border-slate-200 bg-white dark:border-zinc-800 dark:bg-zinc-950" aria-labelledby="audit-surface-title audit-surface-caption">
<div className="border-b border-slate-200 px-5 py-4 dark:border-zinc-800">
<div className="text-xs font-semibold uppercase tracking-widest text-slate-500 dark:text-zinc-400">Result audit surface</div>
<div id="audit-surface-title" className="mt-1 text-sm text-slate-700 dark:text-zinc-300">Read the route-defined evidence around one returned result.</div>
</div>
<div className="p-4">
<div className="mx-auto mb-4 max-w-sm rounded-xl border border-slate-300 bg-slate-50 px-4 py-3 text-center dark:border-zinc-700 dark:bg-zinc-900">
<div className="font-mono text-xs text-slate-500 dark:text-zinc-400">current API result</div>
<div className="mt-1 text-sm font-semibold text-slate-900 dark:text-zinc-100">Inspectable evidence, not a chain-of-thought transcript</div>
</div>
<div className="grid gap-3 md:grid-cols-2">
{areas.map(area => <div key={area.label} className={"rounded-xl border p-4 " + area.tone}>
<div className="text-sm font-semibold text-slate-900 dark:text-zinc-100">{area.label}</div>
<div className="mt-1 font-mono text-xs text-slate-600 dark:text-zinc-300">{area.field}</div>
<div className="mt-2 text-xs leading-5 text-slate-600 dark:text-zinc-400">{area.detail}</div>
</div>)}
</div>
</div>
<figcaption id="audit-surface-caption" className="border-t border-slate-200 px-5 py-3 text-xs leading-5 text-slate-600 dark:border-zinc-800 dark:text-zinc-400">
This grouping uses route-defined examples. Inspect the selected route's schema; the visual does not redefine fields or depict separate internal modules.
</figcaption>
</figure>;
};

## Outcome

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

<AuditSurface />

## Workflow

```text theme={null}
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:

```bash theme={null}
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:

```text theme={null}
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`:

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

## 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](/docs/neuroadapt/design-transition-domains) 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.