docs/analysis.md

Análise Matemática — BiGRU_T_version (Refatoração GRU-RING v13.9.2)

1. Visão geral

A refatoração BiGRU_T_version preserva a filosofia cooperativa do GRU-RING v13.9.2 (4 camadas BiGRU + Transformer + Hypothesis Network + Trust Network), mas reorganiza o cálculo em torno de 4 lemas formais que tornam explícitos os mecanismos de desacoplamento, cirurgia de gradiente, cancelamento de ruído de quantização e auto-configuração.

1.1 Comparação estrutural com v13.9.2

Aspecto	v13.9.2 (original)	BiGRU_T_version (refatorado)
Camadas BiGRU	4 cooperativas (d_model=128)	4 por BiGRU4 × 8 paralelas por u8cell_T
Módulos especialistas	1 (single stack)	até max_modules=64 u8cell_T
Seleção de módulos	implícita (Confidence Gate)	softmax com temperatura α (Lema 1)
Hipótese	16 hipóteses com mapeamento LoRA	HypT: delta correção sobre y_hat (Lema 3)
Trust	TD-learning + softmax norm	τ limiar + MetaConfigurator (Lema 4)
Quantização	W8A8 QOperator (SmoothQuant)	W8A8 fake-quant em Linear (Lema 3)
Interação gradiente main/hyp	Punishment gate	gradient surgery ortogonal (Lema 2)
Multimodalidade	xavante/multimodal/*	mantida (image/audio/video/text encoders)
Otimizador	AdamW	AdamW + HamiltonianWassersteinOptimizer opcional
Tokenizer	BBPE 16K	BBPE 16K (reaproveitado)
Datasets	9 base + 3 PT-BR finetune	mesmos (reaproveitados)

---

2. Lema 1 — Desacoplamento via atenção hierárquica

Enunciado. Seja $\mathcal{M} = {m_1, \ldots, m_K}$ um conjunto de módulos $u8cell_T$ e sejam $\mathbf{z} \in \mathbb{R}^K$ logits de seleção. Define-se

$${\alpha }_k(T)=\frac{e^{z_k\mathrm{/}T}}{\sum _{j=1}^K{e}^{z_j\mathrm{/}T}}\backslash alpha\_k(T)\; =\; \backslash frac\{e^\{z\_k\; /\; T\}\}\{\backslash sum\_\{j=1\}^K\; e^\{z\_j\; /\; T\}\}$$

A saída agregada é $H = \sum_{k=1}^K \alpha_k(T) , h_k$, com $h_k = u8cell_T_k(x)$.

Propriedade (especialização por entropia). A entropia da distribuição $H(\alpha) = -\sum_k \alpha_k \log \alpha_k$ é maximizada em $\log K$ quando $T \to \infty$ (seleção uniforme) e minimizada em $0$ quando $T \to 0^+$ (seleção argmax). Minimizar $H(\alpha)$ indiretamente via regularização $L_{\text{ent}} = \lambda_{\text{ent}} \cdot H(\alpha)$ força especialização: aproximadamente um subconjunto $\mathcal{S} \subset \mathcal{M}$ com $|\mathcal{S}| \ll K$ retém pesos significativos.

Propriedade (redução da disputa de gradiente). Seja $g_k = \nabla_{\theta_k} L$ o gradiente da perda em relação aos parâmetros do módulo $k$. Como $\partial L / \partial \theta_k = \alpha_k \cdot \partial L / \partial h_k \cdot \partial h_k / \partial \theta_k$, quando $\alpha_k \to 0$ o gradiente $|g_k| \to 0$. Logo, módulos inativos não competem por capacidade de gradiente, reduzindo o produto interno $\langle g_i, g_j \rangle$ para $i \neq j$ ativos.

Implementação. Em model/module_selector.py:

• module_logits: nn.Parameter(torch.zeros(K)) — logits aprendíveis
• alpha = F.softmax(module_logits / T, dim=0) no forward
• entropy_reg = -lambda_ent * (alpha * log(alpha + eps)).sum() retornado como aux loss

Meta-ajuste de T. T é tratado como hiperparâmetro aprendível pelo MetaConfigurator (Lema 4) via T = exp(log_temperature).

---

3. Lema 2 — Gradiente cirúrgico

Enunciado. Sejam $L_{\text{main}}(\theta)$ e $L_{\text{hyp}}(\theta)$ duas perdas compartilhando parâmetros $\theta$. Sejam $g_{\text{main}} = \nabla_\theta L_{\text{main}}$ e $g_{\text{hyp}} = \nabla_\theta L_{\text{hyp}}$.

Projeção ortogonal. Quando $\langle g_{\text{main}}, g_{\text{hyp}} \rangle < 0$ (gradientes conflitantes), projeta-se $g_{\text{hyp}}$ no complemento ortogonal de $g_{\text{main}}$:

$$g_{\text{hyp}}^{\perp }=g_{\text{hyp}}-\frac{⟨g_{\text{main}},g_{\text{hyp}}⟩}{\mathrm{\parallel }{g}_{\text{main}}{\mathrm{\parallel }}^2+ϵ}{g}_{\text{main}}g\_\{\backslash text\{hyp\}\}^\{\backslash perp\}\; =\; g\_\{\backslash text\{hyp\}\}\; -\; \backslash frac\{\backslash langle\; g\_\{\backslash text\{main\}\},\; g\_\{\backslash text\{hyp\}\}\; \backslash rangle\}\{\backslash |g\_\{\backslash text\{main\}\}\backslash |^2\; +\; \backslash epsilon\}\; \backslash ,\; g\_\{\backslash text\{main\}\}$$

O gradiente combinado é $g_{\text{total}} = g_{\text{main}} + g_{\text{hyp}}^{\perp}$.

Propriedade (não-interferência). Por construção, $\langle g_{\text{total}}, g_{\text{main}} \rangle = |g_{\text{main}}|^2 + 0 = |g_{\text{main}}|^2 \geq 0$, logo $g_{\text{total}}$ sempre reduz $L_{\text{main}}$. Adicionalmente, $\langle g_{\text{total}}, g_{\text{hyp}} \rangle = \langle g_{\text{main}}, g_{\text{hyp}} \rangle + |g_{\text{hyp}}^{\perp}|^2$. Como $|g_{\text{hyp}}^{\perp}|^2 = |g_{\text{hyp}}|^2 - \frac{\langle g_{\text{main}}, g_{\text{hyp}} \rangle^2}{|g_{\text{main}}|^2}$ e $\langle g_{\text{main}}, g_{\text{hyp}} \rangle < 0$, segue que $\langle g_{\text{total}}, g_{\text{hyp}} \rangle > \langle g_{\text{main}}, g_{\text{hyp}} \rangle$, ou seja, $g_{\text{total}}$ também não piora $L_{\text{hyp}}$ além do que $g_{\text{main}}$ já pioraria.

Quando $\langle g_{\text{main}}, g_{\text{hyp}} \rangle \geq 0$ (gradientes alinhados), não há projeção: $g_{\text{total}} = g_{\text{main}} + g_{\text{hyp}}$.

Implementação. Em training/gradient_surgery.py:

• orthogonalize_gradient(g_main, g_hyp): implementação vetorial da projeção
• apply_gradient_surgery(model, loss_main, loss_hyp): calcula gradientes independentes via torch.autograd.grad (com retain_graph=True para main), aplica projeção e atribui p.grad = g_total

---

4. Lema 3 — Cancelamento de ruído de quantização

Enunciado. Seja $f_\theta: \mathcal{X} \to \mathbb{R}^V$ o modelo principal e $Q_8(\cdot)$ a quantização W8A8 (pesos e ativações em 8 bits). A saída quantizada é

$$\widehat{y}=f_{Q_8(\theta )}(x)=f_{\theta }(x)+\eta (x)\backslash hat\{y\}\; =\; f\_\{Q\_8(\backslash theta)\}(x)\; =\; f\_\backslash theta(x)\; +\; \backslash eta(x)$$

onde $\eta(x)$ é o erro de quantização (viés + variância).

Hipótese corretiva. Define-se uma cabeça de hipótese $h_\phi: \mathbb{R}^d \to \mathbb{R}^V$ que produz uma correção $\delta = h_\phi(o)$ onde $o$ é a representação agregada pelo orquestrador. A predição final é

$$y_{\text{final}}=\widehat{y}+\delta =f_{\theta }(x)+\eta (x)+h_{\varphi }(o)y\_\{\backslash text\{final\}\}\; =\; \backslash hat\{y\}\; +\; \backslash delta\; =\; f\_\backslash theta(x)\; +\; \backslash eta(x)\; +\; h\_\backslash phi(o)$$

Objetivo. Treinar $h_\phi$ para que $h_\phi(o) \approx -\eta(x)$, cancelando o ruído de quantização. A perda é $L_{\text{hyp}} = \ell(y_{\text{final}}, y^*)$ onde $y^*$ é o rótulo verdadeiro.

Isolamento do sinal (stop_grad_hyp). Para evitar que o gradiente de $L_{\text{hyp}}$ contamine os parâmetros principais via $o$, a entrada $o$ de $h_\phi$ é destacada: $\delta = h_\phi(\text{sg}(o))$ onde $\text{sg}$ é stop-gradient. Isso faz $\nabla_\theta L_{\text{hyp}}$ depender apenas dos parâmetros compartilhados via $f_\theta$ (gerenciados pelo Lema 2).

Ativação condicional. A hipótese só é ativada quando $L_{\text{main}} > \tau$, ou seja, quando a perda principal excede um limiar (indicando que a quantização está prejudicando a predição). Caso contrário, $\delta = 0$ e o modelo usa apenas $\hat{y}$.

Implementação. Em model/hyp_t.py e quantization/quantized_linear.py:

• QuantizedLinear(nn.Linear): fake quant W8A8 no forward (STE backward)
• HypT.forward(o, stop_grad=True): aplica o.detach() quando stop_grad
• No UnifiedModel.forward: se use_hypothesis=True e loss_main > tau, calcula y_final = y_hat + delta e retorna ambos

---

5. Lema 4 — Auto-configuração e suavização

Enunciado. Seja $\mathcal{L}_{\text{val}}(T, \tau; \theta)$ a perda de validação como função dos hiperparâmetros temperatura $T$ e limiar $\tau$. O MetaConfigurator mantém $T = \exp(\log T)$ e $\tau = \exp(\log \tau)$ (garantindo positividade) e os otimiza por gradiente descendente em um meta-objetivo:

$${\mathcal{L}}_{\text{meta}}(T,\tau )={\mathcal{L}}_{\text{val}}(T,\tau ;{\theta }^{\ast })+{\lambda }_s\cdot S({\theta }^{\ast })\backslash mathcal\{L\}\_\{\backslash text\{meta\}\}(T,\; \backslash tau)\; =\; \backslash mathcal\{L\}\_\{\backslash text\{val\}\}(T,\; \backslash tau;\; \backslash theta^*)\; +\; \backslash lambda\_s\; \backslash cdot\; S(\backslash theta^*)$$

onde $\theta^* = \theta - \eta \nabla_\theta \mathcal{L}_{\text{train}}(T, \tau; \theta)$ é o parâmetro após um passo de treino (diferenciação implícita), e $S(\theta) = |\nabla_\theta \mathcal{L}|^2$ é uma proxy de agudeza (sharpness) — aproximação de baixo custo para o maior autovalor da Hessiana.

Propriedade (mínimos planos). Minimizar $S(\theta)$ empurra o modelo para regiões de baixa curvatura, onde o ruído de gradiente (devido a mini-batches e quantização W8A8) produz atualizações menores em magnitude, reduzindo variância e melhorando generalização (Keskar et al., 2017; Foret et al., 2021 — SAM).

Controle implícito do número de módulos ativos. Como $T$ controla a entropia de $\alpha$ (Lema 1), minimizar $\mathcal{L}{\text{meta}}$ ajusta $T$ para o regime onde apenas os módulos necessários estão ativos. Não há necessidade de regularização explícita de cardinalidade (embora $L{\text{ent}}$ possa ser adicionada se desejado).

Implementação. Em training/meta_configurator.py:

• log_temperature: nn.Parameter — aprendível, $T = \exp(\log T)$
• log_tau: nn.Parameter — aprendível, $\tau = \exp(\log \tau)$
• forward_with_meta(x_val, y_val):
  1. Forward com $T$ atual → $\mathcal{L}_{\text{val}}$
  2. grads = autograd.grad(L_val, model.parameters(), create_graph=True)
  3. sharpness = sum((g**2).sum() for g in grads)
  4. meta_loss = L_val + lambda_s * sharpness
  5. meta_optim.zero_grad(); meta_loss.backward(); meta_optim.step()
  6. Atualiza model.tau = exp(log_tau).detach()

---

6. Análise de estabilidade e convergência

6.1 Estabilidade do gradiente combinado

Sob os Lemas 1–4, o gradiente efetivo em $\theta$ é

$$g_{\text{eff}}={\alpha }_k(T)\cdot g_{\text{main}}+\mathbb{1}[L_{\text{main}}>\tau ]\cdot g_{\text{hyp}}^{\perp }g\_\{\backslash text\{eff\}\}\; =\; \backslash alpha\_k(T)\; \backslash cdot\; g\_\{\backslash text\{main\}\}\; +\; \backslash mathbb\{1\}[L\_\{\backslash text\{main\}\}\; >\; \backslash tau]\; \backslash cdot\; g\_\{\backslash text\{hyp\}\}^\backslash perp$$

Sob assumir (i) gradientes com norma limitada $|g| \leq G$, (ii) $\alpha_k \in [0,1]$ com $\sum \alpha_k = 1$, (iii) projeção ortogonal preserva norma $|g_{\text{hyp}}^\perp| \leq |g_{\text{hyp}}|$, então $|g_{\text{eff}}| \leq G + G = 2G$. Logo, com clipping em $5.0$ (como no script original), o gradiente é estável.

6.2 Convergência do meta-aprendizado

O MetaConfigurator usa Adam com $\eta_{\text{meta}} = 0.01$ em $(\log T, \log \tau)$. Como a meta-perda é diferenciável em $(\log T, \log \tau)$ via create_graph=True, Adam converge para um mínimo local sob condições padrão (Kingma & Ba, 2015). A proxy de agudeza $S(\theta)$ é não-negativa e diferenciável, garantindo que o meta-objetivo é coercivo.

6.3 Não-divergência do modelo principal

Mesmo se $h_\phi$ divergir, $y_{\text{final}} = \hat{y} + \delta$ é limitado pelo fato de que $L_{\text{hyp}}$ penaliza $\delta$ quando $y_{\text{final}}$ se afasta de $y^*$. Adicionalmente, o stop-gradient isola $\delta$ do caminho principal, então $\hat{y}$ permanece estável.

---

7. Mapeamento de reaproveitamento (source → BiGRU_T_version)

Componente	Source path	Target path	Reuso
BBPE Tokenizer	flexnet/bbpe_tokenizer.py	src/bigru_t/tokenizer/bbpe_tokenizer.py	Cópia fiel
Streaming datasets	flexnet/streaming_datasets_v13_9.py + scripts/streaming_datasets_v13_9.py	src/bigru_t/data/streaming_datasets.py	Merge (9 base + 3 PT-BR + format_template)
W8A8 QOperator	flexnet/w8a8_qoperator.py	src/bigru_t/quantization/w8a8_qoperator.py	Cópia + wrapper QuantizedLinear do Lema 3
Hardware detector	flexnet/hardware_detector.py + xavante/core/hardware_detector.py	src/bigru_t/utils/hardware_detector.py	Cópia do flexnet (mais canônico)
Xeon runtime	flexnet/xeon_runtime.py	src/bigru_t/utils/xeon_runtime.py	Cópia fiel
OOM guard	flexnet/oom_guard.py	src/bigru_t/utils/oom_guard.py	Cópia fiel
Memory monitor	flexnet/memory_monitor.py	src/bigru_t/utils/memory_monitor.py	Cópia fiel
Tensor ops	xavante/utils/tensor_ops.py	src/bigru_t/utils/tensor_ops.py	Cópia fiel
Validators	xavante/utils/validators.py	src/bigru_t/utils/validators.py	Cópia fiel
Logging utils	xavante/utils/logging_utils.py	src/bigru_t/utils/logging_utils.py	Cópia fiel
Hamiltonian-Wasserstein optimizer	flexnet/hamiltonian_wasserstein_optimizer.py	src/bigru_t/optim/hamiltonian_wasserstein.py	Cópia (opcional em treino)
Multimodal: text encoder	xavante/multimodal/text_encoder.py	src/bigru_t/multimodal/text_encoder.py	Cópia fiel
Multimodal: image encoder	xavante/multimodal/image_encoder.py	src/bigru_t/multimodal/image_encoder.py	Cópia fiel
Multimodal: audio encoder	xavante/multimodal/audio_encoder.py	src/bigru_t/multimodal/audio_encoder.py	Cópia fiel
Multimodal: video encoder	xavante/multimodal/video_encoder.py	src/bigru_t/multimodal/video_encoder.py	Cópia fiel
Multimodal: modal router	xavante/multimodal/modal_router.py	src/bigru_t/multimodal/modal_router.py	Cópia fiel

Descartados (superseded):

• flexnet/train_v13_9_minimal.py — superseded by flexnet/train_v13_9.py
• xavante/enhanced/enhanced_xavante_v1.py, v2.py — superseded by v3.py
• xavante/training/medusa_trainer.py — superseded by medusa_trainer_bpe.py
• flexnet/hf_dataset_streamer.py — superseded by streaming_datasets_v13_9.py

---

8. Diferenças do treino (bug-detection run)

Parâmetro	v13.9.2 original	BiGRU_T_version (bug-detection)
Epochs	1 (effective, via max_steps)	2 (fixo por especificação)
Datasets	9 base + 3 PT-BR	mesmos
Max samples por dataset	200-500	50 (bug-detection, reduzido)
Max optimizer steps	40-200	30 (2 épocas × ~15 steps/época)
Grad accum	16	8
LR	1e-5 a 2e-5	1e-3 (treino from-scratch, não fine-tune)
Monitor	loss, ppl, conf	loss, ppl, RAM, disk, módulos ativos
Kill-switch	punishment gate	loss não diminui em N steps OU RAM > 90%

---

9. Conclusão

A refatoração BiGRU_T_version formaliza os mecanismos heurísticos do v13.9.2 em 4 lemas matemáticos verificáveis, mantendo a multimodalidade e o stack de otimização original. O treino de bug-detection (2 épocas) valida o pipeline end-to-end sem pretender produzir um modelo competitivo — o objetivo é detectar erros de implementação nos 4 lemas e nos módulos reaproveitados.