Potato 2.3: anotación agéntica, Solo Mode y Best-Worst Scaling

Potato 2.3.0 añade Solo Mode, un flujo de etiquetado entre humano y LLM que recorre diez fases documentadas, además de anotación de trazas de agentes con once convertidores de trazas registrados, Best-Worst Scaling con tres métodos de puntuación, inicio de sesión SSO y OAuth para Google, GitHub y proveedores OIDC genéricos, exportación a Parquet y 15 proyectos de demostración. Las notas de la versión registran 50 o más commits desde la 2.2.0 y correcciones de 12 vulnerabilidades de seguridad en 8 módulos.

La versión responde a un cambio en lo que se anota. Investigadores que hace dos años etiquetaban sentimiento y entidades nombradas hoy desmenuzan trazas de agentes de varios pasos, comparan salidas de modelos en bloque y construyen conjuntos de datos para tareas que no existían cuando se diseñó el conjunto de esquemas de Potato. Tanto Solo Mode como el trabajo sobre trazas de agentes apuntan a ese cambio.

Actualización

pip install --upgrade potato-annotation==2.3.0

La exportación a Parquet necesita PyArrow 12.0.0 o posterior, que se instala por separado:

pip install "pyarrow>=12.0.0"

Anotación de trazas de agentes

Una ejecución de un agente es una secuencia de llamadas a herramientas, pasos de razonamiento y salidas intermedias, y aplanarla en texto plano elimina la estructura que un evaluador necesita ver. Potato 2.3 muestra las trazas a través del sistema de visualización, de modo que la traza se presenta como una conversación con calificaciones asociadas a turnos individuales.

La visualización se declara en instance_display, con los esquemas de calificación por turno anidados bajo el campo que contiene la conversación:

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

En la 2.3 hay dos tipos de visualización para el trabajo con agentes. La visualización dialogue muestra una traza como turnos y admite anotación de spans sobre ellos, e interactive_chat cubre las conversaciones en las que el anotador participa en lugar de leerlas después. Definir span_target: true es lo que permite a los anotadores resaltar un pasaje dentro de un turno, y así se marcan las alucinaciones y las afirmaciones sin respaldo en el lugar donde aparecen.

Las trazas de otros frameworks entran a través del convertidor, que en esta versión registra once formatos: openai, anthropic, swebench, otel, mcp, multi_agent, langchain, langfuse, react, webarena y atif.

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

Solo Mode

El etiquetado con varios anotadores exige contratar, formar y coordinar a personas, y en muchos proyectos de investigación esa logística es el cuello de botella, más que la interfaz de anotación. Solo Mode empareja en su lugar a un experto del dominio con un LLM. El humano etiqueta, el LLM propone, cada corrección vuelve al prompt, y el humano cede una parte mayor de la cola a medida que ambos convergen.

El flujo recorre diez fases documentadas: configuración, revisión del prompt, síntesis de casos límite, etiquetado de casos límite, validación del prompt, anotación en paralelo, resolución de desacuerdos, revisión periódica, etiquetado autónomo y validación final. No todos los proyectos pasan por todas las fases.

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"

Los cuatro pesos de instance_selection deciden qué elementos merecen la atención de una persona. Dar un peso de 0.4 a la baja confianza y de 0.3 a la diversidad dirige la mayor parte del tiempo del humano a las instancias sobre las que el modelo duda, y a la vez mantiene cobertura suficiente del resto de la distribución para detectar un error sistemático. El 0.2 del muestreo aleatorio es lo que da sentido a la estimación de acuerdo de end_human_annotation_agreement, porque una tasa de acuerdo calculada solo sobre instancias difíciles no es la tasa que se obtiene sobre el corpus.

Solo Mode incluye 85 pruebas de integración y de extremo a extremo, una guía para desarrolladores y dos proyectos de ejemplo en examples/advanced/solo-mode/ y examples/advanced/simple-solo-mode/. Empieza por el sencillo, que funciona con un modelo local de Ollama y no necesita clave de API, para que lo primero que evalúes sea si el flujo se ajusta a tu tarea y no si el modelo vale lo que cuesta.

Best-Worst Scaling

Best-Worst Scaling muestra al anotador una tupla de elementos, normalmente cuatro, y le pide solo el mejor y el peor según un criterio. Esas dos elecciones implican un conjunto de comparaciones por pares, y las puntuaciones sobre muchas tuplas solapadas salen en una escala real a partir de juicios más rápidos de emitir que una calificación.

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

Sobre las tuplas recogidas se ejecutan tres métodos de puntuación. counting es la línea base transparente, con (best_count - worst_count) / appearances; no necesita dependencias adicionales y es determinista. bradley_terry ajusta un modelo de comparación por pares y produce parámetros de fuerza en escala logarítmica. plackett_luce ajusta un modelo de ranking completo. Los dos métodos basados en modelos necesitan pip install choix.

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

Las puntuaciones se guardan en bws_scores.tsv en el directorio de salida, con la puntuación, el rango, los recuentos de mejor y peor y las apariciones de cada elemento. El panel de administración tiene una pestaña BWS Scoring que ejecuta el mismo cálculo desde un botón y muestra los resultados en una tabla.

SSO y OAuth

Un despliegue al que los anotadores acceden por internet necesita cuentas reales, y la 2.3 añade OAuth 2.0 y OpenID Connect para que puedan usar la identidad que ya tienen. Se admiten Google, GitHub y cualquier proveedor OIDC genérico, y el acceso puede restringirse por dominio de correo electrónico o por organización de GitHub.

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

Añade este bloque a tu configuración. Trae consigo dos requisitos. OAuth necesita un despliegue con HTTPS, con localhost exento durante el desarrollo, y necesita una secret_key estable, porque una clave de firma que cambia en cada reinicio invalida las sesiones que el inicio de sesión ya ha emitido. Registra la URI de redirección en tu proveedor como https://your-domain.com/auth/callback/google, sustituyendo el nombre del proveedor.

Exportación a Parquet

Los datos de anotación acaban cada vez más en herramientas de análisis que prefieren un formato columnar, así que la 2.3 añade Parquet al registro de exportación. Una exportación produce hasta tres tablas: annotations.parquet con una fila por instancia y anotador, spans.parquet con una fila por anotación de span, e items.parquet con los datos de origen.

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

Las opciones se pasan en la línea de comandos en lugar de configurarse en el proyecto, y el códec de compresión es uno de snappy (el predeterminado), gzip, zstd, lz4 o none:

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

Las tablas se unen por la clave de instancia, aunque el nombre de la columna cambia entre ellas: annotations.parquet y spans.parquet llevan instance_id, mientras que items.parquet lleva item_id. Eso es lo que permite usar la exportación desde DuckDB sin cargar nada antes en pandas:

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 tiene una fila por instancia y anotador, con cada esquema de anotación aplanado en su propia columna, así que no hay una columna genérica value que seleccionar. Un esquema que guarda varias respuestas a la vez se expande en subcolumnas con punto llamadas <scheme>.<part>.

Correcciones de seguridad

La versión corrige 12 vulnerabilidades de seguridad en 8 módulos, junto con problemas de XSS, robustez e integridad de datos en 25 archivos, y un borrado en cascada de spans que recorría las claves del diccionario en lugar de sus valores y dejaba registros de enlaces huérfanos. Una auditoría de dependencias llevó las dependencias de Python y JavaScript a sus versiones actuales.

Dos de las demás correcciones podrían haber cambiado datos que ya recogiste. Un fallo con el booleano has_free_response (issue #111) y un bucle de navegación en todas las fases afectaban a si las anotaciones se registraban como se pretendía, y el manejo de comillas en multirate dinámico afectaba a cómo se escribían esos valores. Si ejecutaste un estudio en la 2.2 con opciones de respuesta libre o esquemas multirate, revisa la salida antes de darla por definitiva.

Proyectos de demostración

La versión incluye 15 proyectos de demostración en demo/, numerados en el orden en que se apoyan unos en otros, de 01-sentiment-admin a 15-agentic-chat, y cubren spans, diseños de moderación personalizados, clasificación de imágenes, emoción en audio, vídeo, elementos multimodales, adjudicación, sliders, cajas delimitadoras, árboles de dependencias, anotación ELAN por niveles y chat agéntico. Cada directorio de demostración contiene un config.yaml y su data/, y el conjunto comparte un script que genera el material multimedia que necesitan las demostraciones basadas en medios.

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

Para el registro completo de cambios, con cada corrección mencionada arriba, consulta las notas de la versión v2.3.0 en el repositorio. Abre incidencias en GitHub o inicia un hilo en GitHub Discussions.

Enlaces

• Guía de instalación
• Novedades de la v2
• Anotación agéntica
• Solo Mode
• Best-Worst Scaling
• SSO y OAuth
• Exportación a Parquet
• Repositorio en GitHub
• Paquete en PyPI