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](https://developers.openai.com/api/docs/guides/structured-outputs).

## 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](https://developers.openai.com/api/docs/models/gpt-5.6-terra) 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.