miniopenenv

tour/README.md → html

tour/ — the protocol, hand-written, from both chairs

make lines-tour

Three programs, one counter environment. Two are servers — 01_minimal.c with the protocol hand-written as string literals, 02_conformant.c with the library — and their five server frames are byte-for-byte identical on the wire. The third, 03_client.c, is the client that drives the same environment to done, hand-written the same way. Those comparisons are the sharpest thing this repository has, and these files exist so that they are a measurement rather than a paragraph.

FileWhat it isStatements
01_minimal.cthe SERVER protocol, hand-written as string literals. Uses src/wire/ and nothing from src/proto/64 of protocol + 177 of socket
03_client.cthe CLIENT protocol, hand-written the same way — the twenty 8.B MUSTs, src/wire/ only73 of protocol + 391 of socket
02_conformant.cthe same environment, written with the library the way you would ship it77, whole file
$ make lines-tour
  of which: THE PROTOCOL         64
  of which: the socket          177
  of which: neither half         13
  the Python: PROTOCOL           78
  the Python: the socket         0*
  03_client: THE PROTOCOL        73
  03_client: the socket         391
  03_client: neither half        20
  02_conformant: WHOLE FILE      77

Statements only — comments and blank lines are excluded from every row, because comment density is not the comparison. The third row is the arithmetic closing: twelve #includes and one #define fall outside both fences, so 64 + 177 is not the file's 254 and this says where the other thirteen went. A * means recorded, not measured — the Python rows are computed only when the reference checkout is present, which on a fresh clone it is not.


§ 1 · 01_minimal.c — the whole protocol, and the comparison it exists for

01_minimal.c — the whole protocol, and the comparison it exists for

64 lines of C against 78 lines of Python.

The Python is tests/test_core/aca_integration_server.py in the reference implementation — 109 lines total, 78 of protocol, zero of socket, because uvicorn is its other 177. It is not copied here; nothing of the reference is. To read the two side by side:

git clone https://github.com/huggingface/OpenEnv
$EDITOR OpenEnv/tests/test_core/aca_integration_server.py

That file matters because its own docstring says it "implements exactly what GenericEnvClient (simulation mode) needs" — and it is enough for the genuine upstream client to complete a full episode. It is the reference project's own admission of how small the protocol is. It is just hard to notice from inside 164,000 lines.

01_minimal.c is two programs with a fence between them, and make lines measures both halves. Read the count before you read the code. Comparing the file's 466 lines of C against 109 lines of Python and concluding that C is verbose is the exact mistake the fence exists to prevent. Most of those lines are the teaching comment, and 254 of them are statements.

It uses src/wire/ and nothing from src/proto/. So when the genuine Python EnvClient completes an episode against it, what is proved is that the protocol is small — not that our SDK is good. Those are different claims and this repository is careful about which one it is making.

It is not hardened, and says so in a mandatory banner

It validates no message, checks no envelope, and serves one connection at a time. Its only limits are its own: a 64 KiB input buffer and a one-second linger, plus OE_HANDSHAKE_TIMEOUT_MS so a silent peer cannot hold it forever. Every other refusal it makes, src/wire/ makes on its behalf.

It binds 127.0.0.1. The library binds 0.0.0.0, because that is the container contract and this is not the library. Nothing from tour/ is installed by make install, and the packaging test asserts it.

Then the tour points at src/wire/limits.h: here is the 64 lines of protocol, and here are the 200 lines of paranoia that stand between it and the internet.


§ 2 · 02_conformant.c — the same thing with the protocol factored out

02_conformant.c — the same thing with the protocol factored out

Same counter. The action's amount accumulates, the episode is done at three, and the reward is the running total as a float. Drive both programs through the same episode and the server frames are byte for byte identical:

$ ./build/rel/bin/01_minimal    --port 8948 &
$ ./build/rel/bin/02_conformant --port 8947 &
$ for p in 8948 8947; do ./build/rel/bin/oe_probe http://127.0.0.1:$p \
    --episode --steps 3 --action '{"amount":1,"note":"step"}' \
    | grep '^<< {' > /tmp/frames.$p; done
$ diff /tmp/frames.8948 /tmp/frames.8947 && echo IDENTICAL
IDENTICAL

Five frames each. Nothing about the protocol changed between the two files. What changed is who writes the bytes.

Note what the number does not say

77 is more than the 64 statements of hand-written protocol in 01_minimal.c.

A library does not make the two-endpoint case smaller. It makes the other fourteen routes free: 02_conformant.c serves sixteen routes instead of two, eight concurrent sessions instead of one, and has no socket half to fence off at all. Every one of its 77 statements is the environment — the state, the two shapes, the three callbacks, the arithmetic — and not one of them is transport.

That is why the README prints 01_minimal.c beside the Python and not envs/echo.c. Printing the 45-statement echo.c against the 78-line Python file would be a category error. The Python file contains the protocol; echo.c delegates it to 3,900 lines of ours. The comparison silently swaps "the protocol is small" for "our API is small" — the exact conflation this project exists to end.


§ 3 · 03_client.c — the other chair, and the twenty client MUSTs made small

03_client.c — the other chair, and the twenty client MUSTs made small

01_minimal.c measures the protocol from the SERVER chair. 03_client.c measures it from the CLIENT chair. It is the client half of the protocol — docs/PROTOCOL.md's twenty 8.B MUSTs — hand-written with src/wire/ and nothing from src/proto/ or src/client/, fenced the same way so the count is a measurement. 73 statements of client protocol, against 01_minimal.c's 64 of server protocol: both small, both under a hundred, both the whole of one chair.

Its socket half — 391 statements of socket — is larger than 01_minimal.c's 177, and that is a fact about the two roles, not about the code. A client initiates: it parses a URL, polls GET /health over HTTP, and drives the RFC 6455 handshake. A server binds a port and answers. The transport a client pays for is the price of no websockets library, exactly as 01_minimal.c's 177 is the price of no uvicorn.

Two proofs it is the real protocol and not a mirror, both in tools/interop.sh and graded by a peer we did not write:

$ ./build/rel/bin/03_client http://127.0.0.1:8000
  reset   -> {"type":"reset","data":{}}
  step 1   <- reward 1      (float) done=false
  step 2   <- reward 2      (float) done=false
  step 3   <- reward 3      (float) done=true
  done after 3 steps.

§ 4 · Where these three sit on the tour

Where these three sit on the tour

Steps 2, 8 and 8c of ../docs/TOUR.md. 01_minimal.c is step 2 (the server, hand-written); 02_conformant.c is step 8 (the same server with the library); 03_client.c is step 8c, beside src/proto/client_codec.c (step 8b, the client codec) — where a reader first meets the client. Steps 1–7 are the complete answer to "what is OpenEnv"; the 8-series is where this library, and the client that drives it, come in.

§ 5 · See also

See also