32word 0.1.0

The game engine for 3-2-Word: Solve Wordle in three guesses.

32word

The game engine for 3-2-Word: Solve Wordle in three guesses.

What This Is

Most people play Wordle casually. Guess some vowels. Eliminate common letters. Hope for the best. Maybe they've heard that STAIR + LEMON + PUDGY is unbeatable.

We know better.

3-2-Word is a training app that elevates Wordle from a casual puzzle into something you can practice and master—like Scrabble or a spelling bee. This library (32word) is the engine underneath.

Smart players solved Wordle years ago. They proved optimal strategies mathematically. But most people didn't change how they played. This library changes that. It codifies the strategies that work and makes them accessible to everyone.

It's fun to challenge yourself. It's fun to be smart. This gives you the tools to win.

Installation

pip install 32word

Why This Exists

You can solve Wordle blindly, or you can learn the patterns that elite players discovered through exhaustive analysis. This library provides:

1. Optimal two-guess strategies that consistently solve Wordle in three attempts
2. Pre-computed strategy tables based on simulations across all 2,309 target words
3. A clean API for building bots, websites, and training tools

The solver logic lives here. Everything else—web apps, Discord bots, Telegram bots—imports this library as a dependency.

Quick Start

from word32 import generate_clue, filter_targets, load_strategy, get_second_guess

# Load the default optimal strategy
strategy = load_strategy("v1.0")

# Get the best first guess
first_guess = strategy.first_guess()
print(f"First guess: {first_guess}")  # e.g., "STARE"

# Simulate Wordle feedback
target = "TRASH"
clue = generate_clue(first_guess, target)
print(f"Clue: {clue}")  # ('G', 'Y', 'B', 'B', 'G')

# Find remaining possibilities
from word32 import VALID_TARGETS
remaining = filter_targets(VALID_TARGETS, first_guess, clue)
print(f"{len(remaining)} words remain")

# Get optimal second guess
second_guess = get_second_guess(strategy, clue)
print(f"Second guess: {second_guess}")

Two guesses. Then solve. That's the strategy.

Core API

Clue Generation

generate_clue(guess: str, target: str) -> tuple[str, str, str, str, str]

Returns a 5-tuple representing Wordle's feedback:

• 'G': Green (correct letter, correct position)
• 'Y': Yellow (correct letter, wrong position)
• 'B': Black/Gray (letter not in target)

Example:

generate_clue("STARE", "TRASH")
# ('G', 'Y', 'B', 'B', 'G')
# S is green (position 0 matches)
# T is yellow (in word, wrong position)
# A, R are gray (not in target at those positions)
# E is green (position 4 matches)

Target Filtering

filter_targets(targets: list[str], guess: str, clue: tuple) -> list[str]

Returns all words in targets that would produce exactly clue if you guessed guess against them.

Example:

remaining = filter_targets(VALID_TARGETS, "STARE", ('G', 'Y', 'B', 'B', 'G'))
# Returns list of words compatible with that clue pattern

Strategy Loading

load_strategy(version: str = "v1.0") -> Strategy

Loads a pre-computed strategy table. The default v1.0 uses expected-remaining minimization over all 2,309 Wordle targets.

Strategy methods:

strategy = load_strategy("v1.0")

# Get recommended first guess
first = strategy.first_guess()

# Get recommended second guess based on clue
second = strategy.second_guess(clue)

# Get strategy metadata
meta = strategy.metadata()

Convenience Functions

get_second_guess(strategy: Strategy, first_clue: tuple) -> str

Shortcut for getting the optimal second guess.

is_valid_word(word: str) -> bool

Check if a word is in Wordle's valid guess list (12,950 words).

get_remaining_candidates(targets: list[str], guess: str, clue: tuple) -> int

Count how many targets remain after a guess.

Strategy Design

Each strategy is a lookup table built from tournament simulations. The process:

1. First guess selection: Test every valid target word as a first guess against all 2,309 possible Wordle targets
2. Clue simulation: For each first guess, generate all possible clues (up to 243 patterns, though most never occur)
3. Second guess optimization: For each (first_guess, clue) pair, find the second guess that minimizes expected remaining candidates
4. Tournament ranking: Score strategies by expected remaining words after two guesses across all targets

The default v1.0 strategy consistently leaves 1–3 candidates after two guesses, making the third guess nearly deterministic.

Strategy Metadata

strategy = load_strategy("v1.0")
meta = strategy.metadata()

print(meta)
# {
#   'version': 'v1.0',
#   'penalty_function': 'expected_remaining',
#   'depth': 2,
#   'symmetric': True,
#   'created': '2026-01-15',
#   'description': 'Optimal two-deep strategy minimizing expected remaining targets'
# }

Complete Example

from word32 import (
    generate_clue,
    filter_targets,
    load_strategy,
    get_second_guess,
    VALID_TARGETS
)

# Load strategy
strategy = load_strategy("v1.0")

# Simulate a game
target = "TRASH"  # The word Wordle picked
remaining = VALID_TARGETS.copy()

# First guess
guess1 = strategy.first_guess()
clue1 = generate_clue(guess1, target)
remaining = filter_targets(remaining, guess1, clue1)
print(f"After '{guess1}': {len(remaining)} words remain")

# Second guess
guess2 = get_second_guess(strategy, clue1)
clue2 = generate_clue(guess2, target)
remaining = filter_targets(remaining, guess2, clue2)
print(f"After '{guess2}': {len(remaining)} words remain")

# Third guess
if len(remaining) == 1:
    print(f"Solved in 3: {remaining[0]}")
elif len(remaining) <= 3:
    print(f"Choose from: {remaining}")
else:
    # Edge case handling
    print(f"Manual selection needed from {len(remaining)} candidates")

Most games end after two optimal guesses with 1–3 candidates remaining.

Architecture

This library is designed as a single source of truth for Wordle solver logic. All downstream applications (website, bots, mobile apps) import this package.

32word (PyPI library)
  ↓
  ├─ 3-2-Word website (React + Flask/FastAPI)
  ├─ Discord bot
  ├─ Telegram bot
  ├─ Signal bot
  └─ WhatsApp bot (future)

Design Principles

• Stateless: All functions are deterministic and side-effect-free
• Fast: Word lists cached in memory, strategy tables pre-computed
• Tested: 95%+ coverage on core logic (clue generation, filtering)
• Versioned: Strategy tables versioned independently from library code
• Simple API: Six core functions cover all use cases

Development

Running Tests

pip install -e ".[dev]"
pytest tests/ -v --cov=word32

Package Structure

word32/
├── __init__.py           # Public API exports
├── core.py               # Clue generation, filtering
├── strategy.py           # Strategy loading and lookup
├── validation.py         # Word list validation
├── data/
│   ├── strategies/
│   │   └── v1.0.json     # Pre-computed optimal strategy
│   ├── targets.txt       # 2,309 Wordle targets
│   └── valid_guesses.txt # 12,950 valid guesses
└── tests/
    ├── test_clues.py
    ├── test_filtering.py
    ├── test_strategy.py
    └── test_integration.py

Creating New Strategies

Strategy tables are JSON files in word32/data/strategies/:

{
  "metadata": {
    "version": "v1.1-minimax",
    "penalty_function": "minimax",
    "depth": 2,
    "created": "2026-01-20"
  },
  "first_guess": "SALET",
  "clues": {
    "GGGGG": {"second_guess": "N/A", "remaining": 0},
    "GGGYB": {"second_guess": "BLAND", "remaining": 2},
    ...
  }
}

To add a new strategy:

1. Run the tournament simulation to generate the table
2. Save as v{X}.{Y}-{variant}.json
3. Submit a PR with test coverage

Roadmap

Phase 1: Core Library ✅

• Clue generation
• Target filtering
• Strategy loading
• Pre-computed v1.0 strategy
• PyPI package

Phase 2: Downstream Apps (In Progress)

• Website at 3-2-word.com
• Discord bot
• Telegram bot
• Signal bot
• WhatsApp bot

Future Extensions

• Three-deep strategies
• Minimax variants
• Anchor word customization
• Quordle/Weaver support
• Strategy comparison analytics

Why MIT Licensed?

This code should be free. The insights are already published—researchers solved Wordle years ago. I'm just packaging it so anyone can use it.

Build a bot. Build a training app. Build a better solver. The game is solved. Now go teach people how to win.

Contributing

Contributions welcome! Please:

1. Open an issue before starting major work
2. Write tests for new features
3. Follow the existing style (stateless functions, simple API)
4. Update docs if you change the API

Areas for Contribution

• New strategies: Minimax, three-deep, custom anchor words
• Performance: Optimize filtering, caching
• Variants: Quordle, Absurdle, other Wordle clones
• Tests: Edge cases, integration tests
• Docs: Tutorials, strategy explanations

Related Projects

• 3-2-Word website: 3-2-word.com
• Discord bot: Coming soon
• Telegram bot: Coming soon

Acknowledgments

Built on the shoulders of researchers who solved Wordle mathematically. This library packages their insights for practical use.

Special thanks to the Wordle community for exploring optimal strategies and making the game more interesting.

License

MIT License. See LICENSE for details.

---

3-2-Word: The training app for people who want to master Wordle.
Built by Ben Mazzotta. Engine: 32word.

Get better at Wordle. Start here.