Skip to content
Ankündigungen8 Min. Lesezeit

Potato 2.3: Agentische Annotation, Solo Mode und Best-Worst Scaling

Potato 2.3.0 bringt Solo Mode für gemeinsames Labeling durch Mensch und LLM, Annotation von Agenten-Traces, Best-Worst Scaling, SSO- und OAuth-Logins, Parquet-Export und 15 Demo-Projekte.

Potato Team

Hinweis: Dieser Beitrag beschreibt Potato 2.3 im Zustand zum Release im März 2026. Mehrere der unten gezeigten Konfigurationsschlüssel wurden in späteren Versionen umbenannt oder ersetzt, und die aktuelle Syntax steht in der Dokumentation. Kopieren Sie diese Blöcke nicht in ein Projekt, das eine aktuelle Potato-Version verwendet.

Potato 2.3.0 bringt Solo Mode, einen Labeling-Workflow aus Mensch und LLM, der zehn dokumentierte Phasen durchläuft. Dazu kommen die Annotation von Agenten-Traces mit elf registrierten Trace-Konvertern, Best-Worst Scaling mit drei Scoring-Methoden, SSO- und OAuth-Logins für Google, GitHub und generische OIDC-Anbieter, Parquet-Export und 15 Demo-Projekte. Die Release Notes verzeichnen 50 oder mehr Commits seit 2.2.0 und Korrekturen für 12 Sicherheitslücken in 8 Modulen.

Das Release folgt einer Veränderung dessen, was annotiert wird. Forschende, die vor zwei Jahren Sentiment und Named Entities gelabelt haben, zerlegen heute mehrstufige Agenten-Traces, vergleichen Modellausgaben in großer Zahl und bauen Datensätze für Aufgaben, die es noch nicht gab, als Potatos Schema-Set entworfen wurde. Solo Mode und die Arbeit an Agenten-Traces zielen beide auf diese Verschiebung.

Upgrade

bash
pip install --upgrade potato-annotation==2.3.0

Der Parquet-Export braucht PyArrow 12.0.0 oder neuer, das separat installiert wird:

bash
pip install "pyarrow>=12.0.0"

Annotation von Agenten-Traces

Ein Agentenlauf ist eine Folge von Tool-Aufrufen, Denkschritten und Zwischenausgaben, und wer ihn zu reinem Text zusammenfasst, verliert die Struktur, die ein Evaluator sehen muss. Potato 2.3 rendert Traces stattdessen über das Display-System, sodass der Trace als Konversation dargestellt wird, bei der Bewertungen an einzelne Turns gebunden sind.

Das Display wird in instance_display deklariert, mit den Bewertungsschemata pro Turn unter dem Feld, das die Konversation enthält:

yaml
instance_display:
  layout:
    direction: vertical
    gap: 16px
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: conversation
      type: dialogue
      label: "Agent Trace"
      span_target: true
      display_options:
        show_turn_numbers: true
        alternating_shading: true

In 2.3 tragen zwei Display-Typen die Arbeit mit Agenten. Das Display dialogue stellt einen Trace als Turns dar und unterstützt Span-Annotation darüber, und interactive_chat deckt Konversationen ab, an denen die annotierende Person selbst teilnimmt, statt sie nachzulesen. Erst span_target: true erlaubt es Annotatoren, eine Passage innerhalb eines Turns hervorzuheben, und so werden Halluzinationen und unbelegte Behauptungen genau an der Stelle markiert, an der sie auftreten.

Traces aus anderen Frameworks kommen über den Konverter herein, der in diesem Release elf Formate registriert: openai, anthropic, swebench, otel, mcp, multi_agent, langchain, langfuse, react, webarena und atif.

bash
python -m potato.trace_converter -i traces.json -f react -o data/traces.jsonl

Solo Mode

Labeling mit mehreren Annotatoren verlangt, Leute einzustellen, zu schulen und zu koordinieren, und in vielen Forschungsprojekten ist diese Logistik der Engpass und nicht die Annotationsoberfläche. Solo Mode stellt stattdessen einer Fachexpertin oder einem Fachexperten ein LLM zur Seite. Der Mensch labelt, das LLM schlägt vor, jede Korrektur fließt in den Prompt zurück, und der Mensch gibt einen immer größeren Teil der Warteschlange ab, je mehr sich beide annähern.

Der Workflow durchläuft zehn dokumentierte Phasen: Einrichtung, Prompt-Review, Synthese von Grenzfällen, Labeling der Grenzfälle, Prompt-Validierung, parallele Annotation, Auflösung von Meinungsverschiedenheiten, periodisches Review, autonomes Labeling und abschließende Validierung. Nicht jedes Projekt durchläuft jede Phase.

yaml
solo_mode:
  enabled: true
 
  labeling_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
      max_tokens: 256
      temperature: 0.1
 
  revision_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
 
  uncertainty:
    strategy: "direct_confidence"
 
  thresholds:
    end_human_annotation_agreement: 0.90
    minimum_validation_sample: 20
    confidence_low: 0.5
    periodic_review_interval: 50
 
  instance_selection:
    low_confidence_weight: 0.4
    diversity_weight: 0.3
    random_weight: 0.2
    disagreement_weight: 0.1
 
  state_dir: "solo_state"

Die vier Gewichte in instance_selection entscheiden, welche Items die Aufmerksamkeit eines Menschen wert sind. Mit 0.4 für niedrige Konfidenz und 0.3 für Diversität fließt der Großteil der menschlichen Zeit in Instanzen, bei denen das Modell unsicher ist, während der Rest der Verteilung ausreichend abgedeckt bleibt, um einen systematischen Fehler zu bemerken. Die 0.2 für Zufallsstichproben macht die Übereinstimmungsschätzung in end_human_annotation_agreement erst aussagekräftig, denn eine Übereinstimmungsrate, die nur auf schwierigen Instanzen berechnet wird, ist nicht die Rate, die Sie auf dem Korpus erhalten.

Solo Mode wird mit 85 Integrations- und End-to-End-Tests, einem Entwicklerleitfaden und zwei Beispielprojekten unter examples/advanced/solo-mode/ und examples/advanced/simple-solo-mode/ ausgeliefert. Beginnen Sie mit dem einfachen, das mit einem lokalen Ollama-Modell läuft und keinen API-Schlüssel braucht. So prüfen Sie zuerst, ob der Workflow zu Ihrer Aufgabe passt, und nicht, ob das Modell seine Kosten wert ist.

Best-Worst Scaling

Best-Worst Scaling zeigt Annotatoren ein Tupel von Items, meist vier, und fragt nur nach dem besten und dem schlechtesten bezüglich eines Kriteriums. Diese beiden Entscheidungen implizieren eine Reihe paarweiser Vergleiche, und über viele sich überlappende Tupel ergeben sich Scores auf einer echten Skala, aus Urteilen, die schneller zu fällen sind als eine Bewertung.

yaml
annotation_schemes:
  - annotation_type: bws
    name: sentiment_bws
    description: "Sentiment Intensity"
    best_description: "Which sentence expresses the MOST positive sentiment?"
    worst_description: "Which sentence expresses the LEAST positive sentiment?"
    tuple_size: 4
    sequential_key_binding: true

Drei Scoring-Methoden laufen über die gesammelten Tupel. counting ist die transparente Baseline mit (best_count - worst_count) / appearances, braucht keine zusätzliche Abhängigkeit und ist deterministisch. bradley_terry passt ein paarweises Vergleichsmodell an und liefert Stärkeparameter auf logarithmischer Skala. plackett_luce passt ein vollständiges Ranking-Modell an. Beide modellbasierten Methoden brauchen pip install choix.

bash
python -m potato.bws_scoring --config config.yaml --method bradley_terry

Die Scores landen in bws_scores.tsv im Ausgabeverzeichnis, mit Score, Rang, Best- und Worst-Zählungen und Vorkommen jedes Items. Das Admin-Dashboard hat einen Tab BWS Scoring, der dieselbe Berechnung per Knopfdruck ausführt und die Ergebnisse in einer Tabelle zeigt.

SSO und OAuth

Ein Deployment, das Annotatoren über das Internet erreichen, braucht echte Konten, und 2.3 ergänzt OAuth 2.0 und OpenID Connect, damit sie die Identität nutzen können, die sie bereits haben. Unterstützt werden Google, GitHub und jeder generische OIDC-Anbieter, und der Zugang lässt sich nach E-Mail-Domain oder GitHub-Organisation einschränken.

yaml
authentication:
  method: "oauth"
  providers:
    google:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}
  user_identity_field: "email"
 
secret_key: ${POTATO_SECRET_KEY}

Fügen Sie diesen Block Ihrer Konfiguration hinzu. Damit kommen zwei Anforderungen. OAuth braucht ein Deployment über HTTPS, wobei localhost für die Entwicklung ausgenommen ist, und es braucht einen stabilen secret_key, weil ein Signaturschlüssel, der sich bei jedem Neustart ändert, die Sitzungen ungültig macht, die der Login bereits ausgestellt hat. Registrieren Sie die Redirect-URI bei Ihrem Anbieter als https://your-domain.com/auth/callback/google und setzen Sie dabei den Namen des Anbieters ein.

Parquet-Export

Annotationsdaten landen zunehmend in Analysewerkzeugen, die ein spaltenorientiertes Format erwarten, deshalb nimmt 2.3 Parquet in die Export-Registry auf. Ein Export erzeugt bis zu drei Tabellen: annotations.parquet mit einer Zeile pro Instanz und Annotator, spans.parquet mit einer Zeile pro Span-Annotation und items.parquet mit den Quelldaten.

bash
python -m potato.export -c config.yaml -f parquet -o ./export/

Optionen werden auf der Kommandozeile übergeben, statt im Projekt konfiguriert zu werden, und der Kompressions-Codec ist einer von snappy (Standard), gzip, zstd, lz4 oder none:

bash
python -m potato.export -c config.yaml -f parquet -o ./export/ \
    --option compression=gzip --option include_items=false

Die Tabellen werden über den Instanzschlüssel verknüpft, auch wenn der Spaltenname zwischen ihnen abweicht: annotations.parquet und spans.parquet führen instance_id, während items.parquet item_id führt. Dadurch lässt sich der Export aus DuckDB heraus nutzen, ohne vorher etwas in pandas zu laden:

python
import duckdb
duckdb.sql("""
  SELECT i.item_id, a.user_id, a.*
  FROM './export/annotations.parquet' a
  JOIN './export/items.parquet' i ON a.instance_id = i.item_id
""")

annotations.parquet hat eine Zeile pro Instanz und Annotator, wobei jedes Annotationsschema in eine eigene Spalte abgeflacht ist, es gibt also keine generische Spalte value zum Auswählen. Ein Schema, das mehrere Antworten gleichzeitig speichert, wird in Unterspalten mit Punkt aufgeteilt, die <scheme>.<part> heißen.

Sicherheitskorrekturen

Das Release behebt 12 Sicherheitslücken in 8 Modulen, dazu Probleme bei XSS, Robustheit und Datenintegrität in 25 Dateien sowie eine kaskadierende Span-Löschung, die über Dictionary-Schlüssel statt über die Werte iterierte und Link-Einträge zurückließ. Ein Abhängigkeits-Audit brachte die Python- und JavaScript-Abhängigkeiten auf aktuelle Versionen.

Zwei der übrigen Korrekturen könnten bereits erhobene Daten verändert haben. Ein Absturz beim Boolean has_free_response (Issue #111) und eine Navigationsschleife über alle Phasen beeinflussten, ob Annotationen wie beabsichtigt gespeichert wurden, und die Behandlung von Anführungszeichen bei dynamischem Multirate beeinflusste, wie diese Werte geschrieben wurden. Wenn Sie eine Studie unter 2.2 mit Freitextoptionen oder Multirate-Schemata durchgeführt haben, prüfen Sie die Ausgabe, bevor Sie sie als endgültig behandeln.

Demo-Projekte

Das Release liefert 15 Demo-Projekte unter demo/ aus, nummeriert in der Reihenfolge, in der sie aufeinander aufbauen, von 01-sentiment-admin bis 15-agentic-chat. Sie decken Spans, eigene Moderationslayouts, Bildklassifikation, Emotionen in Audio, Video, multimodale Items, Adjudikation, Slider, Bounding Boxes, Abhängigkeitsbäume, mehrstufige ELAN-Annotation und agentischen Chat ab. Jedes Demo-Verzeichnis enthält eine config.yaml und sein data/, und die Sammlung teilt sich ein Skript, das die Medien für die medienbasierten Demos erzeugt.

bash
# From the repository root: generates the demo data, then starts all 15 servers
bash demo/launch.sh

Das vollständige Changelog mit jeder oben genannten Korrektur finden Sie in den Release Notes zu v2.3.0 im Repository. Melden Sie Probleme auf GitHub oder eröffnen Sie einen Thread in GitHub Discussions.