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

# Native planning options and evaluator selection

> Select the native planner's evaluator, depth, work budgets, extensions, and exploration settings, and inspect the limits reported by each search.

Configure native Adapt-1 planning through the request's `options` object and its request-level evaluator fields. Match the search limits to the application's transition unit, then inspect the completed work and evaluator identity in the response. The [integration guide](https://docs.reilabs.org/docs/planning/integration.md) describes HTTP graphs and streaming expansion.

> [!NOTE]
>
> Types and ranges below describe schema version 5. Defaults for nullable options and behavior notes include observed responses. Check `/version` at the API host root and confirm compatibility with your deployment. The [HTTP reference](https://docs.reilabs.org/docs/planning/api.md) describes the request fields.

## Select the evaluator

`evaluator_source` belongs at the request level, alongside `relation`, `policy`, `root`, and `options`.

| Value | Selection |
| - | - |
| `domain_model` | Default evaluator source for the Domain path |
| `value_model` | Installed value learner |
| `value_candidate` | Value candidate under evaluation |

Use `expected_model_sha256` to bind the expected model identity where the planning contract supports it, and check the returned evaluator identity.

Use `evaluator_source: domain_model` for the installed Domain evaluator, including a compatible `sequential_q_mlp`. Responses identify `evaluator.model_type`, `evaluator.model_sha256`, and `evaluator.model_version`. [Align its value objective](#align-the-value-objective) when comparing its choices with another evaluator.

This illustrative response fragment shows the reported model type and identity field. The hash is a placeholder; preserve the actual returned hash and model version.

```json Evaluator identity fragment theme={null}
{
  "evaluator": {
    "model_type": "sequential_q_mlp",
    "model_sha256": "<returned model SHA-256>"
  }
}
```

Completed successors can supply exact `terminal_value` scores, which take precedence over learned estimates. Keep a record of whether terminal scores or learned frontier values determined a choice. See [value learning](https://docs.reilabs.org/docs/neuroadapt/value-learning.md) for fitting the value evaluator.

## Check evaluator readiness

Confirm that the chosen evaluator exists before the first planning request. Requests without an installed model have been refused even when every reachable leaf within the requested depth supplied an exact `terminal_value`.

| Evaluator source | What to check | Reported refusal without a model |
| - | - | - |
| `domain_model` | The Domain has an installed model for the selected binding | HTTP `422`: `owned Domain has no installed value model; supply a numeric checkpoint or train it first` |
| `value_model` | `value/state` identifies the installed value learner | HTTP `409`: `owned Domain has no installed value model` |
| `value_candidate` | `value/state` identifies the candidate you intend to evaluate | Confirm the missing-candidate response for your deployment |

The `domain_model` refusal names a numeric checkpoint as an alternative. The documented request schema types `checkpoint` only as an object or `null`; its supported contents and source compatibility are not yet documented. Follow the installed-model workflow until you have a confirmed checkpoint contract for your deployment.

For sequential acquisition, confirm eligible feedback admission, `training.min_samples`, `sequential.minimum_episodes`, retained episode coverage, completed asynchronous fitting, and a passing validation result. Installation depends on these combined conditions. If training reports `candidate_failed_validation`, inspect reward variation and the validation report; constant-reward acquisition has returned that result. See [sequential installation checks](https://docs.reilabs.org/docs/neuroadapt/sequential-learning.md#feedback-accumulates-without-an-installed-sequential-model).

For the separate value learner, complete [initial fitting and installation](https://docs.reilabs.org/docs/neuroadapt/value-learning.md#run-the-learning-cycle), inspect `value/state`, and then verify the evaluator identity returned by planning.

## Align the value objective

Use one objective and perspective, with compatible neutral values, discounts, and horizon conventions for evaluator estimates and terminal scores. Match the objective as well as the numeric range.

Sequential values are learned from the configured rewards and transitions. An outcome-trained value learner estimates the supplied outcome target. If sequential rewards include intermediate benefits or costs that terminal scores omit, search can change the chosen action because it is comparing different objectives. Exact terminal values take precedence over learned frontier estimates.

When the task objective is a terminal outcome, the value learner's `outcome` targets provide an explicit way to set its value, neutral, discount, and terminal step. Align those settings with planning and validate decisions at the intended search depth. Choose the evaluator whose learned objective matches the task. See [outcome targets](https://docs.reilabs.org/docs/neuroadapt/value-observations.md#observed-outcome) and [rewards and costs in the graph](https://docs.reilabs.org/docs/planning/integration.md#represent-rewards-and-costs).

### Observed terminal discounting

Observed terminal values have matched `n + (t - n) * gamma^d`, where `n` is `neutral_value`, `t` is `terminal_value`, `gamma` is `temporal_discount`, and `d` is the number of transitions to the terminal state.

| Terminal value | Transitions to terminal | Neutral | Discount | Calculated value |
| - | -: | -: | -: | -: |
| `0.6` | 1 | `0.5` | `0.8` | `0.58` |
| `1.0` | 5 | `0.5` | `0.8` | `0.66384` |
| `1.0` | 8 | `0.5` | `0.8` | `0.58388608` |

The one-step calculation is `0.5 + (0.6 - 0.5) * 0.8 = 0.58`. These calculations illustrate terminal discounting toward neutral. For learned frontier values, confirm the backup rule and its interaction with already-discounted training targets in your deployment's contract.

## Bound search work

| Option | Schema default | Use and interpretation |
| - | - | - |
| `max_depth` | `3` | Integer from `1` to `16`. Ordinary search-depth limit; first define one application transition. |
| `branch_width` | `null` | Null or an integer from `1` to `256`. Full width by default; the child-ranking and pruning rule needs confirmation. |
| `max_evaluations` | `4096` | Integer from `1` to `100000`. Inspect the response's `evaluations` and budget diagnostics. |
| `max_transitions` | `200000` | Integer from `1` to `1000000`. Inspect the response's `transitions` and budget diagnostics. |
| `timeout_seconds` | `30` | Number from `1` to `300`. Inspect `deadline_reached` as well as the completed search. |

Treat these as separate limits. Read `completed_depth` for achieved ordinary depth and `budget_exhausted` and `deadline_reached` for stopping conditions. Record every reported stopping condition when multiple limits are reached.

The following fragment makes the schema's depth and work defaults explicit. It is an `options` object, not a complete planning request.

```json Planning options fragment theme={null}
{
  "max_depth": 3,
  "branch_width": null,
  "max_evaluations": 4096,
  "max_transitions": 200000,
  "timeout_seconds": 30,
  "max_extensions": 0,
  "exploration_probability": 0
}
```

## Extensions, proof bounds, and rechecks

| Option | Schema default | Contract detail |
| - | - | - |
| `max_extensions` | `0` | Integer from `0` to `8`. Inspect `extensions` and `completed_extensions` alongside traces and work counts. |
| `extension_mode` | `all` | Accepted values: `all`, `competitive`, `equilibrium`. The conditions that trigger each mode are not yet specified in the available contract. |
| `terminal_proof_bounds` | `null` | Null or an array of exactly two numbers. The ordering and proof semantics of the pair need confirmation. |
| `recheck_pruned_branches` | `false` | The branches revisited, timing, and budget accounting need confirmation. |
| `stability_tolerance` | `0` | Nonnegative number. The measured quantity and effect on stopping or extension need confirmation. |

Use `completed_depth` for completed ordinary search depth and extension counters for extension work. Report these quantities separately. Start with the documented defaults and confirm each optional mode's trigger and accounting rules for your deployment before changing it.

Extensions can reach terminal states beyond the ordinary depth limit. Read `extensions`, `completed_extensions`, and `evaluations` separately; these counters describe different aspects of the completed work.

Record explored paths and work counters to show the depth reached and work performed by each extension mode. Compare modes across representative graphs and decision roles, and confirm their trigger and increment rules against the deployment contract.

## Reuse, value scaling, and exploration

| Option | Schema default | Contract detail |
| - | - | - |
| `reuse_tree` | `false` | Tree reuse is opt-in. Its lifetime and boundaries across calls, sessions, Domains, and model changes need confirmation. |
| `cache_values` | `false` | Value caching is opt-in. Cache keys, lifetime, and invalidation after a model change need confirmation. |
| `exploration_probability` | `0` | Number from `0` to `1`. Confirm returned attribution for an explored action before relying on it in audit logic. |
| `exploration_seed` | `null` | Optional nonnegative integer, with an upper bound in the schema. Bind whole-search reproducibility checks to the build and complete request. |
| `temporal_discount` | `1` | Number greater than `0` and at most `1`. See [observed terminal discounting](#observed-terminal-discounting); the general frontier backup and interaction with value-target discounting still need confirmation. |
| `neutral_value` | `0.5` | Planner setting; keep the declared value perspective consistent with the evaluator and terminal scores. |
| `complementary_total` | `null` | The perspective-conversion rule for a non-null value needs confirmation. |

Configure `temporal_discount` in planning and construct training targets through value observations. To blend a continuation assessment with an observed outcome, calculate the target explicitly and preserve its inputs. See [value observations](https://docs.reilabs.org/docs/neuroadapt/value-observations.md) for target construction.

For a controlled comparison, hold planning options and the transition interface fixed while changing the evaluator. Use `exploration_probability: 0` when evaluating the planner's selected action without exploration. Track model identities independently of cache counters.

## Inspect the result

Record the requested options, returned action, legality check, evaluator identity, completed depth, extensions, evaluation and transition counts, cache counters, and stopping diagnostics. `evaluator.learning_updates` reports evaluator updates within the call; it is separate from search work.

Observed calls returned `evaluator.learning_updates: false`. Planning evaluates the supplied continuations with the selected evaluator. After executing the chosen action, admit its measured outcome through the appropriate learning write. A fit started earlier can finish while planning requests are running. See [frozen-use rules](https://docs.reilabs.org/docs/neuroadapt/choose-a-learning-setup.md#interactions-during-frozen-use).

Native planning routes use `/api/v1/domains/{domain_id}/planning/adversarial` and the corresponding `/stream` WebSocket. The route name supports tasks with only maximizing decisions as well as opposing decisions. [HTTP and contracts](https://docs.reilabs.org/docs/neuroadapt/request-contracts.md) explains authentication and request addressing.


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