docs(masterplan): legg til ML-spor ML-1/2/3, koordiner telemetri A7 vs ml/telemetry.py, oppdater mode-navn til light/heavy

This commit is contained in:
chrischristiansen-glitch 2026-05-26 01:23:47 +02:00
parent 5e1bb4e7ab
commit 3e515bf86f

View File

@ -1,7 +1,7 @@
# VAUCO MASTERPLAN — Chris Christiansen
**Sist oppdatert: 2026-05-24 CEST**
**Status: Repo ferdig — GCP gjenstaar (A4A9 neste) | LLM-strategi: Lett front / tung bakkant — se LLM-RUTINGSSTRATEGI**
**Sist oppdatert: 2026-05-26 CEST**
**Status: Cloud Run live (light/heavy) | A5 Memory Bank gjenstår | ML-1 implementert | B-fasen neste**
---
@ -85,29 +85,26 @@ bash infrastructure/03-teardown.sh
**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
[x] A1 — cp .env.example .env og fyll inn verdier
[x] A2 — bash infrastructure/00-authcheck.sh
[x] A3 — bash infrastructure/01-setupenv.sh
[x] A4 — bash infrastructure/07-rag-setup.sh
RAG corpus: projects/357036551735/locations/europe-west1/ragCorpora/6917529027641081856
[ ] 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)
[x] A6 — Cloud Run live: osvauco-agent (europe-west1)
URL: https://osvauco-agent-357036551735.europe-west1.run.app
Modes: light (gemini-2.0-flash) | heavy (gemini-2.5-pro)
Env: GOOGLE_CLOUD_LOCATION=us-central1 for modellkall
[x] A7 — bash infrastructure/04-observability-setup.sh
TELEMETRI-KOORDINERING: A7 (Cloud Monitoring/Logging) og ml/telemetry.py er komplementære:
- ml/telemetry.py: JSONL til /tmp/vauco_telemetry/ — agent-nivå (latens, mode, suksess)
- A7 Cloud Monitoring: GCP-nivå (CPU, minne, request-rate, feil-rate)
- I prod: GCS sink fra /tmp/ → gs://propane-will-491900-m5-telemetry/ (se 10-cost-guard.sh)
Ingen konflikt — to lag, ulik granularitet. Begge beholdes.
[x] A8 — bash infrastructure/03-teardown.sh (kjør hver kveld)
[x] A9 — bash infrastructure/11-billing-iam-hardening.sh
```
---
@ -120,47 +117,53 @@ bash infrastructure/03-teardown.sh
```
[ ] 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
[ ] DX3 — Konfigurer Playbook med norsk systemprompt
[ ] 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 |
---
## FASE ML — ML-lag for OPAX (parallelt med B/C)
**Mål: Agentene kjører parallelt, lærer fra bruk, gir strategisk innsikt**
**Filer: `ml/`, `AGENTS.md`, `docs/ml-integration.md`**
```
[x] ML-1 — Grunnlag (implementert 2026-05-25)
Komponenter:
ml/task_graph.py — Dask DAG for parallell agent-kjøring
ml/state_store.py — Parameter Server state (in-memory)
ml/telemetry.py — JSONL-logging per agent-kall og DAG-kjøring
Endepunkter i main.py:
POST /run — enkelt kall med telemetri + state push
POST /run/dag — parallell DAG over liste av meldinger
GET /state — live Parameter Server snapshot
GET /telemetry/history — siste N state-operasjoner
Telemetri-koordinering: se A7-notat over
[ ] ML-2 — Adaptiv intelligens (planlagt)
ml/feedback_loop.py — inkrementell feedback-loop (vauco-gemini-tui-bridge)
ml/hypertuner.py — ASHA hyperparametertuning (vauco-bootstrap)
ml/heavy_predictor.py — heavy-mode prediksjon basert på historikk (OSVauco)
Krav: dask-ml>=2024.4.0, ray[tune]>=2.10.0
Trigger: nok telemetri-data fra ML-1 (> 500 kall)
[ ] ML-3 — Strategisk innsikt (planlagt)
ml/agent_importance.py — XGBoost feature importance (OSVauco)
experiments/pbt.py — Population-Based Training (deep-dream)
Krav: xgboost>=2.0.0
Trigger: ML-2 ferdig + Fase C første kunde
```
**Telemetri-ruting (ML-lag):**
| Miljø | Lokasjon | Arkivering |
|---|---|---|
| DX1DX3 (bygging + testing) | ~500 | ~$6 |
| DX4DX5 (integrasjon) | ~1 000 | ~$12 |
| 30 dager pilot (10k req/mnd) | 10 000 | ~$120 |
| **Buffer igjen av kr 5 822** | — | **~$412 (~kr 4 300)** |
| Lokal dev | `/tmp/vauco_telemetry/` | Manuell |
| Cloud Run | `/tmp/vauco_telemetry/` | `10-cost-guard.sh` cron → GCS |
| Prod skala | `gs://propane-will-491900-m5-telemetry/` | Auto via GCS sink |
---
@ -170,22 +173,13 @@ bash infrastructure/03-teardown.sh
```
[ ] 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
[ ] B2 — Opprett GitHub PAT og legg i Secret Manager
[ ] 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
[ ] B4 — Legg til webhook URL i Secret Manager
[ ] B5 — bash infrastructure/10-cost-guard.sh
Aktiverer auto-teardown Cloud Function + chat-varsling ved budsjett-overskridelse
Aktiverer auto-teardown Cloud Function + chat-varsling
OBS: 10-cost-guard.sh skal også sette opp GCS sink for ML-telemetri
[ ] 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)
```
---
@ -195,21 +189,10 @@ bash infrastructure/03-teardown.sh
**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
[ ] C1 — Pakk vauco-bootstrap som Terraform-modul
[ ] C2 — Pakk vauco-os som kundeflate
[ ] 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 DX1DX5)
```
---
@ -219,49 +202,20 @@ bash infrastructure/03-teardown.sh
| Script | Rolle | Status |
|--------|-------|--------|
| `00-authcheck.sh` | Verifiser gcloud-innlogging | Klar |
| `01-setupenv.sh` | Aktiver APIs, SA, IAM, budsjetter ($75+$500), Pub/Sub | Klar |
| `01-setupenv.sh` | Aktiver APIs, SA, IAM, budsjetter, 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 |
| `04-observability-setup.sh` | Cloud Monitoring + alerting (GCP-nivå) | Klar |
| `05-cloudrun-deploy.sh` | ADK-agent til Cloud Run | Klar |
| `06-cicd-setup.sh` | GitHub → Cloud Build **2nd gen** | Oppdatert |
| `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** |
| `10-cost-guard.sh` | Cloud Function auto-teardown + GCS ML-telemetri sink | **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 |
@ -277,64 +231,61 @@ Breakeven: 1 kunde til $300-500/mnd dekker alle kostnader.
| 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 |
| OQ-12 | gemini-2.0-flash ikke tilgjengelig europe-west1 | **LØST** — GOOGLE_CLOUD_LOCATION=us-central1 for modellkall |
| OQ-13 | ML-telemetri /tmp/ flyktig i Cloud Run | B5: GCS sink via 10-cost-guard.sh |
---
## TERRAFORM-VEIKART (Fase C)
## BEKREFTET GA-API
Terraform introduseres **ikke** for nåværende infra — gcloud-scripts er tilstrekkelig.
Terraform blir relevant ved kunde-onboarding:
| 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 |
| CMEK ikke for RAG Engine | Ikke støttet (OQ-03) |
| Idempotente scripts | Trygt å kjøre flere ganger |
| `03-teardown.sh` hver kveld | Agent Runtimes koster 24/7 |
| Conversational Agents (Dialogflow CX) | Playbooks GA |
| Dask `scheduler="threads"` i Cloud Run | Bekreftet — ingen worker-prosesser nødvendig |
| Når | Hva |
---
## DRIFTSKOSTNADER
| Scenario | Kostnad/mnd |
|---|---|
| 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 |
| Bare deg (dev, teardown daglig) | ~$25-75 |
| Dev + Dialogflow CX FAQ (10k req) | ~$145-195 |
| 1 betalende kunde (lett prod) | ~$115-280 |
| Medioteq-type (klinisk, compliance) | ~$220-350 |
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*
Breakeven: 1 kunde til $300-500/mnd dekker alle kostnader.
---
## LLM-RUTINGSSTRATEGI
**Prinsipp:** Lett modell i front, tung modell ved behov i bakkant - vurdert per modul og kost.
**Prinsipp:** Lett modell i front (light), tung modell ved behov (heavy).
| Modell | Pris input/output (per 1M) | EU-tilgang | Bruksomrade |
| Modell | Pris input/output (per 1M) | EU-tilgang | Bruksområde |
|---|---|---|---|
| `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 |
| `gemini-2.0-flash` | $0.10 / $0.40 | Ja (europe-west4) | light — alle enkle kall |
| `gemini-2.5-pro` | $1.25 / $10.00 | Ja (europe-west4) | heavy — kompleks reasoning, compliance |
| `gemini-3.5-flash` | $1.50 / $9.00 | Nei (kun US/global) | heavy reasoning, Fase C |
**Rutetabell per modul:**
| Modul / Agent | Standard modell | Eskalering til | Trigger |
| Modul / Agent | light | heavy | 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.
| OPAX billing-agent | `gemini-2.0-flash` | `gemini-2.5-pro` / `gemini-3.5-flash` | `mode: heavy` |
| RAG retrieval | `gemini-2.0-flash` | `gemini-2.5-pro` | Komplekse flertrinns-spørsmål |
| Memory Bank oppslag | `gemini-2.0-flash` | — | Aldri |
| TUI-cockpit | `gemini-2.0-flash` | `gemini-3.5-flash` | Dyp analyse |
| vauco-os (kundeflate) | `gemini-2.0-flash` | `gemini-2.5-pro` | Compliance |
| Dialogflow CX Playbooks | Gemini (managed) | — | Native |
| Fase C: Terraform-gen | `gemini-3.5-flash` | — | Standard for modulen |
| ML-2 heavy predictor | `gemini-2.0-flash` | — | Predikerer heavy-behov |
**Request-format:**
```json
@ -346,39 +297,31 @@ Bruksomrader: kompleks multi-agent analyse, Terraform-generering, kunde-onboardi
}
```
**Modellfordeling i heavy-modus (OPAX):**
**Modellfordeling:**
| Parameter | Standard | Heavy (OPAX) |
| Parameter | light | heavy |
|---|---|---|
| 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) |
| Multi-agent pipeline | Nei | Ja |
| Budsjettgrense | $1/task | $3/task |
**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)
Legacy-verdier `A` og `A+` aksepteres og normaliseres automatisk.
**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"}
```
## TERRAFORM-VEIKART (Fase C)
**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
```
| Når | Hva |
|---|---|
| Fase C: Medioteq | `vauco-bootstrap` → Terraform-modul |
| Per kunde | `terraform apply -var="customer_id=X"` |
| Ressurser per modul | Cloud Run, Cloud Build 2nd gen, IAP, budsjett, SA, Dialogflow CX agent, ML state store |
| State-backend | GCS bucket (`TF_STATE_BUCKET`) |
| Fase D | Terraform Cloud for sentralisert state |
---
*OSVauco-NMTMD-GCOS | propane-will-491900-m5 | us-central1 (modell) / europe-west1 (infra)*