DatasetForge

Micro-gestionale FastAPI per la curazione e validazione del dataset di fine-tuning LLM Nutriverso. Editor collaborativo, flag system avanzato, grafo di navigazione interattivo e pipeline di validazione incrociata.

Stack tecnologico

Avvio rapido

cd tools/datasetforge
pip install -r requirements.txt
python3 server.py    # → http://localhost:8420

Come iniziare

1. Avvia il server

DatasetForge gira su http://127.0.0.1:8420 di default.

python3 server.py
# ✅ Server running at http://127.0.0.1:8420

2. Verifica che sia attivo

curl http://127.0.0.1:8420/api/health
# → {"status":"ok","entries":4926,"version":"2.1"}

3. Apri l'interfaccia web

Naviga su http://127.0.0.1:8420/ — vedrai la tabella delle entry del dataset con filtri, ricerca e strumenti.

Autenticazione & API Key

Ogni chiamata API (eccetto /api/health, le pagine web e /docs) richiede l'header X-API-Key. Le chiavi sono mappate in keys.json con un agent_id e un role.

Usare una API Key

# Health (pubblico, no key)
curl http://127.0.0.1:8420/api/health

# Autenticato (reader)
curl -H "X-API-Key: YOUR-KEY" http://127.0.0.1:8420/api/stats

# Creare una entry (writer)
curl -X POST -H "X-API-Key: YOUR-KEY" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:8420/api/entries \
  -d '{"messages":[...],"lang":"it"}'

Funzionalità implementate

Le funzionalità dell'interfaccia sono definite da user stories con criteri di accettazione espliciti.

API Reference

La documentazione interattiva completa di tutti gli endpoint è disponibile sulla pagina dedicata, che fetcha lo schema OpenAPI a runtime e lo renderizza dinamicamente con filtri per tag, metodo e ricerca testuale.

Gruppi di endpoint principali

Architettura

DatasetForge segue un'architettura a 3 strati: Managers (logica di dominio + stato) → Routers (endpoint HTTP thin) → LockHub (concorrenza e write-safety).

Managers & Routers

Managers (logica di dominio)

I manager contengono tutta la logica di business e gestiscono lo stato persistente:

Routers (endpoint HTTP)

Ogni router è creato via factory create_router() e riceve i manager come dipendenze. I router sono stateless: non mantengono dati, solo validano e delegano.

# routers/entries.py — pattern
def create_router(dataset_manager, flag_manager, hub):
    router = APIRouter(prefix="/api/entries", tags=["entries"])

    @router.get("")
    async def list_entries(...):
        return dataset_manager.list(...)

    @router.put("/{entry_id}")
    async def update_entry(entry_id, body, actor):
        return dataset_manager.update(entry_id, body, actor)

    return router

LockHub & write-safety

LockHub è il single source of truth per tutti i lock del sistema. Centralizza la concorrenza per evitare deadlock e garantire write-safety cross-file.

class LockHub:
    """Single source of truth per i lock."""
    dataset_lock = threading.RLock()   # dataset.jsonl
    flags_lock   = threading.RLock()   # flags.json
    graph_lock   = threading.RLock()   # kb.json
    _global_lock = threading.RLock()   # cross-file transactions

Write-safety (crash-safe)

Tutte le scritture passano per atomic_write_* con:

• fsync su file + directory
• os.replace (atomic rename, crash-safe)
• Single-writer cross-process garantito da file_lock (RLock intra-processo + flock a livello OS)

Cross-val snapshot + MVCC

La cross-validation usa un pattern snapshot per non bloccare il sistema durante il compute lungo:

def run_crossval():
    # Snapshot breve (millisecondi)
    with hub.dataset_lock, hub.graph_lock:
        ds_snapshot = deepcopy(dataset_manager._load_all())
        kb_snapshot = deepcopy(graph_manager._load_kb())

    # Compute lungo (secondi/minuti) — lock rilasciati
    results = pipeline(ds_snapshot, kb_snapshot)

    # Write flag breve (atomico)
    with hub.flags_lock:
        for flag in results:
            flag_manager._create_or_update(flag)

Flag System V3

Il Flag System è il cuore della curazione collaborativa. Permette di segnalare problemi sul dataset e sul grafo, tracciarli in un workflow strutturato e risolverli — con anti-flooding per i flag generati automaticamente.

11 tipi di flag

Workflow biforcato

I flag umani e quelli automatici seguono percorsi separati:

Anti-flooding (3 meccanismi)

1. dedup_key — hash di type + targets + sub_type. Prima di creare: se open → aggiorna; se resolved/wontfix → skip
2. Rate limit — max N flag aperti per (source, type). Oltre → coalesce in batch
3. Coalescing — 28 schermate orfane identiche → 1 flag con 28 graph_targets

Auto-priority deterministica

La priorità dipende dal contenuto (evidence/verdict), non dalla fonte:

Graph Mapper

Il Graph Mapper è il crawler che mappa automaticamente il grafo di navigazione del sito, espande e verifica kb.json. Risolve il problema delle schermate orfane, edge mancanti e dati stale.

Fase 1 — Analisi statica del bundle

Input: main.bundle.js (già scaricato). Deterministica, no auth.

• Route table — tutti i <Route path>
• Navigation calls — history.push(), <Link to>
• Action labels — i18n keys IT/EN/FR/ES
• Dialog triggers — setDialogVisible(true)

< 10s Veloce, deterministico, non serve il sito online.

Fase 2 — Crawling dinamico

Input: credenziali demo + route dalla Fase 1. Usa Playwright.

• Login automatico → JWT + cookie salvati
• Per ogni route: estrai elementi cliccabili, click, registra edge
• Rate limiting: 0.5s tra click, max 2 concurrent
• Stop su 5xx o 429

5-10 min Cattura la realtà: cosa è visibile, cosa fa ogni bottone.

Fase 3 — Diff & auto-fix

Confronta kb.json con i risultati delle fasi 1-2:

Apply mode con dry_run=true|false: preview o applica fix con backup automatico.

Path Finder

L'endpoint /api/graph/paths risolve il caso d'uso tipico: "Dal login come arrivo a inserire patologie?" — calcola tutti i cammini possibili da A a B con step descritti in linguaggio naturale.

Cross-Validation

La validazione incrociata rileva automaticamente le risposte nel dataset che descrivono path di navigazione non validi rispetto al grafo reale del software, collegando le discrepanze al Flag System.

Pipeline a 5 stadi

Stadio 1 — Ingest

Costruisce il gazetteer multilingue (surface forms normalizzate per ogni entità in 4 lingue) e la matrice di reachability (tutte le coppie src→dst raggiungibili — lookup O(1) con 64 nodi = 4096 entry).

Stadio 2 — Extract (3 vie combinate)

• Aho-Corasick — match esatti e quasi-esatti in O(|testo|), 4 lingue gratis
• Fuzzy (RapidFuzz) — parafrasi e typo, soglie differenziate (L1: 88, L2: 85, L3: 82)
• Semantic (opz.) — LaBSE/MiniLM multilingue per parafrasi cross-lingua

Stadio 3 — Disambiguazione

Context anchoring: una menzione L2/L3 (es. bottone "Nuovo") si risolve solo fra le entità figlie della schermata corrente nel path ricostruito. Risolve la polisemia senza modelli pesanti.

Stadio 4 — Path-check

Verifica che il path dichiarato sia percorribile nel grafo: