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

# Planning integration

> Connect actions, successor states, and value estimates to native search and inspect its decisions.

For the relationship between learning, search, and execution, start with [Learning and planning](/docs/planning/overview.md).

Connect an application's available actions, possible successor states, and evaluator to native search. The planner compares continuations within depth and work limits and returns an action for the application to validate and execute.

Successors can come from exact rules, simulation, or learned forecasts. For the separate Domain-query workflow that predicts successive states itself, use [Planning over learned transitions](/docs/neuroadapt/design-transition-domains.md#planning-over-learned-transitions).

## Evaluate continuations

A transition model predicts an action's effects. A value model estimates the utility of an unfinished state. Exact terminal values score completed outcomes and take precedence over learned estimates.

Keep all values in one perspective. For opposing decisions, maximizing nodes choose the highest continuation value and minimizing nodes choose the lowest. A task without an opponent can use only maximizing nodes. The `/planning/adversarial` route name does not require an opponent.

Record which evaluator supplies the values. Distinguish an installed model, a selected candidate, and a caller checkpoint. A fixed adapter can carry another model's scores into search; record both identities. An installed model's presence does not prove that it ranked the alternatives when explicit terminal scores determined the choice.

## HTTP requests

`POST /domains/{id}/planning/adversarial` accepts a finite set of states and action edges, with a root descriptor and nodes. Each child edge identifies an action and refers to its successor through `target`:

```json theme={null}
{"action": "<executable action>", "target": "<successor node id>"}
```

This is an edge fragment, not a complete request. The top-level `policy` field identifies the policy or value binding. It is distinct from the executable action on an edge.

Define the unit of one transition before setting depth. A transition can represent a primitive action, an action block, or a complete skill. The application constructs valid successors, including any accounting or uncertainty propagation needed by its task.

The Core callback interface `plan_adversarial(...)` provides a separate integration through action, transition, actor-role, terminal-value, and evaluator callbacks.

## Streaming expansion

WebSocket `/domains/{id}/planning/adversarial/stream` lets the server request successors as search proceeds. The recorded initial request includes `session_id`, `relation`, `policy`, `root`, `options`, `evaluator_source`, and `expected_model_sha256`.

An `expand` message identifies a `state_id` and `request_id`. The client generates legal successors and returns children with full `state` descriptors. This abbreviated response shows the message shape:

```json theme={null}
{
  "request_id": "<the expansion request id>",
  "children": [
    {"action": "<legal action>", "state": {"id": "<successor id>"}}
  ]
}
```

Each real descriptor must also include the perspective, features, and terminal status required by the evaluator. HTTP edges use `target`; streamed children use `state`. Check that the final `result` identifies the requested evaluator and returns a legal action.

These hosted shapes come from recorded Fast-UAT integrations. They are partial examples, not complete public schemas or a new deployment test. Use [HTTP and contracts](/docs/neuroadapt/request-contracts.md) for authentication, scope, and request validation.

## Search diagnostics

| Field | Meaning |
| - | - |
| `max_depth` / `completed_depth` | Requested ordinary limit / completed base depth |
| `max_extensions` / `extensions` | Configured ceiling / reported extension work |
| `completed_extensions` | Completed extension counter; inspect actual work and traces alongside it |
| `evaluations`, `transitions`, cache counters | Search work, not training samples |
| `budget_exhausted`, `deadline_reached` | Resource limits that ended work |
| `evaluator.learning_updates` | Evaluator updates within this planning call |

Extensions are not extra-ply counts. Do not add `max_depth` and `max_extensions` to report achieved depth. The separate `transition_plan` response uses `search.depth` and `horizon_complete`; preserve those field names.

Validate the selected action and record what the executor performed. Use [decision boundaries](/docs/neuroadapt/learning-patterns-for-domains.md#decisions-beyond-the-next-move) for first-action replanning, [retained sequence selection](/docs/machina/retained-use.md#select-from-retained-sequences) for complete skills, and [frozen-use rules](/docs/neuroadapt/choose-a-learning-setup.md#interactions-during-frozen-use) for the surrounding learning loop.


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