# Ghost Office — Configuration Guide (GenAI Connection)

This guide explains how to configure GhostOffice for **Google Vertex AI (GenAI)** and optional **local models via Ollama**.

---

## Config file location

- **When running the .exe:** The config file is in the `ghost_data` folder **next to the executable**:  
  `ghost_data/user_settings.json`
- **When running from source:** Same path: `ghost_data/user_settings.json` in the project folder.

---

## Config at a glance

| Field | Purpose |
|-------|--------|
| `project_id` | Google Cloud project ID (Vertex AI). Leave empty for local-only. |
| `location` | Vertex AI region (e.g. `us-central1`). Leave empty for local-only. |
| `credentials_path` | Path to your GCP OAuth credentials JSON file. Leave empty for local-only. |
| `ollama_url` | Base URL for Ollama (default `http://localhost:11434`). Optional; skip if you use only Vertex AI. |

**Example (Google Cloud + default Ollama):**

```json
{
    "project_id": "my-gcp-project",
    "location": "us-central1",
    "credentials_path": "C:\\path\\to\\credentials.json",
    "ollama_url": "http://localhost:11434"
}
```

**Example (local / offline only):**

```json
{
    "project_id": "",
    "location": "",
    "credentials_path": "",
    "ollama_url": "http://localhost:11434"
}
```

---

## Google Vertex AI (GenAI) setup

You will need a Google account and a Google Cloud project with **billing enabled** (required for Vertex AI).

### Option A: Setup via Google Cloud Console

1. **Create a Google Cloud project:** Go to [Google Cloud Console](https://console.cloud.google.com/), create a project, and ensure billing is enabled.
2. **Enable APIs:** Navigate to **APIs & Services** → **Enable APIs and Services**. Search for and enable the **Vertex AI API** (`aiplatform.googleapis.com`).
3. **Configure OAuth consent screen:** 
   - Navigate to **APIs & Services** → **OAuth consent screen**.
   - Choose **External** (or Internal if you have a Google Workspace) and fill out the required app details.
   - Add your own email as a **Test User** (if leaving the app in "Testing" mode).
4. **Create OAuth 2.0 credentials:**
   - Go to **APIs & Services** → **Credentials**.
   - Click **Create Credentials** → **OAuth client ID**.
   - Select Application type: **Desktop app**.
   - Download the resulting JSON file.
5. **Set the config:**
   - Put the JSON file in a known location (e.g., next to the `.exe` or in a dedicated folder).
   - In `user_settings.json` (or the Setup Wizard), set `credentials_path` to the full path of that file.
   - Set `project_id` to your GCP project ID and `location` to a Vertex region (e.g., `us-central1`, `europe-west4`).
6. **First run:** GhostOffice will open a browser for sign-in. After you authorize, a token is stored in `ghost_data/token.json`.

### Option B: Quick Setup with Google Cloud CLI (Advanced)

If you prefer using the terminal, you can script the project and API setup using the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install):

```bash
# 1. Create a new project and set it as default
gcloud projects create my-ghostoffice-project --name="GhostOffice"
gcloud config set project my-ghostoffice-project

# 2. Link your billing account (find your ID with: gcloud billing accounts list)
gcloud billing projects link my-ghostoffice-project --billing-account=YOUR_BILLING_ACCOUNT_ID

# 3. Enable the Vertex AI API
gcloud services enable aiplatform.googleapis.com
```

**Note:** You must still complete the **OAuth consent screen** and **OAuth Desktop client creation** manually in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) as shown in Option A (Steps 3 and 4), because Google does not currently provide a simple `gcloud` command to generate Desktop App OAuth credentials for end users.

### Troubleshooting

- **"API not enabled" error:** Double-check that `aiplatform.googleapis.com` is enabled for the exact `project_id` in your config.
- **"Access blocked: project has not completed Google verification":** Ensure you added yourself as a **Test User** in the OAuth consent screen.
- **"Billing not enabled":** Vertex AI models require an active billing account linked to the project, even if usage falls within the free tier.
- **Wrong Region:** If requests fail, verify your `location` in the config is a valid Vertex AI region where Gemini is supported (e.g., `us-central1`).

---

## Ollama (optional — local models)

- **You can skip Ollama** and use only Google Vertex AI. Leave `ollama_url` as default or ignore it; the app will use cloud models only.
- **If you want local models:**
  1. **Download and install Ollama** from [ollama.com](https://ollama.com) (e.g. [ollama.com/download](https://ollama.com/download)).
  2. **Hardware:** For good performance, a **GPU with 8GB+ VRAM** is recommended. You can also run smaller models on **CPU** with sufficient RAM (e.g. 16GB+); expect slower responses.
  3. After installation, start Ollama and pull a model (e.g. `ollama pull llama3.2`). The app discovers models via the Ollama API at `ollama_url` (default `http://localhost:11434`).
  4. In the app, use **Settings** to change the Ollama base URL if needed (e.g. a different host/port). The value is saved in `user_settings.json`.

---

## First run and Setup Wizard

- If `user_settings.json` does not exist, the app launches the **Setup Wizard**.
- You can choose **Google Cloud (Vertex AI)** or **Local / Offline Only**.
- The wizard includes an optional step about Ollama (Download link and **Skip** if you use only cloud).

For manual setup, create or edit `ghost_data/user_settings.json` as in the examples above and restart the app.
