Novità

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

Potato 2.11.1

Rilasciato a ottobre 2026

Potato 2.11.1 consente di nuovo a potato start config.yaml --debug di avviarsi sull'indirizzo predefinito, aggiunge i classificatori di immagini all'addestramento dei modelli e corregge le pre-etichette che andavano perse a ogni riavvio.

pip install --upgrade potato-annotation

Modalità debug

Dalla 2.8.2 alla 2.11.0, un server in modalità debug sull'indirizzo predefinito 0.0.0.0 si rifiutava di partire se non veniva indicato --host 127.0.0.1. Nella 2.11.1 si avvia su qualsiasi indirizzo, e le altre macchine della rete possono raggiungerlo. La guida al debug descrive che cosa fa ora la modalità debug:

• La pagina di login resta, a meno che tu non aggiunga --debug-phase. Con --debug-phase ogni visitatore entra come il debug_user condiviso, quindi non usarlo per uno studio reale.
• Le pagine di amministrazione si aprono senza chiave solo per le richieste che arrivano dalla macchina stessa del server, cioè da un indirizzo di loopback senza intestazione X-Forwarded-For, X-Real-IP o Forwarded. Questo vale anche con un bind su 127.0.0.1, dove la 2.11.0 lasciava passare ogni richiesta, perché un proxy o un tunnel sulla stessa macchina inoltra a 127.0.0.1 le richieste di altre macchine.
• Il debugger interattivo di Werkzeug funziona solo con un bind su 127.0.0.1, perché esegue il codice digitato nel browser.

POTATO_ALLOW_REMOTE_DEBUG non viene più letto. Un comando di debug con --host 127.0.0.1 funziona ancora e dà ancora accesso al debugger interattivo.

Classificazione di immagini e pre-etichette

• L'addestramento dei modelli adatta classificatori di immagini. Uno schema radio o multiselect i cui item indicano file di immagine viene addestrato su embedding CLIP, mentre prima adattava un TF-IDF sui percorsi dei file. Le immagini remote o mancanti vengono escluse con un avviso.
• L'apprendimento attivo sulle immagini funziona come documentato. vectorizer: {name: image} costruisce il vettorizzatore CLIP. Prima il gestore non sapeva costruire un vettorizzatore con quel nome, quindi uno studio del genere veniva ordinato con TF-IDF sui percorsi dei file.
• Il motore di etichettatura distilla classificatori di immagini in uno studio su immagini (labeling_engine.distill.modality).
• Pre-etichette per gli item non etichettati. model_training.writeback.include_unlabeled: true fa previsioni sugli item che nessuno ha ancora etichettato. Prima un'esecuzione faceva previsioni solo su item tenuti da parte e già etichettati, quindi la scrittura di ritorno non raggiungeva mai gli item a cui serve una pre-etichetta.

La documentazione sull'addestramento dei modelli copre le esecuzioni di addestramento, la scrittura di ritorno e la coda di revisione.

Correzioni che riguardano gli studi precedenti

• Le pre-etichette non sopravvivevano a un riavvio. All'avvio, la riproduzione delle previsioni salvate partiva prima che fosse caricato qualsiasi item, quindi la coda di revisione del modello si svuotava a ogni riavvio. Ora parte dopo il caricamento degli item e applica gli stessi controlli della scrittura di ritorno.
• Un modello di testo si addestrava sugli URL. Per gli item con un campo url, path o file_name, l'addestratore riceveva quel valore invece del testo.
• Il reset della password falliva con l'SSO. Con method: oauth e allow_local_login, ogni reset generava un errore. Ora gli account locali si possono reimpostare.
• ai_support rifiutava OpenRouter. endpoint_type: openrouter ora è accettato.

Le note di rilascio riportano l'elenco completo.

Potato 2.11.0

Rilasciato a ottobre 2026

Potato 2.11.0 aggiunge il motore di etichettatura, che etichetta un dataset con dei modelli e usa un campione casuale e in cieco di etichette umane per misurare quanto spesso i modelli sbagliano. Sei tu a indicare che cosa devono soddisfare le etichette finali, per esempio "al massimo il 5% delle etichette automatiche accettate è sbagliato, con una confidenza del 90%". Il motore accetta le etichette automatiche supportate da un test statistico, manda il resto alle persone e scrive un certificato che registra che cosa è stato testato e su quante etichette umane. Il motore di etichettatura spiega la configurazione.

Le sessioni inattive ora vengono chiuse, per default dopo 8 ore. Prima della 2.11.0, session_timeout_minutes non aveva alcun effetto su un'app in esecuzione, perché il controllo era registrato su un oggetto app che potato start scarta. Una sessione che resta inattiva più a lungo dell'impostazione (480 minuti di default) ora viene cancellata, e la sua richiesta successiva porta alla pagina di login. Sui chioschi e sui computer di laboratorio condivisi che restano connessi tutta la notte inizieranno a verificarsi disconnessioni, quindi aumenta session_timeout_minutes dove conta.

pip install --upgrade potato-annotation

Il motore di etichettatura

Un blocco labeling_engine e assignment_strategy: engine attivano il motore. Le sue fonti sono modelli, provati in ordine di cascata, e un item passa alle persone dopo l'ultima fonte. Ogni contratto riguarda uno schema di annotazione e viene testato su etichette umane che il motore richiede a caso e presenta in cieco, senza pre-annotazione, verdetto del giudice o aiuto dell'IA nella pagina.

• Fonti. LLM, modelli visione-linguaggio, modelli decisionali (Laya e qualsiasi server /v1/systemone), detector YOLO, giudici LLM con scambio dell'ordine delle etichette, giurie, modelli addestrati sulle etichette dello studio stesso ed etichette che hai già.
• Contratti. selective_risk limita, a una confidenza dichiarata, la quota di etichette automatiche accettate che sono sbagliate. ppi fornisce intervalli per la prevalenza o la media che restano validi qualunque sia la qualità della macchina. no_worse_than_human esegue il test dell'annotatore alternativo, budget_first stima che cosa si ottiene con un budget di etichette umane, e distributional confronta le etichette della macchina con il modo in cui le persone si dividono sugli item soggettivi.
• Modalità. Schemi a scelta singola tra N, ordinali, numerici e multi-etichetta, regioni di immagine, audio, video, segmenti di temporal grounding e di annotazione a livelli, oggetti 3D ed etichette dei passi nelle tracce degli agenti. Regioni, segmenti, oggetti 3D e tracce vengono valutati con le misure usate dal report di accordo.
• Audit. Una quota delle etichette automatiche accettate torna alle persone, in cieco. Quando gli audit mostrano un tasso di errore superiore all'obiettivo, il motore smette di accettare etichette automatiche su quello schema (con features.drift, attivo per default), e una nuova certificazione ripristina l'accettazione.
• Interfacce. potato label run|status|certify|certificate|export|calls|distill|optimize|migrate-config, una REST API sotto /api/engine/v1, cinque strumenti MCP engine_*, un Python SDK e una pagina di amministrazione in /admin/labeling-engine.

Un contratto soddisfatto è un'affermazione statistica sull'accordo con le persone che hanno etichettato il campione. Il motore non verifica che quelle persone abbiano ragione, quindi un contratto testato su annotatori inaffidabili certifica l'accordo con annotatori inaffidabili. Contratti del motore di etichettatura spiega che cosa testa ogni contratto e quando fallisce.

icl_labeling, judge_calibration e pre_annotation continuano a funzionare, e ciascuno stampa all'avvio una nota che indica il suo equivalente nel motore. potato label migrate-config scrive il blocco labeling_engine equivalente. La modalità Solo e l'allineamento dei giudici non sono deprecati. Migrare al motore di etichettatura contiene la tabella di conversione.

Accordo

• /admin/iaa riporta più schemi. spatial_annotation, temporal_grounding, tiered_annotation e gli schemi per le tracce degli agenti (process_reward, trajectory_eval, tool_call_review, failure_attribution, gui_trajectory) venivano saltati come non supportati e ora vengono valutati.
• /admin/api/agreement non riporta più gli schemi strutturati. Ridotti a nomi di etichette, tracce degli agenti, segmenti, regioni e oggetti 3D mostravano un accordo perfetto tra ogni coppia di annotatori. La route ora rimanda a /admin/iaa, che confronta le strutture.
• Due segmenti identici di lunghezza zero ora concordano. Prima venivano valutati come disaccordo completo.
• Gli annotatori automatici restano fuori dai dati pubblicati. La pubblicazione e Paper Mode escludono gli annotatori automatici dalle etichette gold e dai dati di accordo.

Modalità Solo

• Suggerimenti in cieco. solo_mode.suggestions nasconde l'etichetta dell'LLM su tutti gli item o su un campione, e il passaggio di consegne legge l'accordo sugli item in cieco, perché un suggerimento sullo schermo ancora la persona che lo controlla.
• Un limite di spesa e una cache delle risposte. ai_budget.cap_usd viene controllato prima che inizi l'etichettatura e prima di ogni batch, e solo_mode.cache riusa la risposta a una chiamata ripetuta.
• Modelli decisionali. Gli endpoint systemone e laya etichettano gli schemi a scelta fissa in un solo forward pass, come primo livello veloce. Modalità Solo contiene una configurazione.
• Gold set, giuria e curriculum. solo_mode.gold valuta un prompt su etichette note prima dell'esecuzione completa, solo_mode.jury fa votare più modelli su ogni item, e instance_selection.curriculum ti fa iniziare dagli item che l'LLM ha trovato più facili. È nuovo anche un controllo della sensibilità al prompt.

Correzioni che riguardano gli studi su 2.10

• Una pagina di immagine salvava da sola una risposta precompilata. In uno schema image_annotation con pre_annotation, il canvas salvava le forme precompilate come risposta dell'annotatore quando ricalcolava il layout dopo il caricamento, quindi un item mai toccato risultava risposto. Ora salva solo una modifica. In uno studio su immagini con 2.10 e pre-annotazioni, alcuni item conteggiati come risposti potrebbero non essere mai stati toccati.
• Le immagini su host senza header CORS non si caricavano. Un host che non invia l'header Access-Control-Allow-Origin, come cocodataset.org, rifiutava la richiesta del canvas, e la pagina mostrava "Failed to load image". Ora la pagina carica queste immagini senza CORS. Il disegno funziona, e il riempimento di regioni, SAM e la segmentazione da prompt testuale, che leggono i pixel dell'immagine, spiegano perché non possono essere eseguiti.
• Una forma pre-annotata senza color veniva scartata. L'item mostrava "Annotations: 0" senza alcun avviso, e ora la forma prende il colore della sua etichetta.
• "Generate prompt" della modalità Solo non chiamava mai un modello. Ora chiede al modello di revisione di scrivere il primo prompt. Senza un modello di revisione ripiega sulla descrizione del task e lo segnala.
• I rifiuti tramite potato mcp connect sembravano successi. Una chiamata a uno strumento rifiutata tornava con isError: false, e ora torna come errore dello strumento con il messaggio del server.
• L'esempio di scheletro di uno studio completo aveva una chiave morta. Potato non legge alcun training.feedback.enabled, quindi ora l'esempio imposta feedback.show_explanations.
• Le sessioni inattive non venivano mai chiuse, come descritto all'inizio di questa voce.
• L'aggiudicazione contava gli annotatori automatici. Gli annotatori automatici potevano mandare un item in aggiudicazione, min_human_annotations veniva ignorato e un punteggio di accordo mancante faceva andare in crash la formattazione.
• L'auto-scaling di Prolific contava le annotazioni automatiche e ignorava i limiti per item. Il numero di posti da aprire ora conta solo le annotazioni umane rispetto al limite di ogni item.
• La scoperta dei casi limite non faceva nulla su vLLM. La decodifica guidata su vLLM non restituiva mai i campi dei casi limite, che ora fanno parte dello schema della risposta.

Le note di rilascio riportano l'elenco completo.

Potato 2.10.3

Rilasciato a ottobre 2026

Potato 2.10.3 corregge tre bug trovati nella 2.10.2 dopo la sua pubblicazione.

pip install --upgrade potato-annotation

• Accordo su dati unanimi. Quando tutti gli annotatori davano la stessa risposta su ogni item, /admin/api/agreement restituiva lo schema come {"error": "float division by zero"}. In questo caso l'accordo dovuto al caso è 1, quindi alpha ed entrambi i kappa non sono definiti. La route ora li riporta come null, con percent_agreement a 1,0 e la stessa nota fornita da /admin/iaa, e la media complessiva esclude lo schema.
• potato deploy button --dry-run resta offline. Senza --hf-backup-repo, la prova a secco chiedeva a HuggingFace a chi appartenesse il token, e un token non valido finiva in un traceback. Ora la prova a secco usa il segnaposto <hf-account>/<name>-annotations, come fa potato deploy up --dry-run, e un'esecuzione reale segnala un token rifiutato con un messaggio di errore.
• Importare Potato non calcola più l'hash di una password. Potato calcolava un hash PBKDF2 al momento dell'import, quindi ogni processo spendeva 100.000 iterazioni all'avvio, strumenti da riga di comando compresi. Ora l'hash viene creato la prima volta che un nome utente sconosciuto prova ad accedere. Inoltre l'import funziona di nuovo sotto Pyodide, il cui hashlib non ha pbkdf2_hmac.

Le note di rilascio riportano l'elenco completo.

Potato 2.10.2

Rilasciato a ottobre 2026

Potato 2.10.2 corregge funzionalità che non funzionavano con un'installazione da pip o nell'immagine Docker, chiude alcuni modi per accedere come un altro utente, fa funzionare il backend MySQL e corregge le statistiche di accordo. Se hai pubblicato valori di accordo calcolati con una versione precedente, ricalcolali.

pip install --upgrade potato-annotation

• Gli account SSO accettavano qualsiasi password. In un task con OAuth, il modulo della password faceva entrare chiunque in un account registrato da un provider. Le identità SSO non si autenticano più tramite password, e in uno studio su MySQL un estraneo non può più registrare il nome utente di un annotatore esistente ed ereditarne il lavoro.
• ai_support e gli strumenti di indagine fallivano con un'installazione da pip. Alla wheel mancavano i prompt AI e gli strumenti di indagine, quindi uno studio che usava uno dei due si fermava all'avvio. Anche i container e le destinazioni di potato deploy saltavano dieci sottosistemi, tra cui il supporto chat.
• Il backend MySQL non si attivava mai. Una configurazione che lo indicava salvava le annotazioni su disco. Installa il driver con pip install 'potato-annotation[mysql]'; ora l'esportazione, i backup e potato deploy pull leggono il database.
• 59 correzioni alle statistiche di accordo, ciascuna verificata rispetto a un'implementazione di riferimento come scipy, sklearn o il pacchetto krippendorff. Un coefficiente indefinito viene riportato come indefinito anziché come 1,0, l'alfa ordinale usa la metrica ordinale di Krippendorff, MACE stima per gli spammer puri una competenza di circa 0,01 invece di 0,35, i risultati non cambiano più dopo un riavvio, e plackett_luce stima la verosimiglianza best-worst invece di ripetere Bradley-Terry.
• Le nuvole di punti in coordinate cartografiche mantengono la loro precisione. Un file LAS in coordinate UTM veniva disegnato su una griglia con passo fino a 0,5 m. Ora Potato lo serve rispetto a un'origine locale e salva le annotazioni nelle coordinate proprie del file.

Le note di rilascio riportano l'elenco completo.

Potato 2.10.1

Rilasciato a ottobre 2026

Potato 2.10.1 corregge cinque problemi di potato deploy e del backup emersi dopo la 2.10.0. Aggiorna prima di affidarti a un'esecuzione di prova.

pip install --upgrade potato-annotation

• Un'esecuzione di prova passava per deploy che poi up rifiutava. Heroku o ECS Express senza --backup, Render o Railway senza uno storage di backup su cui caricare il progetto, e Fly con un progetto troppo grande per essere inviato inline stampavano tutti un piano senza errori. Ora il piano e up eseguono lo stesso controllo, ed entrambi stampano REFUSED: <reason> e terminano con codice di uscita 2.
• --demo veniva proposto dove non può funzionare. Render, Railway ed ECS Express caricano il tuo progetto sullo storage del backup, quindi richiedono --backup hf o --backup s3 anche per uno studio usa e getta. Ora l'avviso del controllo preliminare propone --demo solo per Heroku e HuggingFace.
• --cloud jetstream2 pianificava il flavor sbagliato. L'esecuzione di prova mostrava m1.small, mentre up creava un m3.small.
• Due prezzi erano sbagliati. potato deploy providers indicava circa $16 al mese per aws-ec2 e circa $7 per fly. I piani calcolano $18.31 e $5.85, e ora i riepiloghi indicano circa $18 e circa $6.
• backup: {enabled: false} non disattivava il backup quando la configurazione conteneva ancora un blocco huggingface_backup. Ora prevale il nuovo blocco.

Le note di rilascio riportano l'elenco completo.

Potato 2.10.0

Rilasciato a ottobre 2026

Potato 2.10.0 aggiunge otto piattaforme di hosting a potato deploy, esegue il backup delle annotazioni sugli host il cui disco non sopravvive a un riavvio e aggiunge text_as_image, che mostra il testo di ogni elemento come immagine così che gli annotatori non possano incollarlo in un chatbot. Eseguire Potato in locale o nel cloud indica quale host si adatta a quale studio.

Ora è dichiarato Python 3.9 o successivo. Una dipendenza principale lo richiedeva già, quindi nemmeno le release precedenti si potevano installare su 3.7 o 3.8, e ora pip lo segnala prima di installare qualsiasi cosa.

pip install --upgrade potato-annotation

Deployment

• AWS, in tre modi. --provider aws crea un'istanza Lightsail a un prezzo fisso di $12 al mese che richiede solo i permessi lightsail:*. aws-ec2 serve per gli account in cui Lightsail è disattivato, e aws-ecs esegue il container su ECS Express Mode dietro un indirizzo HTTPS gestito da AWS, a un costo più alto e con un backup obbligatorio.
• Heroku, su un solo dyno Basic. Heroku cancella il disco ogni giorno, quindi Potato si rifiuta di distribuire lì senza --backup o --demo.
• Fly e Railway, ciascuno con un volume persistente.
• Hetzner, Vultr e Linode, come VM configurate allo stesso modo di DigitalOcean, con un certificato Let's Encrypt per l'indirizzo IP.
• OpenStack, con un preset per Jetstream2. Jetstream2 assegna a ogni istanza un nome DNS, quindi il task ottiene un normale certificato. Funzionano anche i cloud OpenStack di ateneo ed EGI.
• Pulsanti di deploy. potato deploy button config.yaml --target heroku|render|aws|railway scrive nel tuo repository i file per un pulsante "Deploy to Heroku", "Deploy to Render" o AWS "Launch Stack", così altre persone possono eseguire il task nei propri account.

I nuovi extra deploy-aws e deploy-openstack installano i client AWS e OpenStack.

Backup e ripristino

Un nuovo blocco backup copia ogni cinque minuti l'output delle annotazioni e gli snapshot dei database SQLite su un dataset HuggingFace, su un bucket compatibile con S3 o su entrambi. Quando un server parte con la directory del task vuota e il backup contiene dati, Potato li ripristina prima di caricare qualsiasi cosa, così dopo un riavvio gli annotatori riprendono da dove si erano fermati. Passa --backup hf, --backup s3 o --backup hf,s3 a potato deploy up. Il vecchio blocco huggingface_backup viene letto come un blocco backup con una sola destinazione e il ripristino disattivato, quindi i deployment esistenti si comportano come prima.

Testo come immagine

text_as_image: true trasforma sul server il testo di ogni elemento in un PNG e rimuove le parole dalla pagina, dal record dell'elemento incorporato e dagli endpoint JSON, così un annotatore non ha nulla da selezionare, copiare o incollare. La funzionalità rende più costoso incollare un elemento in un chatbot, ma un annotatore può comunque ridigitare il testo o eseguire l'OCR su uno screenshot. Uno screen reader non ricava nulla dall'immagine, quindi la funzionalità non è adatta a uno studio con annotatori che ne usano uno. Potato si rifiuta di avviarsi quando text_as_image è combinato con uno schema di span, con uno schema che legge il campo di testo dell'elemento, con Pocket Mode o con Rooms. Contributo di @Eyecatch3r nella PR #169.

Correzioni che incidono sui dati raccolti

• Un riavvio su un host senza disco persistente perdeva il lavoro precedente. Il server partiva vuoto, e il nuovo stato di un annotatore che tornava sovrascriveva la copia di backup. Il ripristino all'avvio risolve il problema.
• DigitalOcean con --volume-gb teneva le annotazioni sul disco root anziché sul volume. L'output e i database SQLite ora si trovano su /data.
• Il backup su HuggingFace non faceva nulla nell'immagine pubblicata, che non includeva huggingface_hub, e su Render e DigitalOcean --hf-token impostava una variabile che nessuno leggeva. L'immagine ora installa il nuovo extra hosting.
• I deploy su Render partivano senza il progetto, e il container terminava con "config file not found". Ora il container scarica il progetto all'avvio e ne verifica lo sha256.

Le note di rilascio riportano l'elenco completo.

Potato dalla 2.9.2 alla 2.9.4

Rilasciato a settembre 2026

Aggiorna alla 2.9.4 o successiva se persone di cui non ti fidi possono raggiungere il tuo server. Prima della 2.9.4, il modulo /forgot-password creava un token di reimpostazione per qualsiasi nome utente inviato e mostrava il link di reimpostazione sulla pagina, quindi chiunque potesse raggiungere il server poteva impadronirsi di qualsiasi account con password, compresi gli account admin (GHSA-43v4-43pw-4rp2). Ora il modulo non crea alcun token. I link di reimpostazione vengono solo da POST /admin/create_reset_token e dal comando potato reset-password. Segnalato, con una patch, da HDEF.

• Telefoni (2.9.4). Sugli schermi touch i controlli sono alti almeno 44 px, l'intestazione occupa due righe invece di tre, multirate diventa un elenco di righe con etichetta e l'evidenziazione degli span funziona con la pressione prolungata.
• Annotatori automatici (2.9.4). Un blocco machine_annotators dichiara valutatori che sono programmi, come rilevatori o LLM. /admin/iaa riporta quindi l'accordo umano-umano, macchina-macchina e aggregato, con le cifre principali calcolate solo sugli umani, e le esportazioni csv, tsv e parquet acquisiscono una colonna annotator_origin quando un record proviene da una macchina.
• Cookie di sessione dietro un prefisso URL (2.9.4). Due studi serviti sotto /app1 e /app2 sullo stesso host condividevano un unico cookie di sessione, quindi accedere a uno ti disconnetteva dall'altro. Ora il cookie è limitato al prefisso. Corretto da @Eyecatch3r nella PR #172.
• Navigazione più veloce (2.9.2). Script e fogli di stile restano in cache tra un elemento e l'altro, e Next richiede meno round trip. Su un collegamento con round trip di 80 ms, Next su un task a pulsanti radio è passato da circa 2,6 s a circa 0,8 s.
• Modifiche al testo subito prima di Next (2.9.2). Svuotare una casella di testo e premere Next entro un secondo manteneva il testo precedente. Ora ogni salvataggio applica prima le modifiche in sospeso.

Potato 2.9.0

Rilasciato a settembre 2026

Potato importa progetti da brat, doccano, Prodigy, CoNLL e REFI-QDA, e trascrive e diarizza l'audio in locale. Le esportazioni registrano se una forma su un'immagine è stata disegnata da una persona, proposta da un modello o importata, e in quale stanza è stato espresso un voto. La maggior parte della release è costituita da correzioni di bug.

Esegui potato validate --strict su ogni configurazione prima di aggiornare. Diverse modifiche possono far sì che uno studio funzionante con la 2.8.2 si rifiuti di avviarsi o si comporti in modo diverso: i nomi di schema duplicati in una stessa fase vengono rifiutati, min_annotators_per_instance è diventato un alias del limite per elemento, require_fully_annotated: true viene applicato, una fase che non riesce a caricarsi interrompe l'avvio, e gli offset degli span sono espressi in code point anziché in unità UTF-16. I valori di accordo per gli schemi con valori a insieme, a ordinamento, a matrice e ordinali con etichette cambiano e vanno ricalcolati. Le note di rilascio riportano l'elenco completo.

pip install --upgrade potato-annotation

Importazione ed esportazione

• Importatori per brat, doccano, Prodigy, CoNLL-2003/CoNLL-U e REFI-QDA .qdpx, e un esportatore .qdpx. Vedi Importare un progetto.
• Provenienza nelle esportazioni. Ogni forma su un'immagine registra se l'ha disegnata una persona o l'ha proposta un modello (source, ai_model, confidence, edited, carried_over, import_format). I voti espressi in una stanza multiplayer riportano la stanza, il ruolo, il voto iniziale, se è cambiato dopo la rivelazione e il numero di votanti.
• Le esportazioni di span in csv, jsonl e parquet includono il testo coperto.
• python -m potato.export --format adjudication è nuovo, e ogni tipo di schema ha ora un controllo di aggiudicazione per "adottare una risposta" (prima lo avevano solo radio e likert).

Audio, video e trascrizioni

• Trascrizione e diarizzazione dei parlanti in locale con faster-whisper e sherpa-onnx, senza PyTorch e senza token Hugging Face: installa potato-annotation[transcribe], poi esegui potato transcripts <dir> --transcribe --diarize --num-speakers N -o out.json. Vedi Formati di trascrizione.
• segment_schemes visualizza qualsiasi tipo di annotazione all'interno di un segmento audio o video. In precedenza veniva accettato e ignorato.

Accordo, qualità e AI

• Accordo nel tempo, messo in relazione con le revisioni del codebook, con un trigger di ricalibrazione su /admin/iaa.
• Una modalità di revisione dell'output del modello che include la porzione di predizioni vuote, così si può calcolare il recall.
• ai_budget.cap_usd rifiuta di avviare un'esecuzione che non può permettersi, e ai_budget.prices imposta nella configurazione le tariffe per modello.
• ai_support registra final_annotation e pre_annotation_seeds, così i tassi di accettazione si possono misurare sui propri dati.

Deployment e interfaccia

• Supporto per reverse proxy e prefisso di percorso su ogni pagina (#168, Aldo Costa). Vedi Reverse proxy.
• card_sort funziona senza mouse, e gli spostamenti vengono annunciati agli screen reader.
• resizable, max_height e min_height funzionano su ogni tipo di visualizzazione.

Correzioni che incidono sui risultati

• /admin/api/agreement non produceva mai un numero, e confrontava i valori memorizzati anziché i nomi delle etichette, quindi ogni schema categoriale mostrava un accordo perfetto.
• Il secondo annotatore in uno studio con due annotatori per elemento veniva mandato alla pagina di fine, e ogni risposta che dava in seguito andava persa.
• I suggerimenti AI riguardavano l'elemento sbagliato con tutte le strategie di assegnazione tranne fixed_order.
• Con la configurazione predefinita in memoria le registrazioni non venivano mai salvate, quindi dopo un riavvio chiunque poteva appropriarsi di un nome utente esistente.

Grazie ad Aldo Costa (@Eyecatch3r) per #168 e #171, e a @ruthenian8 per aver segnalato e diagnosticato #170.

Potato 2.8.2

Rilasciato ad agosto 2026

La 2.8.1 non conteneva due delle cinque correzioni di sicurezza descritte nelle sue note di rilascio: la correzione SSRF sugli endpoint dei media (GHSA-9394-85jj-2mhj) e il rafforzamento della modalità debug (GHSA-r4ww-vc5h-35qf). La 2.8.2 le include entrambe. Se hai aggiornato alla 2.8.1 per uno di questi due problemi, aggiorna di nuovo. Vedi le note di rilascio della 2.8.2.

Potato 2.8.1

Rilasciato ad agosto 2026

Una release di sicurezza. Ha corretto un'esecuzione di codice remoto tramite il live coding agent (GHSA-cm4p-5rfv-x252), una configurazione di amministrazione leggibile senza la chiave admin e un webhook di acquisizione delle tracce che accettava qualsiasi richiesta. Aggiorna se esegui Potato in un ambiente diverso da localhost, e passa direttamente alla 2.8.2, che contiene le due correzioni mancanti nella 2.8.1.

Potato 2.8.0

Rilasciato ad agosto 2026

Potato era una piattaforma di annotazione del testo con una modalità per le immagini. Ora copre immagini, video, scansioni gigapixel, nuvole di punti 3D, mappe di profondità, episodi robotici, rollout di video generativi e grounding visione-linguaggio. Per ciascuno di questi riporta l'accordo corretto per il caso.

Aggiorna se hai installato da PyPI. Le wheel fino alla 2.7.1 dichiaravano i dati del pacchetto con un glob a un solo livello, quindi 27 template nelle sottodirectory mancavano da ogni wheel. Le route di configurazione della modalità Solo, le pagine di amministrazione, la calibrazione dei giudici e la mappa del corpus erano tutte rotte per chiunque avesse eseguito pip install; chi lavorava da un checkout git non se n'è mai accorto. Corretto nella PR #164 da @0x6362.

pip install --upgrade potato-annotation

Accordo su geometria e tempo

• Accordo corretto per il caso per le etichette spaziali, scomposto in rilevamento (se gli annotatori hanno trovato gli stessi oggetti), classificazione (se li hanno chiamati allo stesso modo) e localizzazione (se li hanno collocati nello stesso punto, riportata come σ rispetto a una baseline empirica del caso più un test KS).
• STAPLE per il consenso sulle maschere. Stima un contorno latente e una sensibilità e una specificità per ciascun valutatore. Su un corpus in cui due annotatori accurati sono in minoranza, tre a due, rispetto ad annotatori rumorosi, il voto di maggioranza ottiene un Dice di 0,846 rispetto alla verità e STAPLE ottiene 1,000.
• IoU 3D ruotata esatta, così l'accordo sui cuboidi è corretto per dati da drone, da dispositivi portatili e da ambienti interni, e non solo per box orizzontali.
• Accordo temporale riportato come sweep su più tolleranze di corrispondenza, perché un accordo a 0,25 s è un'affermazione diversa da un accordo a 2 s.
• I valori indefiniti si spiegano da soli. α è davvero indefinito su un corpus unanime, e un NaN senza spiegazione si legge come un calcolo rotto.

Questo corregge anche un bug. L'aggiudicazione confrontava le chiavi di un'annotazione, e gli schemi per immagini memorizzano tutto sotto un'unica chiave chiamata _data. Ogni coppia di immagini otteneva quindi un accordo di 1,0, così due annotatori che non concordavano su nulla sembravano unanimi e nessuna immagine veniva mai inviata alla revisione.

Visione

• Primitive geometriche: polilinee, ellissi, cuboidi 2D, insiemi di keypoint con topologia a scheletro e flag di visibilità COCO, e maschere a pennello indicizzate per istanza.
• Segmentazione con un clic nel browser, con MobileSAM su ONNX Runtime Web, circa 132 ms per clic, senza GPU e senza una chiamata di rete per ogni clic.
• Prompt testuali a vocabolario aperto. Si digita una frase e ogni corrispondenza viene racchiusa in un box. Grounding DINO, Apache-2.0, anch'esso nel browser.
• Propagazione delle maschere video con i moduli di memoria di SAM 2, misurata a 0,974–0,979 di IoU per fotogramma, senza degrado lungo la sequenza. Questa funzione gira lato server per scelta progettuale; il browser ha un percorso di carry-forward separato e più leggero.
• Deep zoom per immagini gigapixel, servite sia come DZI sia come IIIF Image API 3.0, con maschere a pennello alla piena risoluzione della sorgente.
• Acquisizione dei media: TIFF multipagina a 16 bit, HEIC, RAW di fotocamera e ProRes/MKV/MOV tramite un proxy lato server con cache.
• 15 formati di importazione e 29 di esportazione, 11 dei quali supportano l'andata e ritorno. Darwin funziona in entrambe le direzioni.

Le scorciatoie da tastiera per l'annotazione di immagini ora seguono per impostazione predefinita le convenzioni di V7: b pennello, r rettangolo, f riempimento, k keypoint, v selezione. Imposta keybinding_profile: legacy sullo schema per ripristinare le vecchie associazioni in uno studio già in corso.

3D, profondità e robotica

• spatial_annotation per nuvole di punti PCD, PLY, LAS, KITTI .bin e .xyz, con cuboidi 3D, punti, polilinee e segmenti per punto, level-of-detail a octree e pannelli a fetta ortografici. La rotazione è memorizzata come quaternione, quindi l'inclinazione di montaggio che un campo con il solo yaw scarterebbe senza avvisare sopravvive a un round-trip KITTI.
• Mappe di profondità in PNG/TIFF a 16 bit, NPY, PFM ed EXR, con windowing, mappe di colore, lettura in metri sotto il cursore e retroproiezione nello stesso visualizzatore 3D.
• Proiezione basata sulla calibrazione, così un cuboide disegnato in 3D compare in ogni immagine della fotocamera e può essere verificato in 2D.
• episode_annotation mette N flussi video sincronizzati e M corsie di serie temporali del robot su un'unica timeline, con segmentazione in fasi, esiti per fase e curve di reward dense. Importa LeRobot v2, RLDS/TFDS e HDF5. Il sottocampionamento delle corsie preserva minimi e massimi, quindi un picco di forza di un solo fotogramma sopravvive al passaggio in una corsia di 300 pixel.

Valutazione

• rollout_evaluation mostra da 2 a N video generati sincronizzati sullo stesso orologio e chiede all'annotatore di segnare il fotogramma in cui il mondo smette di avere senso, poi di indicare quale proprietà fisica o causale si è rotta. I pannelli possono essere presentati alla cieca e mescolati in modo stabile per ciascun annotatore.
• grounding_eval e region_caption valutano il grounding con la IoU a quattro soglie e il pointing con il tasso di punti che cadono nella regione, perché un punto non ha area e la IoU calcolata su un punto è sempre zero. La mancanza di grounding viene conteggiata a parte.

Tutto il resto

• Conversazioni a thread. La visualizzazione dialogue rende la struttura delle risposte a partire dal reply_to di ogni turno. potato convokit importa qualsiasi corpus ConvoKit e --format convokit lo riesporta, senza alcuna dipendenza da convokit.
• Telemetria del disegno (tempo per forma, dinamica dei tratti, numero di revisioni e latenza di accettazione dei suggerimenti AI). Le pre-etichette accettate in blocco fanno salire l'accordo senza che salga l'accuratezza, perché gli annotatori che accettano lo stesso suggerimento sono unanimi per costruzione. Il tempo è un segnale di processo che distingue la revisione dall'approvazione automatica, dove le etichette non ci riescono.
• Acquisizione live da database. Le righe create dopo l'avvio diventano annotabili entro poll_interval_seconds senza riavvio (#166).
• Specifiche leggibili dalle macchine. Uno JSON Schema che copre 159 chiavi di configurazione, 61 tipi di annotazione e 24 tipi di visualizzazione, più un documento OpenAPI con 419 percorsi. Entrambi sono generati dal codice e la CI fallisce quando uno dei due diverge, così un editor o un agente di programmazione può verificare una configurazione senza inventare opzioni.
• Nessuna richiesta in uscita. Ogni foglio di stile, script, font e icona viene ora servito dall'installazione in tutti i 14 template. styles.css si apriva con un @import di Google Fonts, che al caricamento della pagina inviava a terzi l'indirizzo IP di ogni annotatore, e la pagina di login conteneva una favicon di terzi. Entrambi sono stati rimossi.
• La scheda Instances dell'amministrazione è passata da un costo quadratico a uno lineare. Con 2000 elementi il tempo è sceso da 15,1 s a 23 ms.

Potato 2.7.2

Rilasciato ad agosto 2026

Registrazione dei tasti per i campi di testo libero. Potato registra la tempistica dietro una risposta e mai i caratteri, e questo si rivela sufficiente per distinguere la digitazione dall'incolla.

• Registrazione dei tasti. Cattura cieca rispetto al contenuto di pause, raffiche, revisioni e incollaggi su ogni campo di testo libero, con circa quaranta caratteristiche di sintesi calcolate per risposta. Disattivata per impostazione predefinita.
• Rilevamento del processo di scrittura. Sei regole con nome e soglie esplicite, che riportano i valori delle caratteristiche dietro ogni segnalazione. Le soglie possono essere ricalibrate sul tuo progetto, ed esiste un percorso supervisionato se disponi di etichette.
• Linee guida etiche. Testo di consenso di esempio, conservazione e cancellazione, il problema del tasso di base e perché una segnalazione è un invito a guardare e non un risultato.
• Esportazioni opt-in. export_include_typing_dynamics scrive un file sidecar di sintesi e --format keystrokes scrive i flussi grezzi in Parquet. Nessuna delle due è attiva per impostazione predefinita, quindi i dati comportamentali non finiscono mai per errore in una pubblicazione di dataset.

La comunicazione agli annotatori è attiva per impostazione predefinita, e disattivarla registra un avviso all'avvio.

Potato 2.7.1

Rilasciato a luglio 2026

Importazione di trascrizioni, partendo dal presupposto che la trascrizione esista già. Qualcuno ha eseguito Whisper, o ha scaricato i sottotitoli, o ha ricevuto un corpus, e il passo successivo non dovrebbe essere scrivere uno script di conversione.

• 21 formati di trascrizione e sottotitoli, rispetto ai 6 precedenti. Whisper, WhisperX, whisper.cpp, AWS Transcribe, Deepgram, AssemblyAI, Rev.ai, SPoRC, SubRip, WebVTT, SubStation Alpha, TTML/DFXP, YouTube json3 e srv1/srv2/srv3, NIST CTM, Praat TextGrid ed ELAN EAF. Il rilevamento avviene in base al contenuto del file, non all'estensione.
• File di trascrizione sidecar. Un file di dati può puntare a media/int_001.srt su disco invece di incorporare la trascrizione. I percorsi vengono risolti sotto task_dir attraverso il consueto controllo di sicurezza dei percorsi, quindi le trascrizioni restano file su cui puoi fare diff e che puoi riesportare.
• potato transcripts. Un convertitore che trasforma una cartella di output ASR in un file di dati pronto per l'annotazione, accoppiando trascrizioni e file multimediali per nome base. --dry-run riporta ciò che ha rilevato prima di scrivere qualsiasi cosa, e --emit-config stampa una configurazione corrispondente.
• Un unico vocabolario di formati per quattro schemi. speech_transcript, voice_interaction e tiered_annotation ora accettano tutto ciò che accetta la visualizzazione audio_dialogue. In precedenza lo faceva solo la visualizzazione.
• Annotare le trascrizioni Whisper e Annotare i sottotitoli di YouTube ripercorrono entrambi i punti di partenza dall'inizio alla fine.

Nella 2.7.1 i passaggi di ASR e di diarizzazione avvengono a monte e Potato ne legge l'output. Potato 2.9 ha aggiunto la trascrizione e la diarizzazione locali tramite potato transcripts --transcribe --diarize, e la modalità Think-Aloud trascrive in locale il parlato degli annotatori stessi dalla 2.7.0.

Potato 2.7.0

Rilasciato a luglio 2026

Potato 2.7 nasce da un'idea sola. Uno strumento di annotazione dovrebbe misurare come si formano i giudizi, non limitarsi a registrare quali sono stati. Vale per entrambi i tipi di giudice, le persone che annotano e i modelli AI sotto valutazione.

Misurare come etichettano le persone

Sette funzionalità opzionali, nessuna delle quali richiede un LLM.

• Motore psicometrico. Un livello di item response theory in tempo reale che assegna a ogni etichetta una probabilità a posteriori e un intervallo di sensibilità (p = 0.94 [0.88–0.97]) invece di un semplice voto di maggioranza. Stima l'abilità dell'annotatore e la difficoltà dell'elemento dai soli pattern di accordo, instrada gli elementi verso l'annotatore il cui giudizio porta più informazione e segnala i probabili difetti del codebook.
• Stanze multiplayer. La riunione di calibrazione che il tuo gruppo già svolge in condivisione schermo, integrata nello strumento e strumentata: voto cieco, rivelazione da parte dell'host, discussione, nuovo voto, con un indicatore live dell'α di Krippendorff che mostra quanto è valsa la sessione.
• Boundary Lab. Sonde controfattuali dopo ogni etichetta ("varrebbe ancora?"), che trasformano l'annotazione ordinaria in contrast set e individuano gli annotatori incoerenti senza inserire elementi gold.
• Truth Serum. Punteggio peer-prediction di tipo "sorprendentemente popolare", che batte il voto di maggioranza dove l'annotazione è difficile, senza etichette gold.
• Modalità Think-Aloud. Gli annotatori parlano mentre lavorano; il riconoscimento vocale gira interamente in locale e la trascrizione letterale diventa la motivazione.
• Modalità Paper. Un comando trasforma un progetto in un report LaTeX compilabile sul dataset, statistiche di accordo e citazioni incluse.
• Modalità Pocket. Annotazione mobile di prima classe con una pila di schede scorrevoli, sincronizzazione offline e installazione come PWA.

Valutare gli agenti AI

La suite di valutazione degli agenti si è estesa alla struttura dei gruppi e agli agenti multimodali: un grafo di interazione tra agenti cliccabile, attribuzione dei fallimenti tra agenti, revisione dei passaggi di consegna, scorecard per singolo agente e per gruppo, timeline della contesa sugli strumenti e tagging dei comportamenti emergenti, oltre a traiettorie GUI/computer-use, timeline vocali full-duplex, grounding temporale nei video e struttura delle tabelle nei documenti.

In tutto il resto

Annotazione di eventi tra documenti, annotazione a livello di turno, un codebook come documento vivo con editor a pagina intera, collegamenti PDF tra pagine con OCR opzionale, ruoli RBAC con schemi per coorte, dashboard di amministrazione e di annotazione in 10 lingue e un'installazione molto più leggera. Gli SDK AI ora si caricano in modo lazy, e il tempo di avvio scende da circa 2,0s a 0,7s.

Potato 2.6.0

Rilasciato a giugno 2026

Potato 2.6 entra nell'analisi qualitativa dei dati e approfondisce il kit di valutazione degli agenti. Aggiunge la modalità QDA, un flusso di calibrazione e allineamento per LLM-as-judge con una coda di triage basata sui segnali, e schemi di modifica delle traiettorie che producono dati di addestramento SFT e DPO. Potato passa inoltre alla licenza GPL-3.0-or-later (da PolyForm Shield).

Modalità QDA

Un qda_mode opzionale trasforma Potato in uno spazio di lavoro collaborativo per la codifica qualitativa. Attivarlo compone un codebook vivo, la codifica in vivo, i memo dell'analista, i casi e la ricerca full-text, con impostazioni predefinite pensate per un singolo analista che codifica un intero corpus.

qda_mode:
  enabled: true            # codebook + memos + cases + search
codebook_invivo_key: i     # mint a code from a text selection
search:
  enabled: true
  annotator_claim: true

Scopri di più sulla modalità QDA →

Calibrazione e allineamento LLM-as-Judge

Etichetta automaticamente i dati con uno o più giudici LLM, poi esegui un passaggio di calibrazione umana in cieco per misurare accuratezza, accordo ed errore di calibrazione. Un flusso di allineamento separato, con un solo giudice, traccia il kappa di Cohen rispetto alle tue etichette gold umane mentre affini la rubrica, con un verdetto inline opzionale durante l'annotazione.

Scopri di più sulla calibrazione dei giudici → · Allineamento dei giudici →

Coda di triage basata sui segnali

Ordina la coda di annotazione secondo un segnale di qualità per elemento (un errore dell'agente, un pollice verso in produzione, un punteggio basso o qualsiasi campo personalizzato), così i revisori vedono per primi gli elementi più sospetti invece che in ordine di arrivo.

triage:
  enabled: true
  signal_field: quality_score
  invert_signal: true
assignment_strategy: priority

Scopri di più sulla coda di triage →

Modifica delle traiettorie per SFT/DPO

I nuovi schemi trajectory_edit e trajectory_correction permettono agli annotatori di riscrivere i passi di una traccia di agente. L'esportatore trasforma ogni coppia originale/corretta in target di fine-tuning supervisionato (trajectory_sft.jsonl) e in coppie di preferenza DPO (trajectory_dpo.jsonl).

Scopri di più sulla modifica delle traiettorie →

Visualizzazione eval_trace

Una visualizzazione della traccia dell'agente a tre riquadri (Ragionamento, Chiamate di funzione e Risposta finale), pensata per la valutazione continua, in cui le tracce arrivano tramite un webhook, un poller Langfuse o una directory monitorata e vengono giudicate man mano che arrivano.

Scopri di più su eval_trace →

Flusso di lavoro e assegnazione

• Copertura eterogenea. Limiti di annotatori per elemento, report sull'accordo inter-annotatore e instradamento all'aggiudicazione per compiti in cui gli elementi richiedono numeri diversi di annotatori.
• Recupero delle assegnazioni abbandonate. Recupera le assegnazioni lasciate da lavoratori Prolific o bloccati dal QC, con conservazione configurabile e recupero idempotente.
• Strategia di assegnazione Custom Batch. Assegna lotti predefiniti di elementi a specifici annotatori.
• Prefissi URL per reverse proxy. Servi Potato sotto un sotto-percorso dietro un reverse proxy.

Licenza

Potato è ora distribuito con licenza GPL-3.0-or-later, rilicenziato da PolyForm Shield. Puoi usarlo, modificarlo e ridistribuirlo, anche a fini commerciali, purché le opere derivate restino sotto GPL. Vedi la pagina About per i dettagli.

Prestazioni e stabilità

• Avvio circa 3× più veloce. Lo stack ML non viene più caricato in anticipo all'avvio: il tempo di import è sceso da circa 6,5s a 2s, l'avvio con 50k elementi da circa 10s a 5,7s e la memoria residente da circa 750MB a 365MB.
• Rinomina dello schema. annotation_type: highlight è ora span, con una migrazione predisposta. Aggiorna le vecchie configurazioni rinominando il tipo; le configurazioni span esistenti non sono interessate.
• Un'ampia ondata di consolidamento QA ha toccato la registrazione delle route, le fasi di addestramento, Prolific, la persistenza, l'esportazione e la gestione dei sondaggi, i webhook, la modalità Solo e l'active learning.

Potato 2.5.0

Rilasciato nel 2026

Un'ondata dedicata alla codifica qualitativa, che rende Potato credibile per i flussi di ricerca qualitativa accanto alle sue funzioni di annotazione per NLP e ML.

• Accordo inter-annotatore. Kappa di Cohen (a coppie) e kappa di Fleiss (N valutatori) oltre all'alfa di Krippendorff, esposti tramite l'API di accordo per l'amministrazione. Vedi la guida all'accordo inter-annotatore.
• Nuovi esportatori. codebook (CSV per schema con gerarchia dei codici, colore, descrizione e conteggio d'uso) e quotation_report (CSV per span con testo, offset, documento di origine e codificatore).
• Analisi dei codici. Endpoint di amministrazione per la co-occorrenza a coppie dei codici e una tabella incrociata codici per attributo sui metadati di istanza esistenti.

Potato 2.4.5

Rilasciato nel 2026

Una release dedicata a stabilità e strumenti.

• Raffinamento validato. Un framework estendibile per migliorare iterativamente le linee guida di annotazione in modalità Solo, con protezioni contro le contraddizioni nelle linee guida e la fuga di metadati.
• Validatore di configurazione. Una nuova CLI python -m potato.validate_cli che verifica le chiavi di configurazione rispetto allo schema delle chiavi note.
• Sicurezza. Correzione di un bypass del path traversal tramite prefisso di una directory sorella nella validazione dei percorsi (GHSA-q9m2-fhv9-3jcf).
• Correzioni alla sincronizzazione dello stato di salvataggio e navigazione, all'integrazione con Prolific, alla navigazione multi-fase e al feedback del controllo qualità.

Potato 2.3.0

Rilasciato il 9 marzo 2026

Potato 2.3 è la release più grande nella storia di Potato e 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 formati di traccia, 3 tipi di visualizzazione specializzati e 9 schemi di annotazione predefiniti.

12 convertitori di formati di traccia. Importano tracce di agenti da OpenAI, Anthropic, SWE-bench, OpenTelemetry, MCP, CrewAI/AutoGen/LangGraph, LangChain, LangFuse, ReAct, WebArena/VisualWebArena, ATIF e registrazioni grezze del browser. È disponibile il rilevamento automatico.

La conversione avviene come passaggio CLI prima dell'avvio del server:

python -m potato.trace_converter \
  --input traces.json \
  --input-format react \
  --output data/traces.jsonl

Il file convertito diventa poi un normale file di dati, reso da uno dei tipi di visualizzazione per agenti:

data_files:
  - "data/traces.jsonl"
 
instance_display:
  fields:
    - key: steps
      type: agent_trace
      label: "Agent trajectory"

3 tipi di visualizzazione:

• Agent Trace Display. Schede dei passi con codice colore, osservazioni comprimibili, formattazione leggibile del JSON e una barra laterale con la timeline, per agenti che usano strumenti
• Web Agent Trace Display. Screenshot completi con overlay SVG che mostrano i punti di clic, gli input di testo e le azioni di scorrimento, e navigazione a pellicola, per agenti di navigazione web
• Interactive Chat Display. Modalità chat dal vivo (l'annotatore interagisce con l'agente tramite un proxy) e modalità di revisione delle tracce, per agenti conversazionali

Valutazioni per turno. Valuta i singoli passi insieme alla traccia 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 di proxy per agenti. Proxy OpenAI, HTTP ed echo per la valutazione di agenti dal vivo.

Scopri di più sull'annotazione agentiva →

Modalità Solo

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

La modalità Solo funziona come una macchina a stati di fasi anziché come una sequenza fissa. Attraversa configurazione, revisione del prompt, un ciclo facoltativo sui casi limite, annotazione in parallelo, risoluzione dei disaccordi, annotazione attiva con revisione periodica e revisione delle regole, etichettatura autonoma e validazione finale. Cinque di queste fasi possono tornare alla revisione del prompt quando il problema si rivela essere il prompt, e la validazione finale torna all'annotazione attiva quando il campione non supera la soglia.

solo_mode:
  enabled: true
  labeling_models:
    - endpoint_type: openai
      model: "gpt-4o"
      api_key: ${OPENAI_API_KEY}
  thresholds:
    end_human_annotation_agreement: 0.92
    minimum_validation_sample: 50
  state_dir: "solo_state"

Prioritizzazione multi-segnale delle istanze. instance_selection pondera sette segnali (bassa confidenza, diversità, predizione dell'LLM, disaccordo, casuale, cartografia, regola dei casi limite) per scegliere che cosa vedrà l'umano dopo.

Scopri di più sulla modalità Solo →

Best-Worst Scaling

Annotazione comparativa efficiente in cui gli annotatori selezionano l'elemento migliore e il peggiore da tuple. Generazione automatica delle tuple con disegni a blocchi incompleti bilanciati e tre metodi di punteggio (Counting, Bradley-Terry, Plackett-Luce).

annotation_schemes:
  - annotation_type: bws
    name: fluency
    description: "Which sentence reads most fluently?"
    tuple_size: 4
    best_description: "Most Fluent"
    worst_description: "Least Fluent"

Scopri di più sul Best-Worst Scaling →

Autenticazione SSO e 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 la registrazione automatica, la modalità mista e la gestione delle sessioni.

authentication:
  method: "oauth"
  providers:
    google:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}
      allowed_domain: "umich.edu"
  user_identity_field: "email"
  auto_register: true
 
secret_key: ${POTATO_SECRET_KEY}

Scopri di più su SSO e OAuth →

Esportazione Parquet

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

export_annotation_format:
  - parquet

Scopri di più sull'esportazione Parquet →

15 nuovi progetti demo

Nuove 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 attiva 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 tracce personalizzati per framework di agenti non supportati
• Modalità Solo ibrida con campionamento di verifica multi-annotatore
• Scheda BWS nella dashboard di amministrazione 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 release con importanti nuove funzionalità: 9 nuovi schemi di annotazione, un sistema di esportazione modulare, la stima della competenza con 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 argomentali tipizzati. Annota eventi come ATTACK, HIRE e TRAVEL con argomenti di entità vincolati e una visualizzazione ad archi hub-spoke.

annotation_schemes:
  - annotation_type: event_annotation
    name: events
    description: "Mark the event triggers and their arguments"
    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 base di conoscenza.

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 un'annotazione ad alta produttività.

Scopri di più sul Triage →

Confronto a coppie. Confronta due elementi in modalità binaria (clic sul riquadro preferito) o su scala (slider). Supporta items_key, allow_tie e un 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 in catene le menzioni testuali coreferenti, 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 e documenti. Disegna riquadri sulle pagine PDF per attività di annotazione di documenti.

Span discontinui. allow_discontinuous: true consente di selezionare segmenti di testo non contigui come un unico span.

Annotazione intelligente

Stima della competenza con MACE. Algoritmo EM variazionale bayesiano 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 discrete. Evidenzia le prime k opzioni con un indicatore a stella e attenua 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, così gli annotatori vedono 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

Una nuova 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 i 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, Forme brevi, Dati demografici). Si usano nelle fasi pre-studio e post-studio con instrument: "tipi".

Scopri di più sugli strumenti di indagine →

Altri miglioramenti

• Tracciamento di oggetti nei 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. Mostra qualsiasi combinazione di immagini, video, audio, testo e dialoghi accanto 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
    description: "What category best describes this image?"
    labels: [nature, urban, people]

Supporta 24 tipi di visualizzazione, tra cui text, html, image, video, audio, depth_map, dialogue, conversation_tree, pairwise, code, spreadsheet, document, pdf, gallery e cinque visualizzazioni di tracce di agenti.

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 più campi di testo nella stessa istanza.

annotation_schemes:
  - annotation_type: span
    name: source_entities
    description: "Label the entities in the source document"
    labels: [PERSON, ORGANIZATION]
 
  - annotation_type: span
    name: summary_entities
    description: "Label the entities in the 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 orientati e non orientati, relazioni N-arie, visualizzazione ad archi e vincoli sulle etichette.

annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Highlight the named entities in the text"
    labels:
      - name: "PERSON"
        color: "#3b82f6"
      - name: "ORGANIZATION"
        color: "#22c55e"
 
  - annotation_type: span_link
    name: relations
    description: "Link the entities that stand in a relation"
    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 e veloce
• Ollama Vision. Modelli visione-linguaggio locali (LLaVA, Qwen-VL)
• OpenAI Vision. Visione in cloud con GPT-4o
• Anthropic Vision. Claude con visione

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

Scopri di più sul supporto AI visivo →

Personalizzazione del layout

Crea layout visivi personalizzati e articolati 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 per le sezioni.

task_layout: layouts/custom_task_layout.html

Sono inclusi tre layout di esempio: moderazione dei contenuti, QA di dialoghi e revisione medica.

Scopri di più sulla personalizzazione del layout →

Motivazioni delle etichette

Una quarta funzionalità AI che genera spiegazioni bilanciate sul perché ciascuna 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 release principale che aggiunge assistenza AI, active learning, fasi di addestramento, flussi di lavoro multi-fase e un backend MySQL.

Supporto AI

Integra modelli linguistici di grandi dimensioni per assistere gli annotatori con suggerimenti intelligenti, evidenziazione delle 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 dei segmenti
• Domande di annotazione per segmento
• Oltre 15 scorciatoie da tastiera
• Caching della forma d'onda lato server

annotation_schemes:
  - annotation_type: audio_annotation
    name: speakers
    description: "Mark each speaker turn in the audio"
    mode: label
    labels:
      - Speaker A
      - Speaker B

Scopri di più sull'annotazione audio →

Active learning

Assegna automaticamente la 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à:

• Diverse opzioni di classificatore (LogisticRegression, RandomForest, SVC, MultinomialNB)
• Vari vettorizzatori (TF-IDF, Count, Hashing)
• Persistenza del modello tra i riavvii
• Selezione potenziata da LLM
• Supporto per più schemi

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

Scopri di più sull'active learning →

Fase di addestramento

Qualifica gli annotatori con domande di pratica prima dell'attività principale. Fornisci un 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 ripetere il tentativo
• Monitoraggio dei progressi nella dashboard di amministrazione

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 di amministrazione 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: consultazione dei dati con punteggi di disaccordo
• Configurazione: regolazione delle impostazioni in tempo reale

admin_api_key: ${ADMIN_API_KEY}

Scopri di più sulla dashboard di amministrazione →

Backend database

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

database:
  type: mysql
  host: localhost
  database: potato_db
  username: ${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'audit 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 del compito
4. Addestramento - Domande di pratica
5. Annotazione - Attività principale
6. Post-studio - Questionari 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 della configurazione

Potato 2.0 usa 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/"
export_annotation_format: "jsonl"

Requisito di sicurezza

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

Con la configurazione accanto ai dati, la directory del task è quella corrente:

task_dir: "."

Con la configurazione in una sottodirectory, indica la directory del progetto a cui appartiene:

task_dir: "my_project/"

Confronto rapido

Guida alla migrazione

Aggiornare la configurazione (da v1 a v2)

1. Configurazione dei dati

   yamlCopia

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

2. Configurazione dell'output

   yamlCopia

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

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

Avviare il server

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

Per iniziare

Vuoi provare Potato? Inizia dalla Guida rapida o esplora funzionalità specifiche:

Funzionalità della v2.3:

• Annotazione agentiva - Valuta agenti AI con convertitori di tracce e visualizzazioni a livello di passo
• Modalità Solo - Etichettatura collaborativa umano-LLM
• Best-Worst Scaling - Annotazione comparativa con punteggio
• SSO e OAuth - Autenticazione Google, GitHub e OIDC
• Esportazione Parquet - Esportazione colonnare dei dati

Funzionalità della 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 tra 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 di dati remote - Caricamento dei dati dal cloud
• Strumenti di indagine - 55 questionari validati

Funzionalità della v2.1:

• Visualizzazione delle istanze - Visualizzazione di contenuti multimodali
• Supporto AI visivo - AI per l'annotazione di immagini e video
• Collegamento di span - Annotazione di relazioni tra entità

Funzionalità di base:

• Supporto AI - Assistenza intelligente all'annotazione
• Active learning - Prioritizzazione intelligente delle istanze
• Annotazione audio - Annotazione basata sulla forma d'onda
• Fase di addestramento - Qualifica degli annotatori
• Dashboard di amministrazione - Monitoraggio e gestione