OSVauco/MASTERPLAN.md

# VAUCO MASTERPLAN — Chris Christiansen

**Sist oppdatert: 2026-05-24 CEST**
**Status: Repo ferdig — GCP gjenstaar (A4–A9 neste) | LLM-strategi: Lett front / tung bakkant — se LLM-RUTINGSSTRATEGI**

---

## KONTEKST — Hva vi bygger

Ett AI-drevet operativsystem (OPAX) som kjører på Google Cloud.
Du er første kunde. Når det virker for deg → selg det til andre.

**Repo-oversikt:**
| Repo | Hva det er |
|---|---|
| `OSVauco` | Regler, GCP-scripts, agenter, docs — KJERNEN |
| `vauco-gemini-tui-bridge` | Din TUI-cockpit |
| `vauco-os` | Det kundene bruker |
| `vauco-bootstrap` | Onboarding av nye kunder (→ Terraform-modul i Fase C) |
| `deep-dream` | Strategisk visjon — aldri deploy herfra |

---

## AGENT-IDENTITET

| Identitet | E-post | Rolle | Formål |
|---|---|---|---|
| Eier / admin | `chris.christiansen@vauco.no` | `billing.admin` + `billing.viewer` | Full kontroll |
| Agent (OPAX) | `jason.vauger@vauco.no` | `billing.viewer` | Hente og rapportere kostnadsdata autonomt |
| Fremtidig gruppe | `billing@vauco.no` | `billing.viewer` (Fase C) | Delt innboks for team og kunder |

**Agent-kapabiliteter med `billing.viewer`:**
- Svare på «Hva koster dette prosjektet denne måneden?»
- Sende ukentlig kostnadsrapport til chat-appen
- Reagere på Pub/Sub budget-alerts (via `10-cost-guard.sh`)
- **Ikke:** endre IAM, budsjetter eller koble prosjekter

---

## CLOUD SHELL QUICK-START (kopi-klipp)

> Bruk Cloud Shell: https://shell.cloud.google.com

```bash
# Steg 1: Klon og sett opp miljø
gcloud config set project propane-will-491900-m5
git clone https://github.com/chrischristiansen-glitch/OSVauco.git ~/OSVauco
cd ~/OSVauco

# Steg 2: Kopier og rediger .env
cp .env.example .env
nano .env
# Fyll ut: BILLING_ACCOUNT_ID, ALERT_EMAIL, GITHUB_APP_INSTALLATION_ID
# Alle andre verdier er ferdig-forhåndsutfylt

# Steg 3: Installer Python-avhengigheter
pip install google-adk google-cloud-aiplatform>=1.111.0 --quiet

# Steg 4: Kjør i rekkefølge (kilde .env først)
source .env
bash infrastructure/00-authcheck.sh
bash infrastructure/01-setupenv.sh
bash infrastructure/07-rag-setup.sh
# *** Kopier RAG_CORPUS_NAME fra output inn i .env ***
nano .env
source .env

bash infrastructure/08-memorybank-setup.sh
# *** Kopier MEMORY_ENGINE_NAME fra output inn i .env ***
nano .env
source .env

bash infrastructure/05-cloudrun-deploy.sh
bash infrastructure/04-observability-setup.sh
bash infrastructure/11-billing-iam-hardening.sh

# Om kvelden (OBLIGATORISK — unngå 24/7-fakturering):
bash infrastructure/03-teardown.sh
```

---

## FASE A — Ferdigstill kjernen (GCP oppe)

**Mål: Agenten din er live på Google Cloud | Tid: Ca. 2 timer**

```
[ ] A1 — cp .env.example .env og fyll inn verdier
        PROJECT_ID=propane-will-491900-m5
        REGION=us-central1
        BILLING_ACCOUNT_ID=0171F6-057E6B-A260BA
        ALERT_EMAIL=chris.christiansen@vauco.no
        ORCHESTRATOR_MODEL=gemini-2.0-flash
        SUBAGENT_MODEL=gemini-2.0-flash
[ ] A2 — bash infrastructure/00-authcheck.sh
[ ] A3 — bash infrastructure/01-setupenv.sh
        Oppretter: budsjetter ($75 dev + $500 prod), Pub/Sub topic
[ ] A4 — bash infrastructure/07-rag-setup.sh
        OQ-02: Script faller automatisk tilbake til us-east1 om nødvendig
        ACTION: Kopier RAG_CORPUS_NAME til .env
[ ] A5 — bash infrastructure/08-memorybank-setup.sh
        OQ-01: Python SDK only (auto-installert av script)
        ACTION: Kopier MEMORY_ENGINE_NAME til .env
[ ] A6 — bash infrastructure/05-cloudrun-deploy.sh
[ ] A7 — bash infrastructure/04-observability-setup.sh
[ ] A8 — bash infrastructure/03-teardown.sh   (kjør hver kveld)
[ ] A9 — bash infrastructure/11-billing-iam-hardening.sh
        Gir billing.viewer til: chris.christiansen@vauco.no + jason.vauger@vauco.no
        Løser GCP billing health-advarsel: "0 billing account viewers"
        Fjerner billing.creator fra domenet (hvis ORG_DOMAIN er satt i .env)
```

---

## FASE A2 — Dialogflow CX FAQ-agent (parallelt med A4–A9)

**Mål: Generativ FAQ-agent live på OSVauco | Tid: Ca. 3–5 timer**
**Kreditt: kr 5 822 (dialogflow_cx_credit_v2-0171F6-057E6B-A260BA) + $1 000 Playbooks-trial**
**Detaljer: se `docs/dialogflow-cx-budget-plan.md`**

```
[ ] DX1 — Opprett Playbook-agent i Conversational Agents Console
        URL: https://console.cloud.google.com/conversational-agents
        Prosjekt: propane-will-491900-m5 | Region: us-central1
        Type: Generative (Playbooks) — IKKE Flows
        Språk: Norsk (nb) + Engelsk (en)
        Kreditten aktiveres automatisk — ingen manuell kobling nødvendig

[ ] DX2 — Last opp FAQ-innhold som Data Store
        Console: Agent → Data Stores → Create
        Kilde: Last opp markdown/PDF FAQ-filer fra docs/
        Alternativ: Link til nettsted (crawl) for automatisk oppdatering
        ACTION: Kopier DATA_STORE_ID til .env

[ ] DX3 — Konfigurer Playbook med norsk systempromptin
        Instruksjon: "Du er OPAX-assistent for OSVauco. Svar alltid på norsk.
        Bruk kun informasjon fra Data Store. Henvis til support ved usikkerhet."
        Test: 10 typiske FAQ-spørsmål manuelt i Console

[ ] DX4 — Koble webhook mot OSVauco Cloud Run (etter A6)
        Requires: A6 (cloudrun-deploy) fullført
        Metode: Dialogflow CX → Fulfillment → Webhook → Cloud Run URL
        Auth: Bearer token fra Service Account (jason.vauger@vauco.no)
        Bruksområde: Live data (f.eks. prosjektstatus, kostnader) via OPAX-agenten

[ ] DX5 — Publiser via Dialogflow Messenger (web-widget)
        Integrasjon: Agent → Integrations → Dialogflow Messenger
        Legg til script-tag i vauco-os frontend
        Test på mobil og desktop

[ ] DX6 — Sett budsjett-alert for Dialogflow CX
        Grense: $400 av $550 tilgjengelig kreditt
        Console: Billing → Budgets & Alerts → Create budget
        Koble til Pub/Sub topic fra A3 (10-cost-guard.sh håndterer auto-teardown)
```

**Kostnadsestimat Fase A2:**
| Aktivitet | Requests | Estimert kostnad |
|---|---|---|
| DX1–DX3 (bygging + testing) | ~500 | ~$6 |
| DX4–DX5 (integrasjon) | ~1 000 | ~$12 |
| 30 dager pilot (10k req/mnd) | 10 000 | ~$120 |
| **Buffer igjen av kr 5 822** | — | **~$412 (~kr 4 300)** |

---

## FASE B — Sikring og CI/CD

**Mål: Begrenset tilgang og aktiv CI/CD | Tid: 1 time**

```
[ ] B1 — bash infrastructure/02-deploy.sh   (IAP på opax.vauco.no)
[ ] B2 — Opprett GitHub PAT og legg i Secret Manager:
        gcloud secrets create github-token --data-file=<(echo -n "ghp_TOKEN")
        Finn GITHUB_APP_INSTALLATION_ID:
        https://github.com/settings/installations → Cloud Build-appen → ID i URL
        Fyll inn GITHUB_APP_INSTALLATION_ID i .env
[ ] B3 — bash infrastructure/06-cicd-setup.sh
        OQ-04: LØST — Cloud Build 2nd gen, ingen manuell OAuth i Console
[ ] B4 — Legg til webhook URL i Secret Manager:
        gcloud secrets create webhook-url --data-file=<(echo -n "https://DIN-WEBHOOK-URL")
        Se: infrastructure/notifications/webhook-setup.md
[ ] B5 — bash infrastructure/10-cost-guard.sh
        Aktiverer auto-teardown Cloud Function + chat-varsling ved budsjett-overskridelse
[ ] B6 — Eksporter Dialogflow CX agent til versjonskontroll
        gcloud beta dialogflow agents export --location=us-central1 \
          --destination=gs://propane-will-491900-m5-dialogflow-backup/agent.zip
        Legg backup-rutine i CI/CD pipeline (etter B3)
```

---

## FASE C — Første salgsmodul

**Mål: Ny kunde onboardet på 30 minutter | Tid: Ukentlig arbeid**

```
[ ] C1 — Pakk `vauco-bootstrap` som Terraform-modul for kunde-onboarding
        Ressurser per kunde: Cloud Run, Artifact Registry, Cloud Build 2nd gen,
        IAP, budsjett-alert, Service Account
        Terraform-variabler: customer_id, customer_project_id, customer_region
        State-backend: GCS bucket (TF_STATE_BUCKET i .env)
[ ] C2 — Pakk `vauco-os` som kundeflate
        Inkluder Dialogflow Messenger widget (fra DX5) i kundefront
[ ] C3 — Opprett billing@vauco.no som Google Group
        Legg inn: chris.christiansen@vauco.no + jason.vauger@vauco.no
        Oppdater .env: BILLING_VIEWER_EMAILS="billing@vauco.no"
        Kjør på nytt: bash infrastructure/11-billing-iam-hardening.sh
[ ] C4 — Første kunde: Medioteq
        Region: europe-north1, separat GCP-prosjekt
        Kjør: terraform apply -var="customer_id=medioteq"
        Inkluder dedikert Dialogflow CX-agent per kunde (replikat av DX1–DX5)
```

---

## INFRASTRUKTUR

| Script | Rolle | Status |
|--------|-------|--------|
| `00-authcheck.sh` | Verifiser gcloud-innlogging | Klar |
| `01-setupenv.sh` | Aktiver APIs, SA, IAM, budsjetter ($75+$500), Pub/Sub | Klar |
| `02-deploy.sh` | IAP-deploy på eget domene | Klar |
| `03-teardown.sh` | Riv ned Cloud Run | Klar |
| `04-observability-setup.sh` | Monitoring + alerting | Klar |
| `05-cloudrun-deploy.sh` | ADK-agent til Cloud Run | Klar |
| `06-cicd-setup.sh` | GitHub → Cloud Build **2nd gen** | Oppdatert |
| `07-rag-setup.sh` | RAG Engine corpus + fallback | Oppdatert |
| `08-memorybank-setup.sh` | Memory Bank + auto-install | Oppdatert |
| `09-cost-check.sh` | Kostnadsoversikt + Artifact Registry | Klar |
| `10-cost-guard.sh` | Cloud Function auto-teardown + webhook-alert | **Ny** |
| `11-billing-iam-hardening.sh` | Billing IAM: viewer-roller + fjern domain Creator | **Ny** |

---

## BEKREFTET GA-API

| API | Status |
|-----|--------|
| `google.adk.Agent` (ikke LlmAgent) | Bekreftet GA-API |
| `load_memory_tool` | Bekreftet fra adk-python samples |
| Cloud Build 2nd gen (`cloudbuildv2`) | Bekreftet GA — programmatisk GitHub-kobling |
| CMEK ikke for RAG Engine | Ikke støttet (OQ-03) |
| CI/CD `--no-traffic` | Manuell trafikkbytte — HITL |
| Idempotente scripts | Trygt å kjøre flere ganger |
| `03-teardown.sh` hver kveld | Agent Runtimes koster 24/7 |
| Conversational Agents (Dialogflow CX) | Playbooks GA — Data Store + webhook |

---

## DRIFTSKOSTNADER

| Scenario | Kostnad/mnd |
|---|---|
| Bare deg (dev, teardown daglig) | ~$25-75 |
| Dev + Dialogflow CX FAQ (10k req) | ~$145-195 (Playbooks ~$120 inkl.) |
| 1 betalende kunde (lett prod) | ~$115-280 |
| Medioteq-type (klinisk, compliance) | ~$220-350 |

Breakeven: 1 kunde til $300-500/mnd dekker alle kostnader.
**Dialogflow CX-kreditten (kr 5 822) dekker ~4 måneder pilot uten reell kostnad.**

---

## KJENTE HULL

| ID | Hva | Workaround / Status |
|---|---|---|
| OQ-01 | Memory Bank — ingen gcloud CLI | Python SDK only |
| OQ-02 | RAG Engine regional availability | Auto-fallback til us-east1 |
| OQ-03 | CMEK ikke for RAG Engine | VPC-SC only |
| OQ-04 | Cloud Build GitHub OAuth | **LØST** — 2nd gen programmatisk connection |
| OQ-05 | gcloud alpha monitoring ustabil | Fallback til true |
| OQ-06 | Memory Bank auto-discovery | Eksplisitt env var |
| OQ-07 | Monitoring email flag-format | Teste i dev |
| OQ-08 | VPC connector e2-micro regional | Default us-central1 |
| OQ-09 | GCP billing: 0 viewers | **LØST** — `11-billing-iam-hardening.sh` |
| OQ-10 | GCP billing: Creator på domenet | **LØST** — fjernes når ORG_DOMAIN er satt |
| OQ-11 | Dialogflow CX Data Store norsk indeksering | Teste med nb-NO locale i DX2 |

---

## TERRAFORM-VEIKART (Fase C)

Terraform introduseres **ikke** for nåværende infra — gcloud-scripts er tilstrekkelig.
Terraform blir relevant ved kunde-onboarding:

| Når | Hva |
|---|---|
| Fase C: Medioteq | `vauco-bootstrap` → Terraform-modul |
| Per kunde | `terraform apply -var="customer_id=X"` oppretter isolert GCP-miljø |
| Ressurser per modul | Cloud Run, Cloud Build 2nd gen connection, IAP, budsjett, SA, **Dialogflow CX agent** |
| State-backend | GCS bucket (`TF_STATE_BUCKET`) — én bucket, én state-fil per kunde |
| Fase D | Terraform Cloud for sentralisert state og CI/CD på tvers av kunder |

Terraform-ressurser:
- `google_cloudbuildv2_connection` — programmatisk GitHub-kobling per kunde
- `google_cloudbuildv2_repository` — repo-link
- `google_cloudbuild_trigger` — push-til-main trigger
- `google_billing_budget` — budsjett-alert per kunde
- `google_cloud_run_v2_service` — Cloud Run-tjeneste
- `google_dialogflow_cx_agent` — FAQ-agent per kunde (Fase C)

---

*OSVauco-NMTMD-GCOS | propane-will-491900-m5 | us-central1*

---

## LLM-RUTINGSSTRATEGI

**Prinsipp:** Lett modell i front, tung modell ved behov i bakkant - vurdert per modul og kost.

| Modell | Pris input/output (per 1M) | EU-tilgang | Bruksomrade |
|---|---|---|---|
| `gemini-2.0-flash` | $0.10 / $0.40 | Ja (europe-west4) | Standard - alle enkle kall |
| `gemini-2.5-pro` | $1.25 / $10.00 | Ja (europe-west4) | Kompleks reasoning, compliance, OPAX heavy |
| `gemini-3.5-flash` | $1.50 / $9.00 | Nei (kun US/global) | Tung orkestrering, Fase C, OPAX heavy reasoning |

**Rutetabell per modul:**

| Modul / Agent | Standard modell | Eskalering til | Trigger |
|---|---|---|---|
| OPAX billing-agent (standard) | `gemini-2.0-flash` | - | Aldri - strukturert data |
| **OPAX billing-agent (heavy)** | **`gemini-2.5-pro`** | **`gemini-3.5-flash`** | **`mode: heavy` - komplekse prosjekter / multi-agent** |
| RAG retrieval + svar | `gemini-2.0-flash` | `gemini-2.5-pro` | Komplekse flertrinns-sporsmal |
| Memory Bank oppslag | `gemini-2.0-flash` | - | Aldri - faktahenting |
| TUI-cockpit (operator) | `gemini-2.0-flash` | `gemini-3.5-flash` | Bruker ber om dyp analyse |
| vauco-os (kundeflate) | `gemini-2.0-flash` | `gemini-2.5-pro` | Compliance/kliniske sporsmal |
| **Dialogflow CX Playbooks** | **Gemini (managed)** | - | **Native i plattformen** |
| Fase C: Terraform-gen | `gemini-3.5-flash` | - | Standard for denne modulen |
| Fase C: Kunde-onboarding | `gemini-2.5-pro` | `gemini-3.5-flash` | Multi-step orkestrering |

### OPAX Heavy Mode

OPAX aktiverer `mode: heavy` per request naar prosjektet krever det.
Bruksomrader: kompleks multi-agent analyse, Terraform-generering, kunde-onboarding, dype flertrinns-sporsmal.

**Request-format:**
```json
{
  "message": "...",
  "user_id": "opax",
  "session_id": "opax-proj-001",
  "mode": "heavy"
}
```

**Modellfordeling i heavy-modus (OPAX):**

| Parameter | Standard | Heavy (OPAX) |
|---|---|---|
| Orchestrator | `gemini-2.0-flash` | `gemini-2.5-pro` |
| Sub-agenter | `gemini-2.0-flash` | `gemini-2.5-pro` |
| Reasoning | `gemini-2.0-flash` | `gemini-3.5-flash` |
| Multi-agent pipeline | Nei | Ja (research, compliance, billing sub-agenter) |
| Budsjettgrense | $3/dag per traad | $10/dag (eller per-prosjekt-budsjett) |

**Autoriserte brukere for heavy mode:** `opax`, `admin`
- Andre brukere faar HTTP 403 ved forsok paa `mode: heavy`
- Hard stopp: $1 per oppgave (standard) / $3 per oppgave (heavy)

**Implementasjon (`agent.py` / `config.py`):**
```python
HEAVY_MODE_ALLOWED_USERS = ["opax", "admin"]

def get_models_for_mode(mode: str) -> dict:
    if mode == "heavy":
        return {"orchestrator": "gemini-2.5-pro", "subagent": "gemini-2.5-pro", "reasoning": "gemini-3.5-flash"}
    return {"orchestrator": "gemini-2.0-flash", "subagent": "gemini-2.0-flash", "reasoning": "gemini-2.0-flash"}
```

**Konfigurasjon i `.env`:**
```env
ORCHESTRATOR_MODEL=gemini-2.0-flash
SUBAGENT_MODEL=gemini-2.0-flash
REASONING_MODEL=gemini-3.5-flash
HEAVY_ORCHESTRATOR_MODEL=gemini-2.5-pro
HEAVY_SUBAGENT_MODEL=gemini-2.5-pro
HEAVY_REASONING_MODEL=gemini-3.5-flash
HEAVY_MODE_BUDGET_USD_PER_DAY=10.0
```