README.md

---
license: mit
language:
- pt
tags:
- mixture-of-experts
- cross-moe-attention
- kohonen
- som-attention
- micro-units
- transformer
- cnn-bigru
- bigru
- multimodal
- diffusion
- stable-diffusion
- multi-token-prediction
- medusa
- speculative-decoding
- dpo
- pcgrad
- int8
- torchao
- qat
- fp8
- nlp
- nlg
- long-context
- engineer-agent
- pt-br
metrics:
- perplexity
- clip_score
- cider
- bleu
- rouge_l
- meteor
---

# AURORA v7 — Retreino observado (RAM + métricas de `tests/test_aurora_v6.py`) com comparação ao treino anterior

IA multimodal (texto, imagem, áudio, vídeo) **auto-aprendente** para português do
Brasil. A v7 **retreina DO ZERO** sobre a arquitetura v6 (S-SOM + RPP + métricas)
com os estados salvos APAGADOS do Hub (`estados/fase-v6` removidos em commit de
deleção) e do disco, e coloca o **Agente Engenheiro para observar** treino e
inferência — incluindo o **consumo de memória RAM** a cada 2 s, as métricas de
`tests/test_aurora_v6.py` e a **comparação direta com o treino anterior**
(gráficos abaixo, publicados APENAS neste card):

- **Monitor de RAM integral** (`MonitorRAM` em `scripts/04_treinar.py`):
  6.059 amostras em 3,6 h — RSS mín/méd/**máx = 543/2.692/3.580 MB**, RAM
  disponível mínima 138,6 MB (CPU 2 núcleos, 4 GB);
- **Cláusula 2 da eq. (9.3) IMPLEMENTADA** (`src/aurora/treino/punicao.py`):
  estagnação agora também dispara quando a **EMA da perda não melhora ≥ ε em
  k janelas** — com escada de agressividade (2× `warm_restart` SGDR ⇒
  `reinit_parcial_replay` na camada dorminhoca, Teorema 9.2). Diagnóstico: o
  detector anterior (só mínimos por janela) nunca disparava em platôs ruidosos
  e o treino podia divergir conforme a inicialização;
- **Reprodutibilidade**: `--semente` fixa a init torch (v7 usa semente 2026);
- **Não-regressão APROVADA** (Teorema 16.10, gate do Agente Engenheiro):
  ppl LM **17,09 vs 17,13** (−0,26%), perda média final 0,89 vs 0,79 (ep
  re-executada), taxa de ativos SOM = 1,0 e invariante ZERO órfãos preservados;
- Testes: **48 ✓ / 0 ✗** em `tests/test_aurora_v6.py` (3 novos — cláusula 2);
  174 verificações no total (v1–v7).

## Gráficos de desempenho — retreino v7 vs treino anterior (publicados apenas neste card)

### Perplexidade LM por época
![Perplexidade LM por época](graficos/graf_ppl_lm.png)

### Curva de aprendizado (perda média)
![Curva de aprendizado](graficos/graf_curva_perda.png)

### Consumo de memória RAM durante o retreino (Agente Engenheiro)
![Consumo de RAM](graficos/graf_ram.png)

### Perda final por tarefa
![Perdas por tarefa](graficos/graf_perdas_tarefa.png)

### SOM (taxa de ativos por variante) e RPP (Reward/Punishment/Penalty)
![SOM e RPP](graficos/graf_som_roteador.png)

### Alinhamento multimodal (CLIP / ITM / PPL — leitura honesta)
![Alinhamento](graficos/graf_alinhamento.png)

### Tabela-resumo da comparação (treino anterior vs retreino v7)

| Métrica | Treino anterior (v6) | Retreino v7 | Δ |
|---|---|---|---|
| passos (do zero) | 3192 | 3192 | = |
| ppl LM final | 17,13 | **17,09** | −0,26% |
| ppl LM aleatório | ~16.945 | ~16.859 | referência |
| perda lm / instr / ocr / vqa | 2,84 / 2,21 / 2,11 / 2,45 | 2,84 / **2,04** / **1,42** / **2,18** | 5 de 9 tarefas melhoram |
| CLIP margem (real−controle) | −0,0065 | **+0,0098** | sinal positivo |
| ppl multimodal (VQ por corrida) | 5,59 | 9,41 | ruidoso entre corridas* |
| SOM taxa de ativos (variantes ativas) | 1,0 | **1,0** | = |
| invariante ZERO órfãos | ✓ | **✓** | = |
| `tests/test_aurora_v6.py` | 44 ✓ / 0 ✗ | **48 ✓ / 0 ✗** | +3 cláusula 2 |
| RAM pico / média (Agente) | n/d | **3.580 / 2.692 MB** | observado |
| punições/retreinos | 2 | 0 (sem platô; curva saudável) | — |

\* o codebook VQ é re-estimado por k-means a cada corrida; a variância entre
treinos independentes supera a diferença de qualidade — reportado honestamente,
fora do gate de não-regressão (doc 16 §10). Métricas de geração (BLEU/ROUGE/
METEOR/CIDEr) e benchmarks (MMMU/MME/MathVista proxies) permanecem honestamente
baixos na escala de 13,3M parâmetros CPU — o harness está validado; a escala do
modelo é o fator limitante.

- **ROTEAMENTO POR S-SOM** (doc 18 §1, Teoremas 18.1–18.3): o S-SOM
  supervisionado vira roteador do MoE — viés de rota condicional ao CONTEXTO
  (não só ao rótulo declarado), normalizado por log(1/C), com nascimento
  NEUTRO (λ=0 ⇒ v5 exato) e **restrição a empates de Voronoi** (célula
  dominante fora de empates nunca é sobrescrita — Teorema 18.6);
- **REWARD / PUNISHMENT / PENALTY** (doc 18 §2, Teoremas 18.4–18.7): controlador
  de 3 canais — REWARD multiplicativo com gate de integridade (ρ ∈ [1−ρ̄, 1+ρ̄],
  só com melhora > 1σ e SOM saudável), PUNISHMENT com **SGDR T_mult** (ciclos
  T_i = T_0·m^i — recomeços FINITOS, Teorema 18.5), PENALTY aditivo limitado
  (novidade restrita a empates, balanceamento, ortogonalidade, rotas mortas);
  Robbins–Monro PRESERVADO (Teorema 18.4);
- **PACOTE INTEGRAL DE MÉTRICAS** (doc 18 §3):
  * Alinhamento cross-modal: **CLIP Score** (2.5·cos, controle negativo incluído),
    **Image-Text Matching** (ITM com cabeça binária real/pairs embaralhados),
    **PPL Multimodal** (texto sob prefixo visual/áudio + PPL de códigos visuais VQ);
  * Geração de texto: **CIDEr** (TF-IDF), **BLEU 1–4**, **ROUGE-L**, **METEOR**
    (stem PT-BR determinístico + sinônimos);
  * Benchmarks (proxies PT-BR honestos, fórmulas oficiais): **MMMU** (MCQ A–D),
    **MME** (2·acc + acc⁺), **MathVista** (acerto numérico normalizado);
  * Kohonen/SOM: **QE**, **TE**, **Medida de Distorção** (ponderada pela
    vizinhança), **σ(t)**, **α(t)**, **Weight Codebook Drift**, **Frequência de
    Ativação por neurônio** (+ entropia + rank efetivo), **U-Matrix** (média,
    máx, fronteiras); TODAS as 8 variantes + roteador;
- **Agente Engenheiro v6**: observação integral agora inclui roteador S-SOM,
  RPP e métricas SOM expandidas por variante a cada passo de observação.

## O que a v5 trouxe (preservado)

Atenção ENTRE camadas MoE (Teoremas 16.1–16.2) e ENTRE as variantes Kohonen
(Teoremas 16.3–16.5, ZERO neurônios isolados), difusão multimodal com as 3
pipelines (`StableDiffusionPipeline`, `Img2Img`, `Inpaint`), quantização 8-bits
REAL sem fakes (torchao INT8/QAT/FP8 + bitsandbytes), Agente Engenheiro,
checkpoints locais + publicação em commit único.

## O que a v4 trouxe (preservado)

Auto-escala por computo (Teoremas 12.1–12.3, LPT/Nemhauser), unidades NLP/NLG de
primeira classe (Teorema 15.1 — nascem neutras), janela de contexto 1M indexada
(Teorema 13.1), Medusa especulativa em árvore (Teoremas 14.1–14.2, absorvida de
`medusa_speculative_decoder.py` + `multi_token_predictor.py`), duas fases de
treino (Fase A rede aumentada → Fase B consolidação SOM), MoE agrupável com
foco na tarefa, vocab **16384**, **n_experts_fusao=4**, DPO com β adaptativo,
PCGrad, punição/retreino (SGDR), W8A8 por grupo + correção de viés.

## Matemática (ler antes do código)

- `00–09` (v1): SOM clássico + 8 variantes, atenção mista + KV-cache, W8A8, ortogonais, punição, PDCA
- `10` (v2) · `11` (v3) · `12–15` (v4): MoE agrupável, microunidades, auto-escala, janela 1M, Medusa, NLP/NLG
- `16` (v5): atenção entre MoEs (16.1–16.2), entre variantes SOM (16.3–16.5), custo (16.6), checkpoints (16.9), Agente Engenheiro (16.10)
- `17` (v5): difusão multimodal — força semântica (17.1), degradação honesta (17.2), enriquecimento NLG (17.3), contrato de memória (17.4)
- **`18` (v6): roteamento por S-SOM (18.1–18.3), RPP (18.4–18.7), métricas — CLIP/ITM/PPL-mm, CIDEr/BLEU/ROUGE/METEOR, benchmarks, QE/TE/distorção/drift/U-Matrix (18.8)**

## Estrutura do repositório

```
src/aurora/
  treino/punicao.py           # v7: cláusula 2 da eq. (9.3) — EMA estagnada +
                              #  escada warm_restart→reinit_parcial_replay
  metricas/alinhamento.py     # NOVO v6: CLIP Score + ITM + PPL Multimodal (doc 18 §3.1)
  metricas/geracao_texto.py   # NOVO v6: CIDEr + BLEU 1–4 + ROUGE-L + METEOR (doc 18 §3.2)
  metricas/benchmarks.py      # NOVO v6: MMMU/MME/MathVista — proxies PT-BR (doc 18 §3.3)
  metricas/som_metricas.py    # NOVO v6: QE/TE/distorção/σ/α/drift/freq/U-Matrix (doc 18 §3.4)
  percepcao/roteador_ssom.py  # NOVO v6: RoteadorSSOM — roteamento por S-SOM (doc 18 §1)
  percepcao/moe.py            # v6: viés de rota S-SOM com restrição a empates
  treino/rpp.py               # NOVO v6: GestorRPP — Reward/Punishment/Penalty (doc 18 §2)
  treino/punicao.py           # v6: SGDR com T_mult (Teorema 18.5)
  nucleo/modelo.py            # v6: roteador compartilhado + gerar(emb_prefixo)
  percepcao/atencao_moe.py    # v5: RefinamentoEntreMoEs (doc 16 §§1–2)
  memoria/atencao_som.py      # v5: AtencaoEntreVariantes + anti-órfãos
  geracao/difusao.py          # v5: GeradorMultimodal (3 pipelines SD + ciclo fechado)
  quanta/quantizacao.py       # v5: fakes REMOVIDOS; backends reais §7.1–7.4
  qualidade/agente_engenheiro.py  # v6: + roteador, RPP e SOM expandido na observação
  dados/checkpoints.py        # v5: checkpoints locais + snapshot p/ commit único
scripts/                      # 01..08 (verificar→coletar→tokenizador→treinar→
                              #  avaliar→publicar→reconsolidar_som→graficos_card)
configs/base.json             # vocab 16384, n_experts_fusao 4, roteador, rpp,
                              # atencao_moe, som_atencao, difusao, agente_engenheiro
docs/matematica/              # 00–18: provas ANTES dos scripts
tests/                        # 25 (v1) + 36 (v2) + v3 + 37 (v4) + 29 (v5) + 48 (v6)
avaliacao_v7.json             # evidências: TODAS as métricas do doc 18 (v7)
resumo_treino_v7.json         # curva por época + RPP + roteador + RAM monitorada
comparacao_treino_v7.json     # v7 vs treino anterior + gate de não-regressão
test_aurora_v6_pos_treino.txt # saída integral dos 48 testes pós-treino
graficos/                     # GRÁFICOS DE DESEMPENHO (exibidos no card acima)
relatorio_agente_engenheiro.json  # observação integral do treino/inferência
estados/fase-v7/              # pesos finais (modelo.safetensors + meta.json SHA-256)
```

## Pipeline (scripts organizados)

```bash
pip install -r requirements.txt
export HF_TOKEN=...            # apenas variável de ambiente; NUNCA em arquivo
python3 scripts/01_verificar_ambiente.py
python3 scripts/02_coletar_corpus.py        # um dataset por vez (streaming, subprocesso)
python3 scripts/03_treinar_tokenizador.py   # vocab 16384 (Rust BPE paralelo)
python3 scripts/04_treinar.py --orcamento 460 --semente 2026   # Fase A → DPO → Fase B (SOM)
python3 scripts/05_avaliar.py               # evidências + coerência + Agente Engenheiro
python3 scripts/07_reconsolidar_som.py      # re-consolida SOM após correções pontuais
python3 scripts/08_graficos_card.py         # gráficos do card + comparação + gate 16.10
python3 scripts/06_publicar_hf.py           # publicação ÚNICA e COMPLETA (1 commit)
```

## Métricas observadas pelo Agente Engenheiro (treino + inferência)

atenção (gates global/janela/linear) · MoE por camada (uso, entropia de rotas,
α de refino, β de retroalimentação, fração de rotas S-SOM) · **roteador S-SOM**
(amostras, prontidão, confiança média, drift do codebook, taxa de ativos) ·
**RPP** (ρ, streak, recompensas, punições, penalidades) · microunidades (ramos
ativos, recursão) · SOM e 8 variantes (k, taxa de ativos, EQ, órfãos=0,
**QE/TE/distorção/drift/freq/U-Matrix**) · atenção entre variantes (pesos,
entropia) · NLP (porta, intenção) · NLG (coerência de bigramas, estilo) ·
janela 1M (segmentos, hit de células) · memória interna · quantização (modo
real, erro QAT) · MTP (α) · computo (núcleos, RAM) · inferência (latência,
repetição, coerência) · **avaliação**: CLIP Score, ITM, PPL Multimodal,
CIDEr/BLEU/ROUGE-L/METEOR, benchmarks MMMU/MME/MathVista (proxies PT-BR).

## Licença

MIT — ver `LICENSE`.