> ## 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](https://docs.reilabs.org/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](https://docs.reilabs.org/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. Use maximizing nodes throughout for a task with no opponent; `/planning/adversarial` supports this single-agent setup.

Record which evaluator supplies the values: an installed model, a selected candidate, or a caller checkpoint. A fixed adapter can carry another model's scores into search; record both identities. For each choice, identify the terminal scores or learned frontier estimates that determined the ranking.

The request-level `evaluator_source` defaults to `domain_model`; `value_model` selects the installed value learner and `value_candidate` selects its candidate. Check [evaluator readiness](https://docs.reilabs.org/docs/planning/options.md#check-evaluator-readiness) before sending the first request, including requests with exact terminal values. An installed `sequential_q_mlp` can be selected through `domain_model`. Use `expected_model_sha256` where supported, inspect the returned evaluator identity, and [align the value objective](https://docs.reilabs.org/docs/planning/options.md#align-the-value-objective). See [value learning](https://docs.reilabs.org/docs/neuroadapt/value-learning.md) for acquiring a separate state-value evaluator.

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

For `value_model` and `value_candidate`, keep the request's relation and policy consistent with the value learner configuration. Observed `domain_model` requests accepted a declared action policy and returned a sequential evaluator. Preserve the requested relation and policy with the returned model identity. Confirm the source-specific resolution of `policy` for frontier estimates against your deployment's contract.

The [HTTP planning reference](https://docs.reilabs.org/docs/planning/api.md) supplies the complete documented `GraphPlanningRequest` schema. It requires `session_id`, `relation`, `policy`, and `root`. A state requires `id` and `maximizing`; graph nodes add `children`. The schema allows up to 4096 supplied nodes and 256 children per node. Objects, relations, conditions, context, numeric features, and exact terminal values describe the evaluator input.

Set search depth, width, budgets, extensions, and exploration in `options`. [Native planning options](https://docs.reilabs.org/docs/planning/options.md) lists the documented fields, its default and range, and the optional behaviors that still need semantic confirmation.

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.

## Represent rewards and costs

An HTTP `GraphEdge` carries `action` and `target`. Search scores the terminal values and evaluator estimates supplied through the node representation. Encode accumulated rewards and costs in those state and value inputs; the edge schema has no `reward` or `cost` field.

Make the intended return explicit in the state and value representation. If two paths reach the same physical state with different accumulated costs, preserve the information needed to distinguish their values. Reusing a node that omits those costs can discard a distinction that matters to the decision.

A learned frontier estimate can account for effects represented in its training target. When search reaches a terminal node, its exact score takes precedence, so that score must preserve the same objective. Folding accumulated rewards into terminal scores also requires a consistent discount and horizon convention. Check this [value alignment](https://docs.reilabs.org/docs/planning/options.md#align-the-value-objective) before interpreting a change with search depth as a change in model quality.

Keep the planner's numeric fields and object representation consistent with those used for fitting. For a `projected` value learner, follow the [input mapping checks](https://docs.reilabs.org/docs/neuroadapt/value-observations.md#verify-projected-inputs) before relying on numeric state features.

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

The HTTP interface also exposes a [GET stream-protocol route](https://docs.reilabs.org/docs/planning/stream-protocol.md) at the same path. That GET description is distinct from the WebSocket connection and does not define its complete message schema.

The HTTP request schema describes schema version 5. The streaming shapes above are abbreviated examples, not a complete WebSocket message contract. Use [HTTP and contracts](https://docs.reilabs.org/docs/neuroadapt/request-contracts.md) for authentication, scope, compatibility, 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 |

Recorded HTTP responses place action and search counters under `plan` and evaluator identity under `evaluator`. Preserve both sections when comparing a candidate with an installed model. The schema leaves the success body untyped, so validate the fields your integration consumes.

Use `completed_depth` for completed ordinary search depth and the extension counters for extension work. These counters use different units, so report them separately. 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](https://docs.reilabs.org/docs/neuroadapt/learning-patterns-for-domains.md#decisions-beyond-the-next-move) for first-action replanning, [retained sequence selection](https://docs.reilabs.org/docs/machina/retained-use.md#select-from-retained-sequences) for complete skills, and [frozen-use rules](https://docs.reilabs.org/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.