# Installation & Setup Guide for botagent_gear

`botagent_gear` is an autonomous botWebWars agent powered by **Google Cloud Vertex AI** and **Gemini** models.

---

## Prerequisites
- **Python 3.9+** (tested on 3.10, 3.11, 3.12, and 3.14).
- Active Google Cloud Vertex AI access or Gemini API Key (see [SETUP.md](SETUP.md)).
- Running **botWebWars** game server (by default at `http://localhost:8000/api`).

---

## Installation Steps

### 1. Navigate to the bot directory
```bash
cd botagent_gear
```

### 2. (Recommended) Create and activate a Virtual Environment
```bash
python3 -m venv venv
source venv/bin/activate
```
*(On Windows: `venv\Scripts\activate`)*

### 3. Install Python Dependencies
```bash
pip install -r requirements.txt
```

The dependencies are kept lightweight and robust:
- `requests`: HTTP client for the botWebWars game API and Vertex AI REST endpoints.
- `google-auth`: Google Cloud Application Default Credentials (ADC) and OAuth 2.0 token management.

---

## Configuration

You can configure the bot via environment variables or command-line arguments.

### Environment Variables
| Variable | Default | Description |
|---|---|---|
| `VERTEX_PROJECT_ID` | Auto-detected from `gcloud` | Google Cloud project ID |
| `VERTEX_LOCATION` | `us-central1` | Vertex AI region (`us-central1`, `us-east4`, etc.) |
| `VERTEX_MODEL` | `gemini-2.5-flash` | Model ID (`gemini-2.5-flash`, `gemini-1.5-flash`, `gemini-2.5-pro`) |
| `GEMINI_API_KEY` / `VERTEX_API_KEY` | *(None)* | Optional API key for Google AI Studio or Vertex express mode |
| `BOT_SERVER_URL` | `http://localhost:8000/api` | botWebWars REST API endpoint |
| `BOT_NAME` | `GeminiGearBot` | Bot display name on the grid |
| `BOT_COLOR` | `#4285f4` | Hex color code for the bot avatar |
| `BOT_STRENGTH` | `5` | Starting strength (1 to 10) |

### CLI Options
```text
options:
  -h, --help            show this help message and exit
  -u, --url SERVER_URL  Backend REST API base URL (env: BOT_SERVER_URL)
  -n, --name NAME       Display name for this bot (env: BOT_NAME)
  -c, --color COLOR     Hex color code for the bot avatar (env: BOT_COLOR)
  -s, --strength STRENGTH
                        Strength attribute (1-10) for battle multiplier (env: BOT_STRENGTH)
  -p, --project PROJECT_ID
                        Google Cloud Project ID (env: VERTEX_PROJECT_ID)
  -l, --location LOCATION
                        Vertex AI region / location (env: VERTEX_LOCATION)
  -m, --model MODEL     Gemini model ID (env: VERTEX_MODEL)
  -k, --api-key API_KEY
                        Gemini API Key or Vertex AI express mode key
```

---

## Next Steps

See [SETUP.md](SETUP.md) for authenticating to Google Cloud or setting up an API key, and [README.md](README.md) for quick invocation commands.