Rewrite the README in plain English - #14
Merged
Merged
Conversation
The README mixed three readers (a new user, a user tuning policy, a contributor) and used long sentences and shifting terms, so a first read was hard. It now follows the heading order and glossary that every guideme SDK shares, in short sentences with one word per meaning, and lists the TypeScript SDK under Other SDKs. Design rationale and measurements leave the README for docs/design.md, where most of them already lived; the one missing reason (why Client sits in guideme.api.client) is added there. The sdist test note moves to CONTRIBUTING.md, whose tier list also drops guideme.question.Question, which AGENTS.md moved to the top list. docs/contract.md points at the section that now carries the timeout divergence. Code blocks are unchanged, so tests/typing/readme.py still mirrors the first example.
The review found places where a first read still stalled. The quick start used ticket, noul and the fallback before saying what they are, and it did not say that levels are ordered by declaration. Some terms drifted, and the ConfigError and TransportError rows missed cases. The quick start now defines the state, the three constructors, the level order and "unsure". The policy layers list the setter for each kind of question again. The score value states its scale from the TypeSafe API docs. The base_url row says that guideme follows redirects. Typing notes move under Lower layers, and so does the Thresholds sentence. Testing points to the retry rules in place of repeating them. The contributor lines on spec vendoring leave Other SDKs, and same-topic paragraphs merge. No code block changes, so tests/typing/readme.py still mirrors the README.
pedro-pscunha
added a commit
that referenced
this pull request
Sep 22, 2026
PyPI shows the README as the package's description, and it only changes when a version is uploaded, so the rewrite in #14 is not what a PyPI reader sees until a release carries it. This bumps the version in pyproject.toml and both lock files, and moves the Unreleased notes under 0.2.1. There is no code, contract or spec/ change.
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
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.
What changed
The README is rewritten in plain English (the
simple-englishskill, pragmatic mode). It nowfollows the heading order and the glossary that the three guideme SDKs share: one word for one
meaning ("question", "answer", "option", "level", "rubric", "unsure", "setting", "state"), short
sentences, no semicolons outside the rendered rubric, and conditions before commands.
New heading order: Install, Quick start, Questions, When the model is not sure, Examples and
counterexamples, Several questions in one request, The receipt, Errors, Retries and timeouts,
Testing your code, Observability, Configuration, Sync and async, Lower layers, Other SDKs,
Development, License.
tests/typing/readme.pystill mirrors the first exampleand the other blocks it copies.
guideme.__all__is still inside code (tests/test_surface.py).guideme.api,guideme.api.client,guideme.policy)."
@guideme/sdk(not yet on npm)".What moved where
timeout, and the two
Usageclasses: already indocs/design.md. The README links them.Clientsits inguideme.api.client: new bullet indocs/design.md, Sharp edges.CONTRIBUTING.md, The loop.AGENTS.md.Other files
CONTRIBUTING.md: the tier list dropsguideme.question.Question, whichAGENTS.mdmovedto the top-level list, and names
guideme.api.client.docs/contract.md: one reference renamed. The timeout divergence is now in the README'sRetries and timeouts section. No new prose.
CHANGELOG.md: anUnreleased→ Documentation note. No version bump. The PyPI 0.2.0 pagekeeps the old README until the next release.
Length
README: 568 lines before, 503 after the review fixes. Code blocks: 127 lines before, 121 after.
The shared target was "at most about 320". The review accepted about 470 as the honest length
of one file, because the code blocks are tied to the typing mirror and the rubric contract.
How I verified it
src/guideme/**: builder defaults and refusals(
guide.py), retry and resend rules (api/client.py), rubric rules (enums.py,question.py), state serialization (_json.py), receipt and error fields.docs/line, or a reason it was dropped. Three rows are dropped, all framing text with no user fact.
rg -n -i readmeover the repository: every hit that names a heading or a block was checked,and
docs/contract.mdwas updated.mise run check: ruff, pyright (0 errors), pylint (10.00),pytest (230 passed), build and audit.
Review fixes (second commit)
An opus review found 0 Critical, 4 Major and 17 Minor items. All are applied:
valuestates its scale, from the TypeSafe API docs.base_urlrow says that guideme follows redirects.TransportErrorandConfigErrorcases.