Skip to content

Modernize tutorial for async EnvClient API#897

Merged
burtenshaw merged 5 commits into
huggingface:mainfrom
vedthebear:modernize-tutorial-async-envclient
Jul 3, 2026
Merged

Modernize tutorial for async EnvClient API#897
burtenshaw merged 5 commits into
huggingface:mainfrom
vedthebear:modernize-tutorial-async-envclient

Conversation

@vedthebear

Copy link
Copy Markdown
Contributor

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

ved and others added 2 commits July 1, 2026 12:07
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).
@burtenshaw

Copy link
Copy Markdown
Collaborator

cursor review

@burtenshaw burtenshaw requested review from burtenshaw and init27 July 2, 2026 11:11
@bot-ci-comment

bot-ci-comment Bot commented Jul 2, 2026

Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit 4a5d3cf. Configure here.

@burtenshaw

Copy link
Copy Markdown
Collaborator

Updated this PR to stop using .sync() in the tutorial snippets where auto-sync now makes it unnecessary.

Changes:

  • plain sync examples now use direct EnvClient context/calls instead of .sync()
  • notebook guidance now says notebooks can await, while plain scripts block automatically
  • GRPO tutorial/notebook setup now passes the client directly and notes that sync rollout code blocks automatically

Validation: git diff --check passed, and both edited notebooks parse as valid JSON.

@burtenshaw burtenshaw left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed docs/tutorial async client update; CI is green.

@burtenshaw burtenshaw merged commit cd37686 into huggingface:main Jul 3, 2026
7 checks passed
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.

3 participants