> This page is for version Main (default).
> 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.

# JSONL Datasets

> Define tasks as JSONL rows served by a Resources Server: the row format, dataset configuration, validation and CLI commands.

Each line of a JSONL dataset is one task: the prompt the agent sees, plus anything your verifier needs to score the answer. A Resources Server, a Python server you write or reuse, provides the tools and the scoring code that every task shares.

JSONL rows fit many tasks that share one verifier and toolset, such as math, instruction following or tool calling. Tasks that each need their own software environment, such as terminal and coding tasks, fit [Harbor Task Folders](/nemo/gym/main/data/task-folders) better.

## Data Format

Each JSONL line requires a `responses_create_params` field following the [OpenAI Responses API schema](https://platform.openai.com/docs/api-reference/responses/create). You don't need an OpenAI account: local servers such as vLLM use the same format.

```json
{"responses_create_params": {"input": [{"role": "user", "content": "What is 2+2?"}]}}
```

Additional fields like `expected_answer` vary by resources server—the component that provides tools and reward signals.

### Required Fields

| Field                     | Added By              | Description                                                                                               |
| ------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- |
| `responses_create_params` | User                  | Input to the model during training. Contains `input` (messages) and optional `tools`, `temperature`, etc. |
| `agent_ref`               | `gym dataset collate` | Routes each row to its agent server. Auto-generated during data preparation.                              |

### Optional Fields

| Field             | Description                                    |
| ----------------- | ---------------------------------------------- |
| `expected_answer` | Ground truth for verification (task-specific). |
| `question`        | Original question text (for reference).        |
| `id`              | Tracking identifier.                           |

> **Tip**
>
> Check `resources_servers/<name>/README.md` for fields required by each resources server's `verify()` method.

### The `agent_ref` Field

The `agent_ref` field maps each row to a specific agent server, which in turn knows its resources server from the YAML config. A training dataset can blend multiple agent servers in a single file—`agent_ref` tells NeMo Gym which server handles each row.

```json
{
  "responses_create_params": {"input": [{"role": "user", "content": "..."}]},
  "agent_ref": {"type": "responses_api_agents", "name": "math_with_judge_simple_agent"}
}
```

**You don't create `agent_ref` manually.** The `gym dataset collate` tool adds it automatically based on your config file. The tool matches the agent type (`responses_api_agents`) with the agent name from the config.

### Example Data

```json
{"responses_create_params": {"input": [{"role": "user", "content": "What is 2+2?"}]}, "expected_answer": "4"}
{"responses_create_params": {"input": [{"role": "user", "content": "What is 3*5?"}]}, "expected_answer": "15"}
{"responses_create_params": {"input": [{"role": "user", "content": "What is 10/2?"}]}, "expected_answer": "5"}
```

## Quick Start

Run this command from the repository root:

```bash
gym dataset collate \
    --config responses_api_models/vllm_model/configs/vllm_model_for_training.yaml \
    --resources-server example_multi_step \
    --output-dir data/test \
    --mode example_validation
```

**Success**: `Finished!` message and `data/test/example_metrics.json` created.

## Dataset Types

| Type         | Purpose                    | License      |
| ------------ | -------------------------- | ------------ |
| `example`    | Testing and development    | Not required |
| `train`      | RL training data           | Required     |
| `validation` | Evaluation during training | Required     |

## Configuration

Define datasets in your agent server's YAML config:

```yaml
datasets:
  - name: train
    type: train
    jsonl_fpath: resources_servers/workplace_assistant/data/train.jsonl
    # Unified dataset source. `type` selects the backend; the other fields are backend-specific.
    source:
      type: huggingface
      repo_id: nvidia/Nemotron-RL-agent-workplace_assistant
      artifact_fpath: train.jsonl
    license: Apache 2.0
```

| Field         | Required         | Description                                                        |
| ------------- | ---------------- | ------------------------------------------------------------------ |
| `name`        | Yes              | Dataset identifier                                                 |
| `type`        | Yes              | `example`, `train`, or `validation`                                |
| `jsonl_fpath` | Yes              | Path to data file                                                  |
| `license`     | Train/validation | See valid values below                                             |
| `source`      | No               | Where to fetch the data from when it's missing locally (see below) |
| `num_repeats` | No               | Repeat count (default: `1`)                                        |

### Dataset `source`

`source` is the unified way to declare where a dataset is fetched from. `type` selects the backend; the remaining fields are backend-specific:

```yaml
# Hugging Face Hub
source:
  type: huggingface
  repo_id: nvidia/Nemotron-RL-agent-workplace_assistant
  artifact_fpath: train.jsonl

# GitLab dataset registry
source:
  type: gitlab
  dataset_name: example_multi_step
  version: 0.0.1
  artifact_fpath: train.jsonl
```

> **Note**
>
> The legacy `huggingface_identifier:` / `gitlab_identifier:` blocks still work (a deprecation warning is emitted), so existing configs keep running — but new configs should use `source:`.

### Valid Licenses

`Apache 2.0` · `MIT` · `GNU General Public License v3.0` · `Creative Commons Attribution 4.0 International` · `Creative Commons Attribution-ShareAlike 4.0 International` · `TBD` · `NVIDIA Internal Use Only, Do Not Distribute`

## Workflow

```mermaid
flowchart LR
    A[Create JSONL] --> B[Add to config]
    B --> C[Run gym dataset collate]
    C -->|Pass| D[Train with NeMo RL]
    C -->|Fail| E[Fix and retry]
```

## Validation Modes

| Mode                 | Scope                  | Use Case                         |
| -------------------- | ---------------------- | -------------------------------- |
| `example_validation` | `example` datasets     | Format check before contributing |
| `train_preparation`  | `train` + `validation` | Full prep for RL training        |

To prepare training data with auto-download:

```bash
gym dataset collate \
    --config responses_api_models/vllm_model/configs/vllm_model_for_training.yaml \
    --resources-server workplace_assistant \
    --output-dir data/workplace_assistant \
    --mode train_preparation \
    --download
```

> **Tip**
>
> HuggingFace downloads require authentication. Set `hf_token` in `env.yaml` or export `HF_TOKEN`.

## Common Errors

| Error                                      | Cause           | Fix                                      |
| ------------------------------------------ | --------------- | ---------------------------------------- |
| `JSON parse error at line N`               | Invalid JSON    | Check quotes, commas, brackets at line N |
| `ValidationError: responses_create_params` | Missing field   | Add `responses_create_params.input`      |
| `A license is required`                    | Missing license | Add `license` to dataset config          |
| `Missing local datasets`                   | File not found  | Check path or add `--download`           |

## Guides

#### [Prepare and Validate](/nemo/gym/main/data/jsonl/prepare-validate)

Full data preparation workflow.

data-prep

#### [Download from Hugging Face](/nemo/gym/main/data/jsonl/download-huggingface)

Fetch datasets from HuggingFace Hub.

huggingface

#### [Prompt Config](/nemo/gym/main/data/jsonl/prompt-config)

YAML-based prompt templates applied at rollout time.

prompts

## CLI Commands

| Command                | Description                   |
| ---------------------- | ----------------------------- |
| `gym dataset collate`  | Validate and generate metrics |
| `gym dataset download` | Download from HuggingFace     |

See [CLI Commands](/nemo/gym/main/reference/cli-commands) for details.

## Large Datasets

* Validation streams line-by-line (memory-efficient)
* Single-threaded; >100K samples may take minutes
* Use `num_repeats` instead of duplicating JSONL lines