# ML-integrasjon i OSVauco

**Fase:** ML-1 implementert | ML-2 og ML-3 planlagt  
**Sist oppdatert:** 2026-05-26

---

## Hvorfor ML i OPAX?

OPAX er et multi-agent system. ML-laget gjør agentene sterkere på tre måter:

1. **Parallell kjøring** (ML-1): Dask DAG lar agenter kjøre samtidig i stedet for sekvensielt.
2. **Adaptiv intelligens** (ML-2): Agentene lærer fra faktisk bruk — heavy-mode aktiveres basert på historikk, ikke hardkodede regler.
3. **Strategisk innsikt** (ML-3): XGBoost feature importance avslører hvilke agenter og signaler som faktisk driver vellykkede utfall.

---

## Fase ML-1: Grunnlag (implementert)

### Arkitektur

```
main.py  →  build_agent_dag([agent_a, agent_b], payload)
                    │
             Dask task graph
                    │
         ┌──────────┴──────────┐
         ▼                     ▼
   run_agent_task(a)    run_agent_task(b)    ← parallelt
         │                     │
         └──────────┬──────────┘
                    ▼
           execute_dag(tasks, scheduler="threads")
                    │
                    ▼
           [result_a, result_b]  →  AgentStateStore.push()
                                            │
                                     telemetry.log_agent_call()
```

### Koble ML-laget inn i main.py

```python
# Eksempel: erstatt sekvensielle kall med parallell DAG
from ml import build_agent_dag, execute_dag, get_store, log_agent_call
import time

@app.post("/run")
def run_agent(req: RunRequest):
    store = get_store()
    payload = {"message": req.message, "user_id": req.user_id,
               "session_id": req.session_id, "mode": req.mode}

    # Velg agenter basert på mode
    if req.mode == "heavy":
        agent_fns = [billing_agent_heavy, rag_agent, multi_agent]
    else:
        agent_fns = [billing_agent, rag_agent]

    start = time.monotonic()
    tasks = build_agent_dag(agent_fns, payload)
    results = execute_dag(tasks, scheduler="threads")
    total_dur = time.monotonic() - start

    # Push resultater til state store
    for r in results:
        if r["success"]:
            store.push(r["agent"], "last_result", r["result"])
            store.push(r["agent"], "last_duration_s", r["duration_s"])

    # Logg DAG-kjøring
    from ml.telemetry import log_dag_execution
    log_dag_execution(dag_id=req.session_id, agent_results=results,
                      total_duration_s=total_dur)

    # Returner kombinert svar
    return {"response": [r["result"] for r in results if r["success"]]}
```

---

## Fase ML-2: Adaptiv intelligens (planlagt)

| Komponent | Fil | Repo |
|---|---|---|
| Inkrementell feedback-loop | `ml/feedback_loop.py` | `vauco-gemini-tui-bridge` |
| ASHA hyperparametertuning | `ml/hypertuner.py` | `vauco-bootstrap` |
| Heavy-mode predictor | `ml/heavy_predictor.py` | `OSVauco` |

**Krav:** `dask-ml>=2024.4.0`, `ray[tune]>=2.10.0` (vauco-bootstrap only)

---

## Fase ML-3: Strategisk innsikt (planlagt)

| Komponent | Fil | Repo |
|---|---|---|
| XGBoost feature importance | `ml/agent_importance.py` | `OSVauco` |
| Population-Based Training | `experiments/pbt.py` | `deep-dream` |

**Krav:** `xgboost>=2.0.0` (legg til requirements.txt i Fase ML-3)

---

## Telemetri-ruting

| Miljø | `TELEMETRY_DIR` | Arkivering |
|---|---|---|
| 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 |

---

## Cross-repo referanser

| Repo | ML-relatert fil | Fase |
|---|---|---|
| `OSVauco` | `ml/`, `AGENTS.md`, `docs/ml-integration.md` | ML-1 |
| `vauco-gemini-tui-bridge` | `ml/feedback_loop.py` (planlagt) | ML-2 |
| `vauco-bootstrap` | `ml/hypertuner.py` (planlagt) | ML-2 |
| `vauco-os` | Konsumerer beste konfig fra state store | ML-2 |
| `deep-dream` | `experiments/pbt.py` (planlagt) | ML-3 |