Transition learning, advanced

Use this reference when you need explicit control of transition inputs, target geometry, grouping, and support. Transition Discovery covers discovering eligible inputs automatically. A transition Domain learns this relationship:

observable inputs available before the consequence
+ optional proposed or executed action
-> observable target available afterward

Use policy feedback to update the utility of a committed policy. An observed immediate reward can also be declared as a transition target when the application needs reward predictions for candidate actions; the application compares those predictions and selects the action. See Learn unknown action effects. Sequential learning provides delayed credit and optional scoring toward a bounded objective.

Continuity, ordinary Domain reasoning, feedback adaptation, and stateless structured results do not require custom transition configuration.

Check whether transition learning fits

Use structured transition learning when all of these are true:

The target becomes observable after the configured inputs or action.
Every input can be computed before that consequence.
Equivalent events should be able to reuse one another as evidence.
The application can define one coherent event boundary.
The application can abstain when no eligible support exists.

One event in one picture

last observation before the action
proposed action or intervention
exact external execution
declared observation point
observable target

For direct structured prediction with no action, the eligible input and withheld target belong to one item or event: observable item fields → withheld observable target Each eligible event should represent a declared input-to-target relationship. Retain longer operational traces separately for provenance. Targets combined in one event must share the declared observation boundary.

Minimal setup

Use Discovery to identify useful pre-target inputs for a known target. Set learning.enabled: true and learning.transition.enabled: true, declare the eligible event type and observable target, omit input_paths, and enable autonomous_projection.

{
  "schema": {
    "event_types": ["observed_target"]
  },
  "learning": {
    "enabled": true,
    "transition": {
      "enabled": true,
      "event_types": ["observed_target"],
      "targets": [
        {
          "path": "values.output",
          "type": "number"
        }
      ],
      "autonomous_projection": {
        "enabled": true
      }
    }
  }
}

Adapt-1 can accumulate complete observations while the projection is still forming. When Discovery becomes ready, it selects eligible scalar input paths and rebuilds buffered events under the discovered projection. Author input_paths explicitly when the learner-facing ontology must be fixed or reviewed in advance. Explicit paths remain authoritative when supplied. Add action_path only when the learned relationship includes an action or intervention. Add group_by_paths only when evidence must remain separated across incompatible public contexts. Leave support, distance, neighbor, and retention controls at their defaults until the evidence contract shows a specific need. See Use Discovery for the acquisition lifecycle, discovered projection diagnostics, structural representation discovery, and mixed setup. Structured transition learning can coexist with ordinary policy feedback. It can also be the only adaptive relationship in a Domain with no candidate hypotheses.

Separate data by purpose

Layer	Content	Purpose
Operational record	Complete before and after observations, execution details, timestamps, adapter outputs, provenance, and application metrics	Audit, fault isolation, replay, and Domain revision
Learner view	Configured observations, permitted derived features, optional action, and observable target	Transition evidence and reuse
Application-only context	Hidden evaluator state, withheld evaluation answers, solver internals, and judgments outside the declared learning contract	Application logic and evaluation only

A completed measurement or reference correction can enter the learner view as a target during a declared learning phase. Keep that target and fields derived from it out of prediction inputs. For example, a corrected object region can teach region coordinates after the prediction has been recorded and scored. Use the feedback route to assign utility to a committed choice. A target-learning event supplies the value to predict; policy feedback supplies the usefulness of the choice made. An observation-only dynamics target must still describe the observed effect of execution. A preferred action label requires a learning contract that explicitly accepts that teaching signal.

Learner inputs

Every transition input must be available before the consequence. Inputs can include:

Current observable state.
Relative or normalized geometry.
Public operating mode.
A proposed intervention or action.
A derived feature computed only from pre-consequence observations.

Do not include:

The target or any field derived from it.
A hidden cause unavailable to the application.
The preferred or correct action.
A solver label.
A collision, boundary, or success label calculated from the after-state.

A proposed action can imply a physical or logical configuration. Include that configuration only when the application can compute it before execution.

Target structure

The target must preserve every observable distinction the learner must predict. Use one joint target when separately predicted fields can form an impossible combination. For mutually exclusive effects, one categorical target may be safer than independent booleans:

NO_CHANGE
DIMENSION_A_INCREASE
DIMENSION_A_DECREASE
DIMENSION_B_INCREASE
DIMENSION_B_DECREASE

This vocabulary names the observable effects that transition learning predicts from the declared inputs and action. When the application reconstructs or clamps a prediction, keep these values separate:

Value	Why preserve it
Raw predicted target	Shows what the transition learner returned
Structural or physical validity	Detects impossible combinations
Reconstructed raw next state	Shows the direct predicted consequence
Corrected or clamped next state	Shows what the application accepted

A valid processed state can hide an invalid raw prediction.

Evidence geometry and grouping

The configured input representation determines which observations can support a prediction.

Design choice	Use when	Common failure
Numeric inputs	Magnitude and distance are meaningful	An irrelevant scale controls neighbor selection
Relative or invariant inputs	Translated or transformed events should behave equivalently	Equivalent events remain far apart
Absolute inputs	Position or magnitude changes behavior at a boundary or regime	Removing absolute context mixes incompatible cases
Categorical inputs	Identity changes behavior without implying numeric distance	Arbitrary numeric IDs introduce false ordering
`action_path`	The event relation includes a configured action	Action identity is omitted from an action-dependent transition
`group_by_paths`	Evidence from incompatible public contexts must never mix	Too much grouping prevents useful reuse; too little mixes different dynamics

Configure action_path to identify the action value and group_by_paths to restrict evidence to compatible groups. Start with the smallest observable representation that preserves the real transition relationship. Change geometry only after inspecting which evidence supported a result.

Admission before interpretation

The API can store an event that the transition learner does not accept. Before using transition output, verify:

The request returned an event or memory ID.
Every configured input, target, action, and grouping path was present with the expected type.
The transition learner accepted the event.
Interpret sample_count_delta alongside admission and retention. Buffered events can increase it by more than one after a projection revision; an accepted update at retained-sample capacity can leave it at zero.
The applicable learner or subsystem version advanced as the endpoint contract specifies.

Inspect learner_eligibility, accepted, rejection_reason, missing_paths, sample_count, and model_version when returned. When admission fails, repair the path, type, event kind, target, duplicate handling, or selected learner before sending more events.

Support and abstention

A supported prediction follows a sequence such as:

candidate samples
group eligibility
input distance and category geometry
neighbor selection
required support
prediction or abstention

Expected behavior:

Evidence state	Required result
No relevant observations	Abstain
Fewer matching observations than `required_support`	Abstain
Enough nearby compatible observations	Predict
Many observations from unrelated contexts	Still abstain

Read predicted values only when the returned status is predicted. When available, preserve support_count, evidence IDs, distances, group identity, disagreement, and the selection or abstention reason. Treat confidence according to the route contract. Do not assume it is a calibrated probability of correctness or an exploration policy.

Planning over learned transitions

Configured transition planning uses learned predictions of successive states to evaluate candidate action sequences against a goal and constraints over a bounded horizon. The transition contract must preserve the state and action information needed for each continuation. This path returns transition_plan from /query. Planning integration documents the separate native search interfaces used when the application provides successors and selects the evaluator. Configure this path at learning.transition.planning with transition learning enabled. Set enabled: true, declare the candidate actions, and use state_bindings to map each predicted target_path into the state_path used by subsequent predictions. Declare the task’s goals, constraints, or numeric objectives. Set horizon for the number of predicted transitions and beam_width for the search width. Read the resolved Domain to confirm the configuration. Inspect transition_plan.status and transition_plan.abstention_reason, then review its action_sequence, selected_action, and projected_states when returned. Preserve its model_version and evidence_memory_ids with the execution record. Record whether the application executed the planned action or a policy from another selection path. Define the unit of a transition before choosing the horizon. In a turn-based interaction, an observation taken after the other participant responds describes a different interval from one taken immediately after the selected action. Keep this boundary consistent in learning events and planning. Planning requires explicit actions, state bindings, and goal or objective semantics. Predictor inputs can be discovered or explicitly declared. Build this workflow in order:

Define the state fields that must carry from one predicted step to the next, including resources consumed or availability changed by an action.
Collect observed before-state, action, and after-state records under that same boundary. Check that one-step queries produce supported, coherent targets.
Map those targets back into the next planning input with state_bindings. Keep the action meanings and objective units consistent across every step.
Configure the goal, constraints, candidate actions, and horizon. Decide whether execution commits the whole plan or only its first action before observing again.
Execute the selected action or plan and return the measured transitions. These observations update the evidence used by later plans.

Inspect prediction support and abstention when a continuation reaches states with limited evidence. The separate bound-transition projection binds indexed objects and action roles and contributes to policy scoring. Choose the path from the state representation and result needed by the executor. See Decisions beyond the next move for a game-oriented example and the distinction between planning horizon, delayed credit, and decision timing.

Read a multistep result

An action can enable a later payoff without giving an immediate reward. In a recorded service example, a patch scored three immediately. Preparation scored zero but enabled a repair worth ten. Horizon two selected preparation; horizon one selected the patch. Search reached the explicit payoff, so this example needed no learned value model. This captured response excerpt followed 12 observed samples:

{
  "selected_action": "a",
  "action_sequence": ["a", "c"],
  "score": 0.95,
  "search": {
    "depth": 2,
    "requested_horizon": 2,
    "expanded": 3,
    "generated": 3,
    "horizon_complete": true
  }
}

The planner’s utility score of 0.95 differed from the projected task score of ten. The executor performed a, observed the result, and queried again before c. Keep search.depth distinct from the native-search field completed_depth. This small example had deliberate transition coverage and no evaluation learning writes.

Combine predictions and values

A transition model predicts action effects. A value model estimates the usefulness of an unfinished state or continuation. Build supported predicted states, obtain their values, and use native search to select an action. Execute the first action, observe the actual state, and plan again. A recorded integration used /query with update_memory_state:false for forecasts, /value/predict for frozen learned scores, and /planning/adversarial for selection. This composition is separate from /query returning transition_plan. A fixed scalar adapter carried the learned model’s scores into search. The planner reported caller_checkpoint, so its evaluator identity alone did not identify the model that produced those scores. All nodes had terminal_value:null. For frozen evaluation, hold both learned functions fixed and disable feedback throughout the loop. Check their state separately from the planning call’s update flag. These calls describe a saved integration; see Planning integration for the value and execution boundaries.

Optional workflows

Compare candidate actions without writing

An application can query a fixed set of candidate actions without adding evidence, compare their predicted consequences, and then commit externally. The application still owns candidate construction, selection rules, safety checks, and execution.When the route supports them, use:

{
  "allow_exploration": false,
  "update_memory_state": false
}

Set both flags for a read without exploration or memory-state updates. Verify the endpoint contract and compare the applicable learner-state hash and versions before and after the call.Preserve the complete Domain query and /explain responses. A later explanation can use a different evidence set unless the route explicitly binds it to the original query or result.

Use typed hypothesis evidence

Declare candidate hypotheses when the application needs hypothesis support and counterevidence alongside transition predictions.Candidates should:

Compete over the same declared relation.
Predict different observable consequences.
Receive both supporting evidence and counterevidence.
Share the same public schema.
Avoid encoding a preferred answer.

Confirm that ordinary events actually change support or counterevidence before combining hypothesis output with transition output. Otherwise treat them as separate contracts.

Induce compact predictive structure

Enable learning.structure to induce predictive conditions or relations from accepted events. The numeric settings below are example parameters.

{
  "learning": {
    "structure": {
      "enabled": true,
      "event_types": ["observation"],
      "feature_paths": [
        "values.mode",
        "values.pressure",
        "values.load"
      ],
      "targets": [
        {"path": "values.state", "type": "categorical"},
        {"path": "values.risk", "type": "number"}
      ],
      "min_support": 3,
      "min_calibration_support": 2,
      "max_literals": 3,
      "transfer_enabled": true,
      "min_local_support_for_transfer": 2
    }
  }
}

Supported target types are number, categorical, boolean, and set. Eligible induced hypotheses can appear in ranked_hypotheses with origin: "induced". Causal interpretation requires appropriate intervention evidence. Compatible transfer remains owner-scoped and requires local confirmation.

Troubleshooting

Observed behavior	Likely cause	First correction
Stored event leaves sample count unchanged	Retention capacity, projection buffering, or rejected admission	Inspect `accepted`, `rejection_reason`, retention, and `model_version`; an advancing learner version can confirm an accepted update with unchanged retained count
`no_matching_group`	Query group context differs or no event is eligible	Verify values, types, and missing or `null` handling
Evidence remains same-action without grouping	Input geometry or coverage separates the actions	Inspect distances and add only permitted relational context
Evidence crosses incompatible modes	Missing conditioning or grouping	Add categorical context or a necessary group boundary
Support fills with unrelated samples	Geometry or distance control is too broad	Tighten the documented distance rule or redesign inputs
Valid processed next state conceals an impossible raw effect	Reconstruction or clamping hides the error	Preserve raw target and validity checks
Confidence is high while effects conflict	Confidence is being overinterpreted	Inspect evidence identity, distance, and disagreement
A read-only test changes state	Route flags or another subsystem still writes	Identify the changing state and correct the route contract

Launch checklist

One eligible event represents one input-to-target relationship.
Every input exists before the consequence.
Operational record, learner view, and application-only context remain separate.
Numeric scale, categorical meaning, invariances, and boundaries match the real transition behavior.
action_path and grouping have distinct justified roles.
The target represents one coherent observable consequence.
Raw prediction and application processing remain separately inspectable.
Learner admission is verified in the response diagnostics.
Unsupported or incompatible queries abstain.
Evidence identity, distance, group, disagreement, and abstention reasons are preserved.
Read-only checks leave the applicable learner state unchanged.

Feedback, bounded scoring, and delayed credit

Use the feedback guide when the question is whether a committed action was useful, how it moves a bounded public objective, or how a later outcome should revise earlier decisions.

Get started

Concepts

Guides

Planning

Discovery

Operations

API reference

Check whether transition learning fits

One event in one picture

Minimal setup

Separate data by purpose

Learner inputs

Target structure

Evidence geometry and grouping

Admission before interpretation

Support and abstention

Planning over learned transitions

Read a multistep result

Combine predictions and values

Optional workflows

Troubleshooting

Launch checklist

Feedback, bounded scoring, and delayed credit

​Check whether transition learning fits

​One event in one picture

​Minimal setup

​Separate data by purpose

​Learner inputs

​Target structure

​Evidence geometry and grouping

​Admission before interpretation

​Support and abstention

​Planning over learned transitions

​Read a multistep result

​Combine predictions and values

​Optional workflows

​Troubleshooting

​Launch checklist

Feedback, bounded scoring, and delayed credit

Check whether transition learning fits

One event in one picture

Minimal setup

Separate data by purpose

Learner inputs

Target structure

Evidence geometry and grouping

Admission before interpretation

Support and abstention

Planning over learned transitions

Read a multistep result

Combine predictions and values

Optional workflows

Troubleshooting

Launch checklist