refactor(evaluator)!: rename env_overrides to hydra_params, add env_vars

[SandyChapman]

Summary

env_overrides reads as "environment variables" to everyone who meets it, and it isn't — the "env" is Gym's environment (the resources-server), and the values become Hydra config overrides ({'a': {'b': 1}} → ++a.b=1). Renamed to hydra_params, which says what it does.

That frees the name for the thing people assumed it was. Some Gym environments are configurable only through the OS environment: wmt_translation reads WMT_TRANSLATION_COMET_PY_CACHE for its model-cache root and otherwise defaults to /opt/Gym/.cache/comet-python, a path that exists only inside NVIDIA's container image — so anywhere else it dies with PermissionError: /opt/Gym before the GPU requirement is even reached. Until now the only way to set that was to export it before invoking the runner, which turns a property of the environment into a property of whoever launched the run. A job spec executed elsewhere has no ambient environment to inherit from at all. New env_vars field carries it in the config instead.

Related Issue

Tracked in Linear as AALGO-485. No GitHub issue.

Stacked on #1295 — both change the same regions of gym_runtime.py, so basing on main would guarantee a conflict. Review #1295 first; once it merges, this diff collapses to just this commit.

Changes

• env_overrides → hydra_params on GymRuntimeConfig and the Gym runner-target job spec, plus _redact_env_overrides → _redact_hydra_params (leaving the old name on the helper would defeat the point). Descriptions now say explicitly that the two fields are different things.
• New env_vars: dict[str, str] on both, merged into the environment the gym CLI is invoked with.
• _gym_invocation_env(config) extracted so the precedence is assertable without starting Ray: process environment → RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 → env_vars.
• env_vars redacted in RunnerInfo.config on the same rules as hydra_params.
• Plugin spec regenerated — make refresh-openapi, verified idempotent.

Design calls

• env_vars outranks the Ray default. That setting exists to make Gym work, not as an invariant; someone debugging Ray's uv hook needs a way to restore it. Explicit config beats a built-in default.
• Redaction reuses hydra_params' markers rather than a new list. Verified against real names: OPENAI_API_KEY, HF_TOKEN, AWS_SECRET_ACCESS_KEY and DB_PASSWORD all redact; WMT_TRANSLATION_COMET_PY_CACHE and HTTPS_PROXY stay verbatim. env_vars needs this more than hydra_params does — an environment variable is the conventional way to hand a process an API key, so a caller doing the obvious thing would otherwise write one into the run bundle.
• Clean rename, no deprecated alias. The field landed in main one day ago (feat(evaluator): add GymRunnerTarget plugin wiring and Studio rendering #1257), nothing in web/ references it, and it is absent from the generated Python SDK. Adoption is as close to zero as it will ever be; an alias now would be permanent cost for a day-old field.
• Left alone: the unrelated env_overrides in services/rl and services/core/auth. Different concepts that happen to share a name — and the auth one is genuinely Mapping[str, str] of OS environment variables, which is its own small argument that the old name misleads.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with documentation updates
• Documentation only
• Contributor tooling or automation
• CI, build, or test infrastructure

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Documentation updated for user-visible behavior
• Documentation not applicable — justification: the fields are documented in their own Field(description=...), which is what surfaces in the OpenAPI spec and is regenerated here. examples/gym/README.md is updated for the rename. No Fern page documents the Gym runner target.

Verification

• Pull request title follows the repository's Conventional Commit format
• Every commit includes an appropriate Signed-off-by: trailer
• uv run pre-commit run -a passes, or any blocked checks are identified below
• Targeted tests pass, or tests are marked not applicable above
• No secrets, API keys, or credentials are included

Targeted validation:

Command	Result
pytest packages/nemo_evaluator_sdk/tests -q	1586 passed, 10 skipped
pytest plugins/nemo-evaluator/tests --ignore=…/integration -q	813 passed
uv run ruff check	All checks passed
uv run ruff format --check	350 files already formatted
tools/lint/lint-python-types.sh	exit 0
make refresh-openapi	regenerated; byte-identical on a second run
make vendor	mirror in sync; byte-identical on a second run

Run on Python 3.12, matching make toolchain-versions. See the note below on why that matters.

On make update-sdk — run, and deliberately reverted

I ran it. The Stainless half succeeded but produced nothing for this change, and I reverted what it did produce:

• The root openapi/openapi.yaml — the spec Stainless consumes — is unchanged by this work, and contains zero references to the Gym runner target (hydra_params, env_overrides, resources_server). That target lives only in plugins/nemo-evaluator/openapi/openapi.yaml, which is not Stainless's input. The generated Python SDK never exposed these fields, so renaming them cannot affect it. make refresh-openapi alone was the whole job.
• What it did change was unrelated: access_keys.py, its types __init__, and its tests — the committed SDK no longer matches what Stainless generates from the current spec. The regenerated list() drops the page / page_size docstring params and rewrites the query transform, which looks like a regression rather than cosmetic drift. Reverted here; it deserves its own investigation rather than riding along invisibly in a rename.
• make update-web-sdk failed outright: tsx: command not found, node_modules missing, because this worktree has never run pnpm install in web/. Not run, since per the above there was nothing of this change to generate. Worth knowing that make update-sdk piped through tail reports exit 0 even when this step fails.

Blocked checks (host toolchain, not this change)

Hook	Failure	Why it is not this change
uv-lock	requires uv 0.9.14, host has 0.9.30	diff touches no pyproject.toml/uv.lock; uv-lock-check, which catches real drift, passes
studio-lint-staged	mise ERROR No version is set for shim: pnpm	diff touches no web/ files
Helm Docs	helm-docs container unavailable locally	diff touches no Helm chart

Unrelated finding, filed separately

test_harbor_runtime.py::test_symlink_loop_degrades_the_stamp_instead_of_killing_the_run fails on Python 3.13 and passes on 3.12. Its premise asserts Path.resolve() raises RuntimeError for a symlink loop, which is 3.12 behaviour; on 3.13 it raises nothing. It surfaced because a fresh worktree's venv resolved 3.13.12 — requires-python = ">=3.12,<3.15" permits it even though make toolchain-versions reports 3.12. Nothing to do with this change, but it means the package claims support for a version at least one test does not hold on.

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	33501/42238	79.3%	64.3%
Integration Tests	19542/40037	48.8%	21.0%