compras/docs/ensaio-ia.md

Ensaio de IA preparado para o SGC

Preparado e executado em 30/10/2026: uma geração real concluída, exclusivamente com os três factos fictícios autorizados. Os relatórios da aplicação continuam a usar as sínteses factuais por regras; o ensaio não está ligado a qualquer rota web, processo, fila ou tarefa automática.

Estado actual: ensaio concluído após o proprietário configurar a chave. Foram corrigidos a confiança TLS do processo PHP e o formato duplicado da definição no .env, sem expor a chave, alterar outras definições ou desactivar a validação HTTPS. Tentativas: falha TLS, rejeição 401 por valor malformado, uma resposta 200 concluída. Não houve repetição automática. Provas: proofs/ai-rehearsal-live.json e proofs/ai-rehearsal-authorization.json.

Resultado: três afirmações com as fontes request, comparison e order, sem omissões ou aprovações inventadas na conferência do conteúdo. Consumo reportado: 204 tokens de entrada + 81 de saída = 285. Custo textual teórico pelas tarifas documentadas: US$0,001380, antes de eventuais impostos; saldo, débito de créditos Pro ou cobrança efectiva não foram consultados. Isto valida apenas o cenário fictício, não a qualidade geral do modelo ou utilização em decisões reais. O ensaio autorizado está concluído: não executar de novo por arrasto.

Resultado já disponível

Compras e Pessoas têm sínteses independentes, com fontes, identificação da base e redacção por permissões. O protótipo de IA serve para verificar se um fornecedor consegue resumir um cenário conhecido sem inventar aprovação ou usar referências inexistentes. O adaptador foi implementado segundo a documentação oficial de Structured Outputs da OpenAI.

Chamada autorizada

• Destino: https://api.openai.com/v1/responses.
• Modelo inicial do ensaio: gpt-5.6-terra, que consta da documentação oficial do modelo com suporte de Responses e Structured Outputs. É uma escolha para o ensaio, não uma avaliação comparativa ou recomendação definitiva para o produto.
• Uma chamada manual, sem repetição automática ou redireccionamento HTTP.
• Entrada: instruções fixas, schema e os três factos fictícios abaixo. Corpo JSON limitado a 4 500 bytes.
• Saída: no máximo 1 000 tokens, até três afirmações curtas com referências; raciocínio configurado como none.
• Sem ferramentas, pesquisa web, anexos, conversas anteriores, dados reais, acesso à base ou mudanças de decisões.
• store: false na requisição. Este parâmetro não constitui uma garantia geral de ausência de retenção pelo fornecedor.
• Credencial dedicada configurada no servidor por SGC_AI_REHEARSAL_API_KEY; nunca inserir a chave na conversa, nos testes ou no repositório. Activação técnica por SGC_AI_REHEARSAL_ENABLED=true, apenas depois de autorização para a chamada paga.

Factos exactos enviados:

1. request: A requisição fictícia está em aprovação; não foi aprovada.
2. comparison: Existe uma proposta fictícia registada; a comparação ainda não está pronta.
3. order: Não consta ordem de compra no cenário fictício.

Rever e executar

php artisan sgc:ai-rehearsal mostra a pré-visualização sem rede. Foi executado localmente; prova privada em storage/logs/ai-rehearsal-preview.log.

Depois da autorização e configuração da credencial no servidor, php artisan sgc:ai-rehearsal --live executa apenas o cenário incorporado. Não aceita IDs de processos, ficheiros ou texto livre. A utilização é facturada pelo fornecedor; não há compromisso de gratuidade. O limite de tokens é um limite técnico desta chamada, não um orçamento global de toda a aplicação.

O servidor valida formato e pertença das fontes após receber o JSON. Respostas recusadas, incompletas, malformadas ou com referências desconhecidas são rejeitadas. Uma referência conhecida não prova que a frase seja verdadeira: o resultado continua marcado requires_human_review=true e factual_accuracy=not_automatically_verified.

A revisão do resultado deve conferir cobertura dos três factos, inexistência de aprovações inventadas, exactidão e correspondência de cada afirmação à fonte. O ensaio pode falhar mesmo com JSON válido; nesse caso, não activar a função para documentos reais. O comando não imprime erros brutos do fornecedor nem a credencial.

Validação e limites

php artisan sgc:ai-assess tests/Fixtures/ai-synthetic-result.json confere uma fixture manual, sem rede/chave e sem ser uma saída de modelo. O resultado real concluído está em storage/app/private/ai-rehearsal-live-result.json, em JSON UTF-8, e pode ser conferido pelo mesmo comando sem nova chamada. Apenas aceita resultados synthetic_only: true e fontes do cenário incorporado. Mede fontes por citar, cobertura e correspondências literais; uma frase com citação válida não é automaticamente verdadeira. A geração concluída incluiu estas métricas e teve o conteúdo conferido contra os três factos.

15 testes locais/41 asserções com HTTP simulado, sem chamadas reais, e análise PHPStan aprovados. Os testes verificam pré-visualização sem consultas de base/rede, desactivação/ausência de credencial, requisição limitada, referências, recusa/truncagem/JSON inválido, falhas 429/500 e não divulgação da chave em erros. Fonte de prova: proofs/ai-rehearsal.json.

A activação de IA sobre documentos reais ainda exige configuração pela organização, permissões, política de dados/destino, consumo, auditoria e avaliação de qualidade. Este protótipo não implementa esse editor nem autoriza essa activação. Machine learning preditivo permanece uma evolução separada, dependente de histórico e validação próprios.