# 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](https://docs.astral.sh/uv/).

```sh
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):

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

```sh
uv run black .
```

Lint:

```sh
uv run flake8
```

## Testing

Run all tests:

```sh
uv run pytest
```

Run only unit tests:

```sh
uv run pytest tests/unit
```

Run only e2e tests:

```sh
uv run pytest tests/e2e
```

## Documentation

Build the API documentation:

```sh
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