# AGENTS.md — ML-roller i Vauco OS

**Sist oppdatert:** 2026-06-01  
**Formål:** Definerer hver agents rolle i ML-laget (Parameter Server-mønster + Dask DAG).

---

## Oversikt

```
                    ┌─────────────────────────────┐
                    │   JASON VAUGER               │
                    │   (Personlig assistent /     │
                    │    persona-lag)              │
                    └──────────┬──────────────────┘
                               │ delegerer til
                    ┌──────────▼──────────────────┐
                    │   OPAX Orchestrator          │
                    │   (PS Server-node / DAG hub) │
                    └──────────┬──────────────────┘
                               │
         ┌──────────┬──────────┼──────────┬──────────┐
         ▼          ▼          ▼          ▼          ▼
    billing-    rag-agent  memory-    tui-       multi-
     agent                 agent     bridge     agent
    (worker)   (worker)   (worker)  (worker+   (worker)
                                    input-src)
```

---

## Agenttabell

| Agent | Katalog | PS-rolle | Dask-rolle | Online learning | Heavy mode |
|---|---|---|---|---|---|
| **Jason Vauger** | `agents/jason-vauger.md` | **Persona-wrapper** (over OPAX) | Trigger for OPAX DAG via naturlig-språk | Nei — kontekstuell | Nei |
| OPAX Orchestrator | `agents/core-logic/` | **Server-node** (aggregerer state, dispatcher DAG) | DAG scheduler | Nei | Ja (koordinerer heavy sub-agenter) |
| billing-agent | `agents/core-logic/` | Worker (pusher kostdata til state store) | `dask.delayed`-task | Nei — strukturert data | Nei |
| rag-agent | `agents/rag/` | Worker (pusher retrieval-resultater) | `dask.delayed`-task | **Ja** — `partial_fit` på nye docs (ML-2) | Ja |
| memory-agent | `agents/memory/` | Worker (pusher/puller memory-oppslag) | `dask.delayed`-task | Nei — faktahenting | Nei |
| eval-agent | `agents/eval/` | Worker (pusher evalueringsmetrikker) | `dask.delayed`-task | **Ja** — kvalitetsscore-feedback (ML-2) | Nei |
| multi-agent | `agents/multi_agent/` | Worker + sub-orchestrator | DAG-node med barn | Nei | **Ja — primær heavy-mode bruker** |
| tui-bridge | `vauco-gemini-tui-bridge` | Worker + **primær input-kilde** | Streaming input til DAG | **Ja** — real-time feedback-loop (ML-2) | Ja |
| vauco-bootstrap | `vauco-bootstrap` | **Config-aggregator** (analog til PS shard) | Trigger for nye DAGer | **Ja** — ASHA-tuning (ML-2) | Nei |

---

## ML-fase per agent

| Agent | ML-1 (nå) | ML-2 (neste) | ML-3 (fremtidig) |
|---|---|---|---|
| **Jason Vauger** | Naturlig-språk interface mot OPAX | Kontekstuell tilpasning til bruker | Personlig læringsloop + proaktive forslag |
| OPAX Orchestrator | Kjør DAG via `execute_dag()` | Bytt heavy-mode til ML-predictor | PBT-eksperiment |
| billing-agent | `log_agent_call()` + `state.push()` | — | Feature importance-input |
| rag-agent | `log_agent_call()` + `state.push()` | `partial_fit` på nye docs | Top-K feature importance |
| memory-agent | `log_agent_call()` | — | — |
| eval-agent | `log_agent_call()` + `state.push()` | Kvalitetsscore-feedback | Feature importance-target |
| multi-agent | `log_agent_call()` | — | PBT worker |
| tui-bridge | `log_agent_call()` | `feedback_loop.py` (ML-2.1) | — |
| vauco-bootstrap | — | `hypertuner.py` ASHA (ML-2.3) | PBT vinner-konfig → Terraform |

---

## State store nøkkelkonvensjon

Format: `"<agent_id>:<key>"`

| Agent | Nøkkel | Eksempelverdi |
|---|---|---|
| `billing-agent` | `last_cost_usd` | `12.5` |
| `billing-agent` | `last_report_ts` | `"2026-05-26T01:00:00Z"` |
| `rag-agent` | `last_retrieval_score` | `0.87` |
| `rag-agent` | `chunks_retrieved` | `5` |
| `eval-agent` | `quality_score` | `0.91` |
| `multi-agent` | `active_sub_agents` | `["billing-agent", "rag-agent"]` |
| `tui-bridge` | `last_user_feedback` | `"positive"` |

---

## Telemetri-felter (referanse)

Alle agenter logger via `ml.telemetry.log_agent_call()`. Feltene er:

```json
{
  "ts": "2026-05-26T01:00:00.000Z",
  "agent": "billing-agent",
  "model": "gemini-2.0-flash",
  "mode": "standard",
  "duration_s": 0.312,
  "success": true,
  "error": null,
  "input_tokens": 284,
  "output_tokens": 512
}
```

Filer lagres i: `$TELEMETRY_DIR/YYYY-MM-DD.jsonl` (default: `/tmp/vauco_telemetry/`)  
For GCS-arkivering: sett `TELEMETRY_DIR=gs://...` eller bruk `10-cost-guard.sh`-cron.