feat(eval): export Gym trajectories as ATIF

[afourniernv]

What does this PR do?

Adds a strict offline exporter from completed Gym ng_trajectory v1.0 rollouts to ATIF v1.7. It writes one ATIF file per rollout plus a SHA-256-pinned manifest that Gym's ATIF reverification path can consume.

Together, #2737 and #2767 establish a file-based interoperability path between NeMo Relay and NeMo Gym. Relay-exported ATIF trajectories can be evaluated in Gym, while Gym-native trajectories can be exported to the same ATIF format for downstream consumers. This does not couple the Relay and Gym runtimes or add Relay as a Gym dependency.

This is PR 2 of a two-PR sequence. #2737 owns ATIF ingress and the shared ATIF schema/JSON boundary; this PR owns Gym-to-ATIF egress. Related to #2468.

Before

Gym could store normalized rollout trajectories but could not export them in a portable trajectory format.

After

gym eval export \
  --format atif \
  --rollouts results/rollouts.jsonl \
  --output-dir results/atif \
  --session-id eval-2026-08-25 \
  --agent-version 1.2.3

The exporter maps Gym's normalized trajectory, not provider-native payloads. Raw provider request and response copies are retained opaquely in ATIF extension metadata; they are never parsed to fill gaps in the normalized record.

Initial contract

Supported:

• one completed root invocation and one initial system/user phase;
• exactly one captured model call per agent turn;
• text, reasoning, generic function calls, and correlated text results;
• normalized turn/model/token/timing/status evidence; and
• task/rollout identity plus a hash-pinned manifest.

Rejected rather than guessed or dropped:

• evidence gaps, subagents, later user/system turns, and multimodal content;
• incomplete, failed, or ambiguously correlated model/tool calls;
• unsupported Responses item families or namespaced calls;
• training token IDs, log probabilities, and routed-expert metadata; and
• non-standard JSON.

The exporter writes each known per-step usage field without inventing missing values. reasoning_tokens and total_tokens use the same step-level ATIF extension shape as Relay. A final prompt-, completion-, or cached-token aggregate is emitted only when every captured model call reports that field; an unavailable value is never counted as zero.

An export with partial usage can therefore be valid ATIF for another consumer while remaining ineligible for Gym's strict reverify path. Gym reverify requires complete per-step prompt/completion counts whenever supported usage exists because one verifier request cannot represent partial standard usage. This asymmetry is deliberate.

The exported extra.nemo_gym.conversion.status=complete means every field present in the supported normalized ng_trajectory profile was represented without guessing. It does not certify opaque provider request or response copies retained as provenance.

Out of scope

No ATOF parsing, Relay/NAT dependency, live instrumentation, provider-payload reconstruction, or best-effort export of unsupported structural or content fields is included. Preserving known step-level usage while omitting an unprovable aggregate is exact representation, not best-effort conversion.

Review order

This is the egress follow-on to #2737 and can be read while that PR is open. After #2737 lands, main will be merged into this branch again and the shared ATIF boundary will be reconciled. atif_v1_7.py should then leave this diff after preserving #2737's final_metrics.total_steps validation. atif_json.py will retain the small strict JSON equality helper used by the exporter, so reviewers should inspect that egress-specific delta rather than assume every shared-file change disappears.

Review area	Files	What to verify
Export contract	nemo_gym/atif_export.py	Exact normalized-trajectory mapping, rejection boundaries, batch atomicity, and manifest hashes
Shared boundary delta	nemo_gym/atif_json.py	Strict JSON equality used by export validation
Wiring	nemo_gym/cli/eval.py, nemo_gym/cli/main.py, docs	One-command offline export and documented scope
Evidence	tests/unit_tests/test_atif_export.py, CLI tests	Contract, failure, hash, and round-trip coverage

Suggested pass: review the exporter first, then its small shared-boundary delta and wiring. The test file is intentionally large because unsupported shapes fail closed.

Validation

• Focused exporter, rollout-reverification, and CLI suites: 499 passed, including 179 exporter contract cases.
• Changed-file pre-commit and git diff --check: passed.
• The exact cross-PR test passed from Gym ng_trajectory through this exporter and feat(eval): reverify Relay ATIF trajectories #2737's importer.
• Manifest SHA verification succeeded, tampering was rejected, parallel tool results were correlated by call ID rather than arrival order, usage survived, and native versus round-tripped MCQA verification both returned reward 1.0.

The broader local unit run reported the same five non-ATIF failures listed on #2737. The affected exporter, importer, rollout, and CLI suites pass.

The earlier Codex → Relay → ATIF → Gym live qualification remains evidence for #2737; this offline exporter PR does not claim another provider run.

Checklist

• I have read the contributing guidelines.
• Tests were added and pass locally.
• Commits have DCO sign-off.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-feat-atif-export.docs.buildwithfern.com/nemo/gym

Here are the markdown pages you've updated:

• nemo/gym/reference/cli-commands
• nemo/gym/reference/trajectory-capabilities

[afourniernv]

Review cleanup and the completed hardening commits are now pushed through ce3a7d2. This PR remains draft.

Suggested review order after #2737:

1. atif_provider_reconciliation.py: provider identity, termination, usage, and output fidelity.
2. atif_export.py: Gym trajectory to ATIF conversion and atomic output.
3. CLI registration and docs.
4. Provider tests, now colocated and parameterized separately from exporter orchestration tests.

No supported behavior was removed. The shared ATIF schema and strict JSON helpers now match #2737 exactly. The PR is 193 lines smaller overall.

Validation on the exact pushed tree: 2,875 unit tests passed, 2 skipped, 336 deselected, 15 subtests passed; 666 focused tests passed; all pre-commit hooks passed; and the real Gym trajectory to ATIF to Gym verifier-payload round trip passed.

[afourniernv]

The latest egress hardening is pushed in 16bd3a4, and the PR description now records the current usage contract and round-trip evidence.

• Focused exporter, rollout-reverification, and CLI suites: 499 passed, including 179 exporter contract cases.
• Changed-file pre-commit and git diff --check: passed.
• Exact-head DCO, lint, docs collection, copyright, and secret-scanning checks are green.

This PR remains draft until #2737 lands. After that, main should be merged into this branch so the shared ATIF files leave the review diff.

[afourniernv]

Review-order note: this PR currently duplicates atif_v1_7.py and atif_json.py from #2737, so the shared boundary makes the diff harder to review while #2737 is still open. After #2737 lands, I will merge current main into this branch and reconcile those shared files so this PR's remaining diff is focused on Gym-to-ATIF export, CLI wiring, documentation, and its tests.

[mlazuka]

I don't think there's any test here or in #2737 that tests the combination of both PRs (eg feeds an exporter-produced file through the reverify projection logic). It's hard to test while the 2 PRs are separate branches, but I think this should be added once the first one is merged in before merging the other one

[afourniernv]

Agreed. I am keeping this as a merge-order gate rather than copying the ingress implementation into this sibling branch. After #2737 lands, I will merge main into #2767, retain the canonical shared modules, and add one exporter-output to manifest-load to reverify-projection test before #2767 merges.