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 / T}}{\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{\langle g_{\text{main}}, g_{\text{hyp}} \rangle}{\|g_{\text{main}}\|^2 + \epsilon} \, g_{\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 é

$$\hat{y} = f_{Q_8(\theta)}(x) = f_\theta(x) + \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}} = \hat{y} + \delta = f_\theta(x) + \eta(x) + h_\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^*) + \lambda_s \cdot S(\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$$

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.