botWebWars/AGENTS.md

# AGENTS.md - botWebWars AI Agent Guide

Welcome to **botWebWars**! This document provides architectural context, component specifications, game rule references, and developer workflows for GenAI coding agents (and human developers) working in this repository.

---

## 1. System Overview

**botWebWars** is an autonomous tactical bot arena built on a **64 × 64 discrete grid** (coordinates `(0, 0)` to `(64, 64)`). Bots register with custom names, colors, and strength values, explore the terrain, negotiate party alliances based on relative strength, maintain squad formations, and battle opposing parties in **3-bout D20 tactical confrontations**.

### Tech Stack
- **Backend**: Python 3.12, FastAPI, Uvicorn, Pydantic v2, WebSockets, Pytest.
- **Frontend**: React 19, TypeScript, Vite, Tailwind CSS v4, Lucide React icons.
- **Deployment**: Multi-stage Dockerfile (Node 22 build -> Python 3.12-slim runtime), Docker Compose.
- **Bots**:
  - `botagent`: Python heuristic agent (radar scanning, frontier exploration, deterministic leader negotiation).
  - `botagent_ai`: LLM-assisted Python agent (Ollama / LLM-driven strategic negotiation and pathing).
  - `botagent_gear`: Vertex AI (Gemini) LLM-assisted agent (Google Cloud Vertex AI / Gemini 2.5 & 1.5 strategic reasoning).

---

## 2. Repository Layout

```
botWebWars/
├── AGENTS.md                  # This file: AI agent orientation and system manual
├── GAME_RULES.md              # Canonical rules of engagement, movement, and scoring
├── README.md                  # Human-facing overview and quickstart
├── Dockerfile                 # Multi-stage production container build (frontend + backend)
├── docker-compose.yml         # Single-service container composition on port 8000
│
├── backend/                   # FastAPI application & game engine
│   ├── app/
│   │   ├── main.py            # FastAPI entry point, CORS, static SPA serving, WebSockets
│   │   ├── game.py            # Core game logic, grid state, movement, battle resolution
│   │   ├── models.py          # Pydantic schemas (Player, Party, Battle, Move, etc.)
│   │   ├── config.py          # App settings & environment configurations
│   │   └── api/
│   │       ├── routes.py      # REST endpoints (/api/players, /api/board, /api/parties, etc.)
│   │       └── websocket.py   # Connection manager for real-time WebSocket clients
│   ├── tests/
│   │   └── test_api.py        # Pytest test suite for game mechanics & API routes
│   └── requirements.txt       # Backend dependencies
│
├── frontend/                  # React + Vite + TypeScript application
│   ├── src/
│   │   ├── App.tsx            # Main UI shell, turn HUD, control panel, modals
│   │   ├── components/        # Grid, radar, scoreboard, battle log, player controls
│   │   ├── hooks/             # WebSocket connections and state synchronization
│   │   └── types.ts           # Frontend TypeScript interfaces mirroring backend models
│   ├── package.json           # Frontend dependencies and build scripts
│   └── vite.config.ts         # Vite build configuration
│
├── botagent/                  # Heuristic autonomous bot
│   ├── bot_agent.py           # Autonomous client using radar, memory, and game API
│   └── README.md              # Execution command examples
│
├── botagent_ai/               # LLM-assisted autonomous bot (Ollama)
│   ├── bot.py                 # Bot delegating strategic pathing/alliances to an LLM
│   ├── requirements.txt       # Dependencies (ollama, requests)
│   └── INSTALL.md             # Setup, Ollama configuration, and execution instructions
│
├── botagent_gear/             # LLM-assisted autonomous bot (Google Vertex AI / Gemini)
│   ├── bot.py                 # Bot delegating decisions to Vertex AI Gemini
│   ├── requirements.txt       # Dependencies (google-auth, requests)
│   ├── SETUP.md               # Google Cloud authentication & Vertex AI setup guide
│   ├── INSTALL.md             # Installation, virtual environment, and dependency instructions
│   └── README.md              # Feature overview and invocation examples
│
└── examples/                  # Reference screenshots and board style designs
```

---

## 3. Game Rules & Mechanics (`GAME_RULES.md` Reference)

When writing bots, backend engine logic, or game simulations, adhere strictly to [GAME_RULES.md](GAME_RULES.md):

### 1. Alliances (Solo vs. Solo)
- When two solo bots encounter each other (adjacent or on same tile), they may form an alliance.
- The bot with **greater strength** (or higher score if tied) becomes the **Party Leader**.
- While alliances are voluntary, larger parties have a statistical advantage in battle.

### 2. Solo vs. Party Encounters
- A solo bot **joins** an existing party if the party leader's strength is >= the solo bot's strength.
- If the party leader is **weaker** than the solo bot, the solo bot refuses to join, and the party engages the solo bot in battle.

### 3. Party vs. Party Battles (3-Bout D20)
- Two opposing parties that encounter each other **must** battle.
- **Bout Resolution**:
  - Exactly 3 bouts are conducted.
  - In each bout, each party rolls a 20-sided die (D20 between 1 and 20).
  - Bout Score = Squad Total Strength * D20 Roll.
  - Highest score wins the bout. Best 2-out-of-3 bouts wins the overall battle.
- **Scoring & Penalties**:
  - **Winning Leader**: +2 score points.
  - **Winning Party Members**: +1 score point each.
  - **Losing Leader**: -1 score point, stripped of leadership, removed from party, and respawned at a random open grid coordinate.
  - **Losing Party Members**: 0 score penalty; all surviving followers are **absorbed** into the winning party.

### 4. Party Squad Movement
- The party leader chooses movement direction.
- Follower members follow the leader in a single-file line (each member moves to the position vacated by the bot immediately ahead of them) maintaining Chebyshev distance <= 1.

### 5. Terrain Obstacles & Diagonal Squeeze
- Mountains and forests are impassable.
- Bots can squeeze diagonally between adjacent obstacle corners, with strength penalties:
  - **Solo bot**: -0.1 strength.
  - **Party**: Leader loses -0.2 strength; followers each lose -0.1 strength.
  - Moving along outer obstacle edges has no penalty. Minimum bot strength floor is 0.1.

### 6. Game Conclusion
- The game concludes when all bots on the board are united into a **single remaining party**.
- Final rankings/trophies (1st, 2nd, 3rd) are awarded based on **Score** (with **Strength** as the tiebreaker).

---

## 4. Backend & API Specifications

The backend serves both REST endpoints under `/api` and a live WebSocket stream at `/ws`.

### Key REST Endpoints
| Method | Path | Description |
|---|---|---|
| `GET` | `/api/health` | Container healthcheck endpoint |
| `POST` | `/api/players` | Register bot: `{"name": str, "color": str, "strength": int}` |
| `GET` | `/api/players` | List all active players, scores, and positions |
| `GET` | `/api/board` | Full board state (grid, obstacles, players, parties, current turn) |
| `POST` | `/api/board/reset` | Clear board, reset parties, and reset players |
| `GET` | `/api/players/{id}/radar` | Scans surroundings, finds closest bots, identifies allies/opponents |
| `GET` | `/api/players/{id}/memory` | Coordinate history and visited locations |
| `GET` | `/api/players/{id}/available-moves` | Valid movements in all 8 directions (evaluates terrain & obstacles) |
| `POST` | `/api/players/{id}/move` | Execute a move (`{"direction": "N"|"S"|"E"|"W"|"NE"|"NW"|"SE"|"SW"}`) |
| `POST` | `/api/players/{id}/ai-step` | Perform one autonomous decision step via internal game engine |
| `POST` | `/api/players/{id}/pass` | Pass turn to next queued entity |
| `GET` | `/api/turn` | Current turn owner, round number, and turn order |
| `GET` | `/api/parties` | List all parties, leaders, and member IDs |
| `POST` | `/api/parties` | Manually construct an alliance party |
| `POST` | `/api/battles/fight` | Initiate a 3-bout D20 battle between adjacent parties |

### Real-Time WebSocket (`/ws`)
- Automatically broadcasts state changes (`init`, `move`, `battle`, `party_formed`, `turn_change`, `game_over`).
- Client can send ping messages `{"action": "ping"}` and receives `{"event": "pong"}`.

---

## 5. Frontend Architecture

- **Path**: `frontend/`
- **Framework**: React 19 + TypeScript bundled with Vite.
- **Styling**: Tailwind CSS v4.
- **Key Features**:
  - Real-time 64x64 board renderer with zoom/pan and custom obstacle textures.
  - Live turn indicators, active player highlight, and party squad link lines.
  - Radar visualization panel showing target distances and alignment.
  - Battle modal showing animated D20 rolls, multipliers, bout winners, and score adjustments.
  - Autonomous loop toggle to run rounds continuously from the browser.

---

## 6. Docker & Container Deployment

The application is containerized into a single unified image via [Dockerfile](Dockerfile) and [docker-compose.yml](docker-compose.yml):

1. **Stage 1 (`frontend-builder`)**:
   - Base image: `node:22-alpine`
   - Installs packages and runs `npm run build` to generate `frontend/dist`.
2. **Stage 2 (`production`)**:
   - Base image: `python:3.12-slim`
   - Installs backend requirements from `backend/requirements.txt`.
   - Copies `backend/` source and static assets from `frontend/dist` into `frontend/dist`.
   - FastAPI serves static assets at `/` and `/assets` while mounting API routes at `/api` and `/ws`.
   - Built-in container healthcheck calls `curl -f http://localhost:8000/api/health`.

---

## 7. Bot Implementations

### A. Heuristic Bot: `botagent/`
- **Entry File**: `botagent/bot_agent.py`
- **Technique**: Deterministic rule-based autonomous agent.
- **Workflow**:
  1. Registers bot via `POST /api/players`.
  2. Polls `GET /api/turn` to wait for its turn.
  3. Uses `GET /api/players/{id}/radar` to find nearest target.
  4. Avoids looping using internal coordinate history.
  5. Computes vector direction, evaluates diagonal obstacles, and moves.
  6. Evaluates alliances vs. fights strictly according to strength hierarchy.
- **Run Command**:
  ```bash
  python3 botagent/bot_agent.py --name CyberBot --color "#10b981" -s 4 --url http://localhost:8000/api
  ```

### B. LLM-Assisted Bot: `botagent_ai/`
- **Entry File**: `botagent_ai/bot.py`
- **Technique**: LLM strategic decision maker with deterministic rule safeguards.
- **LLM Integration**:
  - Communicates with an LLM backend (configured for local/remote Ollama HTTP API at `/api/generate` with model `gemma4:12b`, or adaptable to OpenAI-compatible endpoints).
  - Delegates discretionary decisions to the model:
    - Voluntary alliances (whether to ally or keep hunting when solo meets solo).
    - Navigation direction toward radar targets while balancing obstacle squeeze trade-offs.
  - Mandatory rules (forced battles, forced absorption when weaker than leader) are enforced deterministically by the game engine regardless of LLM preference.
- **Configuration & Environment Variables**:
  - `OLLAMA_BASE_URL` / `--ollama-url`: LLM server address (default: `http://192.168.1.220:11434`).
  - `OLLAMA_MODEL` / `--ollama-model`: Model identifier (default: `gemma4:12b`).
  - `BOT_SERVER_URL` / `-u`: botWebWars backend URL (default: `http://localhost:8000/api`).
  - `BOT_NAME` / `-n`: Bot name.
  - `BOT_COLOR` / `-c`: Bot hex color.
  - `BOT_STRENGTH` / `-s`: Starting strength (1-10).
- **Run Command**:
  ```bash
  export OLLAMA_BASE_URL="http://localhost:11434"
  export OLLAMA_MODEL="gemma4:12b"
  python3 botagent_ai/bot.py -n MyAIBot -s 4 -c "#8b5cf6"
  ```

### C. Vertex AI (Gemini) Bot: `botagent_gear/`
- **Entry File**: `botagent_gear/bot.py`
- **Technique**: Google Cloud Vertex AI (Gemini) model reasoning for spatial navigation, minimap analysis, and strategic voluntary alliances.
- **LLM Integration**:
  - Communicates with Google Cloud Vertex AI generateContent REST endpoint or Google AI Studio Gemini API.
  - Features structured JSON generation (`responseMimeType: application/json`) and system instruction enforcement.
  - Supports multiple authentication methods:
    - Interactive developer login (`gcloud auth application-default login` or `gcloud auth login`).
    - Automated service account keys (`GOOGLE_APPLICATION_CREDENTIALS`).
    - Direct API keys (`GEMINI_API_KEY` or `VERTEX_API_KEY`).
- **Documentation**:
  - [SETUP.md](botagent_gear/SETUP.md): Google Cloud authentication, project creation, API enablement, and credentials setup.
  - [INSTALL.md](botagent_gear/INSTALL.md): Virtual environment and dependency installation instructions.
  - [README.md](botagent_gear/README.md): Bot overview, CLI reference, and execution examples.
- **Run Command**:
  ```bash
  python3 botagent_gear/bot.py --name GeminiGear --color "#4285f4" -s 5
  ```

---

## 8. Common Developer Workflows

### Run with Docker Compose (Recommended)
```bash
docker compose up --build
```
Access UI at `http://localhost:8000`.

### Local Development (Manual Setup)

#### 1. Backend:
```bash
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

#### 2. Frontend:
```bash
cd frontend
npm install
npm run dev
```

#### 3. Run Backend Test Suite:
```bash
# Run locally with pytest
PYTHONPATH=backend pytest backend/tests

# Or run via docker container
docker run --rm botwebwars:test pytest backend/tests
```

---

## 9. Guidelines for GenAI Agents Modifying this Codebase

1. **Preserve Rules Fidelity**:
   - Any updates to alliance logic, battles, diagonal squeezes, or victory states must match [GAME_RULES.md](GAME_RULES.md).
   - Update `GAME_RULES.md` and tests in `backend/tests/test_api.py` whenever game mechanics are modified.

2. **Frontend-Backend Sync**:
   - When modifying schemas in `backend/app/models.py`, update matching TypeScript interfaces in `frontend/src/types.ts`.
   - Maintain WebSocket payload compatibility between `backend/app/api/websocket.py` and frontend hooks (`frontend/src/hooks/`).

3. **Bot Compatibility**:
   - Ensure REST endpoint signature modifications are reflected in `botagent/bot_agent.py`, `botagent_ai/bot.py`, and `botagent_gear/bot.py`.
   - Preserve CLI flag compatibility across all bot scripts.

4. **Multi-Stage Build Integrity**:
   - If adding frontend build dependencies, verify `Dockerfile` compiles cleanly in stage 1 (`npm run build`) and correctly mounts to `frontend/dist` in stage 2.