Deets: Themed puzzles using classic Constraint Satisfaction Problem (CSP) techniques...and room to grow into a full “constructor’s workbench” including LLM-assisted theme/clue tooling. When it's done it will supported alphanumeric entries and dynamic theme-based word scoring!
Generates crossword puzzles using:
- AC-3 constraint propagation algorithm
- Backtracking search
- Theme word placement and scoring
- Automatic clue generation
- Support for letters and digits in the answers
python scripts/generate.py --output my_puzzle.json
python scripts/generate.py
--theme "Space Exploration"
--theme-words "ASTRONAUT,SPACECRAFT"
--size 15
--output space_puzzle.json
python scripts/generate.py
--theme-file data/examples/themes/ai_theme.json
--output ai_puzzle.json
crossword-generator/
├── README.md # Project overview and quick start
├── requirements.txt # Python dependencies
├── setup.py # Package installation (optional)
│
├── data/ # Word lists and resources
│ ├── word_lists/
│ │ ├── enable.txt # Main word list (download on setup)
│ │ └── common_words.txt # Curated high-quality words (optional)
│ └── examples/
│ ├── grids/ # Example grid patterns
│ └── themes/ # Example theme configurations
│
├── src/ # Main source code
│ ├── __init__.py
│ ├── grid.py # Grid creation & black square placement
│ ├── solver.py # CSP solver (AC-3 + backtracking)
│ ├── theme.py # Theme word placement & scoring
│ ├── clues.py # Clue metadata generation
│ └── utils.py # Helper functions
│
├── scripts/ # Standalone scripts
│ ├── download_wordlist.py # Setup: download word lists
│ └── generate.py # CLI tool to generate puzzles
│
├── tests/ # Unit tests
│ ├── __init__.py
│ ├── test_grid.py
│ ├── test_solver.py
│ └── test_theme.py
│
└── output/ # Generated puzzles (gitignored)
├── .gitkeep
└── examples/ # Example outputs (committed)
└── sample_puzzle.json
MIT License
- Python 3.7+
- pip
- Clone the repository:
git clone <repository-url>
cd crossword-generator- Install dependencies:
pip install -r requirements.txt- Download word lists:
python scripts/download_wordlist.pyGenerate a crossword puzzle:
python scripts/generate.py --width 15 --height 15 --output output/puzzle.jsonGenerate with theme words:
python scripts/generate.py --width 15 --height 15 --theme PYTHON CODING AI --output output/puzzle.jsonpython -m pytest tests/Or using unittest:
python -m unittest discover tests