# PatchInsight 0.2 — avaliação ampliada e inferência local

A v0.2 avalia os checkpoints da v0.1 em um novo conjunto exploratório, adiciona
métricas probabilísticas, calibração experimental, inferência em lote,
Action–Method e uma demo local. Não houve novo fine-tuning nem alteração dos
pesos, dados congelados ou resultados finais da v0.1. A versão do software é
0.2.0; o checkpoint continua identificado como 0.1.0.

## Resultado que muda a interpretação

| Conjunto / método | Macro-F1 | Exact match | AP macro | Brier ↓ | Log loss ↓ |
|---|---:|---:|---:|---:|---:|
| Original v0.1 — regressão | 0,9888 | 0,9333 | 1,0000 | 0,0089 | 0,0297 |
| Original v0.1 — BERT ajustado | 0,9911 | 0,9500 | 1,0000 | 0,0383 | 0,1941 |
| Novo teste — heurísticas | 0,6910 | 0,3056 | 0,7441 | 0,1833 | 2,9550 |
| Novo teste — regressão | 0,6196 | 0,3056 | 0,8401 | 0,1601 | 0,8540 |
| Novo teste — BERT ajustado | 0,5584 | 0,2500 | 0,7768 | 0,1648 | 0,5053 |
| Novo teste — regressão com temperatura | 0,6196 | 0,3056 | 0,8401 | 0,1355 | 0,4292 |
| Novo teste — BERT com temperatura | 0,5584 | 0,2500 | 0,7768 | 0,1647 | 0,5051 |

A ordenação depende da pergunta. No novo teste, heurísticas têm maior macro-F1
entre os três métodos originais; a regressão ordena melhor os positivos por AP.
Após temperatura, a regressão tem menor Brier/log loss entre as variantes
avaliadas. O resultado original próximo do teto não se sustenta neste desafio.
Os dois testes têm composições distintas; a queda não mede desempenho em
currículos reais nem permite atribuir toda a diferença a um único fator.

O ganho macro-F1 de BERT menos regressão no novo teste foi −0,0612. Bootstrap
pareado de 34 origens, 1.000 reamostragens, seed 42: IC percentil 95%
[−0,1642; 0,0372]. A amostra continua pequena e sintética; não há evidência
robusta de superioridade do BERT.

Brier e log loss avaliam previsões probabilísticas e combinam calibração e
capacidade discriminativa. Confiabilidade é examinada também em cinco bins por
rótulo, com contagens explícitas. Não há alegação de probabilidades externamente
calibradas. A AP implementada é Average Precision, não integração trapezoidal
genericamente chamada de PR-AUC. ROC-AUC e MCC complementam a comparação;
ROC-AUC/AP indefinidas ficam null. Log loss usa clipping em 1e-7 para todos os
métodos, inclusive decisões heurísticas binárias que não são probabilidades
validadas.

## Dados e revisão solicitada

O próprio assistente escreveu, anotou e revisou os 72 textos, com justificativa
semântica por registro antes dos scores. Sem revisão humana, anotador
independente, cegamento ou concordância interavaliadores. O nome exato do
modelo gerador não foi inferido. Não há currículos reais nem dados pessoais.

São 36 textos e 34 origens por split: desenvolvimento e teste. Cada split tem
32 descrições livres e dois pares com/sem marcadores. Temas e formatos ainda
se repetem; o teste não é semanticamente independente da autoria do
desenvolvimento. As tags cobrem versões, medidas por extenso, futuro, negação,
perguntas, contrafactuais, resultados qualitativos e escrita informal.

Fontes, textos, rótulos, gerador determinístico e protocolo foram congelados
antes dos scores. Dados e artigo: CC BY 4.0. A nova suite fica em `data/v02`,
separada dos splits de treinamento da v0.1. Detalhes: [protocolo](../data/v02/README.md)
e [revisão por IA](v02-data-review.md).

## Calibração e abstenção

Somente desenvolvimento ajusta uma temperatura global por modelo na grade
predefinida. BERT: T=0,965936; regressão: T=4,0, o extremo superior da grade.
Esse extremo é relatado como limitação; a grade não foi ampliada após os scores.
A temperatura não muda as decisões no limiar 0,5, por isso F1 e Hamming são
iguais antes/depois. Os scores podem mudar e afetar probabilidades e cobertura.

Nenhum cutoff predefinido conseguiu erro observado de até 5% mantendo pelo
menos 50% das decisões em desenvolvimento. As políticas registram cutoff null:
a abstenção por confiança permanece desativada. A infraestrutura aceita
abstenção quando um experimento futuro atender a seus critérios. Truncamento
continua marcando negativos como unknown independentemente disso.

As políticas são opt-in, ligadas por hash ao bundle e identificadas nos
diagnósticos. Não se tornam padrão. O novo teste usa as políticas congeladas,
sem reestimá-las. Curvas de risco/cobertura de teste são descritivas; não escolher
um cutoff a partir delas. Nenhum score é nota de escrita ou competência.

## Reproduzir a avaliação

Com a stack ML instalada pelo lock e os artefatos originais em `artifacts/run-42`:

```bash
python3 scripts/build_v02_suite.py
uv run --frozen --extra ml python -m patchinsight.research historical
uv run --frozen --extra ml python -m patchinsight.research development --device cuda
uv run --frozen --extra ml python -m patchinsight.research test --device cuda
uv run --frozen --extra ml python -m patchinsight.research latency --device cuda
```

Esses relatórios já existem e os comandos recusam sobrescrita. Para uma
reprodução, acrescente `--root-output artifacts/v02-reproduction` a cada comando,
usando a mesma pasta em desenvolvimento e teste. CPU também é suportada.
O encoder base é carregado apenas do cache local, com revisão fixa; preparar o
cache pelo treino/reprodução original antes de desconectar a rede. `--run`
seleciona a pasta com `model/` e `frozen.json`; não basta baixar apenas o BERT.

Relatórios: [histórico posterior](../reports/v02/historical/README.md),
[desenvolvimento](../reports/v02/development/README.md),
[novo teste](../reports/v02/test/README.md), [erros](../reports/v02/error-analysis.md).
Os JSON incluem versões, ambiente, hashes, métricas por componente, recortes,
risco/cobertura e confiabilidade. Macro-F1 em recortes com rótulos sem positivos
usa zero_division=0: pode ser zero mesmo com previsões negativas corretas.
Comparar esses recortes também por Hamming, suportes e FP/FN, não só macro-F1.

## Inferência em lote

```bash
printf '%s\n' '{"id":"a","text":"Revisei as consultas com SQL."}' \
  '{"id":"b","text":"OAuth 2.0"}' | \
  uv run --frozen --extra ml patchinsight batch --model artifacts/model --batch-size 8
```

JSONL de entrada com text e id opcional (string até 200 caracteres). Um envelope
por linha de saída conserva ordem, número de linha, id e prediction ou error.
O modelo é carregado uma vez e os itens válidos são inferidos juntos. Linhas
inválidas não impedem os demais itens. Exit 0: todos válidos; 1: erros por linha;
2: erro de configuração, limite global ou inferência.

Batch de 1–64, máximo padrão 10.000 itens; `--max-items` ajusta esse total.
Entradas excedendo 100.000 caracteres por linha encerram o fluxo. Textos seguem
o limite de 20.000 caracteres e as regras de truncamento do contrato.
`--timeout` padrão 300 segundos é cooperativo: verificado entre lotes após
leitura. Não interrompe uma inferência ativa nem uma leitura stdin bloqueada.
Saída anterior continua válida em interrupções. `--input arquivo.jsonl` lê arquivo.

## Demo local

```bash
uv run --frozen --extra ml patchinsight serve --model artifacts/model --device cuda
```

Abrir `http://127.0.0.1:8765`. Texto livre, exemplos editáveis, cinco componentes,
combinações, scores, truncamento e JSON versionado. A inferência usa o checkpoint
real. `--backend heuristic` seleciona explicitamente regras. Não há fallback.

[Captura da demo verificada no Firefox](images/v02-demo-desktop.png).

A interface e o endpoint POST `/v1/analyze` ficam restritos a loopback; não é um
serviço publicado. O endpoint aceita apenas `{"text":"..."}`. Modelo carregado
uma vez, inferência serializada, máximo de 100.000 bytes por body, sem persistir
textos ou registrar requests. `/healthz` informa backend pronto e política.
Host/origem são limitados à demo local. CPU: omitir `--device cuda`.

Calibração experimental opt-in, com o bundle usado no experimento:

```bash
uv run --frozen --extra ml patchinsight serve --model artifacts/run-42/model \
  --policy reports/v02/development/bert_finetuned-policy.json
```

Uma política de outro método ou bundle é rejeitada. A política fornecida tem
abstenção desativada por não cumprir os critérios em desenvolvimento.

Action–Method exige action e method presentes; qualquer unknown impede o match.
Assim como as demais estruturas, isso indica coocorrência, não vínculo causal.
Schema e regras: 0.2.0. Não usar um validador JSON 0.1.0 para as novas saídas.

## Escopo concluído e continuidade

SHOULD atendidos nesta rodada: testes adversariais (ML-15), experimento de
calibração (ML-12), inferência em lote (ENG-06), mecanismo de incerteza com
critério explícito (ENG-08), Action–Method (STR-06) e demo (PUB-06). A meta
empírica de abstenção não foi atingida. Tracking continua em arquivos locais;
não foi adicionada infraestrutura de experimentos nem contratada computação.

A revisão permanece por IA conforme solicitado. Spans, task/challenge como novos
rótulos, CAR, vagueza/especificidade supervisionadas e inglês exigem novos dados
e avaliações. A próxima rodada pode trabalhar com escrita livre e novas fontes
ou revisão independente, mantendo um novo teste sem consulta durante ajustes.

## Medição local de inferência

RTX A1000 6 GB, CUDA, revisão fixa dos mesmos encoders; três lotes de aquecimento
e 12 repetições por método/tamanho. Inclui tokenização, modelo e scores; exclui
JSON, regras e I/O. Inferências foram medidas sem inicialização concorrente de
outro modelo na GPU. Uma primeira medição com inicialização concorrente da demo
foi descartada e mantida somente em artifacts, fora do relatório publicado.

| Método | Lote 1 p50 / p95 (ms) | Lote 8 p50 / p95 (ms) | Textos/s no lote 8 |
|---|---:|---:|---:|
| Heurísticas | 0,08 / 0,08 | 1,48 / 1,81 | 5.156 |
| Regressão | 5,44 / 5,56 | 15,43 / 16,41 | 514 |
| BERT ajustado | 4,66 / 4,85 | 14,88 / 15,57 | 537 |

São medições pequenas sobre textos de desenvolvimento, não uma promessa de
latência para qualquer entrada. O tamanho de lote altera também a composição
dos textos, por isso não isola seu efeito. O JSON registra pico de memória CUDA
do processo com ambos os encoders residentes, não consumo isolado por método.
Memória CPU não foi medida. Evidência: [latência](../reports/v02/latency/results.json).

## Verificações concluídas

25 testes passaram com a stack ML e checkpoint real. Em ambiente separado sem
ML, 16 passaram e três testes dependentes de ML foram explicitamente pulados.
Wheel instalado em outra virtualenv: HTML, comparação JSON e inferência
heurística funcionaram sem dependências de ML. Lock conferido com `uv lock --check`.

Firefox headless validou inferência BERT, exemplos, erro de entrada vazia,
ordenação por métrica, troca de conjunto e ausência de overflow horizontal em
tela estreita. A imagem Docker 0.2.0 carregou o modelo real e inferiu sem rede,
com filesystem somente leitura e usuário 65532. A imagem anterior não foi
retagueada. A verificação compara os dados originais e relatórios finais com a
tag v0.1.0, além de conferir o hash dos pesos preservados.

Registro: [verification.json](../reports/v02/verification.json). Binários e logs
em `artifacts/` são evidências locais, não foram enviados a registry, GitHub ou
Hub. Screenshot incluída na documentação. O pacote de fontes usa allowlist e
exclui PDF, credenciais e `docs.md` privado.