docs: rewrite README for a human reader - #78
Merged
Conversation
The README opened with a fifteen-line callout that spent most of its words describing openadapt-flow, so anyone who arrived for the training code read two paragraphs about a demonstration compiler first. That point is true and worth keeping, but it is one sentence, not a wall. Three documented APIs did not exist. Checked against openadapt-ml 0.16.3 installed from PyPI into a clean venv: - `AgentPolicy.predict(sample)` is not a method. The real one is `predict_action_from_sample(sample)`, and it returns a 4-tuple of `(Action, thought, state, raw_text)` rather than an object with `.action` and `.thought` attributes. - `QwenVLAdapter(model_name=...)` does not load a model. The constructor takes an already-loaded model and processor; the loading path is `QwenVLAdapter.from_pretrained(model_name)`. - The smoke test cannot run on the core install. `DummyAdapter` raises `ImportError: torch is required` unless the `training` extra is present. Every example is now a command or a snippet that was executed against that venv, shown with its real output. The benchmark table gains back the episode success column, which is 0% for all four configurations and was the most important number missing from the page. The architecture tree and the ecosystem table move to docs/repo_layout.md. Nothing was deleted. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
AGENTS.md requires a public repo outside the seven product targets to carry a lifecycle state, and records an incident where deleting this banner cost four repos of wasted agent effort. The rewrite removed it. Put it back above the badges. The Set-of-Marks paragraph introduced a login result and then cited registration_som_eval.json. That artifact is the registration scenario: 384 steps over 32 episodes is 12 steps each, and synthetic.py documents registration as 12 steps and 6 elements. Name the scenario and correct three elements to six. The n=4 hardened re-runs are under 8b_hero/eval/, not 2b_dev/eval/, whose two files are both n=32. There is no Azure trainer. cloud/ has train subcommands for lambda_labs, modal_cloud, vast_ai, and local; azure_inference.py is an async inference queue. Drop Azure from the training list and say what it is. The Action line cut 16 of 19 fields with no ellipsis, so it read as though Action has three. Mark the cut and give the count. Training reads --config paths relative to the checkout, and tool.uv.sources points openadapt-capture at ../openadapt-capture, so a fresh clone needs UV_NO_SOURCES=1, which is what test.yml sets. Give the clone and the flag.
Same correction as the README. cloud/ has train subcommands for lambda_labs, modal_cloud, vast_ai, and local; azure_inference.py is an inference queue.
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
1 participant
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.
The old README opened with a fifteen-line callout, and most of its words described a different package. Someone who arrived for the training code read two paragraphs about a demonstration compiler before reaching anything they could run. That "this is research, you do not need it" point is true and it stays. It is one sentence now.
Three documented APIs did not exist
I installed
openadapt-ml==0.16.3from PyPI into a clean venv and ran every command and snippet against that, not against the source tree.AgentPolicy.predict(sample)is not a method. The real one ispredict_action_from_sample(sample), and it returns a 4-tuple of(Action, thought, state, raw_text), not an object with.actionand.thought.QwenVLAdapter(model_name=...)does not load a model. The constructor wants an already-loaded model and processor. Loading goes throughQwenVLAdapter.from_pretrained(model_name).DummyAdapterraisesImportError: torch is required for DummyAdapterunless you have thetrainingextra.Every example on the page now shows its real output.
The benchmark table gets its worst column back
The old table showed action accuracy, coordinate error, and click hit rate. It left out episode success, which is 0% for all four configurations. Fine-tuning moves per-step accuracy and it moves click precision, and neither got any model through a six-step login. That belongs on the page. The Set-of-Marks result that does finish episodes is there too, pointing at the retained artifact behind it.
What moved
docs/repo_layout.mdis new and holds the architecture tree, the per-area descriptions, and the neighbouring-packages table. Nothing was deleted.One thing I could not resolve
The coordinate-mode table cites
docs/qwen_login_experiment.md(December 2025). The hardened re-run JSONs underexperiments/qwen_login/2b_dev/eval/report different figures for the same two fine-tuned models, on n=32 and n=4. I kept the doc's numbers, cited the doc and its date, and said plainly on the page that the later re-runs disagree. Worth someone deciding which set is canonical.There is no committed artifact anywhere in the repo for the Claude Sonnet 4.5 and GPT-5.1 rows beyond that same doc.
README: 318 lines to 195.