Skip to main content
Counterfactual Utility Plasticity (CUP) learns and retains the utility of individual prediction sources and source coalitions inside Adapt-1’s adaptive posterior. It evaluates source predictions captured before each outcome, updates the structural learning state from attributable feedback, and uses that learned state in later selections. As utility and support meet the configured thresholds, CUP activates useful coalitions and inhibits harmful ones. The configured forgetting factor decays older support and utility as new evidence arrives, allowing the learned structure to adapt.
CUP participants are posterior prediction mechanisms such as contextual_memory and learned_model.

When CUP fits

Enable CUP when all of these conditions are true:
  • the Domain makes repeated decisions with attributable measured outcomes;
  • the adaptive posterior is enabled;
  • at least two posterior sources can become usable for the same relation;
  • source value may be complementary, redundant, or harmful under some conditions;
  • rewards can be normalized into [0,1];
  • the application can preserve pre-outcome source predictions and bind feedback to the committed decision.
CUP supports contextual decisions, temporally projected context, sequential workflows, and other decision surfaces that use the same adaptive posterior. Learned structural adjustments contribute to eligible decisions according to the available sources, accumulated support, and utility thresholds. Use multiple usable sources to evaluate coalition learning. To measure performance gains, choose a metric and task with room for improvement. Inspect structural learning through the reported support, utility, and status of each structure.

How CUP enters selection

  1. current context
  2. available posterior sources
  3. source predictions sealed before outcome
  4. CUP utility adjustment
  5. policy selection
  6. measured feedback
  7. source and coalition utility update
CUP evaluates the source predictions captured at decision time. Preserve them before the label or reward becomes visible.

Add CUP to the Domain

Enable the ordinary posterior, then add learning.posterior.plasticity. Numeric settings below are example parameters.
Use this as a starting configuration when the reward is probabilistic or classification-like and the Domain exposes the normal memory and learned-model posterior sources.

Choose the maximum order

For the example sources below, maximum_order: 2 permits singleton structures and their pair:
Increasing maximum_order expands the candidate space and the evidence needed to evaluate it. Choose the order from the available sources, sample budget, and evaluation design.

Read the main controls

Tune thresholds only after the integration trace shows a concrete support, churn, or responsiveness problem. Preserve the full configuration and ordered event record for every test.

Make a second source usable

An empty Domain usually begins with contextual_memory as the available posterior source. Native training fits learned_model candidates from admitted samples. After validation, confirm that the installed model appears in the usable posterior source list. The following example parameters enable training of a candidate learned-model source:
To make learned_model available to CUP, inspect the feedback-policy sample count, training status, validation report, model type, and posterior source list. Confirm that the trained model is installed and usable before evaluating multi-source structural learning.

Bind reward to the sealed decision

CUP learns from the ordinary Domain query and feedback loop. Query first and preserve the posterior diagnostics before the outcome is visible. Then submit one measured feedback write for the executed policy.
The Domain reward declaration should resolve this outcome into [0,1]. Supply the real relation, executed policy, and a supported decision-time context source. A valid decision_id gives the strongest sealed attribution. Do not send a second feedback record for an unexecuted policy. Do not return a counterfactual label, future answer, source score, confidence value, or post-outcome model prediction as reward.

Inspect CUP in the response

For each candidate, inspect:
The active service can expose whether CUP was eligible and applied, the source predictions used, the posterior mean before and after adjustment, and the structures applied to that candidate. Preserve the complete pre-feedback candidate objects. Keep these audit fields in the application trace:
When the active service returns structures, preserve their participants, order, status, support, utility interval, and applied weight:
Singleton utility describes a source contribution. Pair utility measures the contribution beyond the individual members; its sign and support determine whether the pair consolidates or becomes inhibitory. The numeric values above illustrate the response shape. Use the values returned by the active service when auditing a real decision.

Verify CUP in your integration

Use a short controlled stream before production use:
  1. Start with fresh Domain and session state.
  2. Confirm that contextual_memory appears in posterior source diagnostics.
  3. Admit enough attributable outcomes for the configured model-training boundary.
  4. Confirm that a validated learned_model becomes usable.
  5. Preserve pre-feedback source predictions for each committed decision.
  6. Continue feedback until effective support can reach minimum_support.
  7. Inspect whether CUP was eligible, whether it was applied, and which structures affected the candidate.
  8. Repeat selected queries with feedback disabled and confirm that learner-state fingerprints remain unchanged.

Failure checks

If cup_applied remains false, inspect these conditions in order:
  • learning.enabled is true;
  • learning.posterior.enabled is true;
  • learning.posterior.plasticity.enabled is true;
  • at least two sources appear in posterior diagnostics;
  • the trained model is installed and usable;
  • feedback supplies a normalized measured reward;
  • feedback is attributed to the executed relation and policy;
  • effective support has reached minimum_support;
  • source predictions were captured before the outcome;
  • the current condition has eligible candidate structures.
When an active CUP configuration leaves a task metric unchanged, inspect source redundancy, effective support, structure churn, and metric sensitivity. The reported source and coalition states show which structures were learned and applied.

Choose how a Domain learns

Match the Domain to immediate feedback, transition prediction, temporal context, or delayed credit.

Use TCP

Add bounded recent history before posterior source prediction and selection.

Learn from outcomes

Bind the measured consequence to the committed decision.

Verify adaptation

Use paired streams, frozen evaluation, and learner-state fingerprints.