Repository navigation
design(environment): prototype environment authoring runtime - #3557
Closed
cwing-nvidia wants to merge 14 commits into
Closed
cwing-nvidia wants to merge 14 commits into
cwing-nvidia wants to merge 14 commits into
Conversation
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
This was referenced Sep 19, 2026
ananthsub
force-pushed
the
ananthsub/episode-orchestration-prototype
branch
12 times, most recently
from
September 22, 2026 16:28
4fadeae to
f20a6f1
Compare
cwing-nvidia
force-pushed
the
feat/gym-hello-world-runtime
branch
from
September 22, 2026 16:29
d0d51d5 to
1571cd8
Compare
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
Signed-off-by: Chris Wing <cwing@nvidia.com>
cwing-nvidia
force-pushed
the
feat/gym-hello-world-runtime
branch
from
September 22, 2026 16:30
1571cd8 to
7376f17
Compare
ananthsub
force-pushed
the
ananthsub/episode-orchestration-prototype
branch
2 times, most recently
from
September 22, 2026 17:37
4a79da8 to
ff5875d
Compare
cwing-nvidia
changed the base branch from
ananthsub/episode-orchestration-prototype
to
cwing/episode-orchestration-snapshot-f20a6f1
September 22, 2026 18:16
Signed-off-by: Chris Wing <cwing@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the runtime prototype for the environment-authoring design explored in #3469. Its purpose is to exercise the proposed contracts end to end and gather early feedback from environment authors and Gym maintainers before the public design and implementation are finalized.
The prototype makes
hello-world,hello-taskset, andhello-verifier-reusedirectly executable from a source checkout withgym eval run --environment .... Gym loadsenvironment.yaml, materializes its tasks, prepares the declared local Docker runtime, composes the existing server architecture, runs the selected agent, and dispatches the selected verifier.Scope and dependencies
This draft is based on the immutable
cwing/episode-orchestration-snapshot-f20a6f1branch, which pins validated commitf20a6f1fromananthsub/episode-orchestration-prototype. It depends on that unmerged Environment Server stack but is isolated from subsequent force-pushes to Ananth's working branch. This is an integration and design-feedback PR, not a merge-ready public feature.TaskIdcontract. Later upstream changes will be adopted explicitly rather than changing this PR's diff automatically.No issue is linked because this is a focused integration prototype supporting the design proposal in #3469.
Motivation
The broader authoring motivation is described in #3469: environment authors should be able to define the work, its runtime requirements, and what counts as success without first learning Gym's internal inference and server wiring.
This companion PR focuses on the runtime consequence of that proposal. A simpler authoring format improves the user experience only if authors can run it directly. Requiring them to also prepare Responses API JSONL, write a custom Resources Server, or maintain internal server-composition configuration would move the complexity rather than remove it.
Design under review
User-facing execution path
gym eval run --environment ...:environment.yaml.environment_serveroverride.Authors using this path are not required to maintain prepared Responses API JSONL, an environment-local
config.yaml, or aprepare.pyscript. Users who need exact control over already-materialized Responses API inputs can continue using Gym's existing dataset andsplitworkflow. The caller selects the agent and model; this prototype currently fixes execution to a local Docker sandbox.Tasksets use explicit
nameandpathfields. File paths select JSONL-backed collections; directory paths discoverchild directories containing task-local
task.yamlfiles. A taskset nameddefaultis selected when--tasksetisomitted.
Internal runtime boundaries
The following modules and generated configuration are implementation details for Gym runtime maintainers. A typical environment author should only need to define
environment.yamland its referenced task, runtime, and verifier files, then use the CLI; they should not need to import, configure, or understand these components.authoring.pyloads definitions and materializes typed tasks.environment_servers.pyresolves the Environment Server and its required agent roles.runtime_composition.pycombines the selected Environment Server and sandbox runtimes into temporary rollout input and server configuration.local_docker_image.pybuilds or reuses an OCI image; sandbox-provider selection remains independent.environment_adapterResources Server owns the standard sandbox, verification, and cleanup lifecycle.Gym generates
agent_bindingsto connect the caller-selected agent to the roles required by the Environment Server. This field is not part of the environment-authoring format.Advanced integrations can still provide a custom Resources Server for genuinely custom services, state, or lifecycle requirements. The design question is whether the reusable adapter hides the right runtime details for the standard authoring experience.
Prototype coverage
hello-worldexercises one instruction and one task-local verifier.hello-tasksetexercises JSONL materialization, instruction rendering, Pydantic task-data validation, and a shared verifier.hello-verifier-reuseexercises discovered directory tasks, task-local manifests, and per-task verifier selection.hello-mcp-toolremains authoring-only until managed MCP startup, routing, isolation, and cleanup are implemented.Prototype-only integration choices
The end-to-end path intentionally makes several choices that must be revisited before the runtime contract is stabilized:
rollout_inputbypasses the existing dataset andsplitpreparation path. It proves that materialized environment tasks can reach rollout collection, but it does not decide whether both mechanisms should remain separate public contracts.--environmentvalue and the defaultsingle_agentEnvironment Server are supported. Authors omitenvironment_server; explicit alternatives such as iterative proof refinement or framework adapters are not yet registered. The generated role-binding design has not been exercised with multi-agent Environment Servers.trusted_environment_code=true, imports verifier code into the Resources Server process, and keeps session state in one worker's memory. The trust, isolation, persistence, and multi-worker contracts are unresolved.hermes_agent/borrowed_sandbox_openai_compatible; Gym does not yet negotiate capabilities.resources_servers/causes Gym's legacy server validator to require five example inputs, rollouts, and metrics. Its tests pass; the validation command still exits nonzero after testing because this infrastructure adapter does not provide those benchmark artifacts. The prototype does not add fake artifacts solely to satisfy that mismatched contract.Feedback requested
For environment authors
environment.yamlenvironment?gym eval run --environment ...make the environment, taskset, agent, model, runtime-image preparation, and current local-Docker requirement clear?For Gym runtime maintainers
environment_adapterand a custom Resources Server correct?rollout_inputa reasonable prototype bridge for reaching rollout collection, and what should be reconciled with the existing dataset andsplitpath before the runtime contract is stabilized?agent_bindingsgeneralize beyond the default implementation?Validation
Runtime smoke evidence
environment.yaml, materialized the task, generated server composition, prepared the local Docker image, bound Hermes to the Environment Server's agent role, and invoked the task-local verifier. The task returned reward1.0with no episode failure.1.0with no episode failures.--taskset. The complete reusable verifier and task-local uppercase verifier each returned reward1.0with noepisode failures.
Local checks
gym env test +entrypoint=resources_servers/environment_adapter +should_validate_data=truethen exits nonzero in legacy data validation because the generic adapter has no fixed five-row dataset artifacts, as described above.git diff --checkpass.pre-commit run --all-fileshas not been rerun after rebasing onto the rewritten prototype base.Compatibility
This is an additive design prototype on an unmerged base branch. It does not migrate existing datasets or Resources Servers, and its contracts should not yet be treated as stable public APIs.
The prototype-only choices above, public contract documentation, production error handling, integration coverage, and full CI must be resolved before this path is presented as shipped functionality.