Novità

Questa pagina illustra le nuove funzionalità e i miglioramenti introdotti nelle versioni Potato v2.x.

Potato 2.3.0

Rilasciato il 9 marzo 2026

Potato 2.3 è la versione più importante nella storia di Potato: introduce l'annotazione agentiva, la modalità Solo, il Best-Worst Scaling, l'autenticazione SSO/OAuth, l'esportazione Parquet, 15 nuovi progetti demo e il rafforzamento della sicurezza.

Annotazione Agentiva

Un sistema completo per valutare agenti AI tramite annotazione umana. Include 12 convertitori di formato trace, 3 tipi di visualizzazione specializzati e 9 schemi di annotazione predefiniti.

12 Convertitori di Formato Trace — Importa trace di agenti da OpenAI, Anthropic, SWE-bench, OpenTelemetry, MCP, CrewAI/AutoGen/LangGraph, LangChain, LangFuse, ReAct, WebArena/VisualWebArena, ATIF e registrazioni raw del browser. Rilevamento automatico disponibile.

agentic:
  enabled: true
  trace_converter: react       # or openai, anthropic, webarena, auto, etc.
  trace_file: "data/traces.jsonl"

3 Tipi di Visualizzazione:

• Agent Trace Display — Schede di step con codice colore, osservazioni espandibili, formattazione JSON e barra laterale temporale per agenti che usano strumenti
• Web Agent Trace Display — Screenshot completi con overlay SVG che mostrano click, input di testo e azioni di scorrimento; navigazione a pellicola per agenti di navigazione web
• Interactive Chat Display — Modalità chat dal vivo (l'annotatore interagisce con l'agente tramite proxy) e modalità revisione trace per agenti conversazionali

Valutazioni Per-Turno — Valuta i singoli step insieme alla trace complessiva per una valutazione granulare.

9 Schemi Predefiniti — 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.

Sistema Proxy per Agenti — Proxy OpenAI, HTTP ed echo per la valutazione di agenti in tempo reale.

Scopri di più sull'Annotazione Agentiva →

Modalità Solo

Un flusso di lavoro intelligente in 12 fasi in cui un singolo annotatore umano collabora con un LLM per etichettare interi dataset, raggiungendo un accordo del 95%+ con pipeline multi-annotatore richiedendo solo il 10-15% delle etichette umane totali.

Le 12 Fasi:

1. Annotazione iniziale — l'umano etichetta 50 istanze diverse
2. Calibrazione iniziale LLM — l'LLM etichetta usando esempi iniziali
3. Analisi della confusione — identifica pattern di disaccordo sistematici
4. Raffinamento delle linee guida — l'LLM propone, l'umano approva le linee guida aggiornate
5. Generazione di funzioni di etichettatura — regole programmatiche ispirate ad ALCHEmist
6. Etichettatura attiva — l'umano etichetta le istanze più informative
7. Ciclo di raffinamento automatizzato — ri-etichettatura iterativa con linee guida migliorate
8. Esplorazione dei disaccordi — l'umano risolve i conflitti tra LLM e funzioni di etichettatura
9. Sintesi dei casi limite — l'LLM genera esempi ambigui per l'etichettatura umana
10. Escalation a cascata della confidenza — l'umano rivede le etichette con confidenza più bassa
11. Ottimizzazione dei prompt — ricerca automatica dei prompt ispirata a DSPy
12. Validazione finale — revisione su campione casuale

solo_mode:
  enabled: true
  llm:
    endpoint_type: openai
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
  seed_count: 50
  accuracy_threshold: 0.92

Prioritizzazione Multi-Segnale delle Istanze — 6 pool ponderati (uncertain, disagreement, boundary, novel, error_pattern, random) per selezionare le istanze più preziose.

Scopri di più sulla Modalità Solo →

Best-Worst Scaling

Annotazione comparativa efficiente in cui gli annotatori selezionano gli elementi migliori e peggiori da tuple. Generazione automatica di tuple con design a blocchi incompleti bilanciati e tre metodi di punteggio (Counting, Bradley-Terry, Plackett-Luce).

annotation_schemes:
  - annotation_type: best_worst_scaling
    name: fluency
    items_key: "translations"
    tuple_size: 4
    best_label: "Most Fluent"
    worst_label: "Least Fluent"
    scoring:
      method: bradley_terry

Scopri di più sul Best-Worst Scaling →

Autenticazione SSO & OAuth

Autenticazione pronta per la produzione con Google OAuth (restrizione di dominio), GitHub OAuth (restrizione di organizzazione) e OIDC generico (Okta, Azure AD, Auth0, Keycloak). Supporta registrazione automatica, modalità mista e gestione delle sessioni.

authentication:
  method: google_oauth
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    allowed_domains:
      - "umich.edu"
    auto_register: true

Scopri di più su SSO & OAuth →

Esportazione Parquet

Esporta le annotazioni in formato Apache Parquet, producendo tre file strutturati: annotations.parquet, spans.parquet e items.parquet. Supporta compressione snappy, gzip, zstd, lz4 e brotli, esportazione incrementale e partizionamento per data/annotatore. Compatibile con pandas, DuckDB, PyArrow, Polars e Hugging Face Datasets.

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

Scopri di più sull'Esportazione Parquet →

15 Nuovi Progetti Demo

Nuovi demo in project-hub/ che coprono l'annotazione agentiva (5 demo), la modalità Solo (3 demo), il Best-Worst Scaling (3 demo), l'autenticazione (2 demo) e i flussi di esportazione (2 demo). Avvia qualsiasi demo con potato start config.yaml.

Rafforzamento della Sicurezza

• Token di sessione crittograficamente sicuri con scadenza configurabile
• Protezione CSRF abilitata per impostazione predefinita
• Limitazione della frequenza sugli endpoint di autenticazione
• Sanitizzazione dell'input per i contenuti forniti dagli utenti
• Audit delle dipendenze con tutti i pacchetti aggiornati
• Header Content Security Policy

Altri Miglioramenti

• Convertitori di trace personalizzati per framework di agenti non supportati
• Modalità Solo ibrida con campionamento di verifica multi-annotatore
• Scheda dashboard amministrativa BWS con grafici di convergenza dei punteggi
• Esportazione Parquet incrementale con partizionamento per data

Confronto v2.2 vs v2.3

Potato 2.2.0

Rilasciato il 20 febbraio 2026

Potato 2.2 è una versione con importanti nuove funzionalità: 9 nuovi schemi di annotazione, un sistema di esportazione modulare, stima della competenza MACE, 55 strumenti di indagine validati e sorgenti di dati remote.

Nuovi Schemi di Annotazione (9)

Annotazione di Eventi — Strutture di eventi N-arie con span trigger e ruoli argomento tipizzati. Annota eventi come ATTACK, HIRE e TRAVEL con argomenti entità vincolati e visualizzazione ad archi hub-spoke.

annotation_schemes:
  - annotation_type: event_annotation
    name: events
    span_schema: entities
    event_types:
      - type: "ATTACK"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "attacker"
            entity_types: ["PERSON", "ORGANIZATION"]
            required: true

Scopri di più sull'Annotazione di Eventi →

Entity Linking — Collega le annotazioni di span a basi di conoscenza esterne (Wikidata, UMLS, API REST personalizzate). Aggiungi un blocco entity_linking: a qualsiasi schema di span per abilitare la ricerca e il collegamento alla KB.

Scopri di più sull'Entity Linking →

Triage — Interfaccia accept/reject/skip in stile Prodigy per la selezione rapida dei dati. Etichette personalizzabili, scorciatoie da tastiera e avanzamento automatico per annotazioni ad alta produttività.

Scopri di più sul Triage →

Confronto a Coppie — Confronta due elementi con modalità binaria (clic sul riquadro preferito) o su scala (slider). Supporta items_key, allow_tie, blocco scale: con intervallo configurabile.

Scopri di più sul Confronto a Coppie →

Alberi di Conversazione — Annota strutture di conversazione gerarchiche con valutazioni per nodo, selezione del percorso e confronto dei rami.

Scopri di più sugli Alberi di Conversazione →

Catene di Coreferenza — Raggruppa le menzioni di testo che si riferiscono alla stessa entità in catene con indicatori visivi. Supporta tipi di entità, controllo dei singleton e diverse modalità di evidenziazione.

Scopri di più sulle Catene di Coreferenza →

Maschere di Segmentazione — Nuovi strumenti fill, eraser e brush per la segmentazione di immagini a livello di pixel.

Bounding Box per PDF/Documenti — Disegna riquadri su pagine PDF per attività di annotazione di documenti.

Span Discontinui — allow_discontinuous: true abilita la selezione di segmenti di testo non contigui come un singolo span.

Annotazione Intelligente

Stima della Competenza MACE — Algoritmo EM Variazionale Bayes che stima congiuntamente le etichette vere e i punteggi di competenza degli annotatori (0.0-1.0). Funziona con schemi radio, likert, select e multiselect.

mace:
  enabled: true
  trigger_every_n: 10
  min_annotations_per_item: 3

Scopri di più su MACE →

Evidenziazione delle Opzioni — Evidenziazione basata su LLM delle opzioni probabilmente corrette per attività di annotazione discreta. Evidenzia le prime k opzioni con un indicatore a stella attenuando le opzioni meno probabili.

ai_support:
  option_highlighting:
    enabled: true
    top_k: 3
    dim_opacity: 0.4

Scopri di più sull'Evidenziazione delle Opzioni →

Ordinamento per Diversità — Clustering basato su embedding e campionamento round-robin per garantire che gli annotatori vedano contenuti diversi anziché elementi simili in sequenza.

assignment_strategy: diversity_clustering
diversity_ordering:
  enabled: true
  prefill_count: 100

Scopri di più sull'Ordinamento per Diversità →

Sistema di Esportazione

Un nuovo CLI di esportazione modulare (python -m potato.export) converte le annotazioni in 6 formati standard del settore: COCO, YOLO, Pascal VOC, CoNLL-2003, CoNLL-U e Maschere di Segmentazione.

python -m potato.export --config config.yaml --format coco --output ./export/

Scopri di più sui Formati di Esportazione →

Sorgenti di Dati Remote

Carica dati di annotazione da URL, S3, Google Drive, Dropbox, Hugging Face, Google Sheets e database SQL tramite il nuovo blocco di configurazione data_sources:. Include caricamento parziale, caching e gestione delle credenziali.

Scopri di più sulle Sorgenti di Dati Remote →

Strumenti di Indagine

55 questionari validati in 8 categorie (Personalità, Salute Mentale, Affetto, Concetto di Sé, Atteggiamenti Sociali, Stile di Risposta, Forma Breve, Dati Demografici). Da utilizzare nelle fasi pre-studio/post-studio con instrument: "tipi".

Scopri di più sugli Strumenti di Indagine →

Altri Miglioramenti

• Tracciamento di oggetti video con interpolazione dei keyframe
• Supporto per file di configurazione AI esterni
• Miglioramenti al layout a griglia dei moduli
• Gestori di formato per PDF, Word, codice e fogli di calcolo

Potato 2.1.0

Rilasciato il 5 febbraio 2026

Potato 2.1 introduce il sistema di visualizzazione delle istanze, il supporto AI visivo, il collegamento di span, l'annotazione di span su più campi e la personalizzazione del layout.

Sistema di Visualizzazione delle Istanze

Un nuovo blocco di configurazione instance_display che separa la visualizzazione del contenuto dall'annotazione. Visualizza qualsiasi combinazione di immagini, video, audio, testo e dialoghi insieme a qualsiasi schema di annotazione.

instance_display:
  fields:
    - key: image_url
      type: image
      display_options:
        max_width: 600
        zoomable: true
    - key: description
      type: text
 
annotation_schemes:
  - annotation_type: radio
    name: category
    labels: [nature, urban, people]

Supporta 11 tipi di visualizzazione tra cui text, html, image, video, audio, dialogue, pairwise, code, spreadsheet, document e pdf.

Scopri di più sulla Visualizzazione delle Istanze →

Annotazione di Span su Più Campi

Gli schemi di annotazione di span ora supportano un'opzione target_field per annotare su più campi di testo nella stessa istanza.

annotation_schemes:
  - annotation_type: span
    name: source_entities
    target_field: "source_text"
    labels: [PERSON, ORGANIZATION]
 
  - annotation_type: span
    name: summary_entities
    target_field: "summary"
    labels: [PERSON, ORGANIZATION]

Scopri di più sull'Annotazione di Span →

Collegamento di Span

Un nuovo tipo di annotazione span_link per creare relazioni tipizzate tra span annotati. Supporta collegamenti diretti e non diretti, relazioni N-arie, visualizzazione ad archi e vincoli sulle etichette.

annotation_schemes:
  - annotation_type: span
    name: entities
    labels:
      - name: "PERSON"
        color: "#3b82f6"
      - name: "ORGANIZATION"
        color: "#22c55e"
 
  - annotation_type: span_link
    name: relations
    span_schema: entities
    link_types:
      - name: "WORKS_FOR"
        directed: true
        allowed_source_labels: ["PERSON"]
        allowed_target_labels: ["ORGANIZATION"]
        color: "#dc2626"

Scopri di più sul Collegamento di Span →

Supporto AI Visivo

Quattro nuovi endpoint di visione per l'assistenza AI nell'annotazione di immagini e video:

• YOLO — Rilevamento di oggetti locale rapido
• Ollama Vision — Modelli visione-linguaggio locali (LLaVA, Qwen-VL)
• OpenAI Vision — Visione cloud GPT-4o
• Anthropic Vision — Claude con visione

Le funzionalità includono rilevamento di oggetti, pre-annotazione, classificazione, suggerimenti, rilevamento di scene, rilevamento di keyframe e tracciamento di oggetti.

Scopri di più sul Supporto AI Visivo →

Personalizzazione del Layout

Crea sofisticati layout visivi personalizzati usando template HTML e CSS. Potato genera un file di layout modificabile, oppure puoi fornire un template completamente personalizzato con layout a griglia, opzioni con codice colore e stili di sezione.

task_layout: layouts/custom_task_layout.html

Tre layout di esempio inclusi: moderazione dei contenuti, QA di dialogo e revisione medica.

Scopri di più sulla Personalizzazione del Layout →

Motivazioni delle Etichette

Una quarta funzionalità AI che genera spiegazioni bilanciate su perché ogni etichetta potrebbe applicarsi, aiutando gli annotatori a comprendere le diverse prospettive di classificazione.

ai_support:
  features:
    rationales:
      enabled: true

Scopri di più sul Supporto AI →

Altri Miglioramenti

• Oltre 50 nuovi test per una maggiore affidabilità
• Miglioramenti al design responsivo
• Migliore organizzazione del project-hub con esempi di layout
• Correzioni di bug in tutti i tipi di annotazione

Confronto v2.0 vs v2.1

Potato 2.0

Potato 2.0 è una versione principale che introduce potenti nuove funzionalità per un'annotazione intelligente e scalabile. Questa sezione evidenzia le principali aggiunte e miglioramenti.

Supporto AI

Integra Large Language Model per assistere gli annotatori con suggerimenti intelligenti, evidenziazione di parole chiave e proposte di etichette.

Provider supportati:

• OpenAI (GPT-4, GPT-3.5)
• Anthropic (Claude 3, Claude 3.5)
• Google (Gemini)
• Ollama (modelli locali)
• vLLM (self-hosted)

ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4
    api_key: ${OPENAI_API_KEY}
  features:
    hints:
      enabled: true
    label_suggestions:
      enabled: true

Scopri di più sul Supporto AI →

Annotazione Audio

Annotazione audio completa con visualizzazione della forma d'onda basata su Peaks.js. Crea segmenti, etichetta regioni temporali e annota il parlato con scorciatoie da tastiera.

Funzionalità principali:

• Visualizzazione della forma d'onda
• Creazione ed etichettatura di segmenti
• Domande di annotazione per segmento
• Oltre 15 scorciatoie da tastiera
• Caching della forma d'onda lato server

annotation_schemes:
  - annotation_type: audio
    name: speakers
    mode: label
    labels:
      - Speaker A
      - Speaker B

Scopri di più sull'Annotazione Audio →

Apprendimento Attivo

Assegna automaticamente priorità alle istanze di annotazione in base all'incertezza del modello. Addestra classificatori sulle annotazioni esistenti e concentra gli annotatori sugli esempi più informativi.

Capacità:

• Opzioni multiple per i classificatori (LogisticRegression, RandomForest, SVC, MultinomialNB)
• Vari vettorizzatori (TF-IDF, Count, Hashing)
• Persistenza del modello tra i riavvii
• Selezione potenziata da LLM
• Supporto multi-schema

active_learning:
  enabled: true
  schema_names:
    - sentiment
  min_instances_for_training: 30
  update_frequency: 50
  classifier:
    type: LogisticRegression

Scopri di più sull'Apprendimento Attivo →

Fase di Addestramento

Qualifica gli annotatori con domande di pratica prima dell'attività principale. Fornisci feedback immediato e garantisci la qualità tramite criteri di superamento configurabili.

Funzionalità:

• Domande di pratica con risposte note
• Feedback immediato e spiegazioni
• Criteri di superamento configurabili
• Opzioni per i tentativi ripetuti
• Monitoraggio dei progressi nella dashboard amministrativa

phases:
  training:
    enabled: true
    data_file: "data/training.json"
    passing_criteria:
      min_correct: 8
      total_questions: 10

Scopri di più sulla Fase di Addestramento →

Dashboard Amministrativa Potenziata

Interfaccia completa di monitoraggio e gestione per le attività di annotazione.

Schede della dashboard:

• Panoramica: Metriche di alto livello e tassi di completamento
• Annotatori: Monitoraggio delle prestazioni, analisi dei tempi
• Istanze: Navigazione dei dati con punteggi di disaccordo
• Configurazione: Regolazione delle impostazioni in tempo reale

admin_api_key: ${ADMIN_API_KEY}

Scopri di più sulla Dashboard Amministrativa →

Backend Database

Supporto MySQL per deployment su larga scala con connection pooling e supporto alle transazioni.

database:
  type: mysql
  host: localhost
  database: potato_db
  user: ${DB_USER}
  password: ${DB_PASSWORD}

Potato crea automaticamente le tabelle necessarie al primo avvio.

Cronologia delle Annotazioni

Tracciamento completo di tutte le modifiche alle annotazioni con timestamp, ID utente e tipi di azione. Consente l'auditing e l'analisi comportamentale.

{
  "history": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "user": "annotator_1",
      "action": "create",
      "schema": "sentiment",
      "value": "Positive"
    }
  ]
}

Flussi di Lavoro Multi-Fase

Costruisci flussi di lavoro di annotazione complessi con più fasi sequenziali:

1. Consenso - Raccolta del consenso informato
2. Pre-studio - Dati demografici e screening
3. Istruzioni - Linee guida per il task
4. Addestramento - Domande di pratica
5. Annotazione - Attività principale
6. Post-studio - Sondaggi di feedback

phases:
  consent:
    enabled: true
    data_file: "data/consent.json"
  prestudy:
    enabled: true
    data_file: "data/demographics.json"
  training:
    enabled: true
    data_file: "data/training.json"
  poststudy:
    enabled: true
    data_file: "data/feedback.json"

Scopri di più sui Flussi di Lavoro Multi-Fase →

Modifiche alla Configurazione in v2.0

Nuova Struttura di Configurazione

Potato 2.0 utilizza un formato di configurazione più pulito:

v1 (vecchio):

data_files:
  - data.json
id_key: id
text_key: text
output_file: annotations.json

v2 (nuovo):

data_files:
  - "data/data.json"
 
item_properties:
  id_key: id
  text_key: text
 
output_annotation_dir: "output/"
output_annotation_format: "json"

Requisito di Sicurezza

I file di configurazione devono ora trovarsi all'interno di task_dir:

# Valid - config.yaml is in the project directory
task_dir: "."
 
# Valid - config in configs/ subdirectory
task_dir: "my_project/"

Confronto Rapido

Guida alla Migrazione

Aggiornamento della Configurazione (da v1 a v2)

1. Configurazione dei dati

   yamlCopy

   # Old
   id_key: id
   text_key: text
    
   # New
   item_properties:
     id_key: id
     text_key: text

2. Configurazione dell'output

   yamlCopy

   # Old
   output_file: annotations.json
    
   # New
   output_annotation_dir: "output/"
   output_annotation_format: "json"

3. Posizione del file di configurazione Assicurati che il tuo file di configurazione si trovi all'interno della directory del progetto.

Avvio del Server

# v2 command
python -m potato start config.yaml -p 8000
 
# Or shorthand
potato start config.yaml

Per Iniziare

Vuoi provare Potato? Inizia con la Guida Rapida o esplora funzionalità specifiche:

Funzionalità v2.3:

• Annotazione Agentiva - Valuta agenti AI con 12 convertitori e 3 tipi di visualizzazione
• Modalità Solo - Etichettatura collaborativa umano-LLM
• Best-Worst Scaling - Annotazione comparativa con punteggio
• SSO & OAuth - Autenticazione Google, GitHub e OIDC
• Esportazione Parquet - Esportazione dati colonnare

Funzionalità v2.2:

• Annotazione di Eventi - Strutture di eventi N-arie
• Entity Linking - Collegamento a basi di conoscenza
• Triage - Selezione rapida dei dati
• Catene di Coreferenza - Coreferenza delle entità
• Alberi di Conversazione - Annotazione di dialoghi gerarchici
• MACE - Stima della competenza degli annotatori
• Evidenziazione delle Opzioni - Guida alle opzioni assistita da AI
• Ordinamento per Diversità - Ordinamento degli elementi basato su embedding
• Formati di Esportazione - CLI di esportazione con 6 formati
• Sorgenti Dati Remote - Caricamento dati cloud
• Strumenti di Indagine - 55 questionari validati

Funzionalità v2.1:

• Visualizzazione Istanze - Visualizzazione di contenuti multimodali
• Supporto AI Visivo - AI per l'annotazione di immagini e video
• Collegamento Span - Annotazione di relazioni tra entità

Funzionalità Principali:

• Supporto AI - Assistenza intelligente all'annotazione
• Apprendimento Attivo - Prioritizzazione intelligente delle istanze
• Annotazione Audio - Annotazione basata sulla forma d'onda
• Fase di Addestramento - Qualifica degli annotatori
• Dashboard Amministrativa - Monitoraggio e gestione