botWebWars/botagent_gear/README.md

# botagent_gear: Vertex AI (Gemini) Autonomous Agent

**`botagent_gear`** is an intelligent, autonomous agent for **botWebWars** powered by Google Cloud's **Vertex AI** and **Gemini** foundation models (such as `gemini-2.5-flash`).

---

## Overview

Unlike heuristic bots that use static pathing formulas, `botagent_gear` combines:
1. **Gemini Spatial & Strategic Reasoning**:
   - Analyzes real-time radar scans, opponent strengths, party sizes, and an ASCII minimap of nearby terrain.
   - Evaluates obstacle squeezes (balancing strength penalties vs. path efficiency).
   - Decides voluntary alliances with encountered solo bots.
2. **Deterministic Rules Enforcement**:
   - Strictly conforms to [GAME_RULES.md](../GAME_RULES.md).
   - Rule-mandated actions (forced battles, forced joins when weaker than a party leader) are executed deterministically by the game engine, while Gemini guides discretionary tactical decisions.
3. **Multi-Authentication Support**:
   - Works with Google Cloud CLI (`gcloud auth application-default login`), service account keys (`GOOGLE_APPLICATION_CREDENTIALS`), or direct API keys (`GEMINI_API_KEY`).

---

## Quick Start

### 1. Prerequisites & Installation
Ensure you have completed the setup in [SETUP.md](SETUP.md) and [INSTALL.md](INSTALL.md):
```bash
cd botagent_gear
pip install -r requirements.txt
```

### 2. Configure Authentication
Choose one of the methods described in [SETUP.md](SETUP.md). For example, with `gcloud`:
```bash
# 1. Log in to Google Cloud
gcloud auth login

# 2. Set your Google Cloud project
gcloud config set project YOUR_GCP_PROJECT_ID

# 3. Authorize Application Default Credentials
gcloud auth application-default login
```

*(Alternatively, if using an API key from Google AI Studio: `export GEMINI_API_KEY="your-api-key"`).*

### 3. Launch the Bot

#### Default invocation:
```bash
python3 bot.py
```

#### Custom Bot parameters (Name, Color, Strength, Model):
```bash
python3 bot.py \
  --name "GeminiTitan" \
  --color "#0ea5e9" \
  --strength 6 \
  --model "gemini-2.5-flash" \
  --project "YOUR_GCP_PROJECT_ID"
```

#### Using Environment Variables:
```bash
export VERTEX_PROJECT_ID="YOUR_GCP_PROJECT_ID"
export VERTEX_LOCATION="us-central1"
export VERTEX_MODEL="gemini-2.5-flash"
export BOT_NAME="GearBot"
export BOT_COLOR="#10b981"
export BOT_STRENGTH="5"

python3 bot.py
```

#### Connecting to a Remote Game Server:
```bash
python3 bot.py --url "http://192.168.1.100:8000/api" --name "RemoteGear"
```

---

## Command-Line Arguments Reference

| Flag | Long Flag | Environment Variable | Default | Description |
|---|---|---|---|---|
| `-u` | `--url` | `BOT_SERVER_URL` | `http://localhost:8000/api` | botWebWars REST API base URL |
| `-n` | `--name` | `BOT_NAME` | `GeminiGearBot` | Display name of the bot on the grid |
| `-c` | `--color` | `BOT_COLOR` | `#4285f4` | Hex color code for the bot avatar |
| `-s` | `--strength` | `BOT_STRENGTH` | `5` | Starting strength (1 to 10) |
| `-p` | `--project` | `VERTEX_PROJECT_ID` | Auto-detected from `gcloud` | Google Cloud Project ID |
| `-l` | `--location` | `VERTEX_LOCATION` | `us-central1` | Google Cloud region for Vertex AI |
| `-m` | `--model` | `VERTEX_MODEL` | `gemini-2.5-flash` | Gemini model name |
| `-k` | `--api-key` | `VERTEX_API_KEY` / `GEMINI_API_KEY` | *(None)* | Optional Gemini API key |

---

## How It Works in Battle

1. **Lobby & Registration**:
   - The agent calls `POST /api/players` to enter the arena.
   - Waits for the game to start via the frontend UI.
2. **Turn Polling**:
   - Polls `GET /api/turn` until it is this bot's turn.
3. **Radar & Minimap Assessment**:
   - Obtains radar targets via `GET /api/players/{id}/radar`.
   - Computes an 8×8 ASCII minimap centered around the bot displaying obstacles (`M` mountain, `F` forest, `V` valley), allies (`A`), and enemies (`E`).
4. **Gemini Reasoning**:
   - Prompts Gemini with legal moves, diagonal squeeze penalties, distances to targets, and current health/score.
   - Gemini returns structured JSON with the selected direction and reasoning.
5. **Encounters & 3-Bout Confrontations**:
   - If adjacent to another bot, initiates party alliances or engages in 3-Bout D20 tactical battles via `POST /api/battles/fight`.
6. **Game Conclusion**:
   - Detects when all bots are united under a single winning squad and announces final ranking.

---

## Running Multi-Bot Arenas

To experience an arena with diverse AI agents, run multiple bots in separate terminal tabs:

**Terminal 1 (Heuristic Bot):**
```bash
python3 botagent/bot_agent.py --name Heuristic1 --color "#ef4444" -s 3
```

**Terminal 2 (Local Ollama LLM Bot):**
```bash
python3 botagent_ai/bot.py -n OllamaAgent -s 4 -c "#8b5cf6"
```

**Terminal 3 (Vertex AI Gemini Bot):**
```bash
python3 botagent_gear/bot.py --name GeminiGear --color "#4285f4" -s 5
```

Open the web interface at `http://localhost:8000`, click **Start Game**, and watch the tactical confrontations unfold live!