`nemo_rl.experience.route_assembly`#

Shared route-plan executor for direct and deferred router replay.

One implementation turns a verified :class:RouteAssemblyPlan plus fetched

class:: RouteFragment payloads into a training route tensor. The finalizer runs it eagerly in direct mode (a failure rejects the rollout before publication as route_assembly:<reason>); the policy worker runs it after canonical publication in deferred mode (the same reason maps to the existing counted sentinel fallback). The executor owns per-span extras-digest verification against Gym’s receipt-bound commitments, span classification via Gym’s decision table, full/tail slicing, sentinel fill, and shape checks — it returns a tensor or a failure reason and never decides policy.

Module Contents#

Classes#

RouteFragment

One staged route payload plus the metadata its extras digest binds.

Functions#

`verify_route_fragment_integrity`	Rebuild the staged extras envelope and verify the receipt-bound digest.
`execute_route_plan`	Assemble one canonical route tensor from staged fragments.

Data#

`ROUTE_MISSING_SENTINEL`
`ROUTE_FAILURE_CANONICAL_LENGTH`
`ROUTE_FAILURE_MISSING_FRAGMENT`
`ROUTE_FAILURE_INTEGRITY`
`ROUTE_FAILURE_RANK`
`ROUTE_FAILURE_LENGTH`
`ROUTE_FAILURE_MODEL_SHAPE`
`ROUTE_FAILURE_ASSEMBLED_LENGTH`

API#

nemo_rl.experience.route_assembly.ROUTE_MISSING_SENTINEL#: None

nemo_rl.experience.route_assembly.ROUTE_FAILURE_CANONICAL_LENGTH#: ‘canonical_length_mismatch’

nemo_rl.experience.route_assembly.ROUTE_FAILURE_MISSING_FRAGMENT#: ‘missing_fragment’

nemo_rl.experience.route_assembly.ROUTE_FAILURE_INTEGRITY#: ‘fragment_integrity’

nemo_rl.experience.route_assembly.ROUTE_FAILURE_RANK#: ‘fragment_rank’

nemo_rl.experience.route_assembly.ROUTE_FAILURE_LENGTH#: ‘fragment_length’

nemo_rl.experience.route_assembly.ROUTE_FAILURE_MODEL_SHAPE#: ‘fragment_model_shape’

nemo_rl.experience.route_assembly.ROUTE_FAILURE_ASSEMBLED_LENGTH#: ‘assembled_length_mismatch’

class nemo_rl.experience.route_assembly.RouteFragment#

One staged route payload plus the metadata its extras digest binds.

routes is the staged [staged_len, num_moe_layers, topk] tensor, encoding the ROUTE_ENCODING_* wire code the digest was committed over, and extras_metadata_json the canonical non-route extras JSON staged beside it.

routes: torch.Tensor#: None

encoding: int#: None

extras_metadata_json: bytes#: None

nemo_rl.experience.route_assembly.verify_route_fragment_integrity( fragment: nemo_rl.experience.route_assembly.RouteFragment, *, extras_digest_version: int, expected_extras_digest: str, ) → bool#: Rebuild the staged extras envelope and verify the receipt-bound digest.

nemo_rl.experience.route_assembly.execute_route_plan( plan: nemo_rl.experience.route_plan.RouteAssemblyPlan, fragments: Mapping[str, nemo_rl.experience.route_assembly.RouteFragment], *, dims: tuple[int, int], canonical_len: int, ) → tuple[Optional[torch.Tensor], Optional[str]]#

Assemble one canonical route tensor from staged fragments.

Parameters:

plan – The verified assembly plan built by the finalizer.
fragments – Fetched fragments keyed by staging key. Sentinel spans need no entry.
dims – Model-owned (num_moe_layers, topk). The policy worker supplies real model dims (the authoritative shape check); the direct-mode finalizer supplies dims learned from the fetched fragments.
canonical_len – The published row’s token length.

Returns:

(tensor, None) on success — [canonical_len, num_moe_layers, topk] int16, sentinel-filled wherever no fragment contributed — or (None, reason) with a reason from the shared vocabulary.

nemo_rl.experience.route_assembly#