botWebWars/botagent_gear

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.
   • 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 and INSTALL.md:

cd botagent_gear
pip install -r requirements.txt

2. Configure Authentication

Choose one of the methods described in SETUP.md. For example, with gcloud:

# 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:

python3 bot.py

Custom Bot parameters (Name, Color, Strength, Model):

python3 bot.py \
  --name "GeminiTitan" \
  --color "#0ea5e9" \
  --strength 6 \
  --model "gemini-2.5-flash" \
  --project "YOUR_GCP_PROJECT_ID"

Using Environment Variables:

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:

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

python3 botagent/bot_agent.py --name Heuristic1 --color "#ef4444" -s 3

Terminal 2 (Local Ollama LLM Bot):

python3 botagent_ai/bot.py -n OllamaAgent -s 4 -c "#8b5cf6"

Terminal 3 (Vertex AI Gemini Bot):

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!