README.md

# BiGRU_T_version — Refatoração formal do GRU-RING v13.9.2

Refatoração matemática do modelo [PowerMachine/gru-ring-v13-9-2](https://huggingface.co/PowerMachine/gru-ring-v13-9-2) 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.

## Lemas

### Lema 1 — Desacoplamento via atenção hierárquica
Seleção dos módulos `u8cell_T` por softmax com temperatura controlada (α). Durante o treino, a temperatura é meta-ajustada e a entropia dos pesos é minimizada indiretamente pela regularização de agudeza, forçando especialização e reduzindo o produto interno dos gradientes (disputa).

**Implementação**: `src/bigru_t/model/module_selector.py` — `ModuleSelector`
- `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()`

### Lema 2 — Gradiente cirúrgico
`apply_gradient_surgery` implementa a projeção ortogonal quando os gradientes da tarefa principal e da hipótese são conflitantes (produto interno negativo). Garante que ambas as perdas possam ser reduzidas sem interferência destrutiva.

**Implementação**: `src/bigru_t/training/gradient_surgery.py`
- `orthogonalize_gradient(g_main, g_hyp)`: projeção vetorial
- `apply_gradient_surgery(model, loss_main, loss_hyp)`: calcula gradientes independentes via `torch.autograd.grad`, aplica projeção e atribui `p.grad = g_main + g_hyp_perp`

### Lema 3 — Cancelamento de ruído de quantização
A hipótese (`hyp_T`) é treinada com a perda sobre `y_final = y_hat + delta`, aprendendo a corrigir o viés e variância introduzidos pela quantização W8A8 (simulada no forward pelas camadas `QuantizedLinear`). `stop_grad_hyp=True` isola o sinal de correção do gradiente principal, e a cirurgia gerencia os parâmetros compartilhados.

**Implementação**: `src/bigru_t/quantization/quantized_linear.py` + `src/bigru_t/model/hyp_t.py`
- `QuantizedLinear(nn.Linear)`: fake quant W8A8 no forward (STE backward)
- `HypT.forward(o, stop_grad=True)`: aplica `o.detach()` quando stop_grad
- Ativação condicional: hipótese só é calculada quando `loss_main > tau`

### Lema 4 — Auto-configuração e suavização
`MetaConfigurator` ajusta temperatura e limiar τ, e penaliza a agudeza da perda (norma do gradiente), empurrando o modelo para mínimos planos onde o ruído de gradiente é menor. A quantidade de módulos ativos é implicitamente controlada pela softmax com temperatura.

**Implementação**: `src/bigru_t/training/meta_configurator.py`
- `log_temperature: nn.Parameter` — `T = exp(log_temperature)` (positivo)
- `log_tau: nn.Parameter` — `τ = exp(log_tau)` (positivo)
- `forward_with_meta(x_val, y_val)`: meta-loss = `L_val + λ_s * ||∇_θ L_val||²`

## Arquitetura

```
x (batch, T, input_dim)
    │
    ├──→ u8cell_T_1  ─→ h_1 ─┐
    ├──→ u8cell_T_2  ─→ h_2 ─┤       Lema 1: alpha = softmax(logits / T)
    ├──→ ...                  ├─→ H = stack([alpha_k * h_k])  → OrqCell
    └──→ u8cell_T_K  ─→ h_K ─┘                │
                                               ↓
                                              o (batch, d_cache)
                                               │
                                ┌──────────────┴──────────────┐
                                ↓                              ↓
                            TrainT(o)                     HypT(o, stop_grad=True)
                                │                              │
                                ↓                              ↓
                            y_hat                           delta
                                │                              │
                                └──────→ y_final = y_hat + delta * use_hyp  ←── Lema 3

Lema 2: gradient_surgery(g_main, g_hyp) → projeção ortogonal
Lema 4: MetaConfigurator ajusta T (temperatura) e τ (limiar de ativação da hipótese)
```

### Componentes
| Componente | Arquivo | Descrição |
|---|---|---|
| `BiGRU4` | `model/bigru4.py` | 4 camadas BiGRU sequenciais |
| `TransformerUnit` | `model/transformer_unit.py` | Self-attention + FFN para 8 representações |
| `u8cell_T` | `model/u8cell_t.py` | 8 BiGRU4 paralelas + TransformerUnit |
| `OrqCell` | `model/orq_cell.py` | Cache aprendível + cross-attention |
| `TrainT` | `model/train_t.py` | Cabeça de predição principal |
| `HypT` | `model/hyp_t.py` | Cabeça de hipótese (correção delta) |
| `ModuleSelector` | `model/module_selector.py` | Lema 1: softmax + entropia |
| `UnifiedModel` | `model/unified_model.py` | Orquestra todos os componentes |
| `QuantizedLinear` | `quantization/quantized_linear.py` | Lema 3: W8A8 fake quant |
| `apply_gradient_surgery` | `training/gradient_surgery.py` | Lema 2: projeção ortogonal |
| `MetaConfigurator` | `training/meta_configurator.py` | Lema 4: auto-configuração |
| `KillSwitch` | `training/kill_switch.py` | Monitor RAM/disk/loss + kill automático |
| `BiGRU_T_Trainer` | `training/trainer.py` | Loop de treino (2 épocas) |

## Reaproveitamento do source (PowerMachine/gru-ring-v13-9-2)

| Componente | Source | Target |
|---|---|---|
| BBPE Tokenizer | `flexnet/bbpe_tokenizer.py` | `tokenizer/bbpe_tokenizer.py` |
| Streaming datasets (9 base + 3 PT-BR) | `scripts/streaming_datasets_v13_9.py` | `data/streaming_datasets.py` |
| W8A8 QOperator (inferência) | `flexnet/w8a8_qoperator.py` | `quantization/w8a8_qoperator.py` |
| Hardware detector | `flexnet/hardware_detector.py` | `utils/hardware_detector.py` |
| Xeon runtime | `flexnet/xeon_runtime.py` | `utils/xeon_runtime.py` |
| OOM guard | `flexnet/oom_guard.py` | `utils/oom_guard.py` |
| Memory monitor | `flexnet/memory_monitor.py` | `utils/memory_monitor.py` |
| Tensor ops | `xavante/utils/tensor_ops.py` | `utils/tensor_ops.py` |
| Validators | `xavante/utils/validators.py` | `utils/validators.py` |
| Logging utils | `xavante/utils/logging_utils.py` | `utils/logging_utils.py` |
| Hamiltonian-Wasserstein optimizer | `flexnet/hamiltonian_wasserstein_optimizer.py` | `optim/hamiltonian_wasserstein.py` |
| Multimodal: text/image/audio/video encoders | `xavante/multimodal/*` | `multimodal/*` |

## Datasets (12, PT-BR)

**9 base (v13.9.2)**:
1. `CEIA-POSITIVO/ultrachat_br_clustred_balanced_v1`
2. `Madras1/corpus-ptbr-v2`
3. `rhaymison/multmodal_175k_portuguese`
4. `TucanoBR/GigaVerbo`
5. `nvidia/OpenMathReasoning`
6. `MathLLMs/MathVision`
7. `nvidia/OpenMathInstruct-2`
8. `dominguesm/restore-punctuation-ptbr-dataset`
9. `carolina-c4ai/corpus-carolina`

**3 PT-BR finetune**:
10. `orion-research/translations-en_US-pt_BR` (format: `### Instruction:/### Response:`)
11. `cnmoro/Instruct-PTBR-10M` (format: `### Instruction:/### Response:`)
12. `strak2005/corpus-ptbr-v1` (plain text)

## Instalação

```bash
cd BiGRU_T_version
pip install -r requirements.txt
pip install -e .
```

## Uso — Treino de bug-detection (2 épocas)

```bash
export HF_TOKEN="hf_xxx"  # para datasets públicos, opcional
python scripts/train.py \
    --datasets CEIA-POSITIVO/ultrachat_br_clustred_balanced_v1,Madras1/corpus-ptbr-v2 \
    --max-samples 30 \
    --epochs 2 \
    --output-dir model_final
```

## Uso — Inferência

```python
import torch
from bigru_t import create_unified_model
from tokenizers import Tokenizer

model, config = create_unified_model()
state = torch.load("model_final/pytorch_model.bin", map_location="cpu")
model.load_state_dict(state, strict=False)
model.eval()

tokenizer = Tokenizer.from_file("model_final/tokenizer/tokenizer.json")
input_ids = torch.tensor([tokenizer.encode("O presidente anunciou que").ids])
y_hat, delta = model(input_ids, temperature=1.0, use_hypothesis=False)
next_token = y_hat.argmax(dim=-1)
print(tokenizer.decode([next_token.item()]))
```

## Configuração Xeon

O ambiente é automaticamente configurado para Xeon com AVX512/VNNI/AMX:
- `OMP_NUM_THREADS=2`, `MKL_NUM_THREADS=2`
- `torch.set_num_threads(2)`
- `optimize_xeon_environment()` (de `utils/xeon_runtime.py`) chamado no startup

## Estrutura

```
BiGRU_T_version/
├── README.md
├── requirements.txt
├── src/
│   ├── setup.py
│   └── bigru_t/
│       ├── __init__.py
│       ├── model/          # BiGRU4, TransformerUnit, u8cell_T, OrqCell, TrainT, HypT, ModuleSelector, UnifiedModel
│       ├── quantization/   # QuantizedLinear (Lema 3), w8a8_qoperator (reaproveitado)
│       ├── training/       # gradient_surgery (Lema 2), meta_configurator (Lema 4), kill_switch, trainer
│       ├── data/           # streaming_datasets (reaproveitado, 12 datasets)
│       ├── multimodal/     # text/image/audio/video encoders (reaproveitado)
│       ├── optim/          # hamiltonian_wasserstein (reaproveitado)
│       ├── utils/          # hardware_detector, xeon_runtime, oom_guard, memory_monitor, tensor_ops, validators, logging_utils
│       └── tokenizer/      # bbpe_tokenizer (reaproveitado)
├── scripts/
│   ├── train.py            # Treino de bug-detection (2 épocas)
│   ├── smoke_test.py       # Smoke test do pipeline
│   └── upload_to_hf.py     # Upload para HF
├── tests/
│   ├── test_model.py
│   ├── test_gradient_surgery.py
│   ├── test_meta_configurator.py
│   └── test_w8a8.py
├── docs/
│   ├── analysis.md         # Análise matemática dos 4 lemas
│   └── architecture.md
├── configs/
│   └── default.yaml
└── model_final/            # Artefatos treinados
    ├── config.json
    ├── pytorch_model.bin
    └── tokenizer/
```

## Licença

MIT (herdado do source PowerMachine/gru-ring-v13-9-2).