Current implementation: example-level inverse-surprisal weighting

Methodology note: Example-level inverse-surprisal weighting

This note records how example-level inverse-surprisal weighting is currently implemented in code.

Current status

This idea is now implemented as one explicit reconstruction term:

example_inverse_surprisal_weighted_reconstruction_loss

The current loss is:

L_{\mathrm{ex}} = \frac{1}{B}\sum_b \frac{L_{\mathrm{raw},b}}{b_{\mathrm{base},b} + \epsilon},

where:

$L_{\mathrm{raw},b}$ is the latent-conditioned per-example reconstruction loss
$b_{\mathrm{base},b}$ is the aligned z-free uniform base loss for that example
$\epsilon$ is example_inverse_surprisal_epsilon

How the denominator is obtained

The example-level base loss comes from the same frozen-reference statistics bundle used by token-level weighting:

path:core/disentanglement/token_weighting.py

The relevant field is:

example_base_loss

That value is derived from aligned z-free per-token NLL, uniformly averaged over the aligned supervised region.

Where the term is assembled

The scalar loss component is formed in:

path:core/disentanglement/losses.py
integrated in:
- path:core/disentanglement/shared_discrete_cvae.py
- path:core/disentanglement/continuous_cvae.py

The low-level scalar helper is:

example_inverse_surprisal_weighted_reconstruction_loss(...)

Configuration surface

The current configuration contract lives in:

path:core/disentanglement/config.py

under:

ReconstructionLossConfig.example_inverse_surprisal_weight
ReconstructionLossConfig.example_inverse_surprisal_epsilon

The current CLI surface is:

--example-inverse-surprisal-reconstruction-weight
--example-inverse-surprisal-epsilon

Current implementation choice

The current implementation uses the ordinary aligned uniform z-free base loss in the denominator. It does not use a token-weighted baseline in the example-level denominator.

So the present term should be read as:

example-level reweighting based on overall aligned z-free base loss

not:

example-level reweighting matched to a token-weighted reconstruction baseline