Skip to content
Announcements11 min read

Potato 2.3: Anotação Agêntica, Solo Mode e o Futuro da Avaliação Humana

O Potato 2.3.0 introduz anotação agêntica com 12 conversores de formato de trace, Solo Mode para rotulagem colaborativa entre humanos e LLMs, Best-Worst Scaling, SSO/OAuth, exportação para Parquet e 15 projetos de demonstração.

Potato Team

Note: This post describes Potato 2.3 as it was at release. Some configuration keys and features have been updated in later versions. See the current documentation for up-to-date configuration syntax.

O Potato 2.3.0 é nosso maior lançamento até agora. Ele traz dois novos sistemas, anotação agêntica e Solo Mode, além de Best-Worst Scaling, autenticação SSO/OAuth, exportação para Parquet e 15 novos projetos de demonstração.

A razão para a maior parte disso é que aquilo que as pessoas anotam mudou. Muitos pesquisadores já não estão apenas rotulando sentimento e entidades nomeadas. Eles estão dissecando traces de agentes de múltiplos passos, comparando saídas de LLMs em grande volume e construindo datasets para tarefas que não existiam há alguns anos. O Potato 2.3 mira exatamente esse trabalho.

Anotação agêntica

O recurso de destaque na 2.3 é um sistema completo para avaliar agentes de IA por meio de anotação humana.

Agentes, ou seja, sistemas que executam vários passos para concluir algo, estão por toda parte agora, e são genuinamente difíceis de avaliar. Uma única execução pode acumular dezenas de chamadas de ferramentas, passos de raciocínio, navegações de página e saídas intermediárias. A maioria das ferramentas de anotação achata tudo isso em texto puro, o que descarta exatamente a estrutura que um avaliador precisa ver.

O sistema de anotação agêntica do Potato tem três partes.

12 conversores de formato de trace

Os traces de agentes têm aparência diferente dependendo do framework que os produziu. O Potato os normaliza em uma única representação:

ConversorOrigem
openaiOpenAI Assistants API / function calling
anthropicAnthropic Claude tool_use / Messages API
swebenchTraces de tarefas do SWE-bench
opentelemetryExportações de spans do OpenTelemetry
mcpSessões do Model Context Protocol
multi_agentCrewAI / AutoGen / LangGraph
langchainTraces de callback do LangChain
langfuseExportações de observação do LangFuse
reactReAct Thought/Action/Observation
webarenaWebArena / VisualWebArena
atifAgent Trace Interchange Format
raw_webGravações brutas de navegador (HAR + capturas de tela)

A configuração é curta:

yaml
agentic:
  enabled: true
  trace_converter: react
  trace_file: "data/agent_traces.jsonl"

Se você estiver puxando traces de várias fontes ao mesmo tempo, deixe que ele detecte automaticamente:

yaml
agentic:
  enabled: true
  trace_converter: auto

Três tipos de exibição

Diferentes tipos de agentes exigem diferentes visualizações.

O Agent Trace Display renderiza traces de agentes que usam ferramentas como cartões de passos codificados por cor, com observações recolhíveis, JSON formatado de forma legível e uma barra lateral de linha do tempo:

yaml
agentic:
  display_type: agent_trace
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    show_step_numbers: true

O Web Agent Trace Display lida com agentes de navegação: capturas de tela completas, sobreposições SVG marcando alvos de clique e campos de entrada, e um filmstrip para se mover rapidamente:

yaml
agentic:
  display_type: web_agent
  web_agent_display:
    screenshot_max_width: 900
    overlay:
      enabled: true
      click_marker: "circle"
      click_color: "#ef4444"
    filmstrip:
      enabled: true

O Interactive Chat Display cobre dois casos: revisão de trace, em que você avalia uma conversa gravada, e chat ao vivo, em que os anotadores conversam com um agente em tempo real e depois avaliam a conversa:

yaml
agentic:
  display_type: interactive_chat
  interactive_chat_display:
    mode: trace_review
    trace_review:
      show_token_counts: true
      show_latency: true

Avaliações por turno

Com qualquer tipo de exibição, os anotadores podem avaliar passos individuais, bem como o trace como um todo:

yaml
annotation_schemes:
  - annotation_type: likert
    name: overall_quality
    min: 1
    max: 5
 
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"

Esquemas pré-construídos

Nove esquemas prontos cobrem as dimensões usuais de avaliação de agentes de imediato:

yaml
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy
  - preset: agent_safety

Os presets são agent_task_success, agent_step_correctness, agent_error_taxonomy, agent_safety, agent_efficiency, agent_instruction_following, agent_explanation_quality, agent_web_action_correctness e agent_conversation_quality.

Leia a documentação de anotação agêntica →

Solo Mode

O segundo grande recurso na 2.3 é o Solo Mode, um fluxo de trabalho de 12 fases que troca a habitual multidão de anotadores por um único especialista humano trabalhando ao lado de um LLM.

O problema

Normalmente você precisa de vários anotadores para obter rótulos confiáveis. Contratar, treinar e coordenar essa equipe é lento e caro. Em muitos projetos de pesquisa, o gargalo não é a interface de anotação, e sim a logística de gerir uma equipe.

Como o Solo Mode resolve isso

Um especialista de domínio rotula uma fatia cuidadosamente escolhida dos dados. Um LLM aprende com esses rótulos, propõe rótulos para todo o resto, e o humano só intervém de novo onde o LLM está incerto. Um fluxo de trabalho de 12 fases executa todo o ciclo.

Em nossos benchmarks internos, o Solo Mode igualou pipelines completos de múltiplos anotadores com 95% de concordância ou mais, usando apenas 10 a 15% dos rótulos humanos.

As 12 fases

  1. Anotação semente: o humano rotula 50 instâncias diversas.
  2. Calibração inicial do LLM: o LLM rotula um lote de calibração usando esses exemplos semente.
  3. Análise de confusão: encontrar os padrões em que humano e LLM discordam sistematicamente.
  4. Refinamento de diretrizes: o LLM propõe diretrizes melhores e o humano as aprova.
  5. Geração de funções de rotulagem: regras programáticas inspiradas no ALCHEmist para as instâncias fáceis.
  6. Rotulagem ativa: o humano rotula as instâncias mais informativas que restam.
  7. Loop de refinamento automatizado: rerrotular de forma iterativa à medida que as diretrizes melhoram.
  8. Exploração de divergências: o humano resolve casos em que o LLM e as funções de rotulagem se chocam.
  9. Síntese de casos extremos: o LLM inventa exemplos ambíguos para o humano rotular.
  10. Escalonamento em cascata por confiança: o humano revisa os rótulos de menor confiança do LLM.
  11. Otimização de prompt: uma busca automatizada de prompts inspirada no DSPy.
  12. Validação final: revisar uma amostra aleatória e, então, aprovar ou voltar ao ciclo.

Início rápido

yaml
solo_mode:
  enabled: true
  llm:
    endpoint_type: openai
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
  seed_count: 50
  accuracy_threshold: 0.92
  confidence_threshold: 0.85
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    labels: [Positive, Neutral, Negative]

Priorização de instâncias com múltiplos sinais

O Solo Mode extrai de seis pools ponderados para decidir quais instâncias valem o tempo de um humano:

yaml
solo_mode:
  prioritization:
    pools:
      - name: uncertain
        weight: 0.30
      - name: disagreement
        weight: 0.25
      - name: boundary
        weight: 0.20
      - name: novel
        weight: 0.10
      - name: error_pattern
        weight: 0.10
      - name: random
        weight: 0.05

Leia a documentação do Solo Mode →

Best-Worst Scaling

O Potato 2.3 adiciona o Best-Worst Scaling (BWS), às vezes chamado de Maximum Difference Scaling. Os anotadores veem uma tupla de itens, geralmente quatro, e escolhem o melhor e o pior segundo algum critério. A partir desses simples julgamentos binários, o BWS calcula escores escalares confiáveis e chega lá com muito menos anotações do que uma escala Likert exigiria para o mesmo poder estatístico.

yaml
annotation_schemes:
  - annotation_type: best_worst_scaling
    name: fluency
    description: "Select the BEST and WORST translation"
    items_key: "translations"
    tuple_size: 4
    best_label: "Most Fluent"
    worst_label: "Least Fluent"
    randomize_order: true
 
    tuple_generation:
      method: balanced_incomplete
      tuples_per_item: 5
 
    scoring:
      method: bradley_terry
      auto_compute: true
      include_confidence: true

Há três métodos de escore. A contagem é o mais simples: (best_count - worst_count) / aparições. O Bradley-Terry é um modelo de comparação par a par e o padrão recomendado. O Plackett-Luce é um modelo de ranqueamento completo para quando você quer extrair o máximo de seus dados.

Calcule o escore pela CLI:

bash
python -m potato.bws score --config config.yaml --method bradley_terry --output scores.csv

O painel de administração tem uma aba de BWS mostrando distribuições de escore, gráficos de convergência e confiabilidade por divisão pela metade.

Leia a documentação do Best-Worst Scaling →

Autenticação SSO e OAuth

Uma implantação de anotação em produção precisa de autenticação real. O Potato 2.3 oferece suporte a três métodos OAuth.

Google OAuth

yaml
authentication:
  method: google_oauth
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/google/callback"
    allowed_domains:
      - "umich.edu"
    auto_register: true

GitHub OAuth com Restrição de Organização

yaml
authentication:
  method: github_oauth
  github_oauth:
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/github/callback"
    allowed_organizations:
      - "my-research-lab"
    scopes:
      - "read:user"
      - "read:org"

OIDC Genérico

Conecte-se ao Okta, Azure AD, Auth0, Keycloak ou qualquer outra coisa que fale OIDC:

yaml
authentication:
  method: oidc
  oidc:
    discovery_url: "https://accounts.example.com/.well-known/openid-configuration"
    client_id: ${OIDC_CLIENT_ID}
    client_secret: ${OIDC_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/oidc/callback"

Todos os três oferecem suporte a restrição de domínio, registro automático e modo misto, em que vários métodos de autenticação compartilham uma única página de login.

Leia a documentação de SSO e OAuth →

Exportação para Parquet

Cada vez mais, os dados de anotação vão parar em ferramentas de ciência de dados que querem formatos colunares. O Potato 2.3 pode exportar diretamente para o Apache Parquet como três arquivos:

  • annotations.parquet, uma linha por (instância, anotador, esquema) com valores, timestamps e durações
  • spans.parquet, uma linha por span anotado com offsets, rótulos e links
  • items.parquet, metadados de instância com contagens de anotação e status
yaml
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd
  auto_export: true

Carregue diretamente no pandas, DuckDB, PyArrow, Polars ou Hugging Face Datasets:

python
import pandas as pd
annotations = pd.read_parquet("output/parquet/annotations.parquet")
 
# Or with DuckDB for SQL queries
import duckdb
duckdb.sql("""
  SELECT instance_id, value, COUNT(*) as n
  FROM 'output/parquet/annotations.parquet'
  WHERE schema_name = 'sentiment'
  GROUP BY instance_id, value
""")

Ele lida com compressão snappy, gzip, zstd, lz4 e brotli, exportação incremental particionada por data ou anotador, e codificação de dicionário para colunas de string.

Leia a documentação de exportação para Parquet →

15 novos projetos de demonstração

O Potato 2.3 vem com 15 novas demonstrações no diretório project-hub/, uma ou mais para cada novo recurso.

Para anotação agêntica:

  1. react-agent-eval, avaliação de traces de agentes ReAct com avaliações em nível de passo
  2. web-agent-eval, avaliação de traces do WebArena com sobreposições em capturas de tela
  3. chatbot-eval, avaliação de chat interativo com um proxy de agente ao vivo
  4. multi-agent-eval, avaliação de sistemas multiagente do CrewAI
  5. swebench-eval, avaliação de traces do SWE-bench para agentes de programação

Para o Solo Mode: 6. solo-sentiment, classificação de sentimento em avaliações de produtos 7. solo-ner, reconhecimento de entidades nomeadas 8. solo-toxicity, detecção de toxicidade com síntese de casos extremos

Para o Best-Worst Scaling: 9. bws-translation, ranqueamento de qualidade de tradução automática 10. bws-summarization, comparação de qualidade de resumos 11. bws-image-quality, ranqueamento de qualidade de geração de imagens

Para autenticação: 12. google-oauth-demo, um exemplo de configuração do Google OAuth 13. github-oauth-demo, GitHub OAuth com restrição de organização

Para exportação: 14. parquet-export-demo, exportação para Parquet com um script de análise em DuckDB 15. huggingface-upload, exportação para Parquet e envio ao Hugging Face Hub

Cada demonstração vem com um config.yaml completo, dados de exemplo e um README. Inicie qualquer uma delas com:

bash
cd project-hub/react-agent-eval
potato start config.yaml

Reforço de segurança

Uma série de melhorias de segurança chegou na 2.3:

  • Os tokens de sessão agora usam geração aleatória criptograficamente segura com expiração configurável
  • A proteção contra CSRF fica ativada por padrão para todo envio de formulário
  • Limitação de taxa nos endpoints de autenticação (configurável, 10 tentativas por minuto por padrão)
  • Sanitização de entrada para qualquer conteúdo fornecido pelo usuário exibido na interface de anotação
  • Uma auditoria de dependências que trouxe todas as dependências Python e JavaScript para versões seguras atuais
  • Cabeçalhos de Content Security Policy para conter XSS
yaml
security:
  csrf_protection: true
  rate_limiting:
    auth_attempts: 10            # per minute
    api_requests: 100            # per minute
  session:
    token_length: 64
    lifetime_hours: 24
  content_security_policy: true

Atualização

A partir do Potato 2.2.x

bash
pip install --upgrade potato-annotation

Suas configurações da v2.2 são totalmente retrocompatíveis, então nada precisa mudar.

Novas dependências

A exportação para Parquet precisa do PyArrow:

bash
pip install potato-annotation[parquet]

O Solo Mode requer um SDK de provedor de LLM:

bash
pip install potato-annotation[solo]    # installs openai + anthropic SDKs

Ou instale tudo:

bash
pip install potato-annotation[all]

O que vem a seguir

Algumas coisas em que já estamos trabalhando para o próximo lançamento:

  • Diff de anotações, para comparar anotações entre rodadas e anotadores com diffs visuais
  • Anotação federada, para coordenar o trabalho entre múltiplas instâncias do Potato
  • Fontes de dados em streaming, para anotar a partir de Kafka, Pub/Sub e sistemas semelhantes
  • Uma interface amigável para dispositivos móveis, para anotar em tablets e celulares

Gostaríamos genuinamente de saber o que você acha. Abra issues no GitHub, inicie um tópico no GitHub Discussions, ou simplesmente entre em contato com a equipe.

Para o changelog completo, incluindo quaisquer chaves de configuração que mudaram, consulte as notas de versão da v2.3.0 no repositório.

Links