diff --git a/MASTERPLAN.md b/MASTERPLAN.md index 8120961..8e8b8c7 100644 --- a/MASTERPLAN.md +++ b/MASTERPLAN.md @@ -1,7 +1,7 @@ # 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** +**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 | |---|---|---| -| 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)** | +| 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 DX1–DX5) ``` --- @@ -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)*