nemo_gym.token_id_capture.staging.records

Versioned wire records for framework-owned token staging.

Module Contents

Classes

Name	Description
`CallRecord`	One token-free call manifest row in a rollout’s capture ledger.
`CaptureAdmission`	Gate-to-worker identity and exact-prefix contract for one model call.
`CaptureLedgerCommit`	One successfully staged call, as handed to `CaptureLedger.record`.
`CommitCoords`	Metadata returned after an inference worker stages one call.
`GenerationCutContinuation`	A checkpointed prefix of the same call, which the worker continues instead of regenerating.
`ManifestFailure`	A call whose token capture did not complete.
`RolloutManifest`	The token-free ledger read returned by the manifest control route.
`RolloutReceipt`	Token-free immutable manifest the framework assembles at rollout end.
`RolloutRemoval`	The result of retiring or deleting rollouts in a capture store or ledger.
`StageResult`	Durability result returned by `StagingSink.stage`.
`StagedCallBaseSnapshot`	Token columns and metadata for one staged call.
`StagedCallRecord`	One normalized token delta made durable by a framework staging sink.
`StagedCallSnapshot`	The exact staged record returned by a framework-owned source.
`_DigestWireModel`	-
`_WireModel`	-

Functions

Name	Description
`staging_key`	Return the default deterministic key used by the NeMo RL backend.

Data

CaptureDisposition

CaptureMode

DigestHex

INVALID_COMMIT_COORDS_REASON

TERMINAL_DUPLICATE_CALL_ID

TERMINAL_NO_RECORDS

TERMINAL_NO_ROOT

TERMINAL_ORPHANED_ROW

TERMINAL_SELECTED

WORKER_CAPTURE_FAILED_REASON

WORKER_MISSING_COMMIT_COORDS_REASON

_BUILD_STAGING_DIGEST

API

class nemo_gym.token_id_capture.CallRecord()

Bases: _DigestWireModel

One token-free call manifest row in a rollout’s capture ledger.

admitted_at

StrictFloat | None = None

capture_key

Identifier | None = None

chain_hash

DigestHex

continuation_fingerprint

DigestHex | None = None

cum_len

NonNegativeInt

cumulative_hash

DigestHex

delta_len

NonNegativeInt

digest

DigestHex

extras_digest

DigestHex

fingerprint_version

NonNegativeInt = 0

mode

CaptureMode = 'token_in'

model_call_id

Identifier

output_fingerprint

DigestHex | None = None

parent_call_id

Identifier | None = None

prev_len

NonNegativeInt

response_id

Identifier

staging_key

Identifier

weight_version

NonNegativeInt

nemo_gym.token_id_capture.CallRecord._validate_lengths() -> typing.Self

class nemo_gym.token_id_capture.staging.CaptureAdmission()

Bases: _WireModel

Gate-to-worker identity and exact-prefix contract for one model call.

A token_in admission carries its prefix in one of two encodings. required_prefix_token_ids holds the ids inline. staging_chain names the staged records whose token deltas form the prefix. The worker resolves either encoding to a flat id list. It passes that list to CaptureAdapter.enter_prefix and to RolloutTokenCapture.begin_call.

generation_cut

GenerationCutContinuation | None = None

mode

CaptureMode

model_call_id

Identifier

parent_call_id

Identifier | None = None

parent_chain_hash

DigestHex | None = None

prev_len

NonNegativeInt = 0

required_prefix_token_ids

list[StrictInt] = Field(default_factory=list)

rollout_id

Identifier

staging_chain

list[str] = Field(default_factory=list)

nemo_gym.token_id_capture.staging.CaptureAdmission._validate_prefix_contract() -> typing.Self

class nemo_gym.token_id_capture.CaptureLedgerCommit()

Bases: _WireModel

One successfully staged call, as handed to CaptureLedger.record.

record is the manifest row. The remaining fields feed parent resolution and are not part of the manifest.

record

CallRecord

request_items

list[dict]

response_items

list[dict]

rollout_id

Identifier

staging_chain

tuple[Identifier, ...] = ()

class nemo_gym.token_id_capture.staging.CommitCoords()

Bases: _DigestWireModel

Metadata returned after an inference worker stages one call.

chain_hash

DigestHex | None = None

cum_len

NonNegativeInt

cumulative_hash

DigestHex | None = None

delta_len

NonNegativeInt

digest

DigestHex | None = None

disposition

CaptureDisposition = 'staged'

extras_digest

DigestHex | None = None

model_call_id

Identifier

parent_call_id

Identifier | None = None

prev_len

NonNegativeInt

rollout_id

Identifier

staging_key

Identifier | None = None

weight_version

NonNegativeInt

nemo_gym.token_id_capture.staging.CommitCoords._validate_disposition() -> typing.Self

class nemo_gym.token_id_capture.staging.GenerationCutContinuation()

Bases: _WireModel

A checkpointed prefix of the same call, which the worker continues instead of regenerating.

The replacement attempt re-issues the call that was in flight at the checkpoint. The worker reads the staged prefix named by staging_keys, verifies its length and digest, and generates only the remaining tokens within effective_output_limit. A terminal finish reason means the cut captured a finished generation that the worker returns without generating more.

effective_output_limit

PositiveInt

prefix_digest

DigestHex

prefix_token_count

NonNegativeInt

source_capture_key

Identifier

source_model_call_id

Identifier

staging_keys

tuple[Identifier, ...] = Field(min_length=1)

terminal_finish_reason

Literal['stop', 'length'] | None = None

terminal_stop_reason

str | int | None = None

nemo_gym.token_id_capture.staging.GenerationCutContinuation._validate_staging_keys() -> typing.Self

class nemo_gym.token_id_capture.staging.records.ManifestFailure()

Bases: _WireModel

A call whose token capture did not complete.

model_call_id

Identifier

reason

Identifier

class nemo_gym.token_id_capture.staging.records.RolloutManifest()

Bases: _WireModel

The token-free ledger read returned by the manifest control route.

failures

list[ManifestFailure] = Field(default_factory=list)

records

list[CallRecord] = Field(default_factory=list)

rollout_id

Identifier

class nemo_gym.token_id_capture.staging.RolloutReceipt()

Bases: _DigestWireModel

Token-free immutable manifest the framework assembles at rollout end.

capture_poisoned

bool = False

failure_reason

str | None = None

manifest

list[CallRecord] = Field(default_factory=list)

reward

float | None = None

rollout_id

Identifier

terminal_attribution_reason

str | None = None

terminal_model_call_id

Identifier | None = None

terminal_selection

Literal['declared', 'response_id', 'content', 'heuristic'] | None = None

nemo_gym.token_id_capture.staging.RolloutReceipt._validate_attribution_state() -> typing.Self

Keep the terminal fields in one of the three documented states.

A trainable receipt names its terminal and the method that chose it. An unset terminal_selection is reserved for receipts where no attribution stage ran, which cannot name a terminal and must be poisoned with a reason. A poisoned receipt may still carry a terminal and method, because attribution can succeed before another call poisons the rollout.

nemo_gym.token_id_capture.staging.RolloutReceipt._validate_manifest() -> typing.Self

class nemo_gym.token_id_capture.staging.records.RolloutRemoval()

Bases: _WireModel

The result of retiring or deleting rollouts in a capture store or ledger.

absent

list[Identifier] = Field(default_factory=list)

removed

list[Identifier] = Field(default_factory=list)

class nemo_gym.token_id_capture.staging.StageResult()

Bases: _WireModel

Durability result returned by StagingSink.stage.

error

str | None = None

bool

staging_key

Identifier | None = None

nemo_gym.token_id_capture.staging.StageResult._validate_result() -> typing.Self

class nemo_gym.token_id_capture.staging.StagedCallBaseSnapshot()

Bases: _DigestWireModel

Token columns and metadata for one staged call.

This model excludes the optional extras payload. Validation recomputes the call digest from these fields and the recorded extras_digest. It does not verify that the corresponding extras payload exists or matches that digest. A consumer that loads extras must verify them separately with compute_extras_digest.

chain_hash

DigestHex

cum_len

NonNegativeInt

cumulative_hash

DigestHex

delta_len

NonNegativeInt

digest

DigestHex

extras_digest

DigestHex = EMPTY_EXTRAS_DIGEST

generation_log_probs_delta

list[StrictFloat]

mode

CaptureMode

model_call_id

Identifier

parent_call_id

Identifier | None = None

prev_len

NonNegativeInt

rollout_id

Identifier

staging_key

str

token_ids_delta

list[StrictInt]

token_mask_delta

list[StrictFloat]

weight_version

NonNegativeInt

nemo_gym.token_id_capture.staging.StagedCallBaseSnapshot._validate_base_integrity(
    info: pydantic.ValidationInfo
) -> typing.Self

class nemo_gym.token_id_capture.staging.StagedCallRecord()

Bases: StagedCallBaseSnapshot

One normalized token delta made durable by a framework staging sink.

extras

dict[str, Any] | None = None

nemo_gym.token_id_capture.staging.StagedCallRecord._validate_extras_integrity() -> typing.Self

nemo_gym.token_id_capture.staging.StagedCallRecord.from_components(
    rollout_id: str,
    model_call_id: str,
    parent_call_id: str | None,
    mode: nemo_gym.token_id_capture.staging.records.CaptureMode,
    prev_len: int,
    delta_len: int,
    cum_len: int,
    weight_version: int,
    token_ids_delta: list[int],
    token_mask_delta: list[float],
    generation_log_probs_delta: list[float],
    extras: dict[str, typing.Any] | None,
    extras_digest: str,
    chain_hash: str,
    cumulative_hash: str
) -> typing.Self

classmethod

Validate local components and compute their digest exactly once.

Runs normal field, integrity, and extras validators. Wire constructors still require a supplied digest and verify it against the contents.

Raises:

ValueError: A mask or log probability is not an exact Python float.
ValidationError: Other components fail field or integrity validation.

class nemo_gym.token_id_capture.staging.StagedCallSnapshot()

Bases: StagedCallRecord

The exact staged record returned by a framework-owned source.

class nemo_gym.token_id_capture.staging.records._DigestWireModel()

Bases: _WireModel

digest_version

Literal[STAGING_DIGEST_VERSION] = STAGING_DIGEST_VERSION

extras_digest_version

Literal[EXTRAS_DIGEST_VERSION] = EXTRAS_DIGEST_VERSION

class nemo_gym.token_id_capture.staging.records._WireModel()

Bases: BaseModel

model_config

= ConfigDict(extra='forbid', allow_inf_nan=False)

schema_version

Literal[STAGING_SCHEMA_VERSION] = STAGING_SCHEMA_VERSION

nemo_gym.token_id_capture.staging.staging_key(
    rollout_id: str,
    model_call_id: str
) -> str

Return the default deterministic key used by the NeMo RL backend.

nemo_gym.token_id_capture.staging.records.CaptureDisposition = Literal['staged', 'capture_failed']

nemo_gym.token_id_capture.staging.records.CaptureMode = Literal['token_in', 'text']

nemo_gym.token_id_capture.staging.records.DigestHex = Annotated[StrictStr, Field(pattern='^[0-9a-f]{64}$')]

nemo_gym.token_id_capture.staging.records.INVALID_COMMIT_COORDS_REASON = 'invalid_worker_commit_coordinates'

nemo_gym.token_id_capture.staging.records.Identifier = Annotated[StrictStr, Field(min_length=1)]

nemo_gym.token_id_capture.staging.records.NonNegativeInt = Annotated[StrictInt, Field(ge=0)]

nemo_gym.token_id_capture.staging.records.PositiveInt = Annotated[StrictInt, Field(ge=1)]

nemo_gym.token_id_capture.staging.records.TERMINAL_AMBIGUOUS = 'ambiguous_terminal'

nemo_gym.token_id_capture.staging.records.TERMINAL_DUPLICATE_CALL_ID = 'duplicate_call_id'

nemo_gym.token_id_capture.staging.records.TERMINAL_NO_RECORDS = 'no_records'

nemo_gym.token_id_capture.staging.records.TERMINAL_NO_ROOT = 'no_root'

nemo_gym.token_id_capture.staging.records.TERMINAL_ORPHANED_ROW = 'orphaned_row'

nemo_gym.token_id_capture.staging.records.TERMINAL_SELECTED = 'selected'

nemo_gym.token_id_capture.staging.records.WORKER_CAPTURE_FAILED_REASON = 'worker_capture_failed'

nemo_gym.token_id_capture.staging.records.WORKER_MISSING_COMMIT_COORDS_REASON = 'worker_response_missing_commit_coordinates'

nemo_gym.token_id_capture.staging.records._BUILD_STAGING_DIGEST = object()