diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index bb97049..0e65dd5 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -2,7 +2,71 @@ **Sist oppdatert:** 2026-06-09 **Skrevet av:** Jason Vauger (via Perplexity) -**Status:** CostGuard-UI er justert første runde, vauco.no er tonet ned og anonymisert, og Threadstone er satt i lukket pilot med kun @vauco.no-innlogging. +**Status:** CG3e fullført og deployet. CG4 Recommendations & Anomaly Engine planlagt. + +--- + +## ✅ CG3e — LLM Token Usage Logger (fullført 2026-06-09) + +- **`agents/token_logger.py`** — BigQuery-logger for LLM-kall. Skriver til `costguard_dataset.llm_token_usage` med felt: `timestamp`, `agent_name`, `model_name`, `input_tokens`, `output_tokens`, `total_tokens`, `total_cost_usd`. +- **`/billing/tokens/summary`** — nytt endpoint i `app.py`. Henter aggregert tokenbruk per agent/modell siste 30 dager fra BigQuery. +- **`static/billing-dashboard.html`** — nytt "⚡ Tokenbruk per agent"-kort som fetcher `/billing/tokens/summary` og viser tabell med agent, modell, tokens og kost i USD. +- **Cloud Run revisjon `osvauco-agent-00298-6kk`** — deployet og live med alle CG3e-endringer. +- **Commit:** `d2cf63a` (token usage card) på toppen av `33482ae` (token logger + endpoint). + +--- + +## 🗺 CG4 — Recommendations & Anomaly Engine (NESTE) + +### Mål +En FinOps-lignende modul i CostGuard (inspirert av GCP FinOps Hub / Utilization Insights) som: +- Viser anbefalinger om hvordan man kan redusere GCP-kostnader +- Varsler om unormale kostnadsøkninger (anomalier) +- Viser estimert besparelse per måned i NOK + +### Backend — to endpoints + +**`/billing/recommendations`** (NY) +Logikk (kjøres mot BigQuery-data): +1. **Sløsing:** Tjenester med `total_cost > 0` men `0` aktivitet siste 7 dager → "Vurder å skru av [tjeneste]" +2. **Anomali:** Tjeneste der siste 3-dagers snitt er `>= 2x` 30d-snittet → "Unormal spik på [tjeneste]" +3. **Budsjettoverskridelse:** Prognose > budsjett → "Du er på vei til å overskride budsjettet denne måneden" + +Response-format: +```json +{ + "recommendations": [ + { + "type": "anomaly" | "waste" | "budget", + "severity": "high" | "medium" | "low", + "service": "Cloud Build", + "message": "Unormal kostnadsøkning på Cloud Build — 3x over normalt", + "estimated_savings_nok": 42.50 + } + ], + "total_estimated_savings_nok": 42.50 +} +``` + +**`/billing/anomalies`** (UTVIDES) +- Legg til `ratio`, `message` og `severity` i eksisterende response. + +### Frontend — nytt "Anbefalinger"-kort + +Plassering: mellom `.bottom-row` og token-usage-kortet i `billing-dashboard.html`. + +Design (lik GCP FinOps Hub): +- Header: "💡 Anbefalinger" + "Estimert besparelse: kr X,XX/mnd" +- Liste med ikoner: 🔴 høy / 🟡 medium / 💚 lav +- Hver rad: ikon + melding + tjeneste-tag + besparelse +- Tom state: "✅ Ingen anbefalinger — forbruket ser normalt ut" + +### Implementasjonsrekkefølge for Jason +1. Lag `agents/recommendations_engine.py` med de tre analyselogikkene +2. Legg til `/billing/recommendations`-ruten i `app.py` +3. Oppdater `/billing/anomalies` med `ratio` + `severity` + `message` +4. Legg til frontend-kortet i `billing-dashboard.html` +5. Commit + deploy --- @@ -74,7 +138,7 @@ Første betalende produkt: **CostGuard** (GCP-kostnadsanalyse via AI). | Komponent | Status | |---|---| -| Cloud Run `osvauco-agent` | ✅ Live, `us-central1` | +| Cloud Run `osvauco-agent` | ✅ Live, `us-central1`, revisjon `00298-6kk` | | `opax.vauco.no` (LB + SSL) | ✅ Live, IP `34.98.77.173` | | IAP (`@vauco.no` only) | ✅ Aktivert | | PR #15 IAP /health-fix | ✅ Merget til main (commit 7a09871) | @@ -84,7 +148,9 @@ Første betalende produkt: **CostGuard** (GCP-kostnadsanalyse via AI). | AI-modell | ✅ `gemini-2.5-pro` via Vertex AI (us-central1) | | `costguard.oss.vauco.no` | ✅ Live (Cloudflare Pages) | | `static/costguard.html` | ✅ Første versjon live via `osvauco-agent` | -| `static/billing-dashboard.html` | ✅ Første versjon GCP-only, layout strammet inn, AWS-UI parkert | +| `static/billing-dashboard.html` | ✅ GCP-only, CG3e token-kort lagt til | +| `agents/token_logger.py` | ✅ BigQuery LLM-logger ferdig | +| `/billing/tokens/summary` | ✅ Endpoint live | | `vauco.no` | ✅ Oppdatert, anonymisert og deployet via `gs://vauco-site-public` | | `threadstone.vauco.no` | ✅ Landingsside live, satt i lukket pilot m/ @vauco.no-gating |