1 vin.modules.qh_value_decoders
vin.modules.qh_value_decoders
Modular scalar-value decoders for finite-horizon candidate features.
The finite-horizon scorer first builds one candidate-state feature vector per materialized action. This module owns only the terminal map from that shared feature space to conditional value. It deliberately does not own feasibility, hard action masks, Bellman targets, or candidate interaction.
Every decoder returns a scalar conditional_q in the fitted-Q target’s continuous units, so Lightning backup and online selection have one invariant meaning. The direct-regression decoder predicts that scalar. The CORAL decoder instead predicts cumulative ordinal thresholds and differentiably decodes their repaired class probabilities through fixed, monotone Q representatives. Its bin edges define training labels; its representatives define the scalar used by backup and ranking. Both live in a content-addressed support artifact whose provenance is either training-fitted or physically predeclared. A different discretization or construction population is a different value model even when tensor shapes match. Validation/test-derived support is structurally inadmissible; legacy fixed edges can be inspected but cannot enter a scientific bundle.
CORAL is an ordinal ablation, not evidence that metric distances between classes are learned. The continuous interpretation comes only from the fixed representatives supplied by the experiment. Quantile/distributional value models remain a separate decoder family because they model return uncertainty rather than an ordinal discretization of one scalar target.
1.1 Attributes
| Name | Description |
|---|---|
| QhCoralSupportConfig | CORAL support accepted by the decoder, including non-publishable history. |
| QhCoralSupportProvenance | Closed publishable CORAL support-provenance union. |
| QhValueDecoderConfig | Persisted union of terminal scalar-Q decoder configurations. |
1.2 Classes
| Name | Description |
|---|---|
| QhCoralValueDecoder | Decode shared features through cumulative ordinal Q thresholds. |
| QhCoralValueDecoderConfig | Configure a fixed-support CORAL decoder for continuous fitted-Q targets. |
| QhDecodedValue | One decoder’s scalar value and optional objective-specific payload. |
| QhLegacyFixedCoralSupport | Ambiguous fixed support admitted only for explicit historical inspection. |
| QhPredeclaredPhysicalCoralSupport | Support fixed by a physical rule before empirical target inspection. |
| QhRegressionValueDecoder | Decode shared candidate-state features by direct scalar regression. |
| QhRegressionValueDecoderConfig | Configure the canonical direct continuous-Q regression decoder. |
| QhTrainFittedCoralSupport | Support fitted only from a frozen ordered training population. |
1.2.1 QhCoralValueDecoder
vin.modules.qh_value_decoders.QhCoralValueDecoder(
config,
*,
in_dim,
hidden_dim,
dropout,
)Decode shared features through cumulative ordinal Q thresholds.
CORAL shares one projection across thresholds and learns ordered-rank evidence for a discretized scalar target. The runtime still diagnoses adjacent cumulative-probability violations and repairs negative marginal class mass before decoding, because neither ranking nor Bellman backup may consume an invalid probability vector. This repair does not make the threshold probabilities calibrated; that remains an evaluation question.
1.2.1.1 Methods
| Name | Description |
|---|---|
| validate_configured_support | Reject persisted ordinal support that disagrees with configuration. |
| require_publishable_support | Reject historical fixed support lacking construction provenance. |
| forward | Return ordinal logits and their continuous conditional-Q expectation. |
1.2.1.1.1 validate_configured_support
vin.modules.qh_value_decoders.QhCoralValueDecoder.validate_configured_support()Reject persisted ordinal support that disagrees with configuration.
bin_edges and bin_values are persistent buffers because they helped define the training labels and the scalar decode, respectively. Loading a same-shaped state dictionary can otherwise overwrite support constructed from the manifest without a PyTorch shape error. Bundle publication, warm start, and inference therefore call this method after reconstruction or state loading so the manifest-advertised ordinal experiment remains identical to the executable decoder.
1.2.1.1.2 require_publishable_support
vin.modules.qh_value_decoders.QhCoralValueDecoder.require_publishable_support()Reject historical fixed support lacking construction provenance.
1.2.1.1.3 forward
vin.modules.qh_value_decoders.QhCoralValueDecoder.forward(features)Return ordinal logits and their continuous conditional-Q expectation.
The repaired marginal probabilities are used only to form :math:\sum_k p_k u_k. This scalar has the same fitted-Q units as the regression decoder and is therefore safe for the unchanged backup and hard-masked ranking paths. The attached threshold logits retain the standard CORAL loss without a second scorer forward pass.
1.2.2 QhCoralValueDecoderConfig
vin.modules.qh_value_decoders.QhCoralValueDecoderConfig()Configure a fixed-support CORAL decoder for continuous fitted-Q targets.
For K ordered classes, bin_edges contains K-1 boundaries and bin_values contains K continuous representatives. A target :math:y is assigned bucketize(y, edges) and trained with standard CORAL cumulative binary cross-entropy. At inference, repaired class probabilities :math:p_k decode to :math:Q^{cond}=\sum_k p_k u_k using the fixed representatives u_k.
Edge and representative identity is part of the checkpoint manifest. The outer classes remain open-ended, but their decoded values saturate at the first and last representatives; experiments must therefore report target support and saturation rather than interpreting ordinal bins as calibrated uncertainty.
1.2.2.1 Notes
support is the single owner of boundaries, representatives, source population, split role, construction method, return units, and artifact digest. train_fitted_v1 is closed to training rows and predeclared_physical_v1 is fixed before empirical outcomes. The legacy discriminator exists only to read historical configurations and is rejected by bundle publication, warm start, and inference.
1.2.2.2 Attributes
| Name | Description |
|---|---|
| kind | Discriminator persisted in scorer and bundle configuration. |
| support | Versioned support plus its construction provenance and artifact identity. |
| preinit_bias | Use the upstream CORAL threshold-bias initialization. |
| target_type | Return the runtime CORAL decoder class. |
| bin_edges | Return the support’s fitted-Q label boundaries. |
| bin_values | Return the support’s continuous-Q representatives. |
1.2.3 QhDecodedValue
vin.modules.qh_value_decoders.QhDecodedValue(conditional_q, coral=None)One decoder’s scalar value and optional objective-specific payload.
conditional_q always has the candidate-aligned leading shape and is the only value consumed by Bellman backup or online ranking. coral exists only for the ordinal training objective; regression leaves it None.
1.2.3.1 Attributes
| Name | Description |
|---|---|
| conditional_q | Tensor["...", float32] conditional value in additive fitted-Q units. |
| coral | Ordinal training payload, or None for direct regression. |
1.2.4 QhLegacyFixedCoralSupport
vin.modules.qh_value_decoders.QhLegacyFixedCoralSupport()Ambiguous fixed support admitted only for explicit historical inspection.
1.2.4.1 Attributes
| Name | Description |
|---|---|
| provenance_kind | Non-publishable legacy discriminator. |
| bin_edges | Historical label boundaries with no verified construction provenance. |
| bin_values | Historical representatives with no verified construction provenance. |
1.2.5 QhPredeclaredPhysicalCoralSupport
vin.modules.qh_value_decoders.QhPredeclaredPhysicalCoralSupport()Support fixed by a physical rule before empirical target inspection.
1.2.5.1 Attributes
| Name | Description |
|---|---|
| provenance_kind | Promotable support-provenance discriminator. |
| construction_method | Construction family that is independent of observed target outcomes. |
| split_role | Explicit statement that no empirical dataset split selected the support. |
| physical_rule | Versioned rule identifier from which boundaries and representatives derive. |
1.2.5.2 Methods
| Name | Description |
|---|---|
| create | Construct a self-addressed physically predeclared support artifact. |
1.2.5.2.1 create
vin.modules.qh_value_decoders.QhPredeclaredPhysicalCoralSupport.create(
source_population_digest,
ordered_input_digest,
physical_rule,
bin_edges,
bin_values,
)Construct a self-addressed physically predeclared support artifact.
1.2.6 QhRegressionValueDecoder
vin.modules.qh_value_decoders.QhRegressionValueDecoder(
config,
*,
in_dim,
hidden_dim,
dropout,
)Decode shared candidate-state features by direct scalar regression.
This is the canonical decoder because its output and Huber target already share the additive root-gain return units required by Bellman recursion. It adds no bin support, ordinal interpretation, or return-distribution hypothesis to the representation comparison.
1.2.6.1 Methods
| Name | Description |
|---|---|
| forward | Return direct Tensor["...", float32] conditional-Q values. |
1.2.6.1.1 forward
vin.modules.qh_value_decoders.QhRegressionValueDecoder.forward(features)Return direct Tensor["...", float32] conditional-Q values.
1.2.7 QhRegressionValueDecoderConfig
vin.modules.qh_value_decoders.QhRegressionValueDecoderConfig()Configure the canonical direct continuous-Q regression decoder.
1.2.7.1 Attributes
| Name | Description |
|---|---|
| kind | Discriminator persisted in scorer and bundle configuration. |
| initial_output_bias | Optional explicit native-Q scalar output bias; None preserves seeded initialization. |
| target_type | Return the runtime direct-regression decoder class. |
1.2.8 QhTrainFittedCoralSupport
vin.modules.qh_value_decoders.QhTrainFittedCoralSupport()Support fitted only from a frozen ordered training population.
1.2.8.1 Attributes
| Name | Description |
|---|---|
| provenance_kind | Promotable support-provenance discriminator. |
| construction_method | Training construction: empirical quantiles, or fixed edges with train-bin means. |
| split_role | Closed leakage boundary; validation and test targets are never admissible. |
1.2.8.2 Methods
| Name | Description |
|---|---|
| create | Address supplied support and its declared training construction. |
1.2.8.2.1 create
vin.modules.qh_value_decoders.QhTrainFittedCoralSupport.create(
source_population_digest,
ordered_input_digest,
bin_edges,
bin_values,
construction_method='empirical_quantiles_v1',
)Address supplied support and its declared training construction.
The caller owns fitting and its frozen training population. For predeclared_edges_train_means_v1, edges must be predeclared and representatives must be means of the corresponding training bins. This factory validates numeric support and binds construction identity; it does not inspect targets or perform the fitting itself.