# Phutball Simplified Local

A standalone local Phutball app for playing in one browser, with optional neural
network play and analysis. It also includes a local companion page for playing
real phutball.org rooms with private local AI assist.

It supports:

- Local human-vs-human play in the same browser.
- Human-vs-AI, AI-vs-human, and AI-vs-AI play when local model dependencies are installed.
- Online play through phutball.org from a localhost companion page.
- Odd board sizes from 3 through 21.
- A chess-style move tree with branches.
- Setup mode for custom positions.

This folder is intentionally self-contained. It includes its own Python rules
engine, neural network wrapper, static UI, server, requirements, and model
folder. It should not import files from the broader research repo.

## Run Locally

From inside this folder:

```bash
python3 -m pip install -r requirements.txt
python3 server.py --host 127.0.0.1 --port 8080
```

Then open:

```text
http://localhost:8080
```

The start page offers:

- `Play Local Phutball` for the existing local interface.
- `Play Online With AI Assist` for real phutball.org rooms plus private local analysis.

On macOS you can also double-click:

```text
Play Phutball Simplified.command
```

## Run on Linux

Linux does not use the macOS `.command` launcher, so run the server from a
terminal. From inside this folder:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python server.py --host 127.0.0.1 --port 8080
```

Then open:

```text
http://127.0.0.1:8080
```

If port `8080` is already in use, choose another port:

```bash
python server.py --host 127.0.0.1 --port 8090
```

Then open the matching URL:

```text
http://127.0.0.1:8090
```

For AI play or Online mode with local AI assist, install PyTorch in the same
Python environment that runs `server.py`:

```bash
. .venv/bin/activate
python -m pip install -r requirements-ai.txt
python server.py --host 127.0.0.1 --port 8080
```

If you already have a Python environment with PyTorch installed, install the web
requirements into that environment and run the server with that interpreter:

```bash
/path/to/torch-env/bin/python -m pip install -r requirements.txt
/path/to/torch-env/bin/python server.py --host 127.0.0.1 --port 8080
```

To verify the local server:

```bash
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/models
```

To verify AI analysis on the bundled 19x19 model:

```bash
curl -X POST http://127.0.0.1:8080/new_game \
  -H 'Content-Type: application/json' \
  -d '{"rows":19,"cols":19}'
```

The JSON response should include `"ai_analysis":{"available":true,...}`. If it
says `No module named 'torch'`, the server is running under a Python interpreter
without PyTorch.

## AI Play

Human-vs-human mode only needs the small requirements file:

```text
requirements.txt
```

AI play additionally needs PyTorch:

```bash
python3 -m pip install -r requirements-ai.txt
```

Raw `.pt` model checkpoints belong in:

```text
models/
```

The model picker only shows checkpoints compatible with the current board size.

## Online Companion Notes

The Online page at `/online` plays through phutball.org while keeping local AI
analysis on your machine. The local server proxies only `/online/*` room API
requests to phutball.org.

If Online room creation or joining fails, first verify that the local server can
reach phutball.org:

```bash
curl -X POST http://127.0.0.1:8080/online/create \
  -H 'Content-Type: application/json' \
  -d '{"rows":19,"cols":19,"player_num":1,"name":"Test"}'
```

If the request succeeds, it returns a room code and player token. If it fails
with a reachability error, check internet access, firewall rules, or whether
phutball.org is reachable from that machine.

## Suggested Improvements

- Add a Linux launcher script, for example `play-phutball-simplified.sh`, that
  mirrors the macOS `.command` file: create or reuse a venv, install
  dependencies, stop or avoid occupied ports, start the server, and print the
  URL.
- Make the default port configurable through an environment variable such as
  `PHUTBALL_PORT`, and show the active URL prominently in the terminal.
- Keep the Online companion's local AI endpoint dynamic. It should prefer the
  current page origin, then fall back to common localhost ports. This avoids the
  bug where the page was opened on `8090` but still tried to contact AI on
  `8080`.
- Add a startup check that warns when PyTorch is missing but compatible model
  files are present, so users know AI analysis will be disabled before opening
  the browser.
- Add a `/diagnostics` route or startup diagnostics block that reports Python
  executable, dependency status, model catalog, active port, and phutball.org
  proxy reachability.
- Avoid killing an existing process on port `8080` by default. Prefer selecting
  the next open port unless the user explicitly asks the launcher to replace the
  existing listener.
- Document model compatibility in the UI: the bundled models are board-size
  specific, so a 19x19 game needs a 19x19 model and a 9x9 game needs a 9x9
  model.
- Add lightweight automated smoke tests for `/health`, `/models`, `/new_game`,
  `/ai_analysis`, and the `/online/create` proxy behavior.

## Game Tree Behavior

All moves are local. You can move backward in the tree, make a different legal
move, and create a branch without affecting anything outside this browser.

## Folder Boundary

This app is self-contained. Its online companion route proxies only the public
`/online/*` room API to phutball.org; rules, local play, model files, and AI
analysis stay on this machine. It should avoid parent-repo imports, absolute
local paths, or hidden dependencies outside this folder.
