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

# Use counterfactual utility plasticity

> Configure source and coalition utility learning from attributable online feedback.

Use this when an adaptive posterior has multiple usable prediction sources. CUP learns which sources and coalitions contribute predictive utility.

Counterfactual Utility Plasticity (CUP) is an online structural rule inside the adaptive posterior. It learns which available prediction sources, and which small coalitions of sources, add predictive utility before an outcome is observed.

Useful source coalitions become active posterior structures. Harmful coalitions become inhibitory structures. Their support and utility decay as the stream changes. CUP does not train a separate policy model.

<Info>
  CUP participants are posterior prediction mechanisms such as `contextual_memory` and `learned_model`. Domain context features do not automatically become CUP participants.
</Info>

## 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 can support ordinary contextual decisions, temporally projected context, sequential workflows, and other decision surfaces that use the same adaptive posterior. It becomes eligible only when the current decision has enough usable sources and accumulated support.

Tasks with one permanent source provide no coalition to adjudicate. Tasks at a metric ceiling provide no performance headroom even when CUP continues to learn 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

The pre-outcome requirement matters. CUP evaluates the predictions that existed when the decision was made. It must never construct utility from a source score calculated after the label or reward becomes visible.

## Add CUP to the Domain

Enable the ordinary posterior, then add `learning.posterior.plasticity`.

```json theme={null}
{
  "learning": {
    "enabled": true,
    "posterior": {
      "enabled": true,
      "scope": "relation",
      "learning_rate": 2.0,
      "forgetting_factor": 0.985,
      "minimum_feedback": 3,
      "minimum_support": 2.0,
      "variance_floor": 0.0025,
      "complexity_penalty": 0.01,
      "information_gain_weight": 0.0,
      "plasticity": {
        "enabled": true,
        "forgetting_factor": 0.99,
        "maximum_order": 2,
        "minimum_support": 16,
        "birth_threshold": 0.0025,
        "inhibition_threshold": 0.0025,
        "confidence_z": 1.644854,
        "complexity_penalty": 0.001,
        "weight_temperature": 0.025,
        "maximum_structures": 128,
        "maximum_pending": 256,
        "maximum_active": 4,
        "quantization_bins": 5,
        "prior_strength": 1.0,
        "loss": "log"
      }
    }
  }
}
```

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

| Setting            | Structures considered       | Use it when                                                                                     |
| ------------------ | --------------------------- | ----------------------------------------------------------------------------------------------- |
| `maximum_order: 1` | Singleton source utility    | You want a lower-data source-adjudication test.                                                 |
| `maximum_order: 2` | Singletons and source pairs | Pairwise complementarity or redundancy matters. This is the recommended general starting point. |

With two usable sources, order 2 can represent at most three coalitions:

```text theme={null}
contextual_memory
learned_model
contextual_memory × learned_model
```

Increasing `maximum_order` expands the candidate space and evidence burden. Use a higher order only when the source count, sample budget, and evaluation design justify it.

### Read the main controls

| Field                  | Function                                                                 |
| ---------------------- | ------------------------------------------------------------------------ |
| `minimum_support`      | Delays structural activation until enough effective evidence exists.     |
| `birth_threshold`      | Requires positive irreducible utility before a structure becomes active. |
| `inhibition_threshold` | Requires negative utility before a structure becomes inhibitory.         |
| `confidence_z`         | Controls the confidence interval used for structural decisions.          |
| `weight_temperature`   | Controls how sharply supported utility becomes structural weight.        |
| `forgetting_factor`    | Decays stale support and utility under distribution shift.               |
| `maximum_active`       | Bounds the number of structures applied to one decision.                 |
| `loss`                 | Defines the prequential loss used to assign source utility.              |

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. `learned_model` becomes usable only after training has enough admitted samples and its candidate model passes validation.

Use a training configuration that can make a validated learned-model source available:

```json theme={null}
{
  "learning": {
    "context": {
      "feature_paths": ["values.observation"],
      "event_types": [],
      "max_samples": 4096
    },
    "training": {
      "enabled": true,
      "min_samples": 64,
      "retrain_interval": 128,
      "dimensions": 256,
      "epochs": 75,
      "learning_rate": 0.02
    }
  }
}
```

If `learned_model` never becomes usable, CUP has no valid multi-source test. Inspect the feedback-policy sample count, training status, validation report, model type, and posterior source list before tuning plasticity.

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

```json theme={null}
{
  "session_id": "ignored",
  "outcome": "correct",
  "feedback_kind": "execution",
  "decision_id": "DECISION_FROM_QUERY",
  "relation": "selects_output",
  "policy": "emit_2",
  "context": {
    "values": {
      "observation": 2
    },
    "metadata": {
      "episode_id": "episode-0007",
      "step": 42
    }
  },
  "values": {
    "correct": 1.0
  }
}
```

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:

```text theme={null}
ranked_hypotheses[].contextual_policy.posterior_adjudication.sources
ranked_hypotheses[].contextual_policy.posterior_adjudication.counterfactual_utility_plasticity
```

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.

At minimum, keep these two audit fields in the application trace:

```json theme={null}
{
  "posterior_sources": ["contextual_memory", "learned_model"],
  "cup_applied": true
}
```

When the active service returns structures, preserve their participants, order, status, support, utility interval, and applied weight:

```json theme={null}
[
  {
    "participants": ["learned_model"],
    "order": 1,
    "status": "consolidated",
    "effective_support": 24.0,
    "mean_utility": 0.03,
    "utility_interval": [0.01, 0.05],
    "weight": 0.6
  },
  {
    "participants": ["contextual_memory", "learned_model"],
    "order": 2,
    "status": "inhibited",
    "effective_support": 24.0,
    "mean_utility": -0.02,
    "utility_interval": [-0.04, -0.01],
    "weight": -0.4
  }
]
```

The singleton structure represents source utility. The pair represents irreducible utility beyond its members. A positive structure can consolidate, while a sufficiently negative structure can become 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.

This check validates source availability, attribution, support, and structural application. Application-level evaluation should remain separate from the usage guide.

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

If CUP applies but metrics do not improve, inspect source redundancy, task ceiling, support thresholds, structure churn, metric choice, and whether a simpler source-selection control is stronger.

<CardGroup cols={2}>
  <Card title="Choose how a Domain learns" href="/docs/neuroadapt/learning-patterns-for-domains">
    Match the Domain to immediate feedback, transition prediction, temporal context, or delayed credit.
  </Card>

  <Card title="Use TCP" href="/docs/neuroadapt/temporal-context-projection">
    Add bounded recent history before posterior source prediction and selection.
  </Card>

  <Card title="Learn from outcomes" href="/docs/neuroadapt/make-behavior-improve-from-feedback">
    Bind the measured consequence to the committed decision.
  </Card>

  <Card title="Verify adaptation" href="/docs/neuroadapt/evaluate-adaptation">
    Use paired streams, frozen evaluation, and learner-state fingerprints.
  </Card>
</CardGroup>