kdp_generator/README.md

Crossword Puzzle Generator for Amazon KDP

A Python CLI tool that reads words and clues from a CSV file, generates crossword puzzle grids, and outputs a print-ready PDF book formatted for Amazon KDP upload.

Quick Start

# Set up a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Generate a crossword book from the sample data
python main.py --input sample_words.csv \
               --output my_book.pdf \
               --puzzles 20 \
               --title "My Crossword Book" \
               --author "Your Name"

Input Format

A CSV file with at minimum two columns — word and clue:

word,clue
PYTHON,"A large snake, or a programming language"
GRID,"A network of lines that cross each other"
PUZZLE,"A game or problem that tests ingenuity"

Optional columns:

Column	Purpose
difficulty	Group words into easy/medium/hard puzzles
category	Generate themed puzzles (e.g. "Animals", "Science")

Words are automatically normalised to uppercase. Accented characters are stripped (e.g. café → CAFE). Duplicates, words shorter than 3 letters, and words containing non-alpha characters are rejected with a warning.

CLI Reference

Usage: main.py [OPTIONS]

  Generate a KDP-ready crossword puzzle book from a CSV word list.

Required

Flag	Description
--input FILE	Path to a CSV file with word,clue columns

Optional

Flag	Default	Description
--output TEXT	output.pdf	Output PDF file path
--puzzles INTEGER	20	Number of crossword puzzles to generate
--grid-size INTEGER	13	Grid dimensions (e.g. 15 for a 15×15 grid)
--trim-size CHOICE	8.5x11	KDP page trim size — one of 8.5x11, 6x9, 8x10
--title TEXT	Crossword Puzzles	Book title for the cover page
--author TEXT	(empty)	Author name
--words-per-puzzle INTEGER	20	Target number of words per puzzle
--solutions-at-end	off	Group all solution pages at the back of the book
--seed INTEGER	(random)	Random seed for reproducible output
--no-toc	off	Omit the table of contents page
--no-instructions	off	Omit the how-to-solve instructions page
-v, --verbose	off	Enable verbose/debug logging
--help		Show help and exit

Examples

Generate a 50-puzzle book in 6×9 format with solutions at the back:

python main.py --input words.csv \
               --output crossword_book.pdf \
               --puzzles 50 \
               --grid-size 15 \
               --trim-size 6x9 \
               --title "The Ultimate Crossword Book" \
               --author "Jane Doe" \
               --solutions-at-end \
               --seed 42

Quick 10-puzzle book with a smaller grid and no front matter extras:

python main.py --input words.csv \
               --output quick_puzzles.pdf \
               --puzzles 10 \
               --grid-size 10 \
               --no-toc \
               --no-instructions

Book Structure

Each generated PDF contains:

1. Title page — book title and author
2. Copyright page — auto-generated with the current year
3. Table of contents — puzzle numbers mapped to page numbers (optional)
4. Instructions page — "How to Solve" guide (optional)
5. Puzzle pages — empty grid with numbered cells, black squares, and clues in two columns
6. Solution pages — filled grid with all letters visible

Page numbering starts after the front matter. Gutter (inside) margins are automatically calculated based on total page count per KDP specifications.

Project Structure

crossword-kdp-generator/
├── main.py              # CLI entry point
├── csv_reader.py        # CSV parsing and validation
├── generator.py         # Crossword grid generation algorithm
├── renderer.py          # PDF grid and clue rendering
├── kdp_format.py        # KDP page layout and front matter
├── models.py            # Data classes
├── requirements.txt     # Dependencies
├── sample_words.csv     # Example input (50 words, 5 categories)
├── PLAN.md              # Implementation plan
└── README.md            # This file

Dependencies

Package	Purpose
ReportLab	PDF generation
Click	CLI argument parsing

KDP Notes

• Trim sizes: 8.5"×11", 6"×9", 8"×10"
• Margins: Outside 0.5", gutter auto-calculated (0.375"–0.875" based on page count)
• Page count: KDP requires 24–828 pages; the tool warns if below minimum
• Bleed: Not needed for puzzle books (no content extends to the page edge)