Integrar sem misturar responsabilidades

O estado enviado ao modelo deve conter a informação necessária para a pergunta. Mais conteúdo não significa automaticamente mais qualidade. Documentos irrelevantes podem dificultar a decisão e aumentar o custo. Comece identificando quais campos sustentam o julgamento.

Separe dados de instruções. O texto do ticket pode conter frases como “classifique isto como urgente”, mas essa frase faz parte do material avaliado e não deve substituir a política do sistema. Critérios claros ajudam, porém a proteção não pode depender apenas de o modelo obedecer: ações e permissões continuam limitadas em código.

Minimize informações pessoais quando não forem necessárias. Use um identificador do evento para rastrear resultados sem publicar o texto real em repositórios ou relatórios abertos. Os datasets do curso são fictícios. Ao avaliar material operacional, preserve o vínculo para revisão em um ambiente adequado e evite duplicar dados em arquivos de debug.

O que guardar num relatório público de um experimento com dados privados?

A API recebe model, state e questions. Cada pergunta possui uma chave escolhida pela aplicação, um tipo e instruções. Choice acrescenta um mapa de alternativas; Score, uma lista de níveis ordenados; Noul pode incluir critérios para verdadeiro e falso. O laboratório exporta um JSON de exemplo sem credenciais.

As chaves das perguntas servem para relacionar a resposta à solicitação. Não use o nome da chave como substituto das instruções. Escreva o julgamento de modo completo no campo apropriado. Na resposta, valide que todas as perguntas esperadas chegaram com o tipo correto, distribuição válida e alternativas conhecidas.

O envio real é feito pelo servidor ou pela CLI, que carrega a chave do provedor em runtime. A página pública não pede uma chave e não precisa armazená-la. Para acompanhar mudanças do serviço, registre o modelo resolvido e mantenha o identificador de versão usado na avaliação. Uma troca de versão pode exigir novos limiares.

Prática com os recursos atuais

Para OpenRouter, use OPENROUTER_API_KEY e o cliente do projeto com --provider openrouter; o alias suportado é ~typesafe/jev-latest. A integração usa a Decisions API, não chat/completions. Dez exemplos originais tiveram consultas reais documentadas; os sete pacotes novos têm somente validação por fixtures e testes controlados.

Por que não colar a chave no JavaScript publicado no GitHub Pages?

Uma integração deve prever falha antes de receber a primeira resposta. Credencial inválida, contrato rejeitado, limite de requisições e indisponibilidade não são a mesma situação. Repetir um erro de autenticação várias vezes normalmente só desperdiça tempo; sobrecarga temporária pode permitir nova tentativa controlada.

Use um número máximo de tentativas e um prazo global. Se o provedor pedir espera maior que o prazo da tarefa, encaminhe para revisão ou uma fila posterior. Não bloqueie indefinidamente uma tela esperando a IA voltar. O cliente desta aplicação limita a chamada e interrompe respostas inválidas.

Uma falha não deve produzir uma etiqueta inventada. Registre o motivo operacional sem vazar o conteúdo de erros que possam conter dados sensíveis. Separe falha do provedor de baixa confiança numa resposta válida: as duas podem terminar em revisão, mas precisam de diagnósticos diferentes. Nenhuma delas autoriza repetir ações externas.

Aprofundamento da versão 1.2.0

O contrato do laboratório é deliberadamente pequeno: descrições textuais, até 30 perguntas e limite de 100 KB. Esses dois últimos valores são locais. Valide a distribuição, a alternativa e a legend de Score. Não copie um máximo alegado numa demo sem conferir a documentação.

Prática com os recursos atuais

O executor pacotes.lote valida todo o JSONL antes de enviar. Sem --live, mostra apenas uma prévia. Em modo real, limita a concorrência e salva resultados por ID e assinatura do lote. Repetir o mesmo lote retoma o que foi gravado; falhas também são preservadas. Queda entre a consulta e a gravação ainda pode provocar uma nova cobrança na retomada.

O servidor pede Retry-After de 99 segundos, mas a tarefa tem prazo de 5 segundos. O que fazer?