/api/v1. For an executable Python client, see Run the examples.
Create the Domain
Send this body toPOST /domains. Choose a fresh Domain ID and use it in the subsequent request paths.
input_paths: information available when forecasting. Do not include the answer or anything computed from the eventual outcome.targets: values measured later. Supported types arenumber,categorical,booleanandset. 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.
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.
Design inputs and targets for your stream
Select evidence available at issue time
Start with three to six informative signals when they capture the task. The futures kernel uses range-normalized distances and gives each observed input equal weight, so collinear measurements can give one signal too much influence and destabilize numeric fits. Select features explicitly even if the Domain declaresdistance_weighting: "target_relevance". Compare forecast scores as you add or remove inputs. For noisy or heavy-tailed streams, compare max_distance: 1.0 with the default 0.75 and check both accuracy and how often each setting abstains. Keep the cutoff that matches your tolerance for extrapolation.
For uneven feed arrival, send only the keys currently known in context.values. Omit unavailable keys entirely. Keep group and action fields available when your Domain uses them. Each revision should contain all evidence known for that outcome at that time. Use the forecast’s observed_paths and calibration diagnostics to check which evidence sets get support.
Define joint targets and units
- Use a numeric target for a measured value. If an event is fully defined by a threshold on that value, calculate its probability from the numeric forecast atoms. For example, sum the atom weights where final load exceeds the limit. The
final_alarmtarget in this walkthrough represents a separate measured outcome.linear_residualtransports numeric targets only. Read the forecast distribution. - Put joint numeric targets on comparable scales, such as by dividing each by an issue-time or training-period standard deviation. Energy score uses the distance across targets, so a target with a much larger scale can dominate the score. Preserve the applied scales with the forecast and invert them when reporting in physical units.
- Use
linear_residualwhen evidence predicts a changing numeric level. If the spread itself varies with the regime, try dividing the observed outcome by a volatility or spread estimate computed from information available at issue time. Use the saved estimate when the outcome arrives and when restoring the forecast atoms to their original units. Score the forecasts on a consistent scale. Joint numeric example.
Decide which observations should share support
Supply completed observations
Post historical observations to/domains/process-futures-example/events in time order. Send one request per measured transition. For example:
transition_prediction.futures.abstention_reason.
Issue a forecast with partial evidence
POST /domains/process-futures-example/query:
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 samefuture_id and all currently known inputs:
decision_id. Keep future_id stable across revisions of the same eventual outcome, with the same grouping and action. Include the previously known inputs in every revision, along with the new ones. Budget max_pending_forecasts for all simultaneously outstanding revisions. Size the forecast settings.
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:
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 for the returned fields.