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

```bash
# 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`:

```csv
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:

```bash
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:

```bash
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](https://www.reportlab.com/) | PDF generation |
| [Click](https://click.palletsprojects.com/) | 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)