372 lines
15 KiB
Markdown
372 lines
15 KiB
Markdown
# VAUCO MASTERPLAN — Chris Christiansen
|
||
|
||
**Sist oppdatert: 2026-05-27 CEST**
|
||
**Status: ✅ FASE A KOMPLETT | ✅ FASE B (B1-B5) KOMPLETT | ML-1 live | Røyktest 10/10 | Fase C neste**
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
---
|
||
|
||
## DNS / DOMENE-ARKITEKTUR
|
||
|
||
> **Arkitekturavgjørelse — 2026-05-26**
|
||
|
||
| Domene | Type | Teknologi | Fase |
|
||
|---|---|---|---|
|
||
| `opax.vauco.no` | Intern cockpit (kun Chris) | CNAME → Cloud Run (gratis) | B1 nå |
|
||
| `kunde1.vauco.no` / kundedomener | Kunde-instanser | LB + IAP (Terraform) | Fase C |
|
||
|
||
**Begrunnelse:**
|
||
- `opax.vauco.no` er et internt arbeidsverktøy for én bruker — Load Balancer ($18-20/mnd) er unødvendig overhead.
|
||
- Kundeinstanser provisjoneres via `vauco-bootstrap` Terraform-modul i Fase C. LB + IAP bakes inn i modulen én gang og kjøres automatisk per kunde med `terraform apply -var="customer_id=X"`.
|
||
- Terraform-modulen (Fase C) skal inkludere: Cloud Run, Cloud Build, IAP, LB, budsjett, SA, Dialogflow CX, ML state store.
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
# Steg 3: Installer Python-avhengigheter
|
||
pip install google-adk google-cloud-aiplatform>=1.111.0 --quiet
|
||
|
||
# Steg 4: Kjør i rekkefølge
|
||
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
|
||
|
||
gcloud run deploy osvauco-agent
|
||
--source . --region europe-west1
|
||
--project propane-will-491900-m5
|
||
--set-secrets RAG_CORPUS=rag-corpus-name:latest
|
||
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=1,GOOGLE_CLOUD_PROJECT=propane-will-491900-m5,GOOGLE_CLOUD_LOCATION=global,MEMORY_ENGINE_NAME=$MEMORY_ENGINE_NAME
|
||
--no-allow-unauthenticated
|
||
|
||
bash infrastructure/04-observability-setup.sh
|
||
bash infrastructure/11-billing-iam-hardening.sh
|
||
bash scripts/smoke-test.sh
|
||
|
||
# Om kvelden (OBLIGATORISK):
|
||
bash infrastructure/03-teardown.sh
|
||
```
|
||
|
||
---
|
||
|
||
## FASE A — Ferdigstill kjernen ✅ KOMPLETT
|
||
|
||
```
|
||
[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
|
||
[x] A5 — bash infrastructure/08-memorybank-setup.sh
|
||
Memory Engine: projects/357036551735/locations/us-central1/reasoningEngines/2260229219579592704
|
||
export MEMORY_ENGINE_NAME="projects/357036551735/locations/us-central1/reasoningEngines/2260229219579592704"
|
||
[x] A6 — Cloud Run live: osvauco-agent (europe-west1) revision 00006-282
|
||
URL: https://osvauco-agent-357036551735.europe-west1.run.app
|
||
Modes: light (gemini-2.5-flash) | heavy (gemini-2.5-pro)
|
||
Env: GOOGLE_CLOUD_LOCATION=global (krav for gemini-2.5-*)
|
||
[x] A7 — bash infrastructure/04-observability-setup.sh
|
||
TELEMETRI-KOORDINERING:
|
||
- ml/telemetry.py: JSONL /tmp/vauco_telemetry/ — agent-nivå
|
||
- A7 Cloud Monitoring: GCP-nivå (CPU, request-rate, feil-rate)
|
||
- Prod: GCS sink via 10-cost-guard.sh (B5)
|
||
[x] A8 — bash infrastructure/03-teardown.sh (kjør hver kveld)
|
||
[x] A9 — bash infrastructure/11-billing-iam-hardening.sh
|
||
[x] SMOKE — scripts/smoke-test.sh: 10/10 ✅ (2026-05-26 01:45 CEST)
|
||
```
|
||
|
||
---
|
||
|
||
## FASE A2 — Dialogflow CX FAQ-agent
|
||
|
||
**Kreditt: kr 5 822 + $1 000 Playbooks-trial**
|
||
|
||
> **SCOPE-AVKLARING (2026-05-27):** Jason-v1 FAQ er et internt verktøy for operatøren (deg) i første fase —
|
||
> brukes som kunnskapsbase og salgsmodul-assistent i OPAX. Ingen ekstern publisering ennå.
|
||
> Voice-støtte planlagt i DX7.
|
||
|
||
```
|
||
[x] DX1 — Opprett Playbook-agent i Conversational Agents Console (2026-05-27)
|
||
Agent: OSVauco FAQ
|
||
Plattform: Conversational Agents CX Agent Studio
|
||
Region: us-central1
|
||
Prosjekt: propane-will-491900-m5 (Jason-v1)
|
||
[x] DX2 — Last opp FAQ-innhold som Data Store (2026-05-27)
|
||
- FAQ-fil: data/threadstone_faq.csv, 39 Q&A-par, ~9 KB
|
||
- GCS: gs://vauco-faq-store/threadstone_faq.csv
|
||
- Data Store: threadstone-faq-store (FAQ-type, us multi-region)
|
||
[x] DX3 — Konfigurer Playbook med norsk systemprompt (2026-05-27)
|
||
- Status: Norsk instrukssett satt i Default Generative Playbook
|
||
- Svar: Fungerer — kortfattet norsk FAQ-respons med billing@vauco.no
|
||
[x] DX4 — Webhook mot OSVauco Cloud Run
|
||
- AVKLARING: Jason-v1 FAQ er en ren Data Store-agent (ingen runtime-kall til Cloud Run).
|
||
- Cloud Run-webhook håndteres i OSVauco API-laget (C2/C3), ikke i FAQ-agenten.
|
||
- Cloud Run URL (funnet): https://osvauco-agent-zjbqp3prqq-uc.a.run.app
|
||
- → Parkert til C2/C4 (Medioteq-integrasjon).
|
||
[ ] DX5 — Publiser via Dialogflow Messenger
|
||
Trigger: Første ekstern kunde (C4 Medioteq) eller salgsmodul klar
|
||
[ ] DX6 — Sett budsjett-alert for Dialogflow CX
|
||
[ ] DX7 — Voice-kanal for OSVauco FAQ
|
||
Fase 1: Web-mikrofon (WebRTC) for intern bruk (deg)
|
||
Fase 2: Telefoni-kanal (Dialogflow CX telephony gateway / PSTN)
|
||
Samme FAQ data store og playbook gjenbrukes — kun kanal endres
|
||
Trigger: Etter DX5 / første ekstern bruker
|
||
[ ] B6 — Eksporter Dialogflow CX agent til versjonskontroll
|
||
```
|
||
|
||
---
|
||
|
||
## FASE ML — ML-lag for OPAX
|
||
|
||
```
|
||
[x] ML-1 — Grunnlag (2026-05-25)
|
||
ml/task_graph.py — Dask DAG parallell agent-kjøring
|
||
ml/state_store.py — Parameter Server state
|
||
ml/telemetry.py — JSONL per agent-kall og DAG
|
||
POST /run | POST /run/dag | GET /state | GET /telemetry/history
|
||
Røyktest: DAG 2 meldinger parallelt ✅ 4.6s
|
||
|
||
[ ] ML-2 — Adaptiv intelligens
|
||
Trigger: > 500 telemetri-kall fra ML-1
|
||
ml/feedback_loop.py, ml/hypertuner.py, ml/heavy_predictor.py
|
||
Krav: dask-ml>=2024.4.0, ray[tune]>=2.10.0
|
||
|
||
[ ] ML-3 — Strategisk innsikt
|
||
Trigger: ML-2 ferdig + Fase C første kunde
|
||
ml/agent_importance.py (XGBoost), experiments/pbt.py
|
||
Krav: xgboost>=2.0.0
|
||
```
|
||
|
||
| Miljø | Telemetri-lokasjon | Arkivering |
|
||
|---|---|---|
|
||
| Lokal dev | `/tmp/vauco_telemetry/` | Manuell |
|
||
| Cloud Run | `/tmp/vauco_telemetry/` | B5: GCS sink |
|
||
| Prod | `gs://propane-will-491900-m5-telemetry/` | Auto |
|
||
|
||
---
|
||
|
||
## FASE B — Sikring og CI/CD ✅ KOMPLETT
|
||
|
||
```
|
||
[x] B1 — Cloud Run deploy live (osvauco-agent-00065-z7t, us-central1)
|
||
IAP opax.vauco.no: CNAME-metode (se B1-IAP nedenfor)
|
||
[x] B2 — GitHub PAT i Secret Manager (github-pat)
|
||
[x] B3 — Cloud Build 2nd gen pipeline
|
||
Connection: osvauco-github-conn
|
||
Trigger: osvauco-agent-deploy (ID: 2fdd789f-a4dc-4f4a-8297-5e91674d2178)
|
||
Push til main → auto build + deploy
|
||
[x] B4 — Webhook (løst av 2nd gen GitHub App — ingen manuell webhook nødvendig)
|
||
[x] B5 — Cost guard + GCS ML-telemetri
|
||
Budget: osvauco-monthly-guard (500 NOK/mnd, 50/90/100% alerts)
|
||
Bucket: gs://osvauco-ml-telemetry (90-dagers lifecycle)
|
||
Sink: osvauco-ml-sink → Cloud Run logger → GCS
|
||
[x] B1-IAP — opax.vauco.no via CNAME → Cloud Run domain mapping (2026-05-27)
|
||
Status: ✅ KOMPLETT
|
||
[ ] B6 — Eksporter Dialogflow CX agent til versjonskontroll
|
||
```
|
||
|
||
---
|
||
|
||
## FASE C — Første salgsmodul
|
||
|
||
```
|
||
[x] C1 — Pakk vauco-bootstrap som Terraform-modul ✅ KOMPLETT (2026-05-27)
|
||
- infrastructure/modules/vauco-bootstrap/: main.tf, variables.tf, outputs.tf, versions.tf
|
||
- Terraform validate: PASS
|
||
- Inkludert: Dialogflow CX (google_dialogflow_cx_agent), dialogflow_region=europe-west1
|
||
[x] C2 — Pakk vauco-os som kundeflate (2026-05-27) - KOMPLETT
|
||
Note: API-dokumentasjon (docs/CUSTOMER_API.md) opprettet.
|
||
[x] C3 — Opprett billing@vauco.no som Google Group (2026-05-27)
|
||
- Note: Billing Alerts (billing@vauco.no) eksisterte fra før – verifisert medlem/eierrskap.
|
||
[ ] C4 — Første kunde: Medioteq
|
||
- FASE 1 (Design/plan): PLAN KLAR – AVVENTER C4.1 + COST GODKJENT
|
||
- [x] C4.1 – Velg endelig Medioteq-prosjekt-ID og billing_account_id
|
||
- project_id velges i eget HITL-møte (forslag i medioteq.tf-kommentarene)
|
||
- billing_account_id dokumenteres og lagres i .env/.secrets
|
||
- ingen terraform plan/apply før C4.1 er krysset av
|
||
- [ ] C4.2 — Auth-strategi sluttfase (HITL-gate per kundeprosjekt)
|
||
Fase 1: Google login på godkjente enheter
|
||
Sluttfase: Vurder BankID / endelig OAuth-provider per kunde
|
||
```
|
||
|
||
---
|
||
|
||
## FASE CG — CostGuard (GCP Cost Intelligence Assistant)
|
||
|
||
Produkt: AI-drevet webchat-assistent for sanntids GCP-kostnadsovervåking.
|
||
Stack: Dialogflow CX → OSVauco Cloud Run → Cloud Billing API → Gemini 2.5 Flash
|
||
Kostnad å drifte: ~$32-45/mnd. Salgspris: $99-299/mnd pr. kunde.
|
||
[] CG1 — Billing API-integrasjon i OSVauco-agentlaget
|
||
- Ny agent: ml/billing_agent.py
|
||
- Integrer Cloud Billing API (cloudbilling.googleapis.com)
|
||
- Endepunkt: GET /billing/summary → returnerer forbruk pr. tjeneste siste 30 dager
|
||
- Endepunkt: GET /billing/forecast → prognose basert på siste 7 dagers snitt
|
||
- Endepunkt: GET /billing/credits → aktive kreditter og utløpsdato
|
||
[] CG2 — Anomali-deteksjon
|
||
- Trigger: forbruk > 2x 7-dagers snitt for én tjeneste
|
||
- Publiser til billing_alerts Pub/Sub topic (allerede eksisterer)
|
||
[] CG3 — Webchat UI
|
||
- Dialogflow Messenger embed på vauco.no/costguard
|
||
- Standalone webapp: costguard.vauco.no
|
||
[] CG4 — Onboard første kunde via vauco-bootstrap
|
||
[] CG5 — Salgsdemo klar
|
||
|
||
---
|
||
|
||
## INFRASTRUKTUR
|
||
|
||
| Script | Rolle | Status |
|
||
|--------|-------|--------|
|
||
| `00-authcheck.sh` | Verifiser gcloud-innlogging | 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` | Cloud 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 + GCS ML-telemetri sink | **Ny** |
|
||
| `11-billing-iam-hardening.sh` | Billing IAM: viewer-roller + fjern domain Creator | **Ny** |
|
||
| `scripts/smoke-test.sh` | 10-case røyktest: health/light/heavy/legacy/400/403/DAG/state/telemetri | **Ny** |
|
||
|
||
---
|
||
|
||
## KJENTE HULL
|
||
|
||
| ID | Hva | 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 |
|
||
| 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** |
|
||
| OQ-10 | GCP billing: Creator på domenet | **LØST** |
|
||
| OQ-11 | Dialogflow CX Data Store norsk indeksering | Teste nb-NO i DX2 |
|
||
| OQ-12 | gemini-2.0-flash/gemini-2.0-flash-001 ikke tilgjengelig nye prosjekter | **LØST** — gemini-2.5-flash/pro + LOCATION=global |
|
||
| OQ-13 | ML-telemetri /tmp/ flyktig i Cloud Run | **LØST** — B5: GCS sink |
|
||
| OQ-14 | LB vs CNAME for domene-routing | **LØST** — CNAME for opax (intern), LB i Terraform for kunder (Fase C) |
|
||
|
||
---
|
||
|
||
## BEKREFTET GA-API
|
||
|
||
| API | Status |
|
||
|-----|--------|
|
||
| `google.adk.Agent` | Bekreftet GA |
|
||
| `load_memory_tool` | Bekreftet |
|
||
| Cloud Build 2nd gen | Bekreftet GA |
|
||
| CMEK ikke for RAG Engine | Ikke støttet |
|
||
| Idempotente scripts | Trygt å kjøre flere ganger |
|
||
| `03-teardown.sh` hver kveld | Agent Runtimes koster 24/7 |
|
||
| Dialogflow CX Playbooks | GA |
|
||
| Dask `scheduler="threads"` i Cloud Run | Bekreftet |
|
||
| `gemini-2.5-flash` / `gemini-2.5-pro` via `LOCATION=global` | **Bekreftet 2026-05-26** |
|
||
|
||
---
|
||
|
||
## DRIFTSKOSTNADER
|
||
|
||
| Scenario | Kostnad/mnd |
|
||
|---|---|
|
||
| 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 |
|
||
|
||
Breakeven: 1 kunde til $300-500/mnd dekker alle kostnader.
|
||
|
||
---
|
||
|
||
## LLM-RUTINGSSTRATEGI
|
||
|
||
**Prinsipp:** Lett modell i front (light), tung modell ved behov (heavy).
|
||
|
||
| Modell | Pris (per 1M) | Tilgang | Bruksområde |
|
||
|---|---|---|---|
|
||
| `gemini-2.5-flash` | $0.30 / $2.50 | global | light — alle enkle kall |
|
||
| `gemini-2.5-pro` | $1.25 / $10.00 | global | heavy — reasoning, compliance |
|
||
|
||
| Parameter | light | heavy |
|
||
|---|---|---|
|
||
| Orchestrator | `gemini-2.5-flash` | `gemini-2.5-pro` |
|
||
| Sub-agenter | `gemini-2.5-flash` | `gemini-2.5-pro` |
|
||
| Reasoning | `gemini-2.5-flash` | `gemini-2.5-flash` |
|
||
| Multi-agent | Nei | Ja |
|
||
| Budsjettgrense | $1/task | $3/task |
|
||
| `LOCATION` | `global` | `global` |
|
||
|
||
**Autoriserte brukere for heavy:** `opax`, `admin`
|
||
Legacy `A` / `A+` normaliseres automatisk til `light` / `heavy`.
|
||
|
||
---
|
||
|
||
## TERRAFORM-VEIKART (Fase C)
|
||
|
||
| Når | Hva |
|
||
|---|---|
|
||
| Fase C: Medioteq | `vauco-bootstrap` → Terraform-modul |
|
||
| Per kunde | `terraform apply -var="customer_id=X"` |
|
||
| Ressurser | Cloud Run, Cloud Build, IAP (LB), budsjett, SA, Dialogflow CX, ML state store |
|
||
| State-backend | GCS (`TF_STATE_BUCKET`) |
|
||
| Fase D | Terraform Cloud |
|
||
|
||
---
|
||
|
||
*OSVauco-NMTMD-GCOS | propane-will-491900-m5 | global (modell) / europe-west1 (infra)*
|