Tracciamento Comportamentale

Il sistema di tracciamento comportamentale di Potato cattura dati dettagliati sulle interazioni durante le sessioni di annotazione, consentendo ai ricercatori di analizzare il comportamento degli annotatori, i pattern temporali, l'utilizzo dell'assistenza AI e i processi decisionali.

Panoramica

Il sistema di tracciamento comportamentale cattura:

• Ogni azione di annotazione: Selezioni di etichette, annotazioni span, input di testo
• Timestamp precisi: Timestamp lato server e lato client
• Utilizzo dell'assistenza AI: Quando i suggerimenti sono stati mostrati e se sono stati accettati
• Dati di focus e temporali: Tempo trascorso su ciascun elemento, profondità di scorrimento
• Cronologia di navigazione: Percorso completo attraverso le istanze

Cosa Viene Tracciato

Eventi di Interazione

Ogni interazione dell'utente con l'interfaccia di annotazione viene catturata:

Utilizzo dell'Assistenza AI

Tracciamento completo del ciclo di vita per l'annotazione assistita da AI:

{
  "request_timestamp": 1706500010.0,
  "response_timestamp": 1706500012.5,
  "schema_name": "sentiment",
  "suggestions_shown": ["positive", "neutral"],
  "suggestion_accepted": "positive",
  "time_to_decision_ms": 3500
}

Modifiche alle Annotazioni

Cronologia dettagliata delle modifiche per tutte le annotazioni:

{
  "timestamp": 1706500002.5,
  "schema_name": "sentiment",
  "label_name": "positive",
  "action": "select",
  "old_value": null,
  "new_value": true,
  "source": "user"
}

Tipi di sorgente:

• user - Interazione diretta dell'utente
• ai_accept - L'utente ha accettato il suggerimento AI
• keyboard - Utilizzata scorciatoia da tastiera
• prefill - Pre-compilato dalla configurazione

Formato dei Dati

Ogni istanza di annotazione include un oggetto behavioral_data:

{
  "id": "instance_123",
  "annotations": {
    "sentiment": {"positive": true}
  },
  "behavioral_data": {
    "instance_id": "instance_123",
    "session_start": 1706500000.0,
    "session_end": 1706500045.0,
    "total_time_ms": 45000,
    "interactions": [...],
    "ai_usage": [...],
    "annotation_changes": [...],
    "navigation_history": [...],
    "focus_time_by_element": {
      "label:positive": 2500,
      "textbox:explanation": 8000
    },
    "scroll_depth_max": 75.5
  }
}

Configurazione

Il tracciamento comportamentale è abilitato per impostazione predefinita. Non è richiesta alcuna configurazione aggiuntiva.

Modalità Debug Frontend

Per abilitare la registrazione di debug per il tracker di interazioni:

// Nella console del browser
window.interactionTracker.setDebugMode(true);

Esempi di Analisi

Caricamento dei Dati Comportamentali

import json
from pathlib import Path
 
def load_behavioral_data(annotation_dir: str) -> dict:
    data = {}
    for user_dir in Path(annotation_dir).iterdir():
        if not user_dir.is_dir():
            continue
        state_file = user_dir / 'user_state.json'
        if state_file.exists():
            with open(state_file) as f:
                user_state = json.load(f)
            user_id = user_state.get('user_id')
            behavioral = user_state.get('instance_id_to_behavioral_data', {})
            data[user_id] = behavioral
    return data

Analisi del Tempo di Annotazione

def analyze_annotation_time(behavioral_data: dict) -> dict:
    stats = {}
    for user_id, instances in behavioral_data.items():
        times = []
        for instance_id, bd in instances.items():
            if 'total_time_ms' in bd:
                times.append(bd['total_time_ms'] / 1000)
        if times:
            stats[user_id] = {
                'mean_time': sum(times) / len(times),
                'min_time': min(times),
                'max_time': max(times),
                'total_instances': len(times)
            }
    return stats

Rilevamento di Comportamenti Sospetti

def detect_suspicious_annotators(behavioral_data: dict,
                                  min_time_threshold: float = 2.0) -> list:
    suspicious = []
    for user_id, instances in behavioral_data.items():
        fast_count = 0
        for instance_id, bd in instances.items():
            time_sec = bd.get('total_time_ms', 0) / 1000
            if time_sec < min_time_threshold:
                fast_count += 1
 
        total = len(instances)
        if total > 0:
            fast_rate = fast_count / total
            if fast_rate > 0.5:
                suspicious.append({
                    'user_id': user_id,
                    'fast_rate': fast_rate,
                    'total_instances': total
                })
    return suspicious

Integrazione con la Dashboard di Amministrazione

La Dashboard di Amministrazione include una scheda Analisi Comportamentale con:

1. Mappa di calore delle interazioni utente: Rappresentazione visiva dei pattern di interazione
2. Metriche di assistenza AI: Tassi di accettazione/rifiuto, tempi di decisione
3. Distribuzione dei tempi: Istogramma dei tempi di annotazione
4. Avvisi di attività sospetta: Annotatori segnalati che richiedono revisione

Endpoint API

Traccia le Interazioni

POST /api/track_interactions
Content-Type: application/json
 
{
  "instance_id": "instance_123",
  "events": [...],
  "focus_time": {"element": ms},
  "scroll_depth": 75.5
}

Ottieni i Dati Comportamentali

GET /api/behavioral_data/<instance_id>

Restituisce i dati comportamentali completi per un'istanza.

Best Practice

Per i Ricercatori

1. Stabilire una Baseline: Raccogli dati comportamentali da annotatori di qualità nota per stabilire le baseline
2. Metriche di Qualità: Usa i dati comportamentali insieme all'accordo sulle annotazioni per la valutazione della qualità
3. Valutazione dell'Addestramento: Confronta i pattern comportamentali pre e post-addestramento
4. Analisi dell'Impatto AI: Misura come l'assistenza AI influisce sulla qualità e sulla velocità delle annotazioni

Per i Progetti di Annotazione

1. Monitora in Tempo Reale: Usa la dashboard di amministrazione per individuare i problemi tempestivamente
2. Imposta le Soglie: Definisci intervalli accettabili per le metriche temporali e di interazione
3. Fornisci Feedback: Usa le informazioni comportamentali per fornire feedback mirati agli annotatori

Risoluzione dei Problemi

Nessun Dato Comportamentale Raccolto

1. Verifica che interaction_tracker.js sia caricato (controlla la scheda Network del browser)
2. Controlla la console del browser per errori JavaScript
3. Verifica che gli endpoint API siano accessibili (/api/track_interactions)

Dati Non Persistenti

1. Controlla che lo stato utente venga salvato (cerca user_state.json)
2. Assicurati che la directory di output delle annotazioni sia scrivibile

Ulteriori Letture

• Dashboard di Amministrazione - Monitoraggio in tempo reale
• Cronologia delle Annotazioni - Tracciamento dettagliato delle modifiche
• Controllo della Qualità - Controlli automatici della qualità

Per i dettagli di implementazione, consulta la documentazione sorgente.