Skip to content

Modernize tutorial for async EnvClient API#897

Open
vedthebear wants to merge 1 commit into
huggingface:mainfrom
vedthebear:modernize-tutorial-async-envclient
Open

Modernize tutorial for async EnvClient API#897
vedthebear wants to merge 1 commit into
huggingface:mainfrom
vedthebear:modernize-tutorial-async-envclient

Conversation

@vedthebear

Copy link
Copy Markdown

Summary

The tutorial/ content had drifted from the current OpenEnv API — it referenced the removed HTTPEnvClient and a synchronous HTTP POST/GET client. This PR updates the tutorial (notebook + markdown) to match how OpenEnv actually works today.

  • Client: HTTPEnvClient[Act, Obs] -> async EnvClient[Act, Obs, State] with all three hooks (_step_payload, _parse_result, _parse_state).
  • Calls: sync env.reset() -> await env.reset() in the notebook (Jupyter top-level await), with a note on asyncio.run(...) and the .sync() wrapper. Docs/notebooks that run inside synchronous training loops (unsloth_2048, 04-training, 03-scaling) use the .sync() wrapper since GRPOTrainer calls the rollout function synchronously.
  • Transport wording: HTTP POST/GET -> the persistent WebSocket session the client actually uses. (The genuinely-HTTP endpoint table in 02-deployment.md is left intact — those endpoints do exist in simulation mode.)
  • Server: create_fastapi_app(instance) -> create_app(EnvClass, Action, Observation, env_name=...) (factory + type contracts).
  • Models: dataclasses -> Pydantic models that only add fields on top of the Observation/State bases; field reflection switched from dataclasses.fields() to .model_fields.
  • Imports: from core.* / core.types -> openenv.core.* / openenv.core.client_types.
  • Cleared stale notebook outputs (including a broken sync traceback).

Test plan

  • OpenEnv_Tutorial.ipynb and unsloth_2048.ipynb are valid JSON.
  • OpenEnv_Tutorial.ipynb runs top-to-bottom via nbconvert --execute against a live OpenSpiel server — 0 error outputs, real Catch episode + 50-episode policy showdown complete.
  • All tutorial imports resolve in the project venv; confirmed EnvClient.reset is a coroutine and .sync() exists.
  • Part 10 illustrative snippets parse as valid Python.
  • No stale API references remain (HTTPEnvClient, http_env_client, create_fastapi_app, core.types).
  • Only .md / .ipynb changed — no Python sources touched.

Made with Cursor

The tutorial referenced the removed HTTP-based `HTTPEnvClient` and a synchronous
HTTP POST/GET transport. Update everything to the current API so the tutorial
matches how OpenEnv works today.

- Client: `HTTPEnvClient[Act, Obs]` -> async `EnvClient[Act, Obs, State]` with all
  three hooks (`_step_payload`, `_parse_result`, `_parse_state`).
- Transport: HTTP POST/GET wording -> WebSocket (client speaks the OpenEnv
  protocol over a persistent WebSocket session).
- Server: `create_fastapi_app(instance)` -> `create_app(EnvClass, Action, Observation, env_name=...)`.
- Models: dataclasses -> Pydantic models that only add fields on top of the
  Observation/State bases.
- Imports: `from core.*` / `core.types` -> `openenv.core.*` / `openenv.core.client_types`.
- Notebook uses top-level `await` (Jupyter) with a note on `asyncio.run` / `.sync()`;
  unsloth_2048 and the TextArena training doc use the synchronous `.sync()` wrapper
  since GRPOTrainer calls the rollout function synchronously.
- Cleared stale notebook outputs (including a broken sync traceback).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants