CLI, REST API, ferramentas MCP e SDK do motor de rotulagem

O servidor de anotação, a linha de comando, a REST API, as ferramentas MCP e o Python SDK controlam o mesmo motor de rotulagem sobre o mesmo arquivo engine.sqlite no diretório da tarefa. Você pode iniciar um estudo pela linha de comando, servir as solicitações a pessoas com o servidor e certificar a partir de um notebook.

Só um processo controla um estudo por vez. O planejador de um servidor em execução detém o lock de escrita do estudo e, enquanto o detém, potato label run, potato label certify e Study.run() recusam e informam isso. Nesse caso, certifique pelo servidor, com POST /api/engine/v1/certify ou pela página de administração. O lock existe porque dois controladores sorteariam duas amostras de calibração e certificariam com os rótulos um do outro. O lock é liberado quando quem o detém termina. Um detentor encerrado à força na mesma máquina é substituído na hora, e um em outra máquina após dois minutos sem heartbeat. Os comandos somente leitura (status, certificate, calls, export) funcionam a qualquer momento.

Linha de comando

Todo comando do motor recebe o arquivo de configuração do estudo:

potato label <command> <config.yaml> [options]

Os nove comandos cobrem um estudo da primeira chamada a modelo até o conjunto de dados exportado:

Acompanhar o progresso não gasta nada, porque status, certificate e a página de administração leem resultados armazenados. Cada novo teste, seja de certify com novos rótulos ou de certify --retest, gasta parte do orçamento de erro de um contrato.

Arquivos gravados pela exportação

potato label export grava quatro tipos de arquivo no diretório de saída:

Os exportadores comuns (python -m potato.export e a exportação do painel) exportam as anotações das pessoas, e a página de formatos de exportação os lista. Entre eles, o formato labeling_engine grava os mesmos arquivos que potato label export e se recusa a rodar quando o motor não está habilitado. Com o motor ligado, as exportações CSV, Parquet e Hugging Face ganham duas colunas que dizem a qual solicitação do motor cada anotação respondeu. engine_purpose contém a finalidade, por exemplo calibration, e engine_request contém um JSON com a finalidade, a probabilidade de inclusão, a visibilidade, a divisão e o id da solicitação. Use essas colunas para separar a amostra aleatória cega das respostas de verificação.

REST API

Todas as rotas do motor ficam em /api/engine/v1 e devolvem JSON. Autentique-se com a chave de administrador no cabeçalho X-API-Key ou com uma sessão de administrador. As leituras exigem a permissão do painel de administração, certify e plan exigem gerenciamento de atribuições, e o certificado exige permissão de exportação.

As rotas respondem 404 quando o motor está desligado para o estudo. Respondem 400 com um erro em JSON para um parâmetro inválido, como um limit que não é número, um purpose ou status desconhecido, ou um format diferente de json, md ou html.

Por exemplo, esta requisição busca o certificado atual em Markdown de um servidor na porta 8000:

curl -H "X-API-Key: $ADMIN_API_KEY" \
  "http://localhost:8000/api/engine/v1/certificate?format=md"

Ferramentas MCP

O servidor MCP expõe cinco ferramentas do motor, com as mesmas permissões das rotas REST:

• engine_status
• engine_requests
• engine_run, que executa uma passagem do planejador
• engine_certify, que aceita retest
• engine_certificate, em json, md ou html

Conceder essas ferramentas com o motor desligado gera um aviso de validação. Via potato mcp connect, uma chamada recusada (uma permissão ausente, um parâmetro inválido) volta como um erro de ferramenta que traz a mensagem do servidor. A documentação do servidor MCP explica como conceder ferramentas e conectar um cliente.

Python SDK

A classe Study controla o motor a partir do Python, por exemplo em um notebook:

from potato.labeling_engine.sdk import Study
 
study = Study("examples/labeling-engine/text-certified-sentiment/config.yaml")
study.run()                                   # label, sample, certify, resolve
for req in study.requests(status="open")[:5]:
    study.label(req.item_id, req.schema, "positive", user="me")
study.certify()
print(study.certificate(fmt="md"))
study.export("out/")

Cada método espelha um comando ou uma rota:

O exemplo rotula todas as solicitações abertas como "positive" só para mostrar as chamadas. Um rótulo registrado por Study.label que não responde a nenhuma solicitação é guardado como rótulo orgânico, e rótulos orgânicos nunca certificam, então um script que rotula itens que o motor não solicitou acrescenta rótulos que nenhum contrato lê.

Leitura adicional

• O motor de rotulagem
• Configuração do motor de rotulagem
• Contratos do motor de rotulagem
• Painel do administrador, que tem um link para a página de administração do motor

Para detalhes de implementação, consulte a documentação de origem.