# pataniscAI 3.0.0

Motor VLM local, sem treino de pesos, para substituir a extracao visual do Tesseract no fluxo de
admissao do Sabichao. O modelo transcreve; a classificacao, os parsers, os checksums e o merge
continuam no Sabichao.

Estado: `3.0.0-dev`, apenas para DEV. Producao permanece intocada.

## Arranque local

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install-windows.ps1
```

Depois de preencher `C:\pataniscAI\.env`:

```powershell
C:\pataniscAI\.venv\Scripts\pataniscai-api.exe
```

Por defeito a API escuta em `0.0.0.0:8000`, usa o Ollama local em `127.0.0.1:11434` e aceita
apenas os IPs declarados em `PATANISCAI_ALLOWED_IPS`.
O pedido de inferencia usa `keep_alive=-1`, pelo que o modelo escolhido permanece carregado ate o
servico Ollama ser parado ou o modelo ser explicitamente descarregado.

## Contrato

- `GET /health`: nao recebe dados pessoais; confirma API, Ollama, modelo e versao.
- `POST /v1/extract`: `multipart/form-data`, com `manifest` JSON e ficheiros cujas chaves constam
  do manifesto. Exige `X-PataniscAI-Token`.

A API nao persiste imagens nem inclui texto reconhecido nos logs. O endpoint devolve transcricoes
por pagina; o cliente PHP transforma-as no contrato canonico `results[campo] = {valor, fonte}`.

## Limites de seguranca

- Nenhuma imagem ou resposta entra em Git.
- Nenhum valor pessoal e escrito nos logs da API.
- A API nao deve ser publicada na Internet.
- O Ollama nao deve ficar acessivel fora dos clientes internos necessarios.
- O modelo fica congelado; este projecto nao contem treino, LoRA ou alteracao de pesos.

Ver [DEPLOY.md](DEPLOY.md) e [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md).

O benchmark cruzado corre autonomamente no CT DEV através de
`/var/www/develop/scripts/pataniscai_benchmark_ct.sh --background`. A conta de referência de PROD
tem `SELECT` por coluna apenas nas duas tabelas do corpus; o JSON pessoal segue por pipe para o
benchmark e não é gravado. O runner valida os grants, impede execuções simultâneas e não aceita
holdout. Ver `DEPLOY-UPDATE-2026-08-25-HARNESS-CT.md`.

O caminho antigo pelo Mac (`scripts/run-benchmark-from-prod.sh development`) permanece apenas como
rollback. Nesse fluxo o holdout exige `PATANISCAI_UNLOCK_HOLDOUT=YES` e continua reservado para o
gate final.