cnn_bigru/README.md

# CNN-BiGRU — Modelo Multimodal Cooperativo Autoaprendível (v2.0)

Implementação completa de um LLM multimodal com arquitetura **CNN-BiGRU cooperativa**,
inspirada nos projetos de referência:

- `PowerMachine/gru-ring-v13-9-2/xavante_work/`
- `PowerMachine/BiGRU_T_version/src/bigru_t/`
- `dados.txt` (pseudocódigo matemático completo)

O projeto é **diferente** dos anteriores: agrupa todos os componentes multimodais
(texto + imagem + áudio) num único pipeline cooperativo, com divisão por competências.

---

## Novidades v2.0

Esta versão adiciona os **módulos faltantes** identificados na análise matemática
(`docs/MATH_ANALYSIS.md`):

### Novos Módulos

| Módulo | Função | Arquivo |
|--------|--------|---------|
| **EWC** (Elastic Weight Consolidation) | Aprendizado contínuo sem catastrophic forgetting via matriz de Fisher | `utils/ewc.py` |
| **Context Window** | Janela deslizante com cache KV para sequências longas (Sink+Sliding / StreamingLLM) | `models/context_window.py` |
| **RoPE** (Rotary Position Embeddings) | Codificação posicional rotacional (atenção relativa) | `models/rope.py` |
| **TransformerBlock** | CausalSelfAttention + FFN com Pre-LN (decoder-only, estilo GPT) | `models/transformer_block.py` |

### Bug Fixes Críticos

- **`cooperative_bigru.py`**: `SelfAttentionSummary` agora é uma self-attention TRUE
  (CLS-token + multi-head + learned Q/K/V), não mais mean-pool.
- **`hypothesis_controller.py`**: gate logic corrigido — `x_proj` agora é uma projeção
  LINEAR REAL do input (não mais `combined`, o que tornava o gate inefetivo).
- **`generator_verifier.py`**: `enc_out` agora usa a sequência temporal REAL do encoder
  (não mais `fused.unsqueeze(1).expand(...)` que repetia o mesmo vetor).
- **`trainer.py`**: verificador REALMENTE chamado (não proxy); saída da hipótese
  REALMENTE usada (não só flag); EWC integrado à perda total.
- **`losses.py`**: todos os `torch.tensor(0.0)` agora usam `device=` correto.
- **`auto_learner.py`**: `_spec_u` registrado como buffer (migra com `.to(device)`);
  `l2_reg` adicionado ao `AutoLearnConfig`; `estimate_curvature` agora usa `try/finally`.
- **`inference.py`**: geração autoregressiva REAL via GeneratorCNNBiGRU (não single-step).
- **`streaming_dataset.py`**: synthetic fallback agora é ALCANÇÁVEL quando HF falha
  silenciosamente; token HF é limpo após uso.
- **`multimodal_model.py`**: `attn_mask_a`/`attn_mask_b` agora são usados; weight tying opcional.

---

## Características Principais

### 1. Arquitetura Cooperativa de 3 Níveis (do `dados.txt`)

| Nível | Mecanismo | Descrição |
|-------|-----------|-----------|
| 1 | Cross-Attention Global | Ponte de cooperação pós-CNN entre redes A e B, com máscaras de padding |
| 2 | Célula GRU Cooperativa Passo-a-Passo | `CellStepCooperativaComAtenuacao` com porta Gated (alfa ∈ [0,1]) |
| 3 | Self-Attention Final + Fusão | Self-attention TRUE (CLS-token) + concatenação (128+128=256) |

### 2. Multimodal (Texto + Imagem + Áudio)

- **Texto**: Dual-stream CNN-BiGRU cooperativo (streams A e B)
- **Imagem**: `ImageEncoder` (CNN 2D → flatten → projeção)
- **Áudio**: `AudioEncoder` (CNN 1D sobre espectrograma)
- **Fusão**: `MultimodalFusion` com gated fusion por modalidade

### 3. Autoaprendizado (parâmetros matematicamente ajustados)

Conforme `dados.txt` seções 9-10:

- **Ajuste Dinâmico de LR**:
  - `fator_G = exp(-κ * ||grad_G||) * (1 + v_media) / 2`
  - `fator_V = exp(-κ * ||grad_V||) / (1 + L_V_media)`
- **Controle de Gradiente**: clipping L2 + spectral normalization (power iteration, buffer registrado)
- **Inicialização Ortogonal**: matrizes recorrentes e convolucionais (com log de fallback)
- **Estimativa de Curvatura**: aproximação por diferenças finas (com try/finally)

### 4. EWC (Elastic Weight Consolidation) — NOVO v2.0

- **Cálculo da diagonal da Matriz de Fisher** (empirical Fisher)
- **Online EWC**: $F^{\text{agg}} = \gamma F^{\text{prev}} + (1-\gamma) F^{\text{new}}$
- **Penalidade diferenciável**: $L_{\text{EWC}} = \sum_i \frac{\lambda}{2} F_i (\theta_i - \theta_i^*)^2$
- **Integração à perda total**: $L_{\text{total}} = \alpha L_G + \beta L_V + \gamma L_{AH} + \delta L_{\text{reg}} + L_{\text{EWC}}$

### 5. Context Window — NOVO v2.0

- **Cache KV** para CausalSelfAttention (speedup ~T× em inferência)
- **Sliding Window + Sink** (StreamingLLM): mantém $k$ tokens iniciais + últimos $L_{\max}-k$
- **Estratégias**: `sliding`, `sink_sliding` (default), `recompute`
- **Integração com inferência**: `generate_with_sampling(context_window=cw)`

### 6. RoPE (Rotary Position Embeddings) — NOVO v2.0

- Codificação posicional rotacional: $\theta_i = 10000^{-2i/d}$
- Propriedade relacional: $\langle \text{RoPE}(q, m), \text{RoPE}(k, n) \rangle = \langle \text{RoPE}(q, m-n), k \rangle$
- Cache de frequências como buffer (migra com `.to(device)`)
- Extensão dinâmica para sequências longas

### 7. TransformerBlock (Decoder-Only) — NOVO v2.0

- `CausalSelfAttention`: multi-head, máscara triangular inferior, QKV unificada
- `TransformerBlock`: Pre-LN + residual + FFN (Linear → GELU → Linear)
- `TransformerDecoderStack`: N camadas + LayerNorm final + LM head
- **Weight tying** opcional (compartilha embedding ↔ lm_head)
- Suporte a cache KV multicamada para geração autoregressiva

### 8. Mecanismo de Hipóteses (ativado em punições)

Quando o verificador pune um passo (v < threshold), ativa:

- **N hipóteses paralelas** com transforms lineares diferentes
- **Seleção via Gumbel-Softmax** (diferenciável)
- **Porta de ativação** baseada em v — CORRIGIDA v2.0: agora a saída das hipóteses é
  REALMENTE usada (interpolação `gate * combined + (1-gate) * x_proj`)

### 9. Synergy Search (N tentativas de acerto)

No início de cada época, busca N combinações de hiperparâmetros (pesos das perdas)
e seleciona a configuração de menor perda.

### 10. Múltiplas Funções de Perda

Conforme `dados.txt` seção 8:

```
L_total = α * L_G_total + β * L_V + γ * L_AH + δ * L_reg + L_EWC
L_G_total = L_G + λ * L_penal_linear + μ * L_penal_exp
L_penal_linear = Σ (1 - v_t)                              (todos os passos)
L_penal_exp = Σ_{v_t < threshold} exp(γ * (1 - v_t))      (apenas graves)
L_V = BCE(v_t, rotulo_real)
L_AH = Σ (1 - τ_t)                    (anti-alucinação fuzzy)
L_reg = L2 + curvatura
L_EWC = Σ (λ/2) * F * (θ - θ*)²       [NOVO v2.0]
```

### 11. Camada Anti-Alucinação (Lógica Fuzzy de Łukasiewicz)

```python
NOT(x)  = 1 - sigmoid(x)
AND(x,y) = relu(sigmoid(x) + sigmoid(y) - 1)
OR(x,y)  = min(1, sigmoid(x) + sigmoid(y))
IMP(x,y) = min(1, 1 - sigmoid(x) + sigmoid(y))
```

### 12. Inferência Avançada

- Temperatura, Top-K, Top-P (Nucleus Sampling)
- Presence Penalty, Frequency Penalty
- **Geração autoregressiva REAL via GeneratorCNNBiGRU** (v2.0)
- **Cache KV opcional** via ContextWindowManager (v2.0)
- Avaliação de Perplexidade (PPL) com generator real

---

## Estrutura por Competências

```
cnn_bigru/
├── tokenizer/              # Competência: tokenização
│   └── bbpe_tokenizer.py   # BBPE byte-level tokenizer
├── utils/                  # Competência: utilitários
│   ├── xeon_runtime.py     # Ativação Intel Xeon (AVX512+AMX+IPEX)
│   ├── memory_optimizer.py # Otimização de memória (AMP, GC, offload)
│   ├── semantic_embeddings.py  # Embeddings semânticos (Sinkhorn OT + IB)
│   └── ewc.py              # NOVO v2.0: Elastic Weight Consolidation
├── data/                   # Competência: carregamento de dados
│   └── streaming_dataset.py # Dataset streaming multimodal (com fallback)
├── models/                 # Competência: modelos neurais
│   ├── cooperative_bigru.py    # Núcleo CNN-BiGRU cooperativo (self-attn TRUE)
│   ├── multimodal_encoders.py  # Encoders de imagem/áudio + fusão
│   ├── multimodal_model.py     # Modelo multimodal completo (weight tying opc.)
│   ├── generator_verifier.py   # Gerador + Verificador + Anti-alucinação
│   ├── rope.py                 # NOVO v2.0: Rotary Position Embeddings
│   ├── transformer_block.py    # NOVO v2.0: CausalSelfAttention + TransformerBlock
│   └── context_window.py       # NOVO v2.0: Sliding window + KV cache
├── losses/                 # Competência: funções de perda
│   └── losses.py           # Multi-loss + EWC penalty (device-safe)
├── training/               # Competência: treinamento
│   ├── auto_learner.py         # Ajuste dinâmico LR + spectral norm (buffer)
│   ├── hypothesis_controller.py # Hipóteses + synergy search (gate fix)
│   └── trainer.py              # Loop cooperativo + EWC + verificador real
├── inference/              # Competência: inferência
│   └── inference.py        # Sampling + PPL + generator real + context window
├── tests/                  # Competência: testes
│   └── test_50_samples.py  # Teste de 50 amostras (com novos módulos v2.0)
├── scripts/                # Competência: scripts auxiliares
│   └── push_to_hf.py       # Upload ao HF (upload_folder + retry)
├── docs/                   # Competência: documentação
│   └── MATH_ANALYSIS.md    # NOVO v2.0: análise matemática de EWC + Context Window
└── requirements.txt
```

---

## Como Executar

### Requisitos

```bash
pip install torch tokenizers huggingface_hub datasets psutil tqdm numpy
```

### Teste de 50 Amostras (com novos módulos v2.0)

```bash
python -m cnn_bigru.tests.test_50_samples
```

O teste executa:
1. Ativação do runtime Xeon
2. Treino do BBPE tokenizer
3. Criação do dataset streaming (50 amostras)
4. Instanciação dos modelos
5. **Teste isolado dos novos módulos v2.0**:
   - EWC (Fisher, consolidate, penalty)
   - Context Window (cache KV, eviction)
   - RoPE (preservação de norma)
   - TransformerBlock (forward, cache, weight tying)
5'. Treinamento cooperativo com EWC + synergy + hipóteses + auto-learn
6. Inferência com generator + context window
7. Avaliação de perplexidade com generator
8. Relatório de erros lógicos ou falhas

### Resultado Esperado

```
✓ NENHUM ERRO CRÍTICO encontrado
Amostras processadas: 50
Synergy attempts: 3
Hypothesis activations: variável
EWC active: True
Context Window active: True
Used generator for inference: True
STATUS: SUCESSO
```

---

## Análise Matemática

A inclusão de EWC e Context Window foi analisada matematicamente em
[`docs/MATH_ANALYSIS.md`](docs/MATH_ANALYSIS.md), cobrendo:

1. **EWC**: formulação da Fisher Information, integração na perda, garantia de Laplace
2. **Context Window**: complexidade computacional, políticas de evicção (sliding, sink+sliding, recompute)
3. **Demais elementos faltantes**: RoPE, CausalSelfAttention, Self-Attention final, etc.

---

## Referências

- `dados.txt` (arquivo de entrada com pseudocódigo completo)
- `huggingface.co/PowerMachine/gru-ring-v13-9-2/tree/main/xavante_work/`
- `huggingface.co/PowerMachine/BiGRU_T_version/blob/main/src/bigru_t/tokenizer/bbpe_tokenizer.py`
- `huggingface.co/PowerMachine/gru-ring-v13-9-2/blob/main/xavante_work/xavante/utils/semantic_embeddings.py`
- `huggingface.co/PowerMachine/gru-ring-v13-9-2/blob/main/xavante_work/xavante/utils/memory_optimizer.py`
- `huggingface.co/PowerMachine/gru-ring-v13-9-2/tree/main/xavante_work/xavante/training`
- `huggingface.co/PowerMachine/BiGRU_T_version/blob/main/src/bigru_t/utils/xeon_runtime.py`
- `huggingface.co/PowerMachine/gru-ring-v13-9-2/blob/main/xavante_work/flexnet/streaming_datasets_v13_9.py`

---

## Notas de Segurança

- **HF_TOKEN**: usado apenas para push inicial ao repositório. Após o push, o token
  é removido do ambiente e dos scripts. Os scripts publicados não contêm nenhum
  token embutido.
- **Exceções**: todos os módulos usam `try/except` com logging adequado para
  garantir robustez. O treinamento continua mesmo se alguns batches falharem.
- **Curvatura**: `estimate_curvature` agora usa `try/finally` para garantir
  restauração dos parâmetros mesmo em caso de exceção.

---

## Licença

MIT