> This page is for version 0.5.1.
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt

> 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_correlation

## Module Contents

### Classes

| Name                                                                                 | Description                                                                    |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [`RolloutContextMiddleware`](#nemo_gym-rollout_correlation-RolloutContextMiddleware) | Strip a rollout prefix and expose it to downstream Gym calls for this request. |

### Functions

| Name                                                                                             | Description                                                                    |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [`current_episode_id`](#nemo_gym-rollout_correlation-current_episode_id)                         | Return the logical rollout and attempt carried by the current capture key.     |
| [`current_rollout_id`](#nemo_gym-rollout_correlation-current_rollout_id)                         | -                                                                              |
| [`maybe_rollout_id_from_run_body`](#nemo_gym-rollout_correlation-maybe_rollout_id_from_run_body) | Build the capture key for a run request.                                       |
| [`rollout_context`](#nemo_gym-rollout_correlation-rollout_context)                               | -                                                                              |
| [`scope_with_routed_path`](#nemo_gym-rollout_correlation-scope_with_routed_path)                 | Copy the scope for routing and share the rewritten path with outer middleware. |

### Data

[`ROLLOUT_ID_PATTERN`](#nemo_gym-rollout_correlation-ROLLOUT_ID_PATTERN)

[`ROUTED_PATH_STATE_KEY`](#nemo_gym-rollout_correlation-ROUTED_PATH_STATE_KEY)

[`_ROLLOUT_ID`](#nemo_gym-rollout_correlation-_ROLLOUT_ID)

### API

```python
class nemo_gym.rollout_correlation.RolloutContextMiddleware(
    app: typing.Any
)
```

Strip a rollout prefix and expose it to downstream Gym calls for this request.

**`_PREFIX`**

---

```python
nemo_gym.rollout_correlation.RolloutContextMiddleware.__call__(
    scope: dict[str, typing.Any],
    receive: typing.Any,
    send: typing.Any
) -> None
```

async

```python
nemo_gym.rollout_correlation.current_episode_id() -> typing.Optional[nemo_gym.episode_types.EpisodeId]
```

Return the logical rollout and attempt carried by the current capture key.

```python
nemo_gym.rollout_correlation.current_rollout_id() -> typing.Optional[str]
```

```python
nemo_gym.rollout_correlation.maybe_rollout_id_from_run_body(
    body: pydantic.BaseModel | collections.abc.Mapping[str, typing.Any] | None
) -> typing.Optional[str]
```

Build the capture key for a run request.

An explicit `_ng_rollout_id` takes precedence.
Otherwise derive `"{task}-{rollout}"` from the task and rollout indices.
Re-dispatch attempts append `-a{n}`.
The suffix is reserved: an explicit id ending in `-a<N>` names attempt N of the rollout before it,
as a training controller names a restored attempt,
and rollout collection refuses dataset rows that use it as a plain id.
Writers and consumers must use this same identity.
Reused task and rollout indices produce a repeated capture key.
Use an explicit id when numbering restarts across dispatches.

```python
nemo_gym.rollout_correlation.rollout_context(
    rollout_id: typing.Optional[str]
) -> collections.abc.Iterator[None]
```

```python
nemo_gym.rollout_correlation.scope_with_routed_path(
    scope: dict[str, typing.Any],
    path: str
) -> dict[str, typing.Any]
```

Copy the scope for routing and share the rewritten path with outer middleware.

```python
nemo_gym.rollout_correlation.ROLLOUT_ID_PATTERN = re.compile('^[A-Za-z0-9][A-Za-z0-9._-]*$')
```

```python
nemo_gym.rollout_correlation.ROUTED_PATH_STATE_KEY = 'nemo_gym.routed_path'
```

```python
nemo_gym.rollout_correlation._ROLLOUT_ID: ContextVar[Optional[str]] = ContextVar('nemo_gym_rollout_id', default=None)
```