Desenvolvimento Orientado a Avaliação para Aplicações Python com LLM

Você está construindo um pipeline de avaliação automatizada que testa uma aplicação de IA baseada em Python de ponta a ponta — executando-a da mesma forma que um usuário real faria, com entradas reais — depois pontuando as saídas usando avaliadores e produzindo resultados de aprovação/reprovação via pixie test.

O que você está testando é a própria aplicação — seu tratamento de requisições, montagem de contexto (como coleta dados, constrói prompts, gerencia o estado da conversa), roteamento e formatação de respostas. A aplicação usa um LLM, o que torna as saídas não determinísticas — é por isso que você usa avaliadores (LLM-como-juiz, pontuações de similaridade) em vez de assertEqual — mas o item sob teste é o código da aplicação, não o LLM.

Durante a avaliação, o próprio código da aplicação é executado de verdade — roteamento, montagem de prompt, chamadas de LLM, formatação de resposta — nada é simulado (mocked) ou substituído (stubbed). Mas os dados que a aplicação lê de fontes externas (bancos de dados, caches, APIs de terceiros, fluxos de voz) são substituídos por valores especificados nos testes através de instrumentações. Isso significa que cada caso de teste controla exatamente quais dados a aplicação vê, enquanto ainda exercita o caminho completo do código da aplicação.

Regra: As chamadas de LLM da aplicação devem ir para um LLM real. Não substitua, simule, use stubs ou intercepte o LLM com uma implementação falsa. O LLM é o componente central gerador de valor — substituí-lo torna a avaliação tautológica (você controla tanto as entradas quanto as saídas, então as pontuações são sem sentido). Se a suíte de testes do projeto contiver padrões de simulação de LLM, esses são para os testes unitários do próprio projeto — NÃO os adote para o Runnable de avaliação.

O entregável é um pixie test funcional executado com pontuações reais — não um plano, não apenas instrumentação, não apenas um conjunto de dados.

Esta habilidade é sobre fazer o trabalho, não descrevê-lo. Leia código, edite arquivos, execute comandos, produza um pipeline funcional.

Antes de começar

Primeiro, ative o ambiente virtual. Identifique o ambiente virtual correto para o projeto e ative-o. Após o ambiente virtual estar ativo, execute o setup.sh incluído nos recursos da habilidade. O script atualiza a habilidade eval-driven-dev e o pacote Python pixie-qa para a versão mais recente, inicializa o diretório de trabalho do pixie se ele ainda não estiver inicializado e inicia um servidor web em segundo plano para mostrar as atualizações do usuário.

Configure o tratamento de erros — o que você pode pular vs. o que deve ter sucesso:

• Falha na atualização da habilidade → OK para continuar. A versão existente da habilidade é suficiente.
• Falha no upgrade do pixie-qa, mas já estava instalado → OK para continuar com a versão existente.
• O pixie-qa NÃO está instalado e a instalação falha → PARE. Peça ajuda ao usuário. O fluxo de trabalho não pode prosseguir sem o pacote pixie.
• pixie init falha → PARE. Peça ajuda ao usuário.
• pixie start (servidor web) falha → PARE. Peça ajuda ao usuário. Verifique server.log no diretório raiz do pixie para diagnósticos. Causas comuns: conflito de porta, dependência ausente, ambiente lento. NÃO prossiga sem o servidor web — o usuário precisa dele para ver os resultados da avaliação.

O fluxo de trabalho

Siga os Passos 1–6 diretamente, sem parar. Não peça confirmação ao usuário em etapas intermediárias — verifique cada etapa você mesmo e continue.

Como trabalhar — leia isto antes de fazer qualquer outra coisa:

• Um passo de cada vez. Leia apenas as instruções do passo atual. NÃO leia os Passos 2–6 enquanto trabalha no Passo 1.
• Leia as referências apenas quando um passo instruir você a fazê-lo. Cada passo nomeia um arquivo de referência específico. Leia-o quando chegar a esse passo — não antes.
• Crie artefatos imediatamente. Após ler o código de um sub-passo, escreva o arquivo de saída para esse sub-passo antes de seguir em frente. Não acumule entendimento entre vários sub-passos antes de escrever qualquer coisa.
• Verifique, depois siga em frente. Cada passo tem um ponto de verificação. Verifique-o, depois prossiga para o próximo passo. Não planeje os passos futuros enquanto verifica o atual.

Quando parar e pedir ajuda:

Alguns bloqueios não podem e não devem ser contornados. Ao encontrar qualquer um dos seguintes, pare imediatamente e peça ajuda ao usuário — não tente contornar:

• A aplicação não roda devido a variáveis de ambiente ou configuração ausentes: A aplicação requer variáveis de ambiente ou configuração que não estão definidas e não podem ser inferidas. NÃO contorne isso simulando, falsificando ou substituindo componentes da aplicação — a avaliação deve exercitar o código de produção real. Peça ao usuário para corrigir a configuração do ambiente.

…