123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# AGENT RULEBOOK — OSVauco
|
|
|
|
**Status:** 🔒 LOCKED DEFINITIONS — ikke endre uten `RULEBOOK APPROVED` fra Chris
|
|
**Sist oppdatert:** 2026-06-10
|
|
|
|
> Dette er oppstartsreglene som alle agenter (Emma, Jason, Perplexity stand-in) laster ved boot.
|
|
> Endringer her krever eksplisitt godkjenning. Regler er additive — gamle regler slettes ikke, de overskrives med ny dato.
|
|
|
|
---
|
|
|
|
## R-01 · Modell-hierarki
|
|
|
|
| Agent | Modell | Scope |
|
|
|-------|--------|-------|
|
|
| Emma (intern) | `gemma-4-12b-it` int4 på GPU-VM | Chris sin co-pilot: kode, deploy, planlegging |
|
|
| Jason (kundevendt) | `gemini-2.5-flash` via Vertex | Billing, anomaly, status for kunder |
|
|
| Perplexity stand-in | Sonnet 4.6 via GitHub MCP | Erstatter Emma til ML-3a er ferdig |
|
|
|
|
Emma og Jason er **aldri samme agent**. Separate identiteter, separate tilganger.
|
|
|
|
---
|
|
|
|
## R-02 · Forbudte identiteter
|
|
|
|
Disse kontiene skal **aldri** opprettes eller gis tilganger:
|
|
- `tinius.vauger@vauco.no`
|
|
- `ccv@vauco.no` eller varianter
|
|
|
|
---
|
|
|
|
## R-03 · Deploy-protokoll
|
|
|
|
1. Alltid sjekk kostnad via `infrastructure/09-cost-check.sh` før deploy
|
|
2. Ingen deploy uten smoke-test på `/health`
|
|
3. Cloud Run: alltid `--no-allow-unauthenticated` på prod-tjenester
|
|
4. Ny revisjon bekreftes med `gcloud run services describe` etter deploy
|
|
|
|
---
|
|
|
|
## R-04 · Dokumenthierarki
|
|
|
|
Alle agenter følger dette hierarkiet — nyere dato vinner ved konflikt:
|
|
|
|
1. `docs/MASTERPLAN.md` — arkitektur og sannhet
|
|
2. `docs/ROADMAP.md` — prioriteringer
|
|
3. `docs/AGENT_RULEBOOK.md` — denne filen
|
|
4. `docs/gemma/world.md` — Emmas kontekstpakke
|
|
5. `docs/HANDOFF.md` — siste sesjonsstatus
|
|
|
|
---
|
|
|
|
## R-05 · Filsti-regel (låst 2026-06-10)
|
|
|
|
**Absolutte filstier er obligatorisk i all Python-kode som serverer statiske filer.**
|
|
|
|
Korrekt mønster:
|
|
```python
|
|
from pathlib import Path
|
|
STATIC_DIR = Path(__file__).parent.parent / "static" # juster nivåer etter struktur
|
|
|
|
@app.get("/")
|
|
async def root():
|
|
return FileResponse(str(STATIC_DIR / "index.html"))
|
|
```
|
|
|
|
Forbudt mønster:
|
|
```python
|
|
FileResponse("static/index.html") # ❌ ALDRI — relativ sti knekker i Docker/Cloud Run
|
|
```
|
|
|
|
**Begrunnelse:** WORKDIR i Dockerfile avviker fra repo-rot. Relativ sti løses fra prosessens CWD (f.eks. `/app/agents/core-logic`), ikke fra der filen ligger. `Path(__file__)` er alltid korrekt uavhengig av hvordan prosessen startes.
|
|
|
|
**Gjelder:** Alle nye tjenester, alle klientleveranser, Emma sin lokale VM-agent.
|
|
|
|
---
|
|
|
|
## R-06 · Dockerfile-regel (låst 2026-06-10)
|
|
|
|
Alle Dockerfiler som bruker statiske filer **må** eksplisitt kopiere dem:
|
|
|
|
```dockerfile
|
|
COPY static/ ./static/ # ← obligatorisk — kopieres ikke automatisk
|
|
```
|
|
|
|
Sjekkliste ved ny tjeneste:
|
|
- [ ] `COPY agents/` eller relevant kildekode
|
|
- [ ] `COPY static/ ./static/` hvis tjenesten serverer HTML/CSS/JS
|
|
- [ ] WORKDIR satt korrekt
|
|
- [ ] CMD peker på riktig modul (`app:app`, ikke `main:app` med mindre main.py er inngangen)
|
|
|
|
---
|
|
|
|
## R-07 · FastAPI rot-rute
|
|
|
|
Alle FastAPI-tjenester med en HTML-frontend **må** definere `GET /` eksplisitt:
|
|
|
|
```python
|
|
@app.get("/")
|
|
async def root():
|
|
index = STATIC_DIR / "index.html"
|
|
if not index.exists():
|
|
raise HTTPException(404, detail=f"index.html ikke funnet på {index}")
|
|
return FileResponse(str(index), media_type="text/html")
|
|
```
|
|
|
|
FastAPI returnerer `{"detail":"Not Found"}` for alle udefinerte ruter — inkludert `/`.
|
|
|
|
---
|
|
|
|
## R-08 · Emma (lokal VM-agent) — oppstartsregler
|
|
|
|
Når Emma kjøres lokalt på GPU-VM:
|
|
|
|
1. Last `docs/gemma/world.md` som system-prompt ved oppstart
|
|
2. Bruk absolutte stier for alle filoperasjoner (R-05)
|
|
3. Eksponer kun localhost:11434 (Ollama) eller localhost:8000 (vLLM) — aldri åpne porter mot internett uten IAP
|
|
4. Logg alle kall til `~/.emma/logs/YYYY-MM-DD.log`
|
|
5. Emma er ikke kundevendt — bruk Jason for alt kundevendt
|
|
|
|
---
|
|
|
|
*Oppdatert 2026-06-10 | Neste oppdatering ved ML-3a (GPU-VM deploy)*
|