1 rollouts.inspection.audits

rollouts.inspection.audits

Operational validity, provenance, path, and policy audits for rollouts.

This module contains evaluation-only reducers for replay/store behavior. They are not reconstruction metrics or training objectives.

1.1 Classes

Name	Description
CandidateOrderConsistency	Per-table diagnostics for shuffled-candidate consistency.
CandidateOrderConsistencyMetric	Accumulate shuffled-candidate order-consistency diagnostics.
CandidatePathIncrementMetric	Accumulate candidate action path-increment diagnostics in metres.
CandidatePathIncrementStats	Per-table movement-cost diagnostics for candidate action rows.
CandidatePolicyEntropyMetric	Accumulate masked candidate-policy entropy diagnostics.
CandidatePrimaryInvalidReasonMetric	Accumulate primary invalid-reason share among rejected candidates.
CandidatePrimaryInvalidReasonStats	Per-table primary invalid-reason share among rejected candidate rows.
CandidateProvenanceShareMetric	Accumulate candidate provenance-family share diagnostics.
CandidateTableMetrics	Accumulate hard-mask candidate-table diagnostics.
SelectedPathCostMetrics	Accumulate selected camera-center path cost in metres.

1.1.1 CandidateOrderConsistency

rollouts.inspection.audits.CandidateOrderConsistency(
    score_mae,
    top1_match,
    valid_table,
)

Per-table diagnostics for shuffled-candidate consistency.

1.1.1.1 Attributes

Name	Type	Description
score_mae	Tensor	Tensor["B"] mean absolute score difference after inverse-aligning shuffled predictions to the original candidate order.
top1_match	Tensor	Tensor["B"] boolean indicator that the best valid candidate index is unchanged by shuffling.
valid_table	Tensor	Tensor["B"] boolean indicator that a table had at least one comparable valid candidate.

1.1.2 CandidateOrderConsistencyMetric

rollouts.inspection.audits.CandidateOrderConsistencyMetric()

Accumulate shuffled-candidate order-consistency diagnostics.

This metric supports the proposal’s requirement that finite candidate rows have no semantic ordering. It compares paired model scores from the same candidate table before and after a known gather-style permutation, then reports score agreement and top-1 stability over comparable valid tables.

1.1.2.1 Attributes

Name	Description
mae_total	Tensor["", float32] sum of finite paired score errors.
mae_count	Tensor["", float32] number of finite paired score errors.
top1_match_count	Tensor["", float32] number of comparable top-1 matches.
valid_table_count	Tensor["", float32] number of comparable candidate tables.
table_count	Tensor["", float32] number of paired candidate tables presented.

1.1.2.2 Methods

Name	Description
update	Accumulate one paired original/shuffled candidate-score batch.
compute	Return shuffled-candidate consistency diagnostics.

1.1.2.2.1 update

rollouts.inspection.audits.CandidateOrderConsistencyMetric.update(
    scores,
    shuffled_scores,
    permutation,
    valid_mask=None,
    shuffled_valid_mask=None,
    *,
    dim=-1,
)

Accumulate one paired original/shuffled candidate-score batch.

1.1.2.2.2 compute

rollouts.inspection.audits.CandidateOrderConsistencyMetric.compute()

Return shuffled-candidate consistency diagnostics.

1.1.3 CandidatePathIncrementMetric

rollouts.inspection.audits.CandidatePathIncrementMetric()

Accumulate candidate action path-increment diagnostics in metres.

The metric summarizes the per-table distribution of hard-valid candidate movement costs, usually sourced from rollout motion_step_length_m rows. It is separate from selected policy cost: this class describes the action set offered to the policy, not the action the policy selected.

1.1.3.1 Attributes

Name	Description
mean_total	Tensor["", float32] sum of finite table mean increments.
mean_count	Tensor["", float32] number of finite table mean increments.
min_total	Tensor["", float32] sum of finite table minimum increments.
min_count	Tensor["", float32] number of finite table minimum increments.
max_total	Tensor["", float32] sum of finite table maximum increments.
max_count	Tensor["", float32] number of finite table maximum increments.
valid_table_count	Tensor["", float32] number of tables with finite increments.
table_count	Tensor["", float32] number of candidate tables presented.

1.1.3.2 Methods

Name	Description
update	Accumulate one batch of candidate path-increment tables.
compute	Return finite means of candidate path-increment table statistics.

1.1.3.2.1 update

rollouts.inspection.audits.CandidatePathIncrementMetric.update(
    path_increment_m,
    valid_mask,
    *,
    dim=-1,
)

Accumulate one batch of candidate path-increment tables.

1.1.3.2.2 compute

rollouts.inspection.audits.CandidatePathIncrementMetric.compute()

Return finite means of candidate path-increment table statistics.

1.1.4 CandidatePathIncrementStats

rollouts.inspection.audits.CandidatePathIncrementStats(
    mean_m,
    min_m,
    max_m,
    valid_table,
)

Per-table movement-cost diagnostics for candidate action rows.

The rollout replay contract stores each candidate row’s path increment, currently persisted as motion_step_length_m in rollout diagnostics. These statistics summarize that candidate-set cost distribution without changing the selected policy cost column.

1.1.4.1 Attributes

Name	Type	Description
mean_m	Tensor	Tensor["B"] mean finite path increment in metres.
min_m	Tensor	Tensor["B"] minimum finite path increment in metres.
max_m	Tensor	Tensor["B"] maximum finite path increment in metres.
valid_table	Tensor	Tensor["B"] mask for tables with at least one finite hard-valid path increment.

1.1.5 CandidatePolicyEntropyMetric

rollouts.inspection.audits.CandidatePolicyEntropyMetric()

Accumulate masked candidate-policy entropy diagnostics.

The metric summarizes selection diversity for finite candidate tables. It consumes probabilities or probability-like weights, delegates masking and renormalization to candidate_policy_entropy, and reports the finite mean entropy. Invalid candidates affect entropy support only; invalidity remains owned by CandidateTableMetrics.

1.1.5.1 Attributes

Name	Description
entropy_total	Tensor["", float32] sum of finite candidate-policy entropies.
entropy_count	Tensor["", float32] number of finite candidate-policy entropies.

1.1.5.2 Methods

Name	Description
update	Accumulate one batch of candidate selection probabilities.
compute	Return mean entropy or NaN when no table had positive mass.

1.1.5.2.1 update

rollouts.inspection.audits.CandidatePolicyEntropyMetric.update(
    selection_probabilities,
    valid_mask=None,
    *,
    dim=-1,
)

Accumulate one batch of candidate selection probabilities.

1.1.5.2.2 compute

rollouts.inspection.audits.CandidatePolicyEntropyMetric.compute()

Return mean entropy or NaN when no table had positive mass.

1.1.6 CandidatePrimaryInvalidReasonMetric

rollouts.inspection.audits.CandidatePrimaryInvalidReasonMetric(reason_ids)

Accumulate primary invalid-reason share among rejected candidates.

The configured reason ids identify one stable rejection family, for example path-collision or target-support failures. Shares are measured over hard-invalid rows only; valid action rows stay out of the denominator so this diagnostic complements, rather than redefines, aggregate invalidity.

1.1.6.1 Attributes

Name	Description
share_total	Tensor["", float32] sum of finite invalid-reason shares.
share_count	Tensor["", float32] number of finite invalid-reason shares.
valid_table_count	Tensor["", float32] number of tables with invalid rows.
table_count	Tensor["", float32] number of candidate tables presented.

1.1.6.2 Methods

Name	Description
update	Accumulate one batch of primary invalid-reason ids.
compute	Return reason-group share and denominator-validity rate.

1.1.6.2.1 update

rollouts.inspection.audits.CandidatePrimaryInvalidReasonMetric.update(
    primary_invalid_reason,
    valid_mask,
    *,
    dim=-1,
)

Accumulate one batch of primary invalid-reason ids.

1.1.6.2.2 compute

rollouts.inspection.audits.CandidatePrimaryInvalidReasonMetric.compute()

Return reason-group share and denominator-validity rate.

1.1.7 CandidatePrimaryInvalidReasonStats

rollouts.inspection.audits.CandidatePrimaryInvalidReasonStats(
    share_of_invalid,
    valid_table,
)

Per-table primary invalid-reason share among rejected candidate rows.

Rollout replay tables persist the complete invalidity bitset and one priority-selected primary_invalid_reason per candidate row. This diagnostic intentionally consumes only the primary reason field; use the bitset arrays when auditing overlapping reason vectors.

1.1.7.1 Attributes

Name	Type	Description
share_of_invalid	Tensor	Tensor["B"] fraction of hard-invalid candidate rows whose primary reason belongs to the configured reason group.
valid_table	Tensor	Tensor["B"] mask for tables with at least one hard-invalid candidate row and therefore a meaningful denominator.

1.1.8 CandidateProvenanceShareMetric

rollouts.inspection.audits.CandidateProvenanceShareMetric(
    strategy_family_ids=(),
    position_family_ids=(),
)

Accumulate candidate provenance-family share diagnostics.

The metric reports the finite mean fraction of hard-valid candidate rows that belong to configured strategy or position id families. It is designed for rollout-diversity audits such as radial-away/radial-towards plus revisit-backtrack coverage. The ids are passed as persisted integer provenance values, so callers do not need pose-generation enum imports.

1.1.8.1 Attributes

Name	Description
share_total	Tensor["", float32] sum of finite provenance-family shares.
share_count	Tensor["", float32] number of finite provenance-family shares.

1.1.8.2 Methods

Name	Description
update	Accumulate one batch of candidate provenance tables.
compute	Return finite mean family share or NaN when no tables were valid.

1.1.8.2.1 update

rollouts.inspection.audits.CandidateProvenanceShareMetric.update(
    strategy_ids,
    position_ids,
    valid_mask=None,
    *,
    dim=-1,
)

Accumulate one batch of candidate provenance tables.

1.1.8.2.2 compute

rollouts.inspection.audits.CandidateProvenanceShareMetric.compute()

Return finite mean family share or NaN when no tables were valid.

1.1.9 CandidateTableMetrics

rollouts.inspection.audits.CandidateTableMetrics()

Accumulate hard-mask candidate-table diagnostics.

The metric reports valid/invalid fractions and validity-aware value summaries over finite candidate tables. Invalid rows affect invalidity diagnostics but never enter the value mean or best-value mean.

1.1.9.1 Attributes

Name	Description
valid_count	Tensor["", float32] number of hard-valid candidate rows.
total_count	Tensor["", float32] number of candidate rows presented.
mean_total	Tensor["", float32] sum of finite per-table candidate means.
mean_count	Tensor["", float32] number of finite per-table candidate means.
best_total	Tensor["", float32] sum of finite per-table best values.
best_count	Tensor["", float32] number of finite per-table best values.

1.1.9.2 Methods

Name	Description
update_validity	Accumulate candidate hard-mask validity without value summaries.
update	Accumulate validity-aware candidate table summaries.
compute	Return candidate validity and value diagnostics.

1.1.9.2.1 update_validity

rollouts.inspection.audits.CandidateTableMetrics.update_validity(valid_mask)

Accumulate candidate hard-mask validity without value summaries.

1.1.9.2.2 update

rollouts.inspection.audits.CandidateTableMetrics.update(
    values,
    valid_mask,
    *,
    dim=-1,
)

Accumulate validity-aware candidate table summaries.

1.1.9.2.2.1 Parameters

Name	Type	Description	Default
values	Tensor	Candidate values such as rewards, Q estimates, or coverage.	required
valid_mask	Tensor	Boolean hard-validity mask broadcastable to values.	required
dim	int	Candidate dimension reduced inside each table.	-1

1.1.9.2.3 compute

rollouts.inspection.audits.CandidateTableMetrics.compute()

Return candidate validity and value diagnostics.

1.1.10 SelectedPathCostMetrics

rollouts.inspection.audits.SelectedPathCostMetrics()

Accumulate selected camera-center path cost in metres.

The metric expects root-plus-selected camera centers in world coordinates and reports the finite mean path length. Invalid or non-finite path segments are ignored via a hard segment mask; fully invalid paths contribute no cost sample instead of contributing zero.

1.1.10.1 Attributes

Name	Description
path_total	Tensor["", float32] sum of finite selected path lengths.
path_count	Tensor["", float32] number of finite selected paths.

1.1.10.2 Methods

Name	Description
update	Accumulate one batch of selected rollout paths.
compute	Return mean acquisition cost aliases for policy tables.

1.1.10.2.1 update

rollouts.inspection.audits.SelectedPathCostMetrics.update(
    camera_centers_world,
    segment_valid_mask=None,
)

Accumulate one batch of selected rollout paths.

1.1.10.2.1.1 Parameters

Name	Type	Description	Default
camera_centers_world	Tensor	Tensor["H+1 3"] or Tensor["B H+1 3"] camera centers in metres.	required
segment_valid_mask	Tensor | None	Optional hard mask over the H path segments. Masked or non-finite segments are excluded from the path sum.	None

1.1.10.2.2 compute

rollouts.inspection.audits.SelectedPathCostMetrics.compute()

Return mean acquisition cost aliases for policy tables.

1.2 Functions

Name	Description
candidate_best_value	Return the best finite candidate value under a hard mask.
candidate_masked_mean	Reduce candidate-table values with a hard validity mask.
candidate_order_consistency	Compare candidate scores before and after a candidate-order shuffle.
candidate_path_increment_stats	Summarize per-candidate path increments under the hard action mask.
candidate_policy_entropy	Compute masked per-table entropy from candidate selection probabilities.
candidate_primary_invalid_reason_share	Summarize primary invalid-reason concentration among rejected rows.
candidate_provenance_share	Compute per-table share of candidates from selected provenance families.
selected_path_length_tensor	Compute selected camera-center path length in metres.

1.2.1 candidate_best_value

rollouts.inspection.audits.candidate_best_value(values, valid_mask, *, dim=-1)

Return the best finite candidate value under a hard mask.

1.2.1.1 Parameters

Name	Type	Description	Default
values	Tensor	Candidate metric tensor.	required
valid_mask	Tensor	Boolean mask broadcastable to values.	required
dim	int	Candidate dimension to reduce.	-1

1.2.1.2 Returns

Name	Type	Description
	Tensor	Max over finite, valid entries. Empty reductions return NaN.

1.2.2 candidate_masked_mean

rollouts.inspection.audits.candidate_masked_mean(values, valid_mask, *, dim=-1)

Reduce candidate-table values with a hard validity mask.

1.2.2.1 Parameters

Name	Type	Description	Default
values	Tensor	Candidate metric tensor.	required
valid_mask	Tensor	Boolean mask broadcastable to values.	required
dim	int	Candidate dimension to reduce.	-1

1.2.2.2 Returns

Name	Type	Description
	Tensor	Mean over finite, valid entries. Empty reductions return NaN.

1.2.3 candidate_order_consistency

rollouts.inspection.audits.candidate_order_consistency(
    scores,
    shuffled_scores,
    permutation,
    valid_mask=None,
    shuffled_valid_mask=None,
    *,
    dim=-1,
)

Compare candidate scores before and after a candidate-order shuffle.

1.2.3.1 Parameters

Name	Type	Description	Default
scores	Tensor	Original candidate scores.	required
shuffled_scores	Tensor	Scores from the same candidate table after shuffling.	required
permutation	Tensor	Gather-style permutation where shuffled_scores[..., j] corresponds to scores[..., permutation[..., j]] along dim.	required
valid_mask	Tensor | None	Optional hard-validity mask for scores.	None
shuffled_valid_mask	Tensor | None	Optional hard-validity mask for shuffled_scores. If omitted, valid_mask is gathered through permutation.	None
dim	int	Candidate dimension.	-1

1.2.3.2 Returns

Name	Type	Description
	CandidateOrderConsistency	CandidateOrderConsistency with per-table score MAE, top-1 agreement,
	CandidateOrderConsistency	and valid-table mask. Empty comparable tables report NaN MAE and
	CandidateOrderConsistency	False top-1 agreement.

1.2.4 candidate_path_increment_stats

rollouts.inspection.audits.candidate_path_increment_stats(
    path_increment_m,
    valid_mask,
    *,
    dim=-1,
)

Summarize per-candidate path increments under the hard action mask.

1.2.4.1 Parameters

Name	Type	Description	Default
path_increment_m	Tensor	Candidate movement cost in metres, usually rollout diagnostic motion_step_length_m.	required
valid_mask	Tensor	Boolean hard-validity mask broadcastable to path_increment_m. Invalid rows are excluded from all statistics rather than treated as zero-cost actions.	required
dim	int	Candidate dimension reduced inside each table.	-1

1.2.4.2 Returns

Name	Type	Description
	CandidatePathIncrementStats	CandidatePathIncrementStats with per-table mean/min/max increments.
	CandidatePathIncrementStats	Empty tables return NaN statistics and valid_table=False.

1.2.5 candidate_policy_entropy

rollouts.inspection.audits.candidate_policy_entropy(
    selection_probabilities,
    valid_mask=None,
    *,
    dim=-1,
)

Compute masked per-table entropy from candidate selection probabilities.

This is the torch-native counterpart to rollout-store inspection entropy. It accepts probabilities before or after normalization, filters hard-invalid rows plus non-finite and non-positive entries, renormalizes over the candidate axis, and returns NaN for tables with no positive finite mass.

1.2.5.1 Parameters

Name	Type	Description	Default
selection_probabilities	Tensor	Candidate selection probabilities or probability-like non-negative weights.	required
valid_mask	Tensor | None	Optional hard-validity mask broadcastable to selection_probabilities.	None
dim	int	Candidate dimension.	-1

1.2.5.2 Returns

Name	Type	Description
	Tensor	Entropy per candidate table after reducing dim.

1.2.6 candidate_primary_invalid_reason_share

rollouts.inspection.audits.candidate_primary_invalid_reason_share(
    primary_invalid_reason,
    valid_mask,
    *,
    reason_ids,
    dim=-1,
)

Summarize primary invalid-reason concentration among rejected rows.

1.2.6.1 Parameters

Name	Type	Description	Default
primary_invalid_reason	Tensor	Stable primary invalid-reason ids aligned with the candidate table, typically candidates/primary_invalid_reason.	required
valid_mask	Tensor	Boolean hard-validity mask where True marks valid policy actions. Valid rows are excluded from both numerator and denominator.	required
reason_ids	Sequence[int] | Tensor	Reason ids counted as the audited group. The sequence must be non-empty so the metric identity is explicit at construction.	required
dim	int	Candidate dimension reduced inside each table.	-1

1.2.6.2 Returns

Name	Type	Description
	CandidatePrimaryInvalidReasonStats	CandidatePrimaryInvalidReasonStats whose share is measured over
	CandidatePrimaryInvalidReasonStats	invalid rows only. Tables with no invalid rows report NaN and
	CandidatePrimaryInvalidReasonStats	valid_table=False.

1.2.7 candidate_provenance_share

rollouts.inspection.audits.candidate_provenance_share(
    strategy_ids,
    position_ids,
    *,
    strategy_family_ids=(),
    position_family_ids=(),
    valid_mask=None,
    dim=-1,
)

Compute per-table share of candidates from selected provenance families.

Candidate generation stores view-direction provenance (strategy_ids) and position-family provenance (position_ids) separately. This helper reports the fraction of hard-valid rows whose strategy or position id belongs to the requested family sets. It is intentionally id-based so rollout stores can compute radial/backtrack diagnostics from persisted tensors without importing pose-generation enums.

1.2.7.1 Parameters

Name	Type	Description	Default
strategy_ids	Tensor	Stable view-direction ids, such as radial-away or radial-towards strategy ids.	required
position_ids	Tensor	Stable position-family ids aligned with strategy_ids, such as the revisit-backtrack position id.	required
strategy_family_ids	Sequence[int] | Tensor	Strategy ids counted as part of the audited family. Empty means no strategy id contributes.	()
position_family_ids	Sequence[int] | Tensor	Position ids counted as part of the audited family. Empty means no position id contributes.	()
valid_mask	Tensor | None	Optional hard candidate validity mask. Rows with only negative placeholder provenance ids are excluded from the denominator.	None
dim	int	Candidate dimension reduced inside each table.	-1

1.2.7.2 Returns

Name	Type	Description
	Tensor	Share tensor after reducing dim. Tables with no non-placeholder
	Tensor	provenance rows return NaN so missing provenance is not reported as
	Tensor	zero diversity.

1.2.8 selected_path_length_tensor

rollouts.inspection.audits.selected_path_length_tensor(
    camera_centers_world,
    segment_valid_mask=None,
)

Compute selected camera-center path length in metres.

1.2.8.1 Parameters

Name	Type	Description	Default
camera_centers_world	Tensor	Camera centers in world coordinates with shape Tensor["H+1 3"] or Tensor["B H+1 3"]. The first point is the decision-state root pose and later points are selected rollout views.	required
segment_valid_mask	Tensor | None	Optional hard mask over path segments with shape Tensor["H"] or Tensor["B H"]. Non-finite segments are ignored even when this mask is True.	None

1.2.8.2 Returns

Name	Type	Description
	Tensor	Selected path length in metres per rollout. Paths with no finite valid
	Tensor	segment return NaN rather than 0 so invalidity remains separate
	Tensor	from acquisition cost.