Skip to content

docs: README quickstart crashes on copy-paste (missing import asyncio) and tutorial list is out of sync #11

Description

@Koukyosyumei

Problem

Two small but user-facing problems in README.md:

1. The quickstart snippet doesn't run as written.

The code block in section 2. Quickstart (README.md, lines ~48–72) starts with only:

from h5i.orchestra import Conductor

but then uses asyncio.gather(...) and asyncio.run(main(...)). Copy-pasting it into ensemble.py and running python ensemble.py — exactly what the README tells you to do — fails immediately with:

NameError: name 'asyncio' is not defined

This is the very first code a new user runs, so it's worth getting right.

2. The tutorial list in section 3. Examples is out of sync with examples/tutorial/.

The directory contains 9 scripts, but the README lists only 7:

  • pipeline_score.py is missing from the list.
  • quorum_ensemble.py is missing from the list.
  • The entry for debate_then_build.py says "architect-to-implementer pipelines" — but that's actually what pipeline_score.py does (see its docstring: "architect designs, implementer builds, hardener tests"). debate_then_build.py is about settling a design question via debate before building.

Suggested fix

  • Add import asyncio to the quickstart code block.
  • Add pipeline_score.py and quorum_ensemble.py to the section-3 list, with one-line descriptions taken from their header docstrings.
  • Correct the debate_then_build.py description (debate to settle a design question, then build).
  • Bonus: examples/README.md also omits quorum_ensemble.py from its run list and tables — add it there too.

Docs-only change, no code knowledge required beyond reading the example docstrings. A great first contribution.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions