nemo_gym.token_id_capture.terminal

Attribute a finished rollout’s verified terminal model call.

Every agent’s /run result carries response: the object the verifier scored. Capture, by contrast, records every call the model server served, including auxiliary calls, abandoned retries, and sub-agent branches. Terminal attribution joins the verified response to exactly one captured call, so the builder can deliver the chain that earned the reward instead of guessing among chains or masking a healthy rollout.

The join is independent witnesses with corroboration, not a trust hierarchy. The fact “which call was kept” is emitted in different places by different agent classes, so up to four witnesses testify:

explicit — the caller names the kept call directly (a gate seal or an agent-declared terminal id). Soft: a miss is an abstention and other witnesses may still attribute. declared — the harness reports the response id it retained. Selection stops if that id does not match exactly one captured row. response_id — the /run response’s id equals the served id recorded on exactly one entry. Possession of the id proves which response the client actually received. content — the fingerprint of the response’s model-authored items matches one entry. Three readings are pooled: the entry’s cumulative continuation_fingerprint when a lineage-aware writer recorded one (a full-transcript response), the fingerprint of the entry’s own output (a final-turn-only response), and the transcript’s trailing model-authored block (a merged multi-turn transcript).

External staging rows omit token arrays because those tokens remain in framework storage. They carry a staging_key and precomputed content fingerprints instead. This module identifies external staging rows by the presence of staging_key.

Each witness abstains rather than guesses (ambiguity inside a witness is an abstention, not a vote). The verdict then follows the stack’s rule that claims are verified, never ranked: witnesses that agree — or that name calls with identical full token sequences — attribute; witnesses that contradict each other attribute nothing and persist the disagreement, because a contradiction is evidence of a real defect (a stale seal mapping, backend id reuse, a transcript-synthesis bug) that outranking would silently bury. If no terminal response ID is declared, a rollout with no witness or with disagreeing witnesses falls back to the builder’s strict single-chain policy. If a declared terminal response ID cannot be attributed, the consumer masks the rollout instead.

The content witness deliberately uses assistant_fingerprint alone, without a request-context digest. Attribution selects a chain whose tokens the builder verifies independently; it never reuses tokens across the matched boundary. Requiring context verification would spuriously refuse synthesized transcripts that reformat tool output, without adding safety.

Module Contents

Classes

Functions

API

class nemo_gym.token_id_capture.terminal.TerminalAttribution(
    model_call_id: str | None,
    method: str = '',
    reason: str = ''
)

nemo_gym.token_id_capture.terminal._collapse_identical(
    candidates: list[nemo_gym.token_id_capture.records.TokenEntry]
) -> nemo_gym.token_id_capture.records.TokenEntry | None

nemo_gym.token_id_capture.terminal._content_witness(
    entries: list[nemo_gym.token_id_capture.records.TokenEntry],
    response: dict,
    reasons: list[str]
) -> tuple[str, nemo_gym.token_id_capture.records.TokenEntry] | None

nemo_gym.token_id_capture.terminal._is_custody_row(
    entry: nemo_gym.token_id_capture.records.TokenEntry
) -> bool

nemo_gym.token_id_capture.terminal._sequence_identity(
    entry: nemo_gym.token_id_capture.records.TokenEntry
) -> tuple

nemo_gym.token_id_capture.terminal.resolve_terminal(
    entries: list[nemo_gym.token_id_capture.records.TokenEntry],
    response: dict | None,
    explicit_call_id: str | None = None,
    declared_response_id: str | None = None
) -> nemo_gym.token_id_capture.terminal.TerminalAttribution