> 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.token_id_capture.config

Define run-wide training-token capture settings.

```python
env:
  nemo_gym:
    token_id_capture:
      enabled: true
      dir: /tmp/ng_tokcap                  # The writer and consumer share this node-local directory.
      sink: my_pkg.sinks:MyDataPlaneSink   # This optional sink replaces the file store.
```

Evaluation capture uses `/ng-rollout/<id>/...`.
Training capture uses `/ng-rollout/<id>/training-token-capture/...`.
Training capture records token ids and log probabilities.
Evaluation capture records request and response summaries.
A run can enable either path independently.
Training capture applies through the static agent flag or run-level `all_agents`.
Native agents normally leave the static flag disabled.
Their responses already carry token ids.
The top-level `model_call_capture_dir` is the fallback file-store directory.

## Choosing where records go

`sink` names a class implementing `TokenSink`, as `module.path:ClassName`.
Each server process constructs its sink at app startup.
A framework must make that class importable in the server process.
A configured sink replaces the file store.
Consumers construct and inject their `TokenSource` in their own process.
Consumers call `TokenSource.freeze` to obtain an atomic snapshot.
Consumers retire that exact snapshot with its `snapshot_id` and version.
There is no HTTP token reader.
Uvicorn workers use spawned processes.
They do not inherit a sink installed by a launcher.
Configure the sink here so each worker builds its own.
Programmatic installation must occur inside the serving process.

## Choosing who reads them back

`rebuild_response` controls whether Gym rebuilds a finished rollout.
Gym freezes captured records before rebuilding `response.output`.
Rebuilding does not retire the frozen snapshot.
Gym retires a successful build only after durable handoff.
Retirement uses the frozen `snapshot_id` and version.
Failed or masked builds retain their capture evidence.
Set it to false when a framework reads through its own `TokenSource`.
Gym then stops after the write.
Read ownership is independent of write ownership.

## Module Contents

### Classes

| Name                                                                                 | Description                                                    |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| [`TokenIdCaptureConfig`](#nemo_gym-token_id_capture-config-TokenIdCaptureConfig)     | The capture block plus the one top-level key it falls back to. |
| [`TokenIdCaptureSettings`](#nemo_gym-token_id_capture-config-TokenIdCaptureSettings) | The `token_id_capture` block.                                  |

### Functions

| Name                                                                                                         | Description                                                  |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| [`token_id_capture_config`](#nemo_gym-token_id_capture-config-token_id_capture_config)                       | Read the capture settings out of a global config dict.       |
| [`token_id_capture_enabled_for_agent`](#nemo_gym-token_id_capture-config-token_id_capture_enabled_for_agent) | Return whether one configured agent participates in capture. |

### Data

[`TOKEN_ID_CAPTURE_BLOCK`](#nemo_gym-token_id_capture-config-TOKEN_ID_CAPTURE_BLOCK)

[`logger`](#nemo_gym-token_id_capture-config-logger)

### API

```python
class nemo_gym.token_id_capture.config.TokenIdCaptureConfig()
```

**Bases:** `BaseModel`

The capture block plus the one top-level key it falls back to.

**`enabled`** `bool`

---

**`model_call_capture_dir`** `Path | None = None`

---

**`model_config`** `= ConfigDict(extra='ignore')`

---

**`token_id_capture`** `TokenIdCaptureSettings = TokenIdCaptureSettings()`

---

```python
nemo_gym.token_id_capture.config.TokenIdCaptureConfig._build_endpoint(
    target: str,
    kwargs: dict[str, typing.Any],
    protocol: type,
    kind: str
)
```

staticmethod

```python
nemo_gym.token_id_capture.config.TokenIdCaptureConfig._validate() -> 'TokenIdCaptureConfig'
```

```python
nemo_gym.token_id_capture.config.TokenIdCaptureConfig.build_sink() -> nemo_gym.token_id_capture.protocols.TokenSink | None
```

Construct the configured sink.

Return `None` when the file store is in use.
Call this once in each server process.
Launcher-installed sinks do not reach spawned workers.

```python
nemo_gym.token_id_capture.config.TokenIdCaptureConfig.resolved_dir() -> pathlib.Path | None
```

```python
class nemo_gym.token_id_capture.config.TokenIdCaptureSettings()
```

**Bases:** `BaseModel`

The `token_id_capture` block.

**`all_agents`** `bool = False`

---

**`dir`** `Path | None = None`

---

**`enabled`** `bool = False`

---

**`mask_fraction_min_samples`** `int = 50`

---

**`max_mask_fraction`** `float | None = None`

---

**`model_config`** `= ConfigDict(extra='forbid')`

---

**`rebuild_response`** `bool = True`

---

**`sink`** `str | None = None`

---

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

---

```python
nemo_gym.token_id_capture.config.token_id_capture_config(
    global_config_dict: typing.Any
) -> nemo_gym.token_id_capture.config.TokenIdCaptureConfig
```

Read the capture settings out of a global config dict.

```python
nemo_gym.token_id_capture.config.token_id_capture_enabled_for_agent(
    global_config_dict: typing.Any,
    agent_name: str | None
) -> bool
```

Return whether one configured agent participates in capture.

```python
nemo_gym.token_id_capture.config.TOKEN_ID_CAPTURE_BLOCK = 'token_id_capture'
```

```python
nemo_gym.token_id_capture.config.logger = logging.getLogger(__name__)
```