botWebWars/botagent_gear/SETUP.md

# Google Cloud Vertex AI Setup Guide

This guide walks you through setting up Google Cloud authentication and Vertex AI access for `botagent_gear`.

Since you have **not authenticated to a Google Cloud project yet and have not created a key**, choose the method that best fits your workflow below.

---

## Quick Navigation
- [Option 1: Google Cloud CLI & User Authentication (Recommended)](#option-1-google-cloud-cli--user-authentication-recommended)
- [Option 2: Service Account Key (Headless / Automated Servers)](#option-2-service-account-key-headless--automated-servers)
- [Option 3: Gemini API Key (Fastest Setup via Google AI Studio)](#option-3-gemini-api-key-fastest-setup-via-google-ai-studio)
- [Verification & Troubleshooting](#verification--troubleshooting)

---

## Prerequisites
- A Google Cloud account ([Google Cloud Free Tier](https://cloud.google.com/free) includes $300 in credits).
- A Google Cloud Project (or permission to create one).

---

## Option 1: Google Cloud CLI & User Authentication (Recommended)

This is the standard, interactive developer workflow using the Google Cloud CLI (`gcloud`).

### Step 1: Install `gcloud` (if not installed)
Check if `gcloud` is installed:
```bash
gcloud --version
```
If not installed, install it following [Google Cloud SDK Installation](https://cloud.google.com/sdk/docs/install) (or on Debian/Ubuntu: `sudo apt-get install google-cloud-cli`).

### Step 2: Log into your Google Cloud account
```bash
gcloud auth login
```
A browser window will open asking you to sign in with your Google account.

### Step 3: Set or Create your Project
List existing projects:
```bash
gcloud projects list
```
If you already have a project, set it as active:
```bash
gcloud config set project YOUR_PROJECT_ID
```
Or create a brand new project:
```bash
gcloud projects create my-botwebwars-project --name="botWebWars Project"
gcloud config set project my-botwebwars-project
```
*(Ensure billing is enabled for your project in the [Google Cloud Console Billing section](https://console.cloud.google.com/billing).)*

### Step 4: Enable the Vertex AI API
Run:
```bash
gcloud services enable aiplatform.googleapis.com
```

### Step 5: Authorize Application Default Credentials (ADC)
This allows Python scripts and SDKs to authenticate automatically:
```bash
gcloud auth application-default login
```
Follow the browser prompt to grant access.

### Step 6: Set Environment Variables (Optional but convenient)
Add to your `~/.bashrc` or run in your terminal:
```bash
export VERTEX_PROJECT_ID=$(gcloud config get-value project)
export VERTEX_LOCATION="us-central1"
export VERTEX_MODEL="gemini-2.5-flash"
```

---

## Option 2: Service Account Key (Headless / Automated Servers)

If running in a Docker container, CI/CD pipeline, or remote VM without a web browser, use a Service Account:

### Step 1: Create a Service Account
```bash
export PROJECT_ID=$(gcloud config get-value project)

gcloud iam service-accounts create botwebwars-agent \
    --display-name="botWebWars Vertex AI Agent"
```

### Step 2: Grant the Vertex AI User role
```bash
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:botwebwars-agent@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"
```

### Step 3: Create and Download the Key File
```bash
mkdir -p ~/.gcp
gcloud iam service-accounts keys create ~/.gcp/vertex-key.json \
    --iam-account="botwebwars-agent@${PROJECT_ID}.iam.gserviceaccount.com"
```

### Step 4: Point to the Key File
```bash
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcp/vertex-key.json"
export VERTEX_PROJECT_ID="$PROJECT_ID"
export VERTEX_LOCATION="us-central1"
```

---

## Option 3: Gemini API Key (Fastest Setup via Google AI Studio)

If you prefer using an API key without configuring GCP IAM roles or OAuth tokens:

1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey).
2. Click **Create API Key**.
3. Copy your API key.
4. Export the key:
   ```bash
   export GEMINI_API_KEY="YOUR_API_KEY_HERE"
   ```
The `botagent_gear` agent will detect `GEMINI_API_KEY` and interact with Gemini directly.

---

## Verification & Troubleshooting

### 1. Test your credentials
You can quickly verify that Vertex AI accepts your credentials:
```bash
python3 -c "
import subprocess, requests, json, os

token = os.getenv('VERTEX_ACCESS_TOKEN') or subprocess.check_output(['gcloud', 'auth', 'print-access-token'], text=True).strip()
project = os.getenv('VERTEX_PROJECT_ID') or subprocess.check_output(['gcloud', 'config', 'get-value', 'project'], text=True).strip()
location = os.getenv('VERTEX_LOCATION', 'us-central1')
model = os.getenv('VERTEX_MODEL', 'gemini-2.5-flash')

url = f'https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/google/models/{model}:generateContent'
headers = {'Authorization': f'Bearer {token}', 'Content-Type': 'application/json'}
payload = {'contents': [{'role': 'user', 'parts': [{'text': 'Hello Gemini'}]}]}

res = requests.post(url, headers=headers, json=payload, timeout=20)
print('Status:', res.status_code)
if res.status_code == 200:
    print('Vertex AI connection successful! Candidate:', res.json()['candidates'][0]['content']['parts'][0]['text'].strip())
else:
    print('Error response:', res.text)
"
```

### 2. Common Errors

| Error | Cause | Solution |
|---|---|---|
| `403 PermissionDenied: Vertex AI API has not been used...` | API is disabled | Run `gcloud services enable aiplatform.googleapis.com` |
| `401 Unauthorized` / `Token expired` | Token expired or invalid | Re-run `gcloud auth application-default login` or refresh `gcloud auth login` |
| `404 Publisher model ... not found` | Region does not have the model | Default to `us-central1`, `us-east4`, or check model name (`gemini-2.5-flash`, `gemini-1.5-flash`) |
| `No Google Cloud project ID detected` | Project is not set | Run `gcloud config set project <PROJECT_ID>` or export `VERTEX_PROJECT_ID` |

Once setup is complete, proceed to [INSTALL.md](INSTALL.md) and [README.md](README.md) to install dependencies and run your agent!