> 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.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# NeMo User Sim Integration Reference

> Architecture, ownership, request contracts, and saved fields for the NeMo User Sim integration.

This page describes the integration behind the
[NeMo User Sim rollout tutorial](/nemo/gym/main/tutorials/evaluation-tutorials/nemo-user-sim-rollout-collection).

## Component ownership

* **Preparation** materializes one validation row per built-in probe before collection.
* The **rollout collector** loads a task and dispatches an episode request to the Environment Server.
* The **Environment Server** seeds sessions, owns the conversation runtime and tool loop, invokes participants
  and support models, requests verification, and returns the episode response.
* The **User Agent** produces simulated User messages through `user_model`.
* The **Assistant Agent** produces the evaluated Assistant messages and function calls through `policy_model`.
  To evaluate a different agent, point `assistant_agent` at an Agent Server that implements agent sessions and
  returns function calls without executing them; NeMo User Sim executes the tools.
* The **Resources Server** validates the resolved row, stores its session snapshot, evaluates the completed
  episode, and returns Gym's reward contract.
* The **support model** handles structured judge, summary, tool-simulation, evaluator, and probe-scorer requests.
  The Environment Server invokes support roles used during the conversation; the Resources Server invokes final
  evaluator and probe-scorer requests through its configured `probe_scorer_model`.

The Resources Server does not create a second conversation runtime and does not expose probe-tool routes.

## Prepared task contract

Preparation provides stable string `task_id` values and complete `resolved_row` objects. NeMo User Sim calls this
resolved row a materialized row; in Gym, a materialized row is the collector's `task_id` plus `task_input` record
in `rollouts_materialized_inputs.jsonl`. The following row is a
schematic with nested values elided; see `resources_servers/nemo_user_sim/data/example.jsonl` for complete rows:

```json
{
  "task_id": "<trajectory-id>",
  "resolved_row": {
    "persona": {"first_name": "...", "last_name": "..."},
    "probe_type": "general_open_ended",
    "conversation_language": "English",
    "trajectory_id": "<trajectory-id>",
    "usersim_config": {"...": "..."},
    "usersim_provenance": "{\"code_sha\":\"<pinned-revision>\",\"nemotron_personas_version\":\"0.0.2\",\"bank_version\":{}}"
  }
}
```

`usersim_provenance` is JSON text so empty nested values remain Arrow- and Parquet-safe.

A row can also carry an optional `role_request_params` object next to `resolved_row`. It maps a role (`user`,
`assistant`, `judge`, `summary`, or `tool_simulation`) to Responses API parameters that the Environment Server
uses as the base of that role's requests. The conversation input and NeMo User Sim's per-activation parameters
are applied on top.

At `/seed_session`, the Resources Server validates required fields, the configured NeMo User Sim revision, and
the Nemotron-Personas version (`"0.0.2"`, or `"synthetic"` for the committed example rows), and rejects guarded
health rows. It then stores the resolved row and its canonical SHA-256 digest. At `/verify`, it rejects mismatched
episode identity, task identity, resolved-row content, or trajectory identity.

The digest covers only `resolved_row`; task and episode identity are compared separately. It establishes that the
resolved row did not change between seeding and verification. It is not a comparison with a separately stored
preparation artifact.

## Episode execution

The Environment Server constructs one `ProbeEpisodeRuntime.from_resolved_row(...)` from the resolved row.
The runtime owns conversation state, probe state, tool validation and execution, semantic call indices, and
episode evidence.

For `tool_calling`, `safety_agentic`, and `financial_services`, the Assistant Agent returns function calls
without executing them. NeMo User Sim validates and executes accepted calls, appends tool messages, and requests
another Assistant activation when needed. Internal API-response synthesis uses `tool_simulation_model`.

Unexpected runtime exceptions become failures-sidecar records with an `agent` stage. Failures that NeMo User Sim
reports, and Assistant activation errors that the Environment Server classifies as Assistant mistakes
(`failure_class: assistant_activation_error`), appear under `usersim_result.simulation_outcome`.

## Model requirements and routing

`user_model`, `policy_model`, and `support_model` are separate Gym Model Server configurations. Their upstream
URLs can be shared, but every URL must implement an OpenAI-compatible Chat Completions API. `user_model_*` has no
default, so the simulated User never silently runs on the evaluated policy; `support_model_*` defaults to the
`policy_*` values.

The support endpoint must accept JSON Schema response formats because evaluator and scorer requests require
structured output. If it rejects the probe-scorer schema, verification is masked as `verifier_error`. If it
rejects the judge schema, NeMo User Sim returns no quality axes, and a completed scenario is masked as
`judge_failed`.

`financial_services` retrieval embeds queries through `embedding_model`. Its `embedding_model_base_url`,
`embedding_model_api_key`, and `embedding_model_name` settings default to the `support_model_*` values. Embedding
calls do not go through a Model Server: the Environment Server posts directly to
`<embedding_model_base_url>/embeddings` with that endpoint's API key. If the call fails, NeMo User Sim falls back to
lexical retrieval without failing the episode, so a chat-only support endpoint quietly degrades retrieval.

The semantic invocation roles are:

* `user`: simulated User participant.
* `assistant`: evaluated Assistant participant.
* `judge`: conversation-quality judge.
* `summary`: optional context summarization.
* `tool_simulation`: simulated tool-result generation.

## Verification and reward

The Resources Server calls NeMo User Sim's `TrajectoryEvaluatorGenerator.agenerate()` once, with the scorer
selected for the prepared probe when one applies.

`scenario_completed` requires:

1. a completed conversation;
2. both User and Assistant messages; and
3. a passing applicable probe scorer.

When `scenario_completed` is `true` and all required axes exist, `reward` is the mean of normalized helpfulness,
accuracy, and coherence. Otherwise, `reward` is `0.0`.

The verification response includes:

* `reward`: scalar Gym reward.
* `mask_sample`: whether aggregation must exclude the reward.
* `failure_kind` and `failure_reason`: normalized failure details.
* `reward_components`: flat completion flags and quality metrics for Gym aggregation.
* `scenario_completed`: whether the full scoring gate passed.
* `verifier_data`: structured NeMo User Sim evaluator and probe evidence.

The Environment Server copies `reward`, `mask_sample`, `failure_kind`, `failure_reason`, and `reward_components`
onto the top-level persisted rollout. The nested `verification` object retains the complete verifier response.

## Saved rollout fields

* `usersim_result.conversation_messages`: ordered User, Assistant, function-call, and tool-result messages.
* `usersim_result.simulation_outcome`: simulation status, attribution, detail, and warnings, reported by NeMo User
  Sim or, for Assistant activation errors, by the Environment Server.
* `invocations`: ordered participant and support activations made by the Environment Server.
* `verification.verifier_data.normalized_axis_scores`: full normalized NeMo User Sim quality map.
* `reward_components`: Gym's flat projection of quality metrics plus completion/scoring flags.
* `ng_model_call_capture`: provider-level calls captured through the User and Assistant Agents.
* `ng_trajectory`: Gym's normalized Agent execution record, including any reported gaps.
* `_ng_failure_*`: failure-sidecar fields for attempts without a completed episode response.

`reward_components` repeats quality axes with a `quality.` prefix so Gym can aggregate them. The structured
`normalized_axis_scores` map remains in verifier evidence for NeMo User Sim-specific inspection.

## Masking rules

* Assistant-attributed simulation failure: measured zero, `mask_sample: false`.
* Failed applicable probe check: measured zero, `mask_sample: false`.
* Simulation failure that NeMo User Sim attributes outside the Assistant: zero, `mask_sample: true`.
* Scorer/evaluator error or timeout: zero, `mask_sample: true`.
* Inconclusive scorer or missing required judge quality: zero, `mask_sample: true`.
* Resources Server session unknown, closed, or expired at verification: zero, `mask_sample: true`, with
  `failure_kind` `session_lost` or `session_expired`.

Infrastructure failures, such as transport errors, participant timeouts, session 404 and 409 responses, and 408, 425, 429,
and 5xx responses, produce no reward. They are written to `rollouts_failures.jsonl` without a scored row.

For commands and examples, see
[Troubleshoot NeMo User Sim Rollouts](/nemo/gym/main/tutorials/evaluation-tutorials/nemo-user-sim-rollout-collection/rollout-troubleshooting).