Wordle (and friends)

Little Python tools for Wordle, Nerdle, and Quordle: they suggest guesses, cross off words that don’t fit what you typed in, and lean on pre-baked CSV caches so you’re not recomputing everything every time. Word lists and those cache files sit in data/.

What’s here

Thing	What it does
run.py	The main loop: it picks a word, you punch in the score pattern, repeat until you’re down to one answer.
calculate_all_scores.py	Regenerates the cache CSVs (distributions, first-word scores, best-next-word tables) for Wordle or Nerdle. Slow-ish; you don’t need to run it often.
distribution.py	Plays out every answer against the cached strategy and prints how many guesses it took (handy sanity check).
src/	Models (Word, GuessWord, colours), game modes (Basic, Quordle), cache builders.
data/<game>/	possible_words.txt, allowed_words.txt, plus the generated *.csv files.

Quordle is basically four Basic games stapled together (src/game/quordle.py). There’s also a data/hard_mode/ folder for a different word list—it isn’t wired into the default configs in src/config.py, it’s just there if you hook it up.

Setup

You’ll want Python 3.10+ (3.12 works great). Code pulls in rich, tqdm, and skye_comlib (tiny file helpers). Tests want pytest and parameterized.

Install those however you usually do, then run stuff from the repo root so src imports behave.

Running

Easiest is to set PYTHONPATH to this folder (or pip install -e . if you ever add packaging):

cd /path/to/wordle
PYTHONPATH=. python run.py wordle    # or nerdle / quordle

When it asks for scores, match whatever format you’re playing—details are in GuessWord.from_input in src/model/guess_word.py (e.g. five digits for normal 5-letter Wordle).

Rebuild caches (only when you need fresh data):

PYTHONPATH=. python calculate_all_scores.py wordle

Simulate the whole answer list:

PYTHONPATH=. python distribution.py wordle

Tests

PYTHONPATH=. pytest tests/

Most of the meat is in tests/test_guess_word.py (scoring + rules_out); the rest is smaller.