Delete src/bigru_t/model/u8cell_t.py

src/bigru_t/model/u8cell_t.py

@@ -1,209 +0,0 @@
-"""u8cell_t.py — u8cell_T: módulo especialista com 8 BiGRU4 + TransformerUnit.
-
-Componente do Lema 1 (Desacoplamento via atenção hierárquica).
-
-Cada u8cell_T é um "módulo especialista" independente. O UnifiedModel
-instanciará até `max_modules` deles e selecionará quais ativar via softmax
-com temperatura controlada (Lema 1).
-
-Reaproveita a arquitetura "4 camadas BiGRU cooperativas" do v13.9.2, mas:
-- Cada BiGRU4 contém 4 camadas (vs. 1 cooperative layer no v13.9.2)
-- 8 BiGRU4 paralelas por u8cell_T (vs. 1 GRU stack no v13.9.2)
-- TransformerUnit funde as 8 saídas (vs. Confidence Gate no v13.9.2)
-- Sem Hypothesis Network interna (a hipótese é global, Lema 3)
-- Sem Trust Network interna (o orquestrador global faz o papel, Lema 4)
-
-V4 — Aprimoramento da detecção de ativação BiGRU:
-  Adiciona `return_aux=True` no forward para retornar métricas de
-  paralelismo real e diversificação de dados entre as 8 BiGRU4:
-    - `bigru_representations`: lista de (batch, d_transformer) — saídas das 8 BiGRU4
-    - `cosine_diversity`: 1 - média(cos_sim entre pares) ∈ [0, 2]
-        Alto (próximo de 1) = módulos produzindo representações diversas
-        Baixo (próximo de 0) = módulos colapsados (mesma saída)
-    - `gate_norm_ratio`: std(||v_i||) / mean(||v_i||) — coef. variação das normas
-        Alto = módulos com magnitudes diferentes (especialização de escala)
-        Baixo = módulos com mesma magnitude (sem diferenciação)
-    - `activation_variance`: variância inter-BiGRU por sample (média sobre batch)
-        Alto = diversificação de conteúdo
-        Baixo = redundância
-    - `parallelism_score`: geom_mean(||v_i||) / mean(||v_i||) — score de paralelismo
-        Próximo de 1 = todas as 8 BiGRU contribuem ativamente
-        Próximo de 0 = apenas algumas dominam
-
-  Essas métricas permitem monitorar se os 8 BiGRUs estão realmente trabalhando
-  em paralelo com dados diversificados (Lema 1) ou se colapsaram.
-"""
-from __future__ import annotations
-
-import torch
-import torch.nn as nn
-import torch.nn.functional as F
-from typing import Optional
-
-from .bigru4 import BiGRU4
-from .transformer_unit import TransformerUnit
-
-
-class u8cell_T(nn.Module):
-    """Módulo com 8 BiGRU4 paralelas + TransformerUnit.
-
-    Args:
-        input_dim: dimensão da entrada
-        hidden_dim_bigru: dimensão oculta de cada GRU nas BiGRU4
-        d_transformer: d_model do TransformerUnit
-        nhead: nº de cabeças de atenção do TransformerUnit
-        d_ff: dimensão interna do FFN do TransformerUnit
-        output_dim: dimensão de saída do u8cell_T
-
-    Forward (default):
-        x: (batch, T, input_dim) → h_out: (batch, output_dim)
-
-    Forward (return_aux=True):
-        → (h_out, aux_dict) onde aux_dict contém métricas BiGRU (V4)
-    """
-
-    def __init__(
-        self,
-        input_dim: int,
-        hidden_dim_bigru: int,
-        d_transformer: int,
-        nhead: int,
-        d_ff: int,
-        output_dim: int,
-        dropout: float = 0.1,
-    ):
-        super().__init__()
-        self.input_dim = input_dim
-        self.output_dim = output_dim
-        self.n_bigru = 8  # Número de BiGRU4 paralelas (constante arquitetural)
-
-        # 8 BiGRU4 paralelas (cada uma com 4 camadas BiGRU)
-        self.bigru_list = nn.ModuleList(
-            [BiGRU4(input_dim, hidden_dim_bigru, dropout=dropout) for _ in range(self.n_bigru)]
-        )
-        bigru_out_dim = 2 * hidden_dim_bigru  # bidirecional
-
-        # Projeção para o d_model do TransformerUnit
-        self.proj_in = nn.Linear(bigru_out_dim, d_transformer)
-
-        # TransformerUnit funde as 8 representações
-        self.transformer_unit = TransformerUnit(d_transformer, nhead, d_ff, dropout=dropout)
-
-        # Projeção final para output_dim
-        self.proj_out = nn.Linear(d_transformer, output_dim)
-
-    def forward(
-        self,
-        x: torch.Tensor,
-        return_aux: bool = False,
-    ) -> torch.Tensor:
-        """x: (batch, T, input_dim) → h_out: (batch, output_dim)
-
-        Se return_aux=True, retorna (h_out, aux_dict) com métricas de
-        paralelismo e diversificação das 8 BiGRU4 (V4).
-        """
-        representations = []  # cada (batch, d_transformer) — saídas projetadas
-        bigru_raw = []        # cada (batch, 2*hidden_dim) — saídas brutas das BiGRU4
-
-        for bigru in self.bigru_list:
-            v_i = bigru(x)                       # (batch, bigru_out_dim)
-            v_i_proj = self.proj_in(v_i)         # (batch, d_transformer)
-            bigru_raw.append(v_i)
-            representations.append(v_i_proj)
-
-        # Empilha as 8 representações: (batch, 8, d_transformer)
-        stacked = torch.stack(representations, dim=1)
-
-        # TransformerUnit → (batch, d_transformer)
-        h_unit = self.transformer_unit(stacked)
-
-        # Projeção final → (batch, output_dim)
-        h_out = self.proj_out(h_unit)
-
-        if not return_aux:
-            return h_out
-
-        # =====================================================================
-        # V4: Métricas de paralelismo e diversificação das 8 BiGRU4
-        # =====================================================================
-        aux = self._compute_bigru_diversity_metrics(representations, bigru_raw)
-        return h_out, aux
-
-    def _compute_bigru_diversity_metrics(
-        self,
-        representations: list[torch.Tensor],
-        bigru_raw: list[torch.Tensor],
-    ) -> dict:
-        """Computa métricas de paralelismo/diversificação das 8 BiGRU4.
-
-        Args:
-            representations: lista de 8 tensores (batch, d_transformer) — saídas projetadas
-            bigru_raw: lista de 8 tensores (batch, 2*hidden_dim) — saídas brutas
-
-        Returns:
-            dict com:
-                - cosine_diversity: 1 - mean(cos_sim entre pares) ∈ [0, 2]
-                - gate_norm_ratio: std(||v_i||) / mean(||v_i||)
-                - activation_variance: variância inter-BiGRU (média sobre batch)
-                - parallelism_score: geom_mean(||v_i||) / mean(||v_i||)
-                - per_bigru_norms: lista de 8 normas L2 (uma por BiGRU4)
-                - bigru_representations: stacked (batch, 8, d_transformer) — para análise externa
-        """
-        # Stack para (8, batch, d_transformer) → (8, batch)
-        norms = torch.stack(
-            [v.norm(p=2, dim=-1) for v in representations], dim=0
-        )  # (8, batch)
-        per_bigru_norms = norms.mean(dim=1)  # (8,) — norma média de cada BiGRU4
-
-        # Stack das representações projetadas: (batch, 8, d_transformer)
-        stacked_reps = torch.stack(representations, dim=1)
-
-        # 1. Cosine diversity: 1 - mean(cos_sim entre pares i<j)
-        # representations[i]: (batch, d_transformer)
-        # cosine sim(i, j) médio sobre batch
-        n = len(representations)
-        cos_sims = []
-        for i in range(n):
-            for j in range(i + 1, n):
-                # (batch,) — cosine sim por sample, depois média sobre batch
-                cs = F.cosine_similarity(
-                    representations[i], representations[j], dim=-1
-                )  # (batch,)
-                cos_sims.append(cs.mean())
-        if cos_sims:
-            mean_cos = torch.stack(cos_sims).mean()
-            cosine_diversity = 1.0 - mean_cos
-        else:
-            cosine_diversity = torch.tensor(0.0, device=representations[0].device)
-
-        # 2. Gate norm ratio: coef. de variação das normas L2 das 8 BiGRU4
-        # Médio sobre batch: usamos per_bigru_norms (já é média sobre batch)
-        mean_norm = per_bigru_norms.mean()
-        std_norm = per_bigru_norms.std()
-        gate_norm_ratio = (std_norm / (mean_norm + 1e-8)).clamp(min=0.0)
-
-        # 3. Activation variance: variância inter-BiGRU por sample, média sobre batch
-        # stacked_raw: (batch, 8, bigru_out_dim)
-        stacked_raw = torch.stack(bigru_raw, dim=1)  # (batch, 8, bigru_out_dim)
-        # variância sobre dim=1 (inter-BiGRU), depois média sobre batch e features
-        activation_variance = stacked_raw.var(dim=1).mean()
-
-        # 4. Parallelism score: geom_mean(||v_i||) / mean(||v_i||) — score ∈ (0, 1]
-        # geom_mean próximo de mean → 1.0 (todas contribuem)
-        # geom_mean muito menor que mean → algumas BiGRUs dominam
-        log_norms = torch.log(per_bigru_norms + 1e-8)
-        log_geom_mean = log_norms.mean()
-        geom_mean = torch.exp(log_geom_mean)
-        parallelism_score = (geom_mean / (mean_norm + 1e-8)).clamp(min=0.0, max=1.0)
-
-        return {
-            "cosine_diversity": float(cosine_diversity.item()),
-            "gate_norm_ratio": float(gate_norm_ratio.item()),
-            "activation_variance": float(activation_variance.item()),
-            "parallelism_score": float(parallelism_score.item()),
-            "per_bigru_norms": [float(x.item()) for x in per_bigru_norms],
-            # V4: NÃO retornar bigru_representations (consome RAM nos K módulos)
-            # A diversidade INTER-módulos é computada no UnifiedModel usando
-            # h_k (saída do u8cell_T), não as representações internas.
-            # "bigru_representations": stacked_reps.detach(),  # comentado para economizar RAM
-        }