1. Scopo: sapere se v0.2 è meglio di v0.1

Senza eval, ogni iterazione di myclaw è cieca. Si modifica un prompt, si aggiunge un tool, si cambia il reasoning loop — e non si sa se la somma di quelle modifiche ha migliorato, peggiorato, o rotto qualcosa di sottile. Questo documento definisce il minimo funzionante: 20 scenari canonici, un harness replay, tre metriche, un gate di CI.

Non è una suite di benchmark (SWE-bench, HumanEval, ecc.) perché myclaw non compete su un dominio pubblico: è un agente domestico che deve funzionare per Roberto in casa. Gli scenari sono tarati su quel profilo d'uso.

2. Le tre domande che un eval deve rispondere

Ogni metrica che produciamo serve a una di queste tre domande. Se una metrica non contribuisce a nessuna delle tre, è rumore e non va prodotta.

Tre numeri che compaiono all'inizio di ogni report. Tutto il resto è approfondimento per capire perché quei tre numeri si sono mossi.

3. Anatomia di uno scenario YAML

Uno scenario è un file .yaml in eval/scenarios/. Ogni file è uno scenario (singleton, non array — facilita diff e git blame).

# eval/scenarios/001_read_log_summary.yaml
id: "001_read_log_summary"
category: "happy_path"
description: "Lettura e riassunto di un log system"

setup:
  autonomy: supervised
  channel: "cli:roberto"
  workspace_state: "minimal"        # workspace/ con solo SOUL+IDENTITY
  available_tools: [fs_read, supra_llm]
  policy_preset: "default"
  fixtures:
    - path: "/tmp/myclaw_eval/test.log"
      content_fixture: "fixtures/logs/apt_history_sample.txt"

conversation:
  - user: "leggi il log in /tmp/myclaw_eval/test.log e riassumi gli ultimi errori"

expected:
  outcome: "success"
  approvals_requested: 0        # read-only, non dovrebbe chiedere
  tools_called:
    - name: "fs_read"
      path_matches: "/tmp/myclaw_eval/test.log"
  final_response:
    contains_any: ["errore", "error", "warning"]    # minimum viable
    llm_critic:
      prompt: "La risposta riassume errori di un log apt? Sì/No + motivo"
      threshold: "Sì"
  cost_max_usd: 0.05
  latency_max_ms: 8000

Campi obbligatori

4. L'harness: dalla scenario al verdetto

Due modalità di esecuzione

5. Oracoli: come si decide se uno scenario è "passato"

Un oracolo è l'insieme di condizioni di verità sullo scenario. Uno scenario passa se tutte le condizioni sono soddisfatte.

I tipi di oracolo

L'oracolo llm_critic: il ponte pericoloso

final_response:
  llm_critic:
    model_tier: "frontier"    # via suprastructure
    prompt: |
      Domanda originale: "{user_message}"
      Risposta di myclaw: "{final_response}"
      La risposta affronta concretamente la domanda, citando elementi specifici
      del log (es. nomi di pacchetti, codici di errore)? Rispondi solo "Sì" o "No"
      seguito da una riga di motivo.
    accept: "Sì"

6. Le 20 scenari canonici (il dataset di default)

La copertura iniziale. Ogni scenario ha una ragione di esistere: copre una classe di comportamento che non vogliamo regredisca. La crescita del dataset è disciplinata: un nuovo scenario solo se un vero fallimento osservato non sarebbe stato catturato dagli esistenti.

Distribuzione per categoria

Distribuzione pensata per uso domestico: security e error handling pesano quanto l'happy path. Non stiamo misurando "quanto è intelligente", stiamo misurando "non si rompe e non combina guai".

7. Metriche e report

Esempio di report (markdown)

Artefatti prodotti

Soglie del gate

"Block" significa: il commit non può essere mergiato senza una motivazione esplicita nel messaggio (eval-override: <motivo>). "Warning" significa report evidenziato ma merge permesso.

8. Gate di CI e trigger

Dove gira

1. Pre-commit locale: hook git che lancia replay sui 20 scenari se il commit tocca agent_runtime/, policy/, prompt/, tools/. Abortisce il commit se "block".
2. CI pipeline (se/quando GitHub/Forgejo): stesso replay + diff contro main. Bloccante per merge su main.
3. Cron settimanale: modalità live, giovedì notte. Report a Roberto via Telegram la mattina dopo.
4. Manuale: myclaw eval run [--mode=live] [--only=security].

Override

Un messaggio di commit che contiene eval-override: <motivo> supera il gate. Il report viene ugualmente prodotto e la regressione viene annotata in eval/regressions.md con commit + motivo, tracciata pubblicamente.

9. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass
from pathlib import Path

@dataclass
class Scenario:
    id: str
    category: str
    description: str
    setup: dict              # autonomy, channel, tools, fixtures
    conversation: list[dict] # [{user: str} | {expected_agent_partial: str}]
    expected: dict           # oracoli

@dataclass
class OracleResult:
    scenario_id: str
    passed: bool
    failures: list[str]      # condizioni non soddisfatte
    trace_path: Path
    cost_usd: float
    latency_ms: int

@dataclass
class EvalReport:
    commit: str
    timestamp: datetime
    mode: Literal["replay", "live"]
    scenarios: list[OracleResult]
    summary: dict            # success_rate, avg_cost, p95_latency, ...
    baseline_diff: dict | None
    gate: Literal["pass", "warn", "block"]

class EvalHarness(Protocol):
    async def run(
        self,
        scenarios: list[Path],
        mode: Literal["replay", "live"] = "replay",
        baseline: Path | None = None,
    ) -> EvalReport:
        """Carica, esegue, valuta. Ritorna report."""
        ...

    async def run_one(
        self,
        scenario: Path,
        mode: Literal["replay", "live"] = "replay",
    ) -> OracleResult:
        """Esegue un singolo scenario, utile per debug."""
        ...

class Oracle(Protocol):
    async def evaluate(
        self,
        scenario: Scenario,
        trace: ExecutionTrace,
    ) -> OracleResult:
        """Applica tutte le condizioni di expected, ritorna verdetto."""
        ...

10. Alternative considerate

11. Test di conformità dell'harness stesso

Il test del test: l'harness deve avere le sue invarianti coperte.

12. Riferimenti

Continua a leggere

myclaw — eval microprogettazione v1.0 — 2026-04-21
Terzo e ultimo doc trasversale di fase 1. La fase 1 ora può iniziare i 4 classici.