Potato 2.3: Annotazione Agentica, Solo Mode e il Futuro della Valutazione Umana

Siamo entusiasti di annunciare Potato 2.3.0, la release più grande nella storia di Potato. Questo aggiornamento introduce due nuovi sistemi principali -- l'annotazione agentica e Solo Mode -- insieme a Best-Worst Scaling, autenticazione SSO/OAuth, esportazione Parquet e 15 nuovi progetti demo.

Il tema di questa release è semplice: le cose che dobbiamo annotare sono cambiate, e i nostri strumenti devono stare al passo. I ricercatori non si limitano più a etichettare il sentiment del testo e le entità nominate. Stanno valutando tracce di agenti AI multi-step, confrontando output di LLM su larga scala e costruendo dataset per task sempre più complessi. Potato 2.3 è costruito per questa nuova realtà.

Annotazione Agentica

La funzionalità principale di Potato 2.3 è un sistema completo per la valutazione degli agenti AI attraverso l'annotazione umana.

Gli agenti AI -- sistemi che compiono azioni multi-step per portare a termine task -- si stanno moltiplicando rapidamente. Ma valutarli è difficile. Un singolo run di un agente può coinvolgere dozzine di chiamate a strumenti, passi di ragionamento, navigazioni di pagine web e output intermedi. Gli strumenti di annotazione esistenti mostrano gli output degli agenti come testo piatto, perdendo la ricca struttura di cui i valutatori hanno bisogno per vedere.

Il sistema di annotazione agentica di Potato risolve questo problema con tre componenti.

12 Convertitori di Formato Traccia

Le tracce degli agenti vengono in formati diversi a seconda del framework. Potato le normalizza tutte in una rappresentazione unificata:

La configurazione è semplice:

agentic:
  enabled: true
  trace_converter: react
  trace_file: "data/agent_traces.jsonl"

Il rilevamento automatico è disponibile per i progetti che devono acquisire tracce da più fonti:

agentic:
  enabled: true
  trace_converter: auto

Tre Tipi di Display

Le diverse modalità degli agenti richiedono visualizzazioni diverse.

Agent Trace Display renderizza le tracce di agenti che usano strumenti come card colorate per passo con osservazioni comprimibili, formattazione JSON e una barra laterale con la timeline:

agentic:
  display_type: agent_trace
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    show_step_numbers: true

Web Agent Trace Display renderizza le tracce di agenti di navigazione con screenshot completi, overlay SVG che mostrano i target dei clic e i campi di input, e un filmstrip per la navigazione rapida:

agentic:
  display_type: web_agent
  web_agent_display:
    screenshot_max_width: 900
    overlay:
      enabled: true
      click_marker: "circle"
      click_color: "#ef4444"
    filmstrip:
      enabled: true

Interactive Chat Display supporta sia la revisione delle tracce (valutazione di una conversazione registrata) che la chat live (gli annotatori interagiscono con un agente in tempo reale, poi valutano la conversazione):

agentic:
  display_type: interactive_chat
  interactive_chat_display:
    mode: trace_review
    trace_review:
      show_token_counts: true
      show_latency: true

Valutazioni per Turno

Per qualsiasi tipo di display, gli annotatori possono valutare i singoli passi insieme alla traccia complessiva:

annotation_schemes:
  - annotation_type: likert
    name: overall_quality
    min: 1
    max: 5
 
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"

Schemi Preconfigurati

Nove schemi di annotazione coprono le dimensioni comuni di valutazione degli agenti già pronti all'uso:

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy
  - preset: agent_safety

Preset disponibili: agent_task_success, agent_step_correctness, agent_error_taxonomy, agent_safety, agent_efficiency, agent_instruction_following, agent_explanation_quality, agent_web_action_correctness, agent_conversation_quality.

Leggi la documentazione sull'Annotazione Agentica →

Solo Mode

La seconda funzionalità principale di Potato 2.3 è Solo Mode: un flusso di lavoro a 12 fasi che sostituisce il paradigma tradizionale multi-annotatore con un singolo esperto umano che collabora con un LLM.

Il Problema

L'annotazione tradizionale richiede più annotatori per garantire l'affidabilità. Ma assumere, formare e coordinare un team è costoso e lento. Per molti progetti di ricerca, il collo di bottiglia dell'annotazione non è l'interfaccia -- è la logistica.

La Soluzione

Solo Mode consente a un singolo esperto del dominio di etichettare un sottoinsieme strategicamente selezionato dei dati. Un LLM impara da quelle etichette, propone etichette per le istanze rimanenti, e il revisore umano esamina solo i casi in cui l'LLM ha difficoltà. Un flusso di lavoro a 12 fasi orchestra tutto questo automaticamente.

Nei benchmark interni, Solo Mode ha raggiunto un accordo superiore al 95% con le pipeline complete multi-annotatore richiedendo solo il 10-15% del totale delle etichette umane.

Le 12 Fasi

1. Seed Annotation -- l'umano etichetta 50 istanze diverse
2. Initial LLM Calibration -- l'LLM etichetta un batch di calibrazione usando gli esempi seed
3. Confusion Analysis -- identifica gli schemi sistematici di disaccordo umano-LLM
4. Guideline Refinement -- l'LLM propone linee guida migliorate; l'umano approva
5. Labeling Function Generation -- regole programmatiche ispirate ad ALCHEmist per le istanze facili
6. Active Labeling -- l'umano etichetta le istanze rimanenti più informative
7. Automated Refinement Loop -- ri-etichettatura iterativa con linee guida aggiornate
8. Disagreement Exploration -- l'umano risolve i casi in cui l'LLM e le funzioni di etichettatura sono in conflitto
9. Edge Case Synthesis -- l'LLM genera esempi ambigui sintetici per l'etichettatura umana
10. Cascaded Confidence Escalation -- l'umano revisiona le etichette LLM con confidenza più bassa
11. Prompt Optimization -- ricerca automatizzata del prompt ispirata a DSPy
12. Final Validation -- revisione di un campione casuale; passa o torna al ciclo

Avvio Rapido

solo_mode:
  enabled: true
  llm:
    endpoint_type: openai
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
  seed_count: 50
  accuracy_threshold: 0.92
  confidence_threshold: 0.85
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    labels: [Positive, Neutral, Negative]

Prioritizzazione delle Istanze Multi-Segnale

Solo Mode usa sei pool ponderati per selezionare le istanze più preziose per l'etichettatura umana:

solo_mode:
  prioritization:
    pools:
      - name: uncertain
        weight: 0.30
      - name: disagreement
        weight: 0.25
      - name: boundary
        weight: 0.20
      - name: novel
        weight: 0.10
      - name: error_pattern
        weight: 0.10
      - name: random
        weight: 0.05

Leggi la documentazione di Solo Mode →

Best-Worst Scaling

Potato 2.3 aggiunge Best-Worst Scaling (BWS), noto anche come Maximum Difference Scaling. Gli annotatori vedono una tupla di elementi (tipicamente 4) e selezionano il migliore e il peggiore secondo un certo criterio. BWS produce punteggi scalari affidabili da semplici giudizi binari, richiedendo molte meno annotazioni delle scale Likert per la stessa potenza statistica.

annotation_schemes:
  - annotation_type: best_worst_scaling
    name: fluency
    description: "Select the BEST and WORST translation"
    items_key: "translations"
    tuple_size: 4
    best_label: "Most Fluent"
    worst_label: "Least Fluent"
    randomize_order: true
 
    tuple_generation:
      method: balanced_incomplete
      tuples_per_item: 5
 
    scoring:
      method: bradley_terry
      auto_compute: true
      include_confidence: true

Sono disponibili tre metodi di scoring:

• Counting -- semplice (best_count - worst_count) / apparizioni
• Bradley-Terry -- modello di confronto a coppie (default consigliato)
• Plackett-Luce -- modello di ranking completo per la massima efficienza dei dati

Calcola il punteggio dalla CLI:

python -m potato.bws score --config config.yaml --method bradley_terry --output scores.csv

La dashboard admin include una scheda BWS con distribuzioni dei punteggi, grafici di convergenza e metriche di affidabilità split-half.

Leggi la documentazione su Best-Worst Scaling →

Autenticazione SSO e OAuth

I deployment di annotazione in produzione hanno bisogno di un'autenticazione adeguata. Potato 2.3 supporta tre metodi OAuth:

Google OAuth

authentication:
  method: google_oauth
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/google/callback"
    allowed_domains:
      - "umich.edu"
    auto_register: true

GitHub OAuth con Restrizione all'Organizzazione

authentication:
  method: github_oauth
  github_oauth:
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/github/callback"
    allowed_organizations:
      - "my-research-lab"
    scopes:
      - "read:user"
      - "read:org"

OIDC Generico

Connettiti a Okta, Azure AD, Auth0, Keycloak o qualsiasi provider conforme a OIDC:

authentication:
  method: oidc
  oidc:
    discovery_url: "https://accounts.example.com/.well-known/openid-configuration"
    client_id: ${OIDC_CLIENT_ID}
    client_secret: ${OIDC_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/oidc/callback"

Tutti i metodi supportano la restrizione per dominio, la registrazione automatica e la modalità mista (più metodi di autenticazione sulla stessa pagina di login).

Leggi la documentazione SSO e OAuth →

Esportazione Parquet

I dati di annotazione sono sempre più consumati da strumenti di data science che si aspettano formati colonnari. Potato 2.3 può esportare le annotazioni direttamente in Apache Parquet, producendo tre file strutturati:

• annotations.parquet -- una riga per (istanza, annotatore, schema) con valori, timestamp e durate
• spans.parquet -- una riga per span annotato con offset, etichette e link
• items.parquet -- metadati delle istanze con conteggi e stato delle annotazioni

parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd
  auto_export: true

Carica direttamente in pandas, DuckDB, PyArrow, Polars o Hugging Face Datasets:

import pandas as pd
annotations = pd.read_parquet("output/parquet/annotations.parquet")
 
# O con DuckDB per query SQL
import duckdb
duckdb.sql("""
  SELECT instance_id, value, COUNT(*) as n
  FROM 'output/parquet/annotations.parquet'
  WHERE schema_name = 'sentiment'
  GROUP BY instance_id, value
""")

Supporta compressione snappy, gzip, zstd, lz4 e brotli, esportazione incrementale con partizionamento per data/annotatore e codifica a dizionario per colonne di stringhe.

Leggi la documentazione sull'Esportazione Parquet →

15 Nuovi Progetti Demo

Potato 2.3 viene fornito con 15 nuovi progetti demo nella directory project-hub/, che coprono le nuove funzionalità:

Demo di Annotazione Agentica

1. react-agent-eval -- Valuta le tracce degli agenti ReAct con valutazioni a livello di passo
2. web-agent-eval -- Valutazione delle tracce WebArena con overlay degli screenshot
3. chatbot-eval -- Valutazione della chat interattiva con proxy dell'agente live
4. multi-agent-eval -- Valuta i sistemi multi-agente CrewAI
5. swebench-eval -- Valutazione delle tracce SWE-bench per agenti di programmazione

Demo di Solo Mode

6. solo-sentiment -- Classificazione del sentiment in Solo Mode su recensioni di prodotti
7. solo-ner -- Riconoscimento di entità nominate in Solo Mode
8. solo-toxicity -- Rilevamento della tossicità in Solo Mode con sintesi di casi limite

Demo di Best-Worst Scaling

9. bws-translation -- Ranking della qualità della traduzione automatica
10. bws-summarization -- Confronto della qualità dei riassunti
11. bws-image-quality -- Ranking della qualità della generazione di immagini

Demo di Autenticazione

12. google-oauth-demo -- Esempio di configurazione Google OAuth
13. github-oauth-demo -- GitHub OAuth con restrizione all'organizzazione

Demo di Esportazione

14. parquet-export-demo -- Esportazione Parquet con script di analisi DuckDB
15. huggingface-upload -- Esporta in Parquet e carica su Hugging Face Hub

Ogni demo include un config.yaml completo, dati di esempio e un README con le istruzioni di configurazione. Avvia qualsiasi demo con:

cd project-hub/react-agent-eval
potato start config.yaml

Hardening della Sicurezza

Potato 2.3 include diversi miglioramenti alla sicurezza:

• I token di sessione usano la generazione casuale crittograficamente sicura con scadenza configurabile
• La protezione CSRF è abilitata per impostazione predefinita per tutti i form
• Il rate limiting sugli endpoint di autenticazione (configurabile, default 10 tentativi al minuto)
• La sanitizzazione degli input per tutti i contenuti forniti dall'utente visualizzati nell'interfaccia di annotazione
• Audit delle dipendenze -- tutte le dipendenze Python e JavaScript aggiornate alle ultime versioni sicure
• Header Content Security Policy aggiunti per prevenire XSS

security:
  csrf_protection: true
  rate_limiting:
    auth_attempts: 10            # per minuto
    api_requests: 100            # per minuto
  session:
    token_length: 64
    lifetime_hours: 24
  content_security_policy: true

Aggiornamento

Da Potato 2.2.x

pip install --upgrade potato-annotation

Tutte le configurazioni v2.2 sono completamente retrocompatibili. Non sono necessarie modifiche alle configurazioni esistenti.

Nuove Dipendenze

L'esportazione Parquet richiede PyArrow:

pip install potato-annotation[parquet]

Solo Mode richiede un SDK del provider LLM:

pip install potato-annotation[solo]    # installa gli SDK openai + anthropic

Oppure installa tutto:

pip install potato-annotation[all]

Cosa C'è Dopo

Potato 2.3 rappresenta un'espansione significativa di ciò che gli strumenti di annotazione possono fare. Stiamo già lavorando al prossimo set di funzionalità:

• Annotation diffing -- confronta le annotazioni tra i round e gli annotatori con diff visivi
• Federated annotation -- coordina l'annotazione tra più istanze di Potato
• Streaming data sources -- annota dati da Kafka, Pub/Sub e altri sistemi di streaming
• Interfaccia ottimizzata per mobile -- annotazione responsive per tablet e telefoni

Ci piacerebbe ricevere il tuo feedback. Apri issue su GitHub, partecipa alla discussione in GitHub Discussions o contatta direttamente il team.

Link

• Guida all'Installazione
• Novità in v2.3
• Annotazione Agentica
• Solo Mode
• Best-Worst Scaling
• SSO e OAuth
• Esportazione Parquet
• Repository GitHub
• Pacchetto PyPI