> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.rollout_health

Deterministic post-run rollout quality verification workflow.

Checks operate only on persisted rollout records and their canonical
`ng_trajectory` evidence. They return evidence; this module derives verdicts
and writes reports.

## Module Contents

### Classes

| Name                                                            | Description                                                 |
| --------------------------------------------------------------- | ----------------------------------------------------------- |
| [`CheckInput`](#nemo_gym-health-types-CheckInput)               | Persisted or derived evidence required to evaluate a check. |
| [`CheckScope`](#nemo_gym-health-types-CheckScope)               | -                                                           |
| [`CheckSpec`](#nemo_gym-health-types-CheckSpec)                 | Stable, self-describing health-check contract.              |
| [`CheckSubject`](#nemo_gym-health-types-CheckSubject)           | -                                                           |
| [`Finding`](#nemo_gym-health-types-Finding)                     | Evidence emitted by a check. Checks never emit verdicts.    |
| [`HealthCheckResult`](#nemo_gym-health-types-HealthCheckResult) | -                                                           |
| [`RolloutDigest`](#nemo_gym-health-types-RolloutDigest)         | -                                                           |

### Functions

| Name                                                                                | Description                                                                 |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`_index_jsonl`](#nemo_gym-rollout_health-_index_jsonl)                             | -                                                                           |
| [`_mark_duplicate_identities`](#nemo_gym-rollout_health-_mark_duplicate_identities) | Flag physical records that claim the same logical rollout identity.         |
| [`_process_pool_chunksize`](#nemo_gym-rollout_health-_process_pool_chunksize)       | Keep several schedulable chunks per worker without unbounded IPC batches.   |
| [`_read_record`](#nemo_gym-rollout_health-_read_record)                             | -                                                                           |
| [`_reduce`](#nemo_gym-rollout_health-_reduce)                                       | -                                                                           |
| [`_resolve_rollout_path`](#nemo_gym-rollout_health-_resolve_rollout_path)           | -                                                                           |
| [`_sort_key`](#nemo_gym-rollout_health-_sort_key)                                   | -                                                                           |
| [`_task_findings`](#nemo_gym-rollout_health-_task_findings)                         | -                                                                           |
| [`_unique_task_repeats`](#nemo_gym-rollout_health-_unique_task_repeats)             | Collapse duplicate persisted records for task-level repeat semantics.       |
| [`_worker`](#nemo_gym-rollout_health-_worker)                                       | -                                                                           |
| [`_write_reports`](#nemo_gym-rollout_health-_write_reports)                         | -                                                                           |
| [`format_health_report`](#nemo_gym-rollout_health-format_health_report)             | -                                                                           |
| [`health_check_run_dir`](#nemo_gym-rollout_health-health_check_run_dir)             | -                                                                           |
| [`normalize_ignored_checks`](#nemo_gym-health-checks-normalize_ignored_checks)      | Normalize and validate check IDs supplied by library, CLI, or Hydra config. |
| [`run_health_checks`](#nemo_gym-rollout_health-run_health_checks)                   | Run the RFC's map/group/reduce pipeline and write both reports.             |

### Data

[`CHECK_REGISTRY`](#nemo_gym-health-checks-CHECK_REGISTRY)

[`Verdict`](#nemo_gym-health-types-Verdict)

[`_PROCESS_POOL_CHUNKS_PER_WORKER`](#nemo_gym-rollout_health-_PROCESS_POOL_CHUNKS_PER_WORKER)

[`_PROCESS_POOL_MAX_CHUNKSIZE`](#nemo_gym-rollout_health-_PROCESS_POOL_MAX_CHUNKSIZE)

### API

```python
class nemo_gym.rollout_health.CheckInput
```

**Bases:** `enum.Enum`

Persisted or derived evidence required to evaluate a check.

**`AGENT_TURNS`** `= 'agent_turns'`

---

**`BOUND_CALLS`** `= 'bound_calls'`

---

**`OBSERVED_MODEL_CALLS`** `= 'observed_model_calls'`

---

**`OWNED_MODEL_CALLS`** `= 'owned_model_calls'`

---

**`RECORD`** `= 'record'`

---

**`REPEAT_DIGESTS`** `= 'repeat_digests'`

---

**`REPEAT_VERDICTS`** `= 'repeat_verdicts'`

---

**`TRAJECTORY`** `= 'trajectory'`

---

```python
class nemo_gym.rollout_health.CheckScope
```

**Bases:** `enum.Enum`

**`ROLLOUT`** `= 'rollout'`

---

**`RUN`** `= 'run'`

---

**`TASK`** `= 'task'`

---

```python
class nemo_gym.rollout_health.CheckSpec()
```

**Bases:** `BaseModel`

Stable, self-describing health-check contract.

**`evaluation_scope`** `CheckScope`

---

**`id`** `str`

---

**`model_config`** `= ConfigDict(frozen=True)`

---

**`reads`** `frozenset[CheckInput]`

---

**`subject`** `CheckSubject`

---

```python
nemo_gym.rollout_health.CheckSpec._require_one_call_binding_view(
    reads: frozenset[nemo_gym.health.types.CheckInput]
) -> frozenset[nemo_gym.health.types.CheckInput]
```

classmethod

```python
class nemo_gym.rollout_health.CheckSubject
```

**Bases:** `enum.Enum`

**`AGENT_TURN`** `= 'agent_turn'`

---

**`CHECK_EXECUTION`** `= 'check_execution'`

---

**`MODEL_CALL`** `= 'model_call'`

---

**`RECORD`** `= 'record'`

---

**`ROLLOUT`** `= 'rollout'`

---

**`TASK`** `= 'task'`

---

**`TRAJECTORY_CAPTURE`** `= 'trajectory_capture'`

---

```python
class nemo_gym.rollout_health.Finding()
```

**Bases:** `BaseModel`

Evidence emitted by a check. Checks never emit verdicts.

**`check`** `str`

---

**`detail`** `dict[str, Any] = Field(default_factory=dict)`

---

**`locator`** `dict[str, int | str] | None = None`

---

**`subject`** `dict[str, int | str]`

---

```python
class nemo_gym.rollout_health.HealthCheckResult()
```

**Bases:** `BaseModel`

**`rollouts`** `list[RolloutDigest]`

---

**`summary`** `dict[str, Any]`

---

**`summary_path`** `Path`

---

**`verdicts_path`** `Path`

---

```python
class nemo_gym.rollout_health.RolloutDigest()
```

**Bases:** `BaseModel`

**`capture_completion_tokens`** `int = 0`

---

**`capture_observed`** `bool`

---

**`capture_prompt_tokens`** `int = 0`

---

**`duplicated_calls`** `int = 0`

---

**`ended_on_error`** `bool = False`

---

**`errors_by_status`** `dict[str, int] = Field(default_factory=dict)`

---

**`findings`** `list[Finding]`

---

**`model_call_errors`** `int = 0`

---

**`model_calls`** `int = 0`

---

**`policy_calls_observed`** `bool = False`

---

**`rollout_id`** `str`

---

**`rollout_index`** `int | str`

---

**`stage_index`** `int | str | None = None`

---

**`successful_model_calls`** `int = 0`

---

**`task_index`** `int | str`

---

**`transcript_completion_tokens`** `int = 0`

---

**`transcript_prompt_tokens`** `int = 0`

---

**`unobserved`** `list[str]`

---

**`verdict`** `Verdict`

---

```python
nemo_gym.rollout_health._index_jsonl(
    paths: collections.abc.Sequence[pathlib.Path]
) -> list[nemo_gym.health.types._LineSlice]
```

```python
nemo_gym.rollout_health._mark_duplicate_identities(
    digests: list[nemo_gym.health.types.RolloutDigest],
    ignored_checks: frozenset[str]
) -> None
```

Flag physical records that claim the same logical rollout identity.

```python
nemo_gym.rollout_health._process_pool_chunksize(
    item_count: int,
    workers: int
) -> int
```

Keep several schedulable chunks per worker without unbounded IPC batches.

```python
nemo_gym.rollout_health._read_record(
    line: nemo_gym.health.types._LineSlice
) -> tuple[dict[str, typing.Any], str | None]
```

```python
nemo_gym.rollout_health._reduce(
    digests: list[nemo_gym.health.types.RolloutDigest],
    ignored_checks: frozenset[str]
) -> dict[str, typing.Any]
```

```python
nemo_gym.rollout_health._resolve_rollout_path(
    run_dir: pathlib.Path,
    rollout_file: str | pathlib.Path | None
) -> pathlib.Path
```

```python
nemo_gym.rollout_health._sort_key(
    digest: nemo_gym.health.types.RolloutDigest
) -> tuple[tuple[int, typing.Any], ...]
```

```python
nemo_gym.rollout_health._task_findings(
    grouped: dict[int | str, list[nemo_gym.health.types._TaskRepeat]],
    ignored_checks: frozenset[str]
) -> tuple[dict[int | str, list[nemo_gym.health.types.Finding]], dict[str, dict[str, int]]]
```

```python
nemo_gym.rollout_health._unique_task_repeats(
    digests: list[nemo_gym.health.types.RolloutDigest]
) -> list[nemo_gym.health.types._TaskRepeat]
```

Collapse duplicate persisted records for task-level repeat semantics.

```python
nemo_gym.rollout_health._worker(
    payload: nemo_gym.health.types._WorkerInput
) -> nemo_gym.health.types.RolloutDigest
```

```python
nemo_gym.rollout_health._write_reports(
    summary: dict[str, typing.Any],
    digests: list[nemo_gym.health.types.RolloutDigest],
    output_dir: pathlib.Path
) -> tuple[pathlib.Path, pathlib.Path]
```

```python
nemo_gym.rollout_health.format_health_report(
    result: nemo_gym.health.types.HealthCheckResult
) -> str
```

```python
nemo_gym.rollout_health.health_check_run_dir(
    run_dir: str | pathlib.Path,
    rollout_file: str | pathlib.Path | None = None,
    workers: int | None = None,
    ignored_checks: collections.abc.Sequence[str] = (),
    json_output: bool = False
) -> nemo_gym.health.types.HealthCheckResult
```

```python
nemo_gym.rollout_health.normalize_ignored_checks(
    checks: collections.abc.Sequence[str] | str | None
) -> tuple[str, ...]
```

Normalize and validate check IDs supplied by library, CLI, or Hydra config.

```python
nemo_gym.rollout_health.run_health_checks(
    rollout_paths: pathlib.Path | collections.abc.Sequence[pathlib.Path],
    output_dir: pathlib.Path | None = None,
    workers: int | None = None,
    ignored_checks: collections.abc.Sequence[str] = ()
) -> nemo_gym.health.types.HealthCheckResult
```

Run the RFC's map/group/reduce pipeline and write both reports.

```python
nemo_gym.health.checks.CHECK_REGISTRY: tuple[CheckSpec, ...] = (CheckSpec(id='check_execution_error', evaluation_scope=(CheckScope.ROLLOUT), su...
```

```python
nemo_gym.health.types.Verdict = Literal['healthy', 'unhealthy', 'unobserved']
```

```python
nemo_gym.rollout_health._PROCESS_POOL_CHUNKS_PER_WORKER = 4
```

```python
nemo_gym.rollout_health._PROCESS_POOL_MAX_CHUNKSIZE = 128
```