Merge pull request #562 from LayoutParser/feat-import-checkpoints

feat: checkpoints de importação

Author: elson-vinicius-lopes

.claude/agent-memory/lp-parser-llm/MEMORY.md

@@ -24,6 +24,7 @@
 - [DSL mapper Camadas 0-1-2 implementadas](dsl-mapper-camadas-0-1-2-implementadas.md) — parser DSL→JSON (DslStructuredParser), schema versionado, catálogo de funções via MetadataLoadContext (ofuscação documentada), FewShotIndex.RetrieveStructured; branch feat/dsl-mapper-contexto-ia commit 8c6c2e0, 11 testes verdes.
 - [Smoke-test #3 checkpointing+chunking](finetuning-smoke-test3-checkpointing-chunking.md) — checkpointing resolve OOM em MAX_LEN=2048 (custa 2,7x/passo); chunking completo explode dataset 6,84x, inviável no fim de semana (56,6h/época).
 - [Issue #140 motor de resolução estrutural implementado](issue-140-motor-resolucao-estrutural-implementado.md) — XSD real NF-e via XmlSchemaSet (dono decidiu XSD > LayoutVO), classificador mappingKind, composer authoritative/best-effort; branch feat/resolucao-estrutural-txt-xml-140 commit 36ae5cb, 25 testes novos (36/36 verdes).
+- [Degeneração por época no fine-tuning (2026-08-30)](finetuning-degeneracao-por-epoca-2026-08-30.md) — checkpoints nunca existiam (save_strategy="no"); VM 15GB não aguenta treino+generate concorrentes (mata treino); resultado época-1 inconsistente com smoke-test #4 (protocolo frágil); repetition_penalty/no_repeat_ngram_size troca sintoma, não resolve.
 - [PR #209 falso conflito com develop](pr209-falso-conflito-develop-stale.md) — 2026-08-28: "conflito" era develop LOCAL desatualizado; origin/develop já tem 1992ed4 + fix IsDeclaredEmpty via PR #205; merge-tree limpo (docs-only), nenhum código a reconciliar.
 - [Fine-tuning smoke-test #2 dado real OOM](finetuning-smoke-test2-dado-real-oom.md) — MAX_LEN=4096 mata processo por OOM na VM; MAX_LEN=1024 usa 12Gi/15Gi e ~42s/passo; RAM é o limite real, não tempo; extrapolação anterior (256 tokens) inválida pro dado real.
 - [Smoke-test fine-tuning VM 2026-08-29](finetuning-smoke-test-vm-2026-08-29.md) — specs reais (i7-4790 4c, 15GB, sem GPU); sudo bloqueado contornado com pip --break-system-packages; bitsandbytes NÃO quantiza em CPU (LoRA fp32, não QLoRA); 10,7s/passo medido (Qwen2.5-Coder-1.5B, seq 256) — falta medir com seq_len real (~16.6k chars) antes do treino completo.

.claude/agent-memory/lp-parser-llm/finetuning-degeneracao-por-epoca-2026-08-30.md

@@ -0,0 +1,42 @@
+---
+name: finetuning-degeneracao-por-epoca-2026-08-30
+description: Diagnóstico de degeneração por época no smoke-test de fine-tuning (par único NFe) — checkpoints nunca existiam, resultado inconsistente com smoke-test #4, mitigadores de geração não resolvem sozinhos.
+metadata:
+  type: project
+---
+
+Investigação de 2026-08-30 sobre por que o treino de 3 épocas (171 passos, 57 chunks, 1 par NFe
+real, VM `elson@172.25.32.5`) degenerou em repetição alucinada.
+
+**Achado 1 — checkpoints intermediários nunca existiram.** `smoke_train_single_pair.py` usa
+`save_strategy="no"`; só o adapter final é salvo, sobrescrito a cada rodada. Sempre confirmar isso
+lendo o script antes de assumir que dá pra "carregar o checkpoint da época X" — não tinha como.
+
+**Achado 2 — VM tem teto duro de RAM: treino (~11,8GB pico) + `generate()` (~6,6GB) juntos
+excedem os 15GB e o SO mata o processo de treino silenciosamente** (sem mensagem visível sem
+`dmesg` root — o processo só some do `ps`). Aconteceu 2x nesta sessão. **Nunca rodar treino e
+inferência concorrentes nesta VM.** Isso limitou a coleta ao checkpoint da época 1 (retreino
+completo até 3 épocas ficou fora do orçamento de tempo).
+
+**Achado 3 — resultado desta sessão é inconsistente com o smoke-test #4 documentado.** O
+smoke-test #4 (mesma config: greedy, `MAX_LEN=2048`, 1 época, `max_new_tokens=1024`) reportava
+convergência para XSLT válido com defaults semânticos corretos após ~1024 tokens de eco. A
+reprodução desta sessão (checkpoint da época 1, mesmo par, script equivalente) produziu eco puro
+sem nenhuma transição para XSLT (`xsl:` count = 0). Hipótese mais provável: sensibilidade a
+não-determinismo em CPU (ordem de float ops/threading), não uma mudança real de protocolo — a
+única diferença de script foi `save_strategy`. **Tratar "converge em N épocas" como resultado
+frágil/não confiável neste protocolo até reproduzir de forma estável.**
+
+**Achado 4 — `repetition_penalty=1.2` + `no_repeat_ngram_size=3` NÃO resolve a degeneração
+sozinho.** Testado no adapter final de 3 épocas: elimina o padrão de repetição/eco degenerado, mas
+o modelo migra para **alucinação de conteúdo fora de domínio** (JSON pseudo-estruturado
+inventado), não para XSLT (`xsl:` continua em 0). Mitigador de geração troca o sintoma, não ataca
+a causa (transição prompt→resposta mal aprendida).
+
+**Recomendação registrada no plano:** não investir mais em variar número de épocas neste
+protocolo; atacar a causa mais provável — truncamento do prompt a 1024 tokens de um `.tcl` real
+com >10K tokens, que corta a âncora da transição prompt→resposta. Ver
+`docs/architecture/plano-finetuning-especializacao-mapeamento-sysmiddle-2026-08-29.md`, seção
+"Diagnóstico de degeneração por época — 2026-08-30", para o detalhe completo.
+
+Relacionado: [[finetuning-small-model-poc]] (memória de usuário), [[finetuning-poc-fase1-dataset]].