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

# Issue and revise a forecast

> Create a Domain, forecast joint outcomes, and score each revision against the observed result.

A process monitor may know the current load before it receives an alarm reading. Adapt-1 can forecast the final load and alarm together, then revise their probabilities when the alarm reading arrives. One measured outcome scores both forecasts.

Use a UAT deployment that supports transition futures. Send the same Bearer token and session ID throughout the example. Paths are relative to the deployment’s API base, including `/api/v1`. For an executable Python client, see [Run the examples](https://docs.reilabs.org/docs/neuroadapt/futures/examples.md).

## Create the Domain

Send this body to `POST /domains`. Choose a fresh Domain ID and use it in the subsequent request paths.

```json theme={null}
{
  "domain_id": "process-futures-example",
  "session_id": "my-stable-session",
  "schema": {
    "signals": ["load", "alarm", "final_load", "final_alarm"],
    "event_types": ["outcome"]
  },
  "learning": {
    "transition": {
      "enabled": true,
      "event_types": ["outcome"],
      "input_paths": ["values.load", "values.alarm"],
      "targets": [
        {"path": "values.final_load", "type": "number"},
        {"path": "values.final_alarm", "type": "boolean"}
      ],
      "required_support": 4,
      "max_samples": 2048,
      "futures": {
        "enabled": true,
        "conditioning": "adaptive",
        "max_support": 256,
        "max_branches": 16,
        "max_pending_forecasts": 256,
        "numeric_transport": "none"
      }
    }
  }
}
```

Choose paths according to the actual payload, not the question text:

* `input_paths`: information available when forecasting. Do not include the answer
  or anything computed from the eventual outcome.
* `targets`: values measured later. Supported types are `number`, `categorical`,
  `boolean` and `set`. A target's type describes its data, not its reward role.
* `event_types`: which completed observations are eligible to train this learner.
* `group_by_paths`: optional exact partitions, such as an instrument or process
  identity. Include the same grouping fields in queries and observations.
* `action_path`: optional executed-action field. With it, outcomes are conditioned
  on that action, and planning can evaluate the declared alternatives.

Do not group by an episode ID or a unique request ID unless you really want each
episode/request to have its own independent pool of examples. Support is required
within the matching group and action, not just somewhere in the Domain.

For time-based forecasting, define the target horizon explicitly in the data
contract: for example, `final_load` means the load one hour after observation.
If combining horizons in one learner, declare horizon/lead time as an input or
grouping field and include it in training. The clock advancing alone is not new
evidence.

For automatic input selection, see [Discover transition inputs](https://docs.reilabs.org/docs/neuroadapt/discovery-transition-projection.md).

## Supply completed observations

Post historical observations to `/domains/process-futures-example/events` in time order. Send one request per measured transition. For example:

```json theme={null}
{
  "session_id": "my-stable-session",
  "event_type": "outcome",
  "values": {"load": 0.58, "alarm": false, "final_load": 0.44, "final_alarm": false}
}
```

The example requires four matching observations. Until it has sufficient support, read the reason in `transition_prediction.futures.abstention_reason`.

## Issue a forecast with partial evidence

`POST /domains/process-futures-example/query`:

```json theme={null}
{
  "session_id": "my-stable-session",
  "question": "Forecast the process outcome",
  "context": {
    "values": {"load": 0.6},
    "metadata": {"future_id": "process-event-001"}
  },
  "return_fields": ["decision_id", "transition_prediction"]
}
```

Read `transition_prediction.futures`. The surrounding point forecast can abstain
because an input is missing while the futures forecast remains available.

## Revise with new evidence

Query again with the same `future_id` and all currently known inputs:

```json theme={null}
{
  "session_id": "my-stable-session",
  "question": "Update the process forecast",
  "context": {
    "values": {"load": 0.6, "alarm": false},
    "metadata": {"future_id": "process-event-001"}
  },
  "return_fields": ["decision_id", "transition_prediction"]
}
```

Every query returns a new `decision_id`. Keep `future_id` stable only for revisions
of the same eventual outcome, with the same grouping and action. Send cumulative
evidence: omitting an earlier input does not tell the server to remember it from
the preceding request.

Probabilities can concentrate, spread out, or reverse when evidence changes.
Repeated identical queries do not manufacture confidence or new training samples.

## Resolve the forecasts

`POST /domains/process-futures-example/events`:

```json theme={null}
{
  "session_id": "my-stable-session",
  "event_type": "outcome",
  "values": {
    "load": 0.6,
    "alarm": false,
    "final_load": 0.4,
    "final_alarm": false
  },
  "metadata": {
    "future_id": "process-event-001",
    "decision_id": "REPLACE_WITH_RETURNED_DECISION_ID"
  }
}
```

Supply an actual returned decision ID from that future. This scores retained
issue-time forecasts before using the newly observed target for learning. It
resolves the outstanding revisions together; do not submit one duplicate outcome
for every revision.

Inspect `learner_eligibility.futures_update.accepted`. An eligible outcome without
a decision link can still train transitions, but it cannot score a forecast that
was never recorded. A successful HTTP response alone does not prove every learner
accepted the row.

For ordinary historical training, submit completed events in chronological order.
An optional event `timestamp` is an ISO-8601 timestamp. For a historical online
evaluation, reveal each outcome only after the corresponding simulated prediction
and only when it would actually have become available. Backdating a leaked
outcome does not undo that leakage.

See [Read the forecast distribution](https://docs.reilabs.org/docs/neuroadapt/futures/distribution.md) for the returned fields.


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