ai_demo_backend

A backend HTTP server that powers a word search puzzle game playable in a web browser. Built with Python and Tornado.

What is Word Search?

Word search is a puzzle where a grid of letters contains hidden words placed horizontally, vertically, or diagonally. Players scan the grid to find and select each hidden word from a provided list.

This backend serves the game logic — generating puzzles, validating found words, and managing game state — over HTTP for a browser-based frontend.

Installation

Requires Python 3.13+ and uv.

uv sync

This installs all runtime and dev dependencies into a local .venv.

Database Setup

Apply migrations and seed the database with word categories (animals, colors, food):

uv run alembic upgrade head
uv run python seed.py

This creates a local wordsearch.db SQLite file. The seed script is idempotent — running it again skips existing categories.

Development

Format code:

uv run black .

Lint:

uv run flake8

Testing

Run all tests:

uv run pytest

Run only unit tests:

uv run pytest tests/unit

Run only e2e tests:

uv run pytest tests/e2e

Documentation

Build the API documentation:

uv run sphinx-build -b html docs/source docs/build/html

Then open docs/build/html/index.html in a browser.

See Also

• Mathew Guest
• Co-Authored with Claude