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

# Plan with uncertain outcomes

> Choose an action, inspect the probability of failure, and replan after execution.

Use the probabilistic planner when the observed result depends on the action or when the action changes the state you face at the next step. If the same uncertainty applies to every action and your application already has the cost formula, forecast it once and apply that formula to each candidate using the [joint forecast atoms](https://docs.reilabs.org/docs/neuroadapt/futures/distribution.md#read-the-joint-atoms). [Choose a probabilistic futures workflow](https://docs.reilabs.org/docs/neuroadapt/futures/overview.md).

The [runnable examples](https://docs.reilabs.org/docs/neuroadapt/futures/examples.md) include single-step and two-step planning declarations. Configure these pieces.

1. `action_path`, also included in transition `input_paths`.
2. Observed transitions containing the actual action and measured result.
3. Planning `actions`, or a supported dynamic `actions_path`.
4. `state_bindings` mapping predicted targets into the next projected state.
5. At least an appropriate goal/objective for the task.
6. `futures.enabled: true` and planning `enabled: true, probabilistic: true`.

For example, the binding from `values.next_x` to `values.x` means the predicted next value becomes the current value at the next search step. Include every bound `state_path` in `input_paths`. If a one-step objective binds a metric with no meaningful pre-action value, send a constant anchor such as `0.0` in the query and completed observation. The planner replaces it with the predicted target during expansion.

Query with the current state and request `transition_plan`. For a planner-led
decision, leave the action unset; the planner assigns each candidate action
during evaluation. An explicitly action-conditioned forecast can take precedence
for the stored forecast receipt, so do not forecast one action and report a
different action as its execution.

## Set up a one-step risk limit

1. Start at `horizon: 1` with a small discrete action set. Check `required_support` for each action at the states you expect to query. Compare `conditioning: "kernel"` with adaptive conditioning if some actions have few resolved forecasts.
2. Keep `futures.max_support` at or below `futures.max_branches`, for example `128` for both. The planner expands the displayed branches. Truncated or unsupported mass contributes to `unresolved_probability` and to `failure_probability_upper` when constraints are set.
3. Set `constraints` and `max_failure_probability` for the modeled breach limit. Start with `risk_weight: 0.0` and use a positive value when you also want a separate preference for lower-tail utility. The planner applies a `-3.0` penalty to a constraint-violating branch and uses the failure upper bound to gate the plan.
4. Choose each objective's `scale` in the units of the difference it scores. The scaled objective term is clipped to `[-1, 1]` before weighting. Too small a scale can saturate the term. Too large a scale can make the fixed constraint penalty dominate.
5. Define what your application will do during warmup or when the plan abstains, such as holding the current setting or deferring the decision. Check how often this path is taken when testing the Domain.

[One-step dispatch example](https://docs.reilabs.org/docs/neuroadapt/futures/examples.md#plan-one-dispatch-step-under-a-reserve-limit).

## Plan across multiple steps

1. Start with two steps and a small action set. Bind each next-state target into the matching input. Use categorical states when the task permits, such as storage reserve bands. Put the current state category in `group_by_paths` when each band needs separate transition evidence. Fewer distinct joint outcomes keep branch expansion manageable.
2. Check support for each reachable state and action, including branches you expect to be rare. If the model continues to roll out an absorbing failure state, include its self-transitions from a simulator or known task rules. Refresh that coverage as old samples leave retention. If you have valid counterfactual transitions from those sources, use them to cover actions the application rarely takes.
3. If utility should accumulate per step, test the objective on a few hand-computed sequences. For a numeric maximize or minimize objective, the score follows the change in the bound state. Binding a per-step reward directly can make successive equal rewards contribute a zero change after the first step.
   * For an undiscounted sum of step rewards, set `discount: 1.0`, predict the next cumulative reward, and bind it to current cumulative reward. With `linear_residual`, cover cumulative values across the range reached in rollouts, then check for transport and clipping.
   * For a short horizon with empirical per-step reward targets, bind the next step reward to a reward input and start that input at zero. With discount `0.5` and no clipping, the discounted differences give equal relative weights to the two rewards at horizon two. At horizon three the relative weights are `0.50`, `0.25`, and `0.25`. Use this weighting only if it represents your objective.
4. Inspect candidate sequences, unresolved mass, and budget use as you increase the horizon. Increase `beam_width` or `max_rollouts` when you can identify the budget limiting evaluation.

[Two-step storage example](https://docs.reilabs.org/docs/neuroadapt/futures/examples.md#plan-two-storage-intervals).

## Execute and replan

Read `transition_plan.status`. On `abstained`, inspect the reason, rejected candidates, and available failure and unresolved probability fields, then use the application's fallback. When it is `planned` and the modeled bounds meet your application's limits, follow these steps.

1. Take `transition_plan.selected_action`.
2. Execute only that first action.
3. Report the real result and that decision's ID. If your application executed a different action, record the actual action independently of the planner's forecast receipt.
4. Query again using the new observed state.

`action_sequence` is the candidate sequence explored by the model, not permission
to execute all its actions without observing the environment again.
This is bounded action-sequence planning with replanning, not a full contingent
policy tree for every possible future observation.

`selection.selected_policy` is a separate output from the contextual policy
selector. Probabilistic planning does not silently replace it. An application
using this planner must deliberately consume `transition_plan.selected_action`.

## Inspect the plan

Inspect `selected_action`, `action_sequence`, `expected_utility`,
`lower_tail_utility`, `goal_probability`, `failure_probability`,
`failure_probability_upper`, `unresolved_probability`, `probability_mass`,
`trajectories`, `candidate_sequences` and `rejected_sequences`.

The selected action's first-step distribution is available as
`transition_plan.futures`. This is especially useful when the ordinary forecast
abstains because no action was supplied in the query.

Constraint-failing branches and unsupported probability mass remain visible.
They are not silently dropped to make the remaining plan look safer. Probability
estimates describe the learned model; they are not certified safety bounds.


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