Delete docs/MATH_ANALYSIS.md with huggingface_hub

docs/MATH_ANALYSIS.md

@@ -1,819 +0,0 @@
-# Análise Matemática — EWC, Context Window e Elementos Faltantes
-
-**Projeto:** CNN-BiGRU Multimodal Cooperativo Autoaprendível
-**Versão:** 2.0 (aprimoramento com EWC + Context Window + RoPE + Transformer Decoder)
-**Data:** 2026-08-11
-
----
-
-## 1. Visão Geral
-
-Este documento registra a **análise matemática e lógica** da inclusão de:
-
-1. **EWC (Elastic Weight Consolidation)** — aprendizado contínuo sem catastrophic forgetting
-2. **Context Window** — janela deslizante com cache KV para sequências longas
-3. **RoPE (Rotary Position Embeddings)** — codificação posicional rotacional
-4. **CausalSelfAttention / TransformerBlock** — bloco decodificador causal
-5. **Self-Attention final layer** — camada de auto-atenção verdadeira ao final de cada bloco (dados.txt linha 470)
-
-Também lista demais elementos faltantes identificados na análise do `dados.txt`.
-
----
-
-## 2. Análise Matemática do EWC (Elastic Weight Consolidation)
-
-### 2.1. Fundamentação Teórica
-
-O EWC (Kirkpatrick et al., 2017) regulariza o treinamento contínuo penalizando
-mudanças grandes nos parâmetros $\theta$ que foram importantes para tarefas
-anteriores. A importância é estimada pela **diagonal da matriz de informação
-de Fisher** $\mathcal{I}$.
-
-Para uma tarefa $\mathcal{T}_A$ treinada primeiro, a loss para a próxima tarefa
-$\mathcal{T}_B$ é:
-
-$$
-\mathcal{L}_{\text{total}}(\theta) \;=\; \mathcal{L}_{B}(\theta) \;+\; \sum_{i}
-\frac{\lambda_{\text{EWC}}}{2} \, \mathcal{I}_{i}^{A} \, \bigl(\theta_{i} -
-\theta_{A,i}^{*}\bigr)^{2}
-$$
-
-onde:
-- $\theta_{A}^{*}$ é o ótimo da tarefa $\mathcal{T}_A$ (congelado após treino de $A$)
-- $\mathcal{I}_{i}^{A}$ é a entrada diagonal $i$-ésima da matriz de Fisher para $A$
-- $\lambda_{\text{EWC}}$ é o peso da regularização
-
-### 2.2. Estimativa da Matriz de Fisher (Diagonal)
-
-Para modelos com saída probabilística $p(y \mid x; \theta)$, a diagonal da
-Fisher Information Matrix pode ser estimada **em uma única passagem** como a
-média do quadrado dos gradientes pontuais:
-
-$$
-\mathcal{I}_{i}^{A} \;\approx\; \frac{1}{N} \sum_{n=1}^{N}
-\Bigl[\,\nabla_{\theta_{i}} \log p\bigl(y_{n}^{*} \mid x_{n}; \theta_{A}^{*}\bigr)
-\,\Bigr]^{2}
-$$
-
-onde $y_{n}^{*} = \arg\max_{y} p(y \mid x_n; \theta_A^*)$ (rótulo predito pelo
-próprio modelo — *empirical Fisher*).
-
-**Justificativa matemática:** A Fisher Information é a variância esperada do
-gradiente da log-verossimilhança; sob a hipótese de que $y_n^*$ é o rótulo
-verdadeiro (maximização), $\mathbb{E}[(\nabla \log p)^2] = -\mathbb{E}[\nabla^2
-\log p]$, que é a definição da Fisher Information. A versão *empirical* usa
-$y^*$ no lugar de $y$ verdadeiro, que é viesada porém consistente para modelos
-bem-treinados.
-
-### 2.3. Integração na Função de Perda do CNN-BiGRU
-
-A perda total do projeto (conforme `dados.txt` seção 8) é:
-
-$$
-\mathcal{L}_{\text{total}} \;=\; \alpha \, \mathcal{L}_{G}^{\text{total}}
-\;+\; \beta \, \mathcal{L}_{V} \;+\; \gamma \, \mathcal{L}_{AH} \;+\; \delta \,
-\mathcal{L}_{\text{reg}}
-$$
-
-A inclusão do EWC adiciona um novo termo $\mathcal{L}_{\text{EWC}}$ à
-regularização $\mathcal{L}_{\text{reg}}$:
-
-$$
-\mathcal{L}_{\text{reg}}^{\text{new}} \;=\; \mathcal{L}_{\text{reg}}^{\text{old}}
-\;+\; \mathcal{L}_{\text{EWC}}
-\;=\; \lambda_{L2} \sum_i \theta_i^2 \;+\;
-\kappa \, \text{tr}(\hat{H}) \;+\; \sum_i \frac{\lambda_{\text{EWC}}}{2} \,
-F_i \, (\theta_i - \theta_i^*)^2
-$$
-
-**Implementação diferenciável:** a penalidade é uma forma quadrática nos
-parâmetros atuais, portanto $\nabla_{\theta} \mathcal{L}_{\text{EWC}} = \lambda_{\text{EWC}}
-\cdot F \odot (\theta - \theta^*)$, onde $\odot$ é produto Hadamard.
-
-### 2.4. Pontos de Integração no Pipeline
-
-| Etapa | Ação | Módulo |
-|-------|------|--------|
-| Após treinar tarefa A | Calcular $F$ e armazenar $\theta^*$ | `utils/ewc.py:compute_fisher` |
-| A cada step da tarefa B | Somar $\mathcal{L}_{\text{EWC}}$ à perda | `losses/losses.py` |
-| Treino multitarefa | Manter lista $[(\theta^*_k, F_k)]$ e somar EWC de todas as tarefas anteriores | `utils/ewc.py:EWCState` |
-
-### 2.5. Análise de Estabilidade
-
-- **Limit $\lambda_{\text{EWC}} \to 0$:** EWC desligado → catastrophic forgetting total
-- **Limit $\lambda_{\text{EWC}} \to \infty$:** parâmetros congelados → sem aprendizado novo
-- **Compromisso prático:** $\lambda_{\text{EWC}} \in [100, 10000]$ tipicamente
-  recomendado na literatura
-
-**Garantia matemática:** sob a hipótese de que $\mathcal{L}_B$ é fortemente
-convexa em $\theta^*$ e $F \succ 0$, o EWC é equivalente a uma aproximação
-de Laplace da posterior $p(\theta \mid \mathcal{D}_A)$, garantindo que a solução
-ótima permaneça próxima de $\theta^*$ ao longo do treino de $\mathcal{T}_B$.
-
-### 2.6. Riscos e Mitigação
-
-| Risco | Mitigação |
-|-------|-----------|
-| $F$ é ruidosa para pequenos batches | Usar `n_samples_fisher ≥ 500` e média móvel exponencial |
-| Memória: armazenar $F$ igual ao tamanho do modelo | Usar **diagonal apenas** (mesmo tamanho do modelo, viável) |
-| $\theta^*$ fica defasado após muitas tarefas | Implementar **online EWC**: $F^{\text{new}} = \gamma F^{\text{old}} + F^{\text{current}}$ |
-| EWC pode entrar em conflito com spectral norm | Aplicar EWC **apenas** aos pesos não-normalizados espectralmente |
-
----
-
-## 3. Análise Matemática do Context Window
-
-### 3.1. Motivação
-
-O `dados.txt` seção 7 (Transformer Decoder) define `max_seq_len` como
-comprimento máximo de contexto. Sem um mecanismo de **janela deslizante**, o
-modelo:
-
-1. Não consegue processar entradas maiores que `max_seq_len`
-2. Recomputa toda a sequência a cada token gerado → $O(T^2)$ em inferência
-3. Não consegue manter coerência em diálogos longos
-
-### 3.2. Formulação Matemática
-
-Seja $x_{1:T}$ uma sequência de comprimento $T > L_{\max}$ (janela máxima).
-Definimos a janela deslizante $\mathcal{W}_t$ no passo $t$ como:
-
-$$
-\mathcal{W}_t \;=\; x_{\max(1,\,t-L_{\max}+1)\,:\,t}
-$$
-
-A saída do modelo no passo $t$ depende apenas de $\mathcal{W}_t$:
-
-$$
-h_t \;=\; f_\theta\bigl(\mathcal{W}_t\bigr)
-$$
-
-### 3.3. Cache KV para Atenção Eficiente
-
-Para a CausalSelfAttention, o custo de inferência autoregressiva sem cache é:
-
-$$
-\text{FLOPs}_{\text{no cache}}(T) \;=\; O\bigl(T^2 \cdot d\bigr)
-$$
-
-Com cache dos pares $(K, V)$ dos passos anteriores, cada novo token $t$ apenas:
-
-1. Calcula $q_t, k_t, v_t$ para o novo token (custo $O(d)$)
-2. Concatena com cache: $K_{1:t} = [K_{1:t-1}; k_t]$, $V_{1:t} = [V_{1:t-1}; v_t]$
-3. Calcula atenção apenas do novo $q_t$ contra todo $K_{1:t}$ (custo $O(t \cdot d)$)
-
-$$
-\text{FLOPs}_{\text{with cache}}(T) \;=\; O\bigl(T \cdot d\bigr)
-$$
-
-**Speedup teórico:** fator $T$. Para $T = 512$ e $d = 256$, speedup ~512×.
-
-### 3.4. Política de Evicção (Chunked Cache)
-
-Quando $|\mathcal{W}_t| > L_{\max}$, aplicamos uma política de evicção. As três
-estratégias analisadas:
-
-#### 3.4.1. Sliding Window Pura
-Mantém apenas os últimos $L_{\max}$ tokens. Custo: $O(L_{\max})$ por step.
-Desvantagem: perde informação histórica relevante.
-
-#### 3.4.2. Sink + Sliding (StreamingLLM)
-Mantém os primeiros $k$ tokens ("sink", tipicamente BOS + system prompt) e os
-últimos $L_{\max} - k$ tokens. Custo: $O(L_{\max})$. Vantagem: preserva
-informação estrutural inicial.
-
-$$
-\mathcal{W}_t \;=\; \bigl[\,x_{1:k}\,;\, x_{t-(L_{\max}-k)+1\,:\,t}\,\bigr]
-$$
-
-#### 3.4.3. Attention Recomputation (sem cache)
-Recomputa a atenção sobre toda a sequência a cada step. Custo: $O(T^2)$.
-Vantagem: máxima precisão. Desvantagem: proibitivo para $T$ grande.
-
-**Implementação escolhida:** Sink + Sliding (StreamingLLM), com $k=4$ tokens
-sink configurável. Esta estratégia tem garantia teórica de estabilidade para
-$T \to \infty$ (Xiao et al., 2023).
-
-### 3.5. Integração com CNN-BiGRU Cooperativo
-
-O CNN-BiGRU cooperativo é **bidirecional** (processa $x_{1:T}$ em ambos os
-sentidos). Isto quebra a hipótese causal. Para preservar a bidirecionalidade:
-
-- **Modo encoder (treino/classificação):** sem cache, processa a janela inteira
-  $\mathcal{W}_t$ com BiGRU normal (forward + backward).
-- **Modo decoder (geração):** usa GRU unidirecional + CausalSelfAttention com
-  cache KV. Esta é a configuração usada para geração autoregressiva.
-
-### 3.6. Análise de Complexidade
-
-| Componente | Sem Context Window | Com Context Window |
-|------------|-------------------|-------------------|
-| Geração de $T$ tokens | $O(T^2 d)$ | $O(T \cdot L_{\max} \cdot d)$ |
-| Memória de cache | $O(T d)$ | $O(L_{\max} d)$ |
-| Precisão em longas sequências | Falha para $T > L_{\max}$ | Mantém coerência via sink |
-
-### 3.7. Riscos e Mitigação
-
-| Risco | Mitigação |
-|-------|-----------|
-| Perda de contexto ao evictar | Estratégia sink + sliding |
-| Cache desatualizado após fine-tuning | Invalidar cache quando pesos mudam |
-| Incompatibilidade com BiGRU (bidirecional) | Usar GRU unidirecional no decoder |
-| Memória cresce com $L_{\max}$ | Limitar $L_{\max} \leq 1024$ para CPU |
-
----
-
-## 4. Demais Elementos Faltantes Identificados
-
-### 4.1. RoPE (Rotary Position Embeddings)
-
-**Status no projeto atual:** AUSENTE. A codificação posicional atual depende
-apenas da convolução 1D (local) e da recorrência GRU (implícita).
-
-**Formulação matemática (Su et al., 2021):**
-
-Para um par $(q, k)$ em uma dada posição $(m, n)$, RoPE aplica uma rotação
-no plano 2D para cada par de dimensões $(q_{2i}, q_{2i+1})$:
-
-$$
-\begin{pmatrix} q'_{2i} \\ q'_{2i+1} \end{pmatrix}
-\;=\;
-\begin{pmatrix} \cos(m\theta_i) & -\sin(m\theta_i) \\ \sin(m\theta_i) & \cos(m\theta_i) \end{pmatrix}
-\begin{pmatrix} q_{2i} \\ q_{2i+1} \end{pmatrix}
-$$
-
-com $\theta_i = 10000^{-2i/d}$. A propriedade chave é:
-
-$$
-\langle \text{RoPE}(q, m), \text{RoPE}(k, n) \rangle \;=\; \langle
-\text{RoPE}(q, m-n), k \rangle
-$$
-
-→ a atenção depende apenas da diferença posicional relativa, não absoluta.
-
-**Integração:** Substitui `position_embedding = nn.Embedding(max_seq_len, embed_dim)`
-no TransformerBlock. Aplica-se a `q` e `k` antes do produto escalar.
-
-### 4.2. CausalSelfAttention / TransformerBlock
-
-**Status no projeto atual:** AUSENTE. Apenas Bahdanau attention existe no
-`generator_verifier.py`, e ela é não-causal (encoder-decoder).
-
-**Especificação (dados.txt seções 6-7):**
-
-```python
-class CausalSelfAttention(nn.Module):
-    # Multi-head com máscara triangular inferior
-    # QKV projection unificada
-    # Scaled dot-product: (q @ k.T) / sqrt(d_head)
-    # Máscara causal: triu(ones(T,T)) == 0 → -inf
-    # Softmax + dropout
-
-class TransformerBlock(nn.Module):
-    # Pre-LN: x = x + attn(ln1(x))
-    #         x = x + ffn(ln2(x))
-    # FFN: Linear(d, 4d) → GELU → Linear(4d, d) → Dropout
-```
-
-**Integração:** Como camada opcional no `CooperativeCNNBiGRU` para agregar
-informação global antes da fusão final.
-
-### 4.3. Self-Attention Final Layer (dados.txt linha 470)
-
-**Status no projeto atual:** PARCIAL. Existe `SelfAttentionSummary` mas usa
-`x.mean(dim=1)` como query — não é uma self-attention verdadeira.
-
-**Correção:** substituir por uma self-attention com `query = Linear(d, d)(x)`
-(verdadeira projeção de query, não média).
-
-### 4.4. Gradient Checkpointing
-
-**Status no projeto atual:** Declarado em `memory_optimizer.py` mas NUNCA
-chamado. Deve ser ativado no `CooperativeTrainer` para reduzir consumo de
-VRAM em modelos grandes.
-
-### 4.5. Weight Tying
-
-**Status no projeto atual:** AUSENTE. O `dados.txt` linha 632 explicitamente
-recomenda: `self.token_embedding.weight = self.lm_head.weight`. Deve ser
-opcional no `MultimodalCNNBiGRU`.
-
-### 4.6. AMP (Automatic Mixed Precision)
-
-**Status no projeto atual:** PARCIAL — `memory_optimizer.amp_context` retorna
-`nullcontext()` para CPU. Como o `xeon_runtime.py` detecta AMX/AVX512_BF16,
-deve habilitar `bfloat16` autocast em CPU também (PyTorch 1.10+).
-
-### 4.7. Online EWC
-
-**Status no projeto atual:** AUSENTE. Após múltiplas tarefas, a soma de
-$F_k$ explode em memória. Online EWC mantém apenas uma $F$ agregada:
-
-$$
-F^{\text{agg}} \;=\; \gamma \, F^{\text{prev}} \;+\; (1-\gamma) \, F^{\text{new}}
-$$
-
-### 4.8. Tokenizer: add_tokens dinâmico
-
-**Status no projeto atual:** AUSENTE. O `BBPETokenizer` não suporta adicionar
-novos tokens após o treino. Útil para fine-tuning com vocabulário especializado.
-
-### 4.9. Verificador Realmente Acionado
-
-**Status no projeto atual:** BUG. `trainer.py` instancia `VerifierCNNBiGRU`
-mas **NUNCA chama seu forward** — usa um proxy `sigmoid(fused.mean(-1))`.
-
-**Correção:** Chamar `verifier(premissas_a, passo_a, premissas_b, passo_b)`
-com tokens reais gerados pelo `GeneratorCNNBiGRU`.
-
-### 4.10. Hipótese com Porta Funcional
-
-**Status no projeto atual:** BUG. `hypothesis_controller.py` calcula `gate`
-mas `output = gate*combined + (1-gate)*combined = combined` (sempre).
-
-**Correção:** `x_proj = hypothesis_layer(x)` (projeção real), `output = gate *
-x_proj + (1-gate) * x` (interpolação entre a hipótese e o input original).
-
-### 4.11. Geração Autoregressiva Real
-
-**Status no projeto atual:** BUG. `inference.py` chama
-`model(..., mode="generate")` que retorna `[B, V]` (single-step) — não há
-autoregressão real.
-
-**Correção:** Implementar loop que:
-1. Processa prompt inicial
-2. A cada passo: extrai último logit, aplica sampling, anexa novo token,
-   atualiza cache KV, repete
-
-### 4.12. Multi-loss com Device Consistency
-
-**Status no projeto atual:** BUG. `losses.py` usa `torch.tensor(0.0)` sem
-`device=`, quebrando em GPU.
-
-**Correção:** Sempre criar tensores zero no device correto, ou usar
-`torch.zeros((), device=device)`.
-
-### 4.13. Inicialização Ortogonal Robusta
-
-**Status no projeto atual:** PARCIAL — `_orthogonal_init` faz fallback
-silencioso para `xavier_uniform_` em caso de exceção.
-
-**Correção:** Registrar o erro em log, propagar exceção em modo debug.
-
-### 4.14. Penalidade Exponencial Conforme Spec
-
-**Status no projeto atual:** DESVIO SEMÂNTICO. `losses.py` aplica
-$\sum \exp(\gamma(1-v))$ **apenas** para $v < \text{threshold}$, mas o
-`dados.txt` seção 8.2 diz "SE v_t < THRESHOLD_ERR: L_exp_penal += ..." (que é
-o comportamento atual — OK na verdade). Mas a soma linear
-$\sum (1-v_t)$ deve ser sobre TODOS os passos, não apenas os penalizados.
-
-**Revisão:** está correto conforme spec; apenas documentar claramente.
-
-### 4.15. Package `__init__.py`
-
-**Status no projeto atual:** VAZIO. Deve exportar principais classes,
-definir `__version__`, configurar logging.
-
----
-
-## 5. Resumo dos Elementos a Implementar
-
-| ID | Elemento | Prioridade | Complexidade | Impacto |
-|----|----------|-----------|--------------|---------|
-| E1 | EWC (Fisher + penalty) | Alta | Média | Mitiga catastrophic forgetting |
-| E2 | Context Window (sliding + KV cache) | Alta | Alta | Suporte a sequências longas |
-| E3 | RoPE | Média | Baixa | Codificação posicional relativa |
-| E4 | CausalSelfAttention + TransformerBlock | Alta | Média | Decoder autoregressivo |
-| E5 | Self-Attention final layer correta | Alta | Baixa | Resumo temporal conforme spec |
-| E6 | Gradient Checkpointing | Baixa | Baixa | Reduz VRAM |
-| E7 | Weight Tying | Baixa | Baixa | Reduz parâmetros |
-| E8 | AMP em CPU (bfloat16) | Média | Baixa | Speedup em Xeon |
-| E9 | Online EWC | Baixa | Baixa | Suporte a múltiplas tarefas |
-| E10 | Verificador real no trainer | Alta | Média | Funcionalidade core |
-| E11 | Hipótese com porta funcional | Alta | Baixa | Funcionalidade core |
-| E12 | Geração autoregressiva real | Alta | Alta | Inferência correta |
-| E13 | Multi-loss device-safe | Alta | Baixa | Correção de bug |
-| E14 | Orthogonal init robusto | Média | Baixa | Estabilidade |
-| E15 | `__init__.py` com exports | Baixa | Baixa | Usabilidade |
-
----
-
-## 6. Plano de Implementação
-
-### Fase 1 — Novos Módulos
-1. `cnn_bigru/utils/ewc.py` — EWC completo (offline + online)
-2. `cnn_bigru/models/context_window.py` — Context window com KV cache
-3. `cnn_bigru/models/rope.py` — RoPE
-4. `cnn_bigru/models/transformer_block.py` — CausalSelfAttention + TransformerBlock
-
-### Fase 2 — Correções de Bugs Críticos
-5. `cnn_bigru/models/cooperative_bigru.py` — Self-Attention final correta
-6. `cnn_bigru/models/multimodal_model.py` — Fix dimensão d_text + weight tying
-7. `cnn_bigru/training/hypothesis_controller.py` — Fix gate logic
-8. `cnn_bigru/models/generator_verifier.py` — Fix enc_out repetition
-9. `cnn_bigru/training/trainer.py` — Integrar verificador + hipótese + EWC + context window
-10. `cnn_bigru/losses/losses.py` — Device-safe + EWC term
-11. `cnn_bigru/training/auto_learner.py` — Buffer registration + l2_reg + try/finally
-12. `cnn_bigru/inference/inference.py` — Geração autoregressiva real
-13. `cnn_bigru/data/streaming_dataset.py` — Synthetic fallback reachability
-14. `cnn_bigru/utils/semantic_embeddings.py` — Integrar no pipeline
-
-### Fase 3 — Embalagem
-15. `cnn_bigru/__init__.py` — Exports + versão
-16. `cnn_bigru/scripts/push_to_hf.py` — `upload_folder` + filtro robusto
-
-### Fase 4 — Validação
-17. `cnn_bigru/tests/test_50_samples.py` — Testar todos os novos módulos
-18. Executar teste, capturar erros, iterar
-
-### Fase 5 — Publicação
-19. Push para HF `CNN-BiGRU` (overwrite outdated)
-20. Deletar `HF_TOKEN` do ambiente
-
----
-
-## 7. Referências
-
-- Kirkpatrick, J. et al. **"Overcoming catastrophic forgetting in neural networks"**. PNAS 2017.
-- Xiao, G. et al. **"Efficient Streaming Language Models with Attention Sinks"**. 2023.
-- Su, J. et al. **"RoFormer: Enhanced Transformer with Rotary Position Embedding"**. 2021.
-- Vaswani, A. et al. **"Attention Is All You Need"**. NeurIPS 2017.
-- `dados.txt` — pseudocódigo completo do projeto CNN-BiGRU cooperativo.
-
----
-
-**Fim do documento.**
-
----
-
-# Análise Matemática v3.0 — Novos Módulos
-
-**Data:** 2026-08-11  
-**Versão:** 3.0 (aprimoramento com 9 novos módulos)
-
----
-
-## 8. Raciocínio Cíclico (Cyclic Reasoning)
-
-### 8.1. Fundamentação
-
-O Raciocínio Cíclico refina iterativamente a representação $h \in \mathbb{R}^d$
-através de múltiplos ciclos, cada um combinando o estado atual com uma
-hipótese gerada por um controlador externo:
-
-$$
-h_0 \xrightarrow{\text{cycle 1}} h_1 \xrightarrow{\text{cycle 2}} h_2 \xrightarrow{\text{cycle 3}} \dots \xrightarrow{\text{cycle } C} h_C
-$$
-
-Em cada ciclo $c$:
-
-$$
-\begin{aligned}
-g_c &= \text{HypothesisController}(h_{c-1}, \text{penalty}_c) \in \mathbb{R}^d \\
-r_c &= \text{RefinementLayer}([h_{c-1}; g_c]) \in \mathbb{R}^d \\
-\alpha_c &= \sigma(w_\alpha^\top h_{c-1} + b_\alpha) \in [0, 1] \\
-h_c &= \text{LayerNorm}(h_{c-1} + \alpha_c \cdot r_c)
-\end{aligned}
-$$
-
-### 8.2. Critério de Convergência
-
-O loop para quando $\|h_c - h_{c-1}\|_2 < \epsilon$ ou $c = C_{\max}$.
-
-### 8.3. Garantias Matemáticas
-
-1. **Diferenciabilidade**: todas as operações são diferenciáveis. Suporte a
-   truncated BPTT (Backpropagation Through Time) com $K$ ciclos preservados
-   no grafo.
-2. **Contração**: se o refinement for Lipschitz com $L < 1$, a sequência
-   $\{h_c\}$ é de Cauchy e converge.
-3. **Anti-hallucination gate**: valor de verdade fuzzy $\tau_c \in [0, 1]$
-   baseado em lógica de Łukasiewicz. Se $\tau_c < \tau_{\min}$, o ciclo é
-   rejeitado (h permanece).
-
----
-
-## 9. NLG (Natural Language Generation) com Medusa MTP
-
-### 9.1. Arquitetura
-
-O módulo NLG combina:
-- **TransformerDecoderStack** (backbone causal com RoPE)
-- **MedusaMTP** (Multi-Token Prediction com $K$ cabeças extras)
-- **CyclicReasoning** (opcional, refinamento iterativo)
-- **ContextWindowManager** (janela deslizante com cache KV)
-
-### 9.2. Loss de Treinamento
-
-$$
-\mathcal{L}_{\text{NLG}} = \mathcal{L}_{\text{CE}}(\text{lm\_head}(h_t), y_{t+1}) + \mu_{\text{medusa}} \cdot \mathcal{L}_{\text{Medusa}} + \mu_{\text{ewc}} \cdot \mathcal{L}_{\text{EWC}}
-$$
-
-onde:
-
-$$
-\mathcal{L}_{\text{Medusa}} = \sum_{k=1}^{K} \lambda_k \cdot \text{CE}(\text{head}_k(h_t), y_{t+k+1})
-$$
-
-com pesos decrescentes $\lambda_k = \frac{1}{k+1}$.
-
----
-
-## 10. NLP (Natural Language Processing)
-
-### 10.1. Tarefas Suportadas
-
-1. **Sequence Classification**: $\text{logits} = \text{Linear}(D, C) \cdot \text{Pool}(\text{seq})$
-2. **Token Classification**: $\text{logits}_{t} = \text{Linear}(D, L) \cdot h_t$ para cada posição $t$
-3. **Span Detection**: $(\text{start\_logits}, \text{end\_logits}) = \text{Linear}(D, 1) \cdot h_t$
-4. **Embedding (retrieval)**: $\text{emb} = \text{normalize}_{L^2}(\text{mean\_pool}(h))$
-
-### 10.2. Loss InfoNCE para Retrieval
-
-$$
-\mathcal{L}_{\text{InfoNCE}} = -\log \frac{\exp(\text{sim}(q, p^+) / \tau)}{\exp(\text{sim}(q, p^+) / \tau) + \exp(\text{sim}(q, p^-) / \tau)}
-$$
-
-onde $\text{sim}(u, v) = \cos(u, v)$ (similaridade cosseno após normalização $L^2$).
-
----
-
-## 11. W8A8 Quantization via SmoothQuant
-
-### 11.1. Problema dos Outliers em Ativações
-
-Em modelos LLM, alguns canais de ativação têm outliers que saturam a
-quantização INT8 direta. A solução SmoothQuant (Xiao et al., 2023) migra
-a variância das ativações para os pesos.
-
-### 11.2. Fórmula Matemática
-
-Seja $Y = X \cdot W$ onde $X \in \mathbb{R}^{B \times T \times d_{\text{in}}}$,
-$W \in \mathbb{R}^{d_{\text{in}} \times d_{\text{out}}}$.
-
-Para cada canal de entrada $i$, computa-se a escala de suavização:
-
-$$
-s_i = \frac{\max|X_i|^\alpha}{\max|W_i|^{1-\alpha}}, \quad \alpha \in [0, 1]
-$$
-
-com $\alpha = 0.5$ (default, balanceado).
-
-A operação matricial é matematicamente equivalente:
-
-$$
-Y = X \cdot W = \left(\frac{X}{s}\right) \cdot (s \cdot W) = X' \cdot W'
-$$
-
-Após a suavização, ambos $X'$ e $W'$ têm variância uniforme e podem ser
-quantizados a INT8 com perda mínima:
-
-$$
-X_q = \text{round}\left(\frac{X'}{\text{scale}_x}\right) \cdot \text{scale}_x, \quad
-W_q = \text{round}\left(\frac{W'}{\text{scale}_w}\right) \cdot \text{scale}_w
-$$
-
-### 11.3. Redução de Memória
-
-- FP32: 4 bytes/parâmetro
-- INT8: 1 byte/parâmetro
-- **Redução teórica**: 4× (75%)
-- Em hardware com AMX/AVX512-VNNI: speedup de 2-4×
-
----
-
-## 12. VQ-VAE-2 Hierárquico
-
-### 12.1. Arquitetura de Dois Níveis
-
-$$
-x \xrightarrow{\text{BottomEnc}} z_b \xrightarrow{\text{TopEnc}} z_t \xrightarrow{\text{TopQ}} z_t^q \xrightarrow{\text{TopDec}} \hat{z}_t \xrightarrow{+ z_b^q} \xrightarrow{\text{BottomDec}} \hat{x}
-$$
-
-Onde:
-- $z_b \in \mathbb{R}^{B \times d_b \times H \times W}$: representação bottom (detalhes locais)
-- $z_t \in \mathbb{R}^{B \times d_t \times H/2 \times W/2}$: representação top (semântica global)
-
-### 12.2. Loss Total
-
-$$
-\mathcal{L} = \mathcal{L}_{\text{recon}} + \beta \cdot (\mathcal{L}_{\text{commit}}^{\text{top}} + \mathcal{L}_{\text{commit}}^{\text{bottom}}) + \gamma \cdot (\mathcal{L}_{\text{codebook}}^{\text{top}} + \mathcal{L}_{\text{codebook}}^{\text{bottom}})
-$$
-
-onde:
-- $\mathcal{L}_{\text{recon}} = \text{MSE}(x, \hat{x})$
-- $\mathcal{L}_{\text{commit}}^k = \|\text{sg}(z_k) - e_k\|_2^2$ (commit loss)
-- $\mathcal{L}_{\text{codebook}}^k = \|z_k - \text{sg}(e_k)\|_2^2$ (codebook loss)
-- $\text{sg}$ = stop-gradient
-
-### 12.3. Atualização EMA do Codebook
-
-$$
-\begin{aligned}
-n_k^{(t+1)} &= \gamma_{\text{ema}} \cdot n_k^{(t)} + (1 - \gamma_{\text{ema}}) \cdot \sum_i \mathbb{1}[k_i = k] \\
-m_k^{(t+1)} &= \gamma_{\text{ema}} \cdot m_k^{(t)} + (1 - \gamma_{\text{ema}}) \cdot \sum_i z_i \cdot \mathbb{1}[k_i = k] \\
-e_k &= \frac{m_k}{n_k + \epsilon}
-\end{aligned}
-$$
-
-### 12.4. Straight-Through Estimator (STE)
-
-$$
-z_q^{\text{ST}} = z + (z_q - z).\text{detach}()
-$$
-
-Garante que o gradiente flua para $z$ apesar da operação não-diferenciável de quantização.
-
----
-
-## 13. Multi-Token Prediction (MTP) com Medusa Heads
-
-### 13.1. Cabeças Múltiplas
-
-Para cada hidden state $h_t$, o Medusa adiciona $K$ cabeças de previsão:
-
-$$
-y_{t+k} = \text{softmax}(W_k \cdot h_t + b_k), \quad k = 1, \ldots, K
-$$
-
-A cabeça $k=1$ é o LM head original; $k=2, \ldots, K$ são cabeças extras.
-
-### 13.2. Loss Medusa
-
-$$
-\mathcal{L}_{\text{Medusa}} = \sum_{k=1}^{K} \lambda_k \cdot \text{CE}(\text{head}_k(h_t), y_{t+k+1})
-$$
-
-com $\lambda_k = \frac{1}{k+1}$ (pesos decrescentes — previsões mais distantes são mais difíceis).
-
-### 13.3. Tree Decoding em Inferência
-
-Em inferência, cada cabeça Medusa gera top-$B$ candidatos, formando uma
-árvore de $B^K$ filhos. A árvore é avaliada em paralelo (single forward)
-e os candidatos são aceitos se coincidirem com a previsão do modelo.
-
-**Speedup teórico**: até $K\times$ (em prática 2-3× devido à taxa de aceitação < 1).
-
----
-
-## 14. Multimodal Multi-Head Attention
-
-### 14.1. Cross-Modal Attention
-
-Para modalidades $i$ e $j$ ($i \neq j$):
-
-$$
-\begin{aligned}
-Q_i &= H_i \cdot W_Q^i \\
-K_j &= H_j \cdot W_K^j \\
-V_j &= H_j \cdot W_V^j \\
-A_{i \to j} &= \text{softmax}\left(\frac{Q_i \cdot K_j^\top}{\sqrt{d_h}}\right) \cdot V_j
-\end{aligned}
-$$
-
-### 14.2. Atualização da Modalidade
-
-$$
-H_i' = H_i + \sum_{j \neq i} A_{i \to j}
-$$
-
-### 14.3. Modality Gate
-
-$$
-\alpha_i = \text{softmax}\left(\text{scorer}(\tanh(\text{proj}_i(\text{Pool}(H_i))))\right)
-$$
-
-Permite pesar dinamicamente cada modalidade (e.g., imagem é mais importante para pergunta visual).
-
-### 14.4. Fusão Final
-
-$$
-H_{\text{fused}} = \text{Linear}\left([\alpha_a \cdot \bar{H}_a; \alpha_b \cdot \bar{H}_b; \alpha_{\text{img}} \cdot \bar{H}_{\text{img}}; \alpha_{\text{aud}} \cdot \bar{H}_{\text{aud}}]\right)
-$$
-
----
-
-## 15. Long Context Window (1M tokens) — Chunked / Ring Attention
-
-### 15.1. Motivação
-
-Para 1M tokens, o cache KV FP32 requer:
-
-$$
-\text{memória} = n_{\text{layers}} \times d_{\text{model}} \times 10^6 \times 8 \text{ bytes} \approx 12 \text{ GB}
-$$
-
-Isto é inviável em CPU. A solução é **chunked attention**: dividir a
-sequência em chunks de tamanho $C$ (e.g., 8192) e processar cada chunk
-separadamente.
-
-### 15.2. Estratégias
-
-1. **chunked**: cache KV apenas para o chunk atual + sink tokens
-2. **ring**: Ring Attention — distribui chunks entre $N$ GPUs (memória/N)
-3. **sink_sliding_long**: sink + sliding com window grande
-4. **hybrid**: chunked para encoder, sink_sliding para decoder
-
-### 15.3. Sumarização Hierárquica
-
-Para manter contexto global, cada chunk produz um sumário:
-
-$$
-\bar{c}_k = \text{Pool}(\text{Attention}(c_k))
-$$
-
-Os sumários são agregados em um contexto global:
-
-$$
-\bar{C} = \frac{1}{K} \sum_{k=1}^{K} \bar{c}_k
-$$
-
-### 15.4. Memória por Chunk
-
-$$
-\text{memória/chunk} = n_{\text{layers}} \times d_{\text{model}} \times C \times 8 \approx 16 \text{ MB} \quad (C = 8192)
-$$
-
----
-
-## 16. Monitor Completo
-
-### 16.1. Métricas Rastreadas
-
-1. **Treino**: loss, PPL, LR (G/V), grad norm, hypothesis activations, synergy history
-2. **Inferência**: tokens gerados, Medusa accept rate, ms/token, throughput
-3. **Evolução**: CyclicReasoning stats, VQ-VAE-2 codebook usage, quantization stats, EWC penalty evolution
-4. **Sistema**: CPU%, memória (MB), GPU memory (se disponível)
-
-### 16.2. Exportação
-
-- JSON report completo (`monitor_report.json`)
-- CSV time series (`batch_metrics.csv`)
-- Markdown summary (`monitor_summary.md`)
-
----
-
-## 17. Elementos Adicionais Identificados como Faltantes
-
-Após análise completa dos requisitos v3.0, foram identificados os seguintes
-elementos que ainda podem ser adicionados em versões futuras:
-
-| ID | Elemento | Prioridade | Complexidade | Justificativa |
-|----|----------|-----------|--------------|---------------|
-| F1 | Speculative Decoding (diferente do Medusa) | Média | Média | Speedup adicional em inferência |
-| F2 | LoRA / QLoRA fine-tuning | Alta | Média | Treino eficiente em downstream tasks |
-| F3 | DPO / RLHF training | Alta | Alta | Alinhamento com preferências humanas |
-| F4 | Flash Attention 2 | Média | Baixa | Speedup em GPU (não aplicável em CPU) |
-| F5 | MoE (Mixture of Experts) | Baixa | Alta | Escalar capacidade sem aumentar FLOPs |
-| F6 | KV cache quantization (FP8) | Média | Baixa | Reduzir memória do cache KV |
-| F7 | Continuous batching | Alta | Alta | Throughput em serving |
-| F8 | Distributed training (DDP/FSDP) | Alta | Alta | Treino em múltiplas GPUs |
-| F9 | Gradient checkpointing | Alta | Baixa | Reduzir memória de treino |
-| F10 | Tokenizer special tokens expandable | Baixa | Baixa | Suporte a tool calling |
-
----
-
-## 18. Plano de Implementação v3.0
-
-### Fase 1 — Novos Módulos v3.0
-1. `cnn_bigru/models/cyclic_reasoning.py` — Cyclic Reasoning com convergência
-2. `cnn_bigru/models/medusa_heads.py` — Medusa MTP com K cabeças
-3. `cnn_bigru/models/nlg.py` — NLG com Transformer Decoder + Medusa
-4. `cnn_bigru/models/nlp.py` — NLP com 4 tarefas (SeqCls, TokCls, Span, Embed)
-5. `cnn_bigru/models/multimodal_attention.py` — Cross-modal attention + modality gate
-6. `cnn_bigru/utils/quantization.py` — W8A8 SmoothQuant
-7. `cnn_bigru/utils/vqvae2.py` — VQ-VAE-2 hierárquico com EMA
-8. `cnn_bigru/utils/monitoring.py` — Monitor completo
-9. `cnn_bigru/models/context_window.py` — Estendido para 1M tokens (chunked/ring)
-
-### Fase 2 — Correções de Bugs
-10. `cnn_bigru/inference/inference.py` — Fix context_window misuse (mistura de históricos)
-11. `cnn_bigru/models/generator_verifier.py` — Fix Verifier classifier dim (4*gru_hidden -> 8*gru_hidden)
-
-### Fase 3 — Integração
-12. `cnn_bigru/__init__.py` — Exports v3.0
-13. `cnn_bigru/data/streaming_dataset.py` — Priorizar PowerMachine/CNN-BiGRU repo
-
-### Fase 4 — Validação
-14. `cnn_bigru/tests/test_500_samples.py` — Teste 500 amostras (5 batches x 100)
-15. Executar teste, capturar erros, iterar
-
-### Fase 5 — Publicação
-16. Push para HF `CNN-BiGRU` (overwrite outdated)
-17. Deletar `HF_TOKEN` do ambiente e scripts
-18. Deletar estado salvo do modelo (não enviar para lugar algum)
-
----
-
-## 19. Referências v3.0
-
-- Xiao, G. et al. **"SmoothQuant: Accurate and Efficient Post-Training Quantization for Large Language Models"**. 2023.
-- Roy, A. et al. **"Efficient Conditional Variational Autoencoders for Video Prediction"** (VQ-VAE-2). 2019.
-- Cai, T. et al. **"Medusa: Simple LLM Inference Acceleration Framework with Multiple Decoding Heads"**. 2024.
-- van den Oord, A. et al. **"Neural Discrete Representation Learning"** (VQ-VAE). NeurIPS 2017.
-- Liu, H. et al. **"Ring Attention with Blockwise Transformers for Near-Infinite Context"**. 2023.
-
----
-
-**Fim do documento v3.0.**