Crossword Generator API

A FastAPI server that generates playable crossword puzzles from words and clues using the pycrossword library.

Installation

cd /home/spic/Documents/Clients/AIML.com/aiml.com-ddev/ai-fun/crossword-server

# Install with pipx (recommended)
pipx install --editable .

# Inject pycrossword dependency (required for clue generation)
pipx inject crossword-server pycrossword-generator

# Or install dependencies directly
pip install fastapi uvicorn pydantic pycrossword-generator

Configuration

Authentication

The server supports optional authentication via an API token. To enable:

1. Copy .env.example to .env
2. Set your secret token:

CROSSWORD_AUTH_TOKEN=your-secret-token-here

3. When CROSSWORD_AUTH_TOKEN is set, all requests to /generate must include the X-Auth-Token header:

curl -X POST "http://localhost:8000/generate" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: your-secret-token-here" \
  -d '{"words": ["NEURAL\tA network of nodes"]}'

If CROSSWORD_AUTH_TOKEN is not set or empty, authentication is disabled (not recommended for production).

Usage

Running the Server

# Using the installed script
crossword-server

# Or run directly with Python
python server.py

The server will start on http://localhost:8000

API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

API Endpoints

POST /generate

Generate a playable crossword HTML puzzle.

Headers:

Header	Type	Required	Description
X-Auth-Token	string	Conditional	Required if CROSSWORD_AUTH_TOKEN is set

Request Body:

{
  "words": [
    "NEURAL\tA network of nodes",
    "AGENT\tAn autonomous system",
    "LEARNING\tProcess of acquiring knowledge"
  ],
  "title": "AI Crossword",
  "width": 26,
  "height": 26,
  "seed": 42
}

Parameters:

Parameter	Type	Required	Description
words	array	Yes	List of "word", "word clue", or "word\tclue"
title	string	No	Puzzle title (default: "Crossword Puzzle")
width	integer	No	Max width constraint (default: auto)
height	integer	No	Max height constraint (default: auto)
seed	integer	No	Random seed for reproducibility

Response: Complete HTML file with embedded Exolve player

Example:

# With authentication (if CROSSWORD_AUTH_TOKEN is set)
curl -X POST "http://localhost:8000/generate" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: your-secret-token-here" \
  -d '{
    "words": ["NEURAL\tA network of nodes", "AGENT\tAn autonomous system"],
    "title": "AI Crossword"
  }' \
  --output crossword.html

# Without authentication (if CROSSWORD_AUTH_TOKEN is not set)
curl -X POST "http://localhost:8000/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "words": ["NEURAL\tA network of nodes", "AGENT\tAn autonomous system"],
    "title": "AI Crossword"
  }' \
  --output crossword.html

Development

Project Structure

crossword-server/
├── pyproject.toml     # Project configuration
├── server.py          # FastAPI application
└── README.md          # This file

Dependencies

• Python 3.12+
• fastapi >= 0.115.0
• uvicorn[standard] >= 0.32.0
• pydantic >= 2.0.0
• pycrossword-generator (includes OpenAI for AI clue generation)

Future Enhancements

• WordPress plugin integration
• Database persistence of generated puzzles
• Caching for common word sets
• Authentication/authorization
• Custom styling options
• AI clue generation via OpenAI