# OpenAI para Devs com documentos e evidências

Um exercício completo de aplicação Python: recuperar documentos sintéticos, pedir uma resposta estruturada e conferir os trechos citados. O objetivo é aprender a separar busca, geração, validação e avaliação.

**Status da entrega:** código e testes offline executados. A integração real com a API OpenAI não foi executada nesta preparação, pois não foram disponibilizadas credenciais. A demonstração é uma resposta fixa criada para o exercício, identificada como `demo_fixture`. Nenhuma qualidade de modelo foi medida.

## Executar sem conta nem chave

Python 3.10 ou posterior. Não há pacotes externos a instalar.

```bash
python -m unittest discover -s tests -v
python app.py --demo
python avaliar.py
```

O primeiro comando testa o comportamento local e uma integração simulada. O segundo valida uma resposta fixa. O terceiro verifica o recuperador lexical nos 10 casos do conjunto. Os resultados realmente obtidos estão em `VALIDACAO.json` e `resultados/`.

## Como funciona

1. A aplicação lê apenas os três documentos do manifesto local.
2. No modo online, a primeira chamada à Responses API solicita exatamente uma execução de `buscar_documentos`.
3. A função local valida os argumentos e busca palavras nos documentos autorizados. Ela não executa shell, não acessa caminhos arbitrários e não consulta a internet.
4. A segunda chamada recebe os documentos recuperados e pede JSON conforme `ANSWER_SCHEMA`. Novas chamadas de ferramenta são desabilitadas nessa etapa.
5. O programa rejeita IDs fora da recuperação, trechos inventados, ausência de evidência em uma resposta factual, recusas e respostas incompletas.
6. O resultado aprovado mecanicamente ainda pede revisão humana: uma citação literal pode não sustentar a conclusão.

O fluxo tem no máximo duas requisições à API por pergunta bem-sucedida. Não há repetição automática em caso de falha. Uma requisição que falha na validação local ainda pode ter gerado cobrança do provedor.

## Executar com sua conta da API

Configure `OPENAI_API_KEY` e `OPENAI_MODEL` nas variáveis de ambiente locais. Use um modelo disponível em sua conta que suporte Responses API, function calling e Structured Outputs. O kit não presume modelo, preço ou acesso específico.

A chave é lida somente no modo `--online`. Não cole a chave nos documentos, prompts, código, repositório ou página do site. O modo online envia a pergunta e os documentos sintéticos recuperados para a OpenAI.

```bash
python app.py --online --pergunta "Qual é o prazo para solicitar reembolso?" --salvar resultados/minha-execucao.json
```

Para avaliar três casos com o modelo configurado:

```bash
python avaliar.py --online --limite 3 --salvar resultados/minha-avaliacao.json
```

Essa execução pode fazer até seis requisições. Amplie para os demais casos depois de conferir configuração e uso. Compare o `expected_fact` com as afirmações e as citações. Registre a decisão do revisor. Não publique uma taxa de acerto sem distinguir formato, recuperação, abstenção e apoio semântico.

## Estimar custo sem preço inventado

`estimar_custo.py` usa os tokens de uma execução online bem-sucedida e os preços que você fornecer, por um milhão de tokens. Não vem com uma tabela de preços fixa.

Substitua os marcadores por valores aplicáveis ao seu modelo e contrato:

```text
python estimar_custo.py --uso resultados/minha-execucao.json --entrada PRECO_ENTRADA --entrada-cache PRECO_CACHE --saida PRECO_SAIDA --moeda MOEDA
```

A entrada sem cache é a entrada total menos a parcela em cache. Saída inclui a quantidade informada pela API. A estimativa não inclui impostos, câmbio, serviços externos ou outras tarifas. Se não houver uso, como no modo demo, o programa recusa a estimativa. Os valores numéricos usados nos testes são fictícios e servem apenas para conferir a aritmética.

## Arquivos principais

| Arquivo | Função |
|---|---|
| app.py | Ferramenta, chamada REST, schema e validação local |
| documentos/ | Três políticas fictícias e manifesto de acesso |
| avaliacao/casos.json | Dez perguntas, expectativas e casos sem suporte |
| avaliacao/demo-resposta.json | Resposta fixa para demonstração offline |
| avaliar.py | Avaliação de recuperação e execução online opcional |
| estimar_custo.py | Cálculo com preços informados pelo operador |
| tests/test_app.py | Testes locais de comportamento e contrato de integração |
| RUBRICA.md | Critérios para revisão humana das respostas |
| FONTES.md | Documentação oficial consultada |

## Limites deliberados

O recuperador usa sobreposição de palavras. Ele não faz busca semântica, não entende sinônimos e pode recuperar um documento sem suporte suficiente. Um caso adversarial no conjunto pode recuperar a política por uma palavra genérica; isso não significa que a resposta do modelo será correta ou incorreta. O programa exige abstenção sem evidência e a avaliação online deve conferir esse comportamento.

O validador confere formato e existência literal do trecho. Não verifica automaticamente se a frase citada implica a afirmação, se o resumo omitiu ressalvas, ou se a própria política está correta. Há um teste que demonstra essa limitação. É obrigatório revisar o significado antes de usar uma resposta em uma decisão.

O kit não oferece autenticação multiusuário, autorização por documento para diferentes pessoas, banco vetorial, processamento de PDF, trilha de produção, proteção completa contra injeção de prompt ou política de retenção organizacional. `store: false` é uma configuração da requisição, não uma promessa geral de retenção zero pelo provedor.

Preparado em 21/10/2026. Todos os documentos de negócio são fictícios. Este material não é um caso de cliente nem uma medição de desempenho da OpenAI.
