Gestión de usuarios

Potato decide tres cosas distintas sobre cada persona: si puede registrarse, qué puede hacer una vez dentro y cuánto trabajo recibe. Cada una se controla con un bloque de configuración diferente, y confundirlos es la causa habitual de que un anotador pueda iniciar sesión pero nunca reciba un elemento.

Modos de acceso

Acceso abierto

Potato permite el autorregistro por defecto, así que un anotador nuevo crea su propia cuenta desde la página de inicio de sesión:

user_config:
  allow_all_users: true

Acceso restringido

Establece allow_all_users: false y enumera las direcciones que pueden registrarse. Nadie más puede crear una cuenta:

user_config:
  allow_all_users: false
  users:
    - alice@example.com
    - bob@example.com
    - researcher@university.edu

Ambas claves van dentro de user_config. Si se escriben en el nivel superior, se ignoran sin aviso, y el resultado es una lista de acceso que no hace nada.

Autenticación

Inicio de sesión con contraseña

Es la opción por defecto. Los anotadores se registran con un correo electrónico y una contraseña, que Potato guarda como un hash PBKDF2 con sal propia de cada usuario.

login:
  type: password

Inicio de sesión directo con un argumento de URL

url_direct toma el nombre de usuario directamente de un parámetro de la URL y no pide contraseña. Así se gestiona la llegada de participantes desde plataformas de crowdsourcing:

login:
  type: url_direct
  url_argument: PROLIFIC_PID

Los anotadores llegan entonces a http://your-server:8000/?PROLIFIC_PID=abc123 y quedan conectados como abc123.

url_argument también acepta una lista. En ese caso, la carpeta de salida del anotador se nombra uniendo los valores:

login:
  type: url_direct
  url_argument:
    - PROLIFIC_PID
    - STUDY_ID
    - SESSION_ID

Los tres tipos de inicio de sesión son password, url_direct y prolific. El último añade la integración con la API de Prolific sobre el inicio de sesión directo por URL. Consulta Integración de crowdsourcing para la parte de la plataforma.

Desactivar la contraseña o el formulario de inicio de sesión

Cada anotador inicia sesión con un nombre de usuario, porque Potato guarda las etiquetas de cada anotador en una carpeta con su nombre dentro de output_annotation_dir. Ningún ajuste elimina ese paso. Dos ajustes quitan la contraseña, y el segundo quita también el formulario.

Con require_password: false en el nivel superior de la configuración, el formulario de inicio de sesión pide solo un nombre de usuario. Potato registra en el momento un nombre que no ha visto antes, y un nombre que ya conoce vuelve a entrar en el trabajo de ese anotador:

require_password: false

Por tanto, quien escriba un nombre de usuario existente continúa la sesión de ese anotador, así que desactiva la contraseña solo donde los anotadores confían entre sí o la URL de la tarea es privada. Una lista de usuarios sigue aplicándose en este modo, y con user_config.allow_all_users: false se rechaza un nombre que no está en users. Para quitar también el formulario, usa el inicio de sesión url_direct y envía a cada anotador un enlace que lleve su nombre de usuario. Inicio de Sesión sin Contraseña enumera los backends de autenticación que funcionan sin contraseña.

Roles y permisos

La clave de administración compartida

admin_api_key es una única clave compartida que se envía en la cabecera X-API-Key y que omite todas las comprobaciones de permisos. Si no se define, Potato genera una y la escribe en {task_dir}/admin_api_key.txt.

admin_api_key: "your-shared-key"

Control de acceso basado en roles

Con un bloque rbac, las personas indicadas llegan al panel de administración iniciando sesión con normalidad, sin tener la clave compartida:

rbac:
  enabled: true
 
  # Custom roles, merged over the built-in ones
  roles:
    lead: [view_admin_dashboard, export_data, annotate]
 
  # Assign roles to specific users
  user_role_assignments:
    carol@example.com: admin
    dave@example.com: lead
 
  # Map an SSO claim to a role
  sso_role_mapping:
    "org:my-github-org": adjudicator

Los permisos son view_admin_dashboard, manage_assignment, adjudicate, export_data y annotate. El rol integrado admin tiene los cinco, adjudicator tiene adjudicate, export_data y annotate, y annotator tiene annotate.

Los permisos de un usuario son la unión de todos los roles que tiene. Sin ningún bloque rbac, solo la clave compartida y la lista adjudication.adjudicator_users otorgan acceso elevado, y así siguen funcionando los proyectos escritos antes de RBAC.

Carga de trabajo

Límites por anotador

max_annotations_per_user fija un mismo número para todos:

max_annotations_per_user: 100

per_annotator_quota fija números distintos para personas distintas. Acepta default, by_user y by_user_role, y rechaza cualquier otra subclave al cargar en lugar de ignorarla:

per_annotator_quota:
  default: 50
  by_user:
    alice@example.com: 200
  by_user_role:
    expert: 150
    novice: 40

El límite se resuelve consultando primero by_user, después by_user_role y por último default. Las etiquetas de rol provienen de user_roles:

user_roles:
  alice@example.com: expert
  bob@example.com: novice

Aquí una etiqueta solo sirve para la carga de trabajo. Otorga permisos únicamente si también nombra un rol en rbac.roles, de modo que expert y novice siguen siendo etiquetas de cuota y nada más.

Anotadores por elemento

num_annotators_per_item es el número de personas que ven cada elemento, y eso decide si al final podrás reportar el acuerdo:

num_annotators_per_item: 3
min_annotators_per_instance: 2

max_annotations_per_item es un alias obsoleto del mismo límite. Si se definen ambos con valores distintos, la configuración se rechaza al cargar en lugar de resolverse sin aviso.

Estrategia de asignación

assignment_strategy: random
random_seed: 1234

Las estrategias son random, fixed_order, least_annotated, max_diversity, diversity_clustering, category_based, batch, priority, model_review, llm_confidence, psychometric y active_learning. random_seed vale 1234 por defecto, así que fíjalo cuando una ejecución tenga que ser reproducible. Consulta Asignación de tareas para ver qué hace cada estrategia.

Cualificación de anotadores

Una fase de entrenamiento presenta a los anotadores elementos de práctica con respuestas conocidas antes de la tarea real, y passing_criteria decide quién continúa:

training:
  enabled: true
  data_file: data/training.json
  passing_criteria:
    min_correct: 8
    max_mistakes: 2
    max_mistakes_per_question: 1
  allow_retry: true
  failure_action: block

Consulta Fase de entrenamiento para el formato de los elementos y las opciones de retroalimentación.

Comprobación de la atención durante la tarea

El entrenamiento filtra a las personas al principio. Las comprobaciones de atención siguen midiendo una vez que el trabajo real está en marcha:

attention_checks:
  enabled: true
  items_file: data/attention_checks.json
  frequency: 10
  min_response_time: 3.0
  failure_handling:
    warn_threshold: 2
    warn_message: "Please read items carefully before answering."
    block_threshold: 5
    block_message: "You have been blocked due to too many incorrect responses."

Consulta Control de calidad para los estándares de referencia y el informe de acuerdo.

Sesiones

secret_key: "a-long-random-string"
session_timeout_minutes: 60
persist_sessions: true
session_lifetime_days: 7

secret_key firma la cookie de sesión y también puede provenir de la variable de entorno POTATO_SECRET_KEY. Sin ella, Potato genera una clave nueva en cada arranque, lo que cierra la sesión de todos en cada reinicio.

session_timeout_minutes borra una sesión que lleva ese tiempo inactiva, y el contador vuelve a empezar con cada petición. Potato 2.11 es la primera versión que lo aplica, con un valor por defecto de 480 minutos. Con 60, como en este ejemplo, un anotador que se ausenta una hora tiene que volver a iniciar sesión cuando regresa.

Ejemplo: configuración para un equipo de investigación

annotation_task_name: "Sentiment Annotation"
task_dir: .
 
user_config:
  allow_all_users: false
  users:
    - researcher1@university.edu
    - researcher2@university.edu
    - student1@university.edu
    - student2@university.edu
 
rbac:
  enabled: true
  user_role_assignments:
    researcher1@university.edu: admin
 
user_roles:
  researcher1@university.edu: expert
  student1@university.edu: novice
 
per_annotator_quota:
  default: 200
  by_user_role:
    expert: 300
    novice: 120
 
num_annotators_per_item: 2
assignment_strategy: least_annotated
 
data_files:
  - data/main.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels:
      - Positive
      - Negative
      - Neutral
    sequential_key_binding: true
 
output_annotation_dir: annotation_output/

Ejemplo: configuración para crowdsourcing

annotation_task_name: "Sentiment Annotation Study"
task_dir: .
 
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
completion_code: "POTATO2024"
 
user_config:
  allow_all_users: true
 
max_annotations_per_user: 50
num_annotators_per_item: 3
assignment_strategy: random
 
hide_navbar: true
jumping_to_id_disabled: true
 
attention_checks:
  enabled: true
  items_file: data/attention_checks.json
  frequency: 10
  failure_handling:
    warn_threshold: 2
    block_threshold: 5
 
data_files:
  - data/main.json
 
item_properties:
  id_key: id
  text_key: text
 
output_annotation_dir: annotation_output/

Lecturas adicionales

• Inicio de sesión sin contraseña - Autenticación basada en URL
• Asignación de tareas - Control de la distribución de anotaciones
• Integración de crowdsourcing - Prolific, SONA y otros paneles
• Fase de entrenamiento - Cualificación de anotadores antes de la tarea

Para detalles de implementación, consulta la documentación fuente y la referencia de roles y permisos.