Upload cnn_bigru/README.md with huggingface_hub

cnn_bigru/README.md

@@ -0,0 +1,178 @@
+# CNN-BiGRU — Modelo Multimodal Cooperativo Autoaprendível
+
+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/`
+
+O projeto é **diferente** dos anteriores: agrupa todos os componentes multimodais
+(texto + imagem + áudio) num único pipeline cooperativo, com divisão por competências.
+
+---
+
+## 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]) que regula o quanto uma rede aceita da outra |
+| 3 | Fusão Final | Concatenação forward+backward de cada rede (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)
+- **Inicialização Ortogonal**: matrizes recorrentes e convolucionais
+- **Estimativa de Curvatura**: aproximação por diferenças finitas
+
+### 4. Mecanismo de Hipóteses (ativado em punições)
+
+Quando o verificador pune um passo (v < THRESHOLD_ERR), ativa:
+
+- **N hipóteses paralelas** com transforms lineares diferentes
+- **Seleção via Gumbel-Softmax** (diferenciável)
+- **Porta de ativação** baseada em v
+
+### 5. 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.
+
+### 6. Múltiplas Funções de Perda
+
+Conforme `dados.txt` seção 8:
+
+```
+L_total = α * L_G_total + β * L_V + γ * L_AH + δ * L_reg
+L_G_total = L_G + λ * L_penal_linear + μ * L_penal_exp
+L_penal_linear = Σ (1 - v_t)
+L_penal_exp = Σ exp(γ * (1 - v_t))   se v_t < threshold
+L_V = BCE(v_t, rotulo_real)
+L_AH = Σ (1 - τ_t)                    (anti-alucinação fuzzy)
+L_reg = L2 + curvatura
+```
+
+### 7. 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))
+```
+
+### 8. Inferência Avançada
+
+- Temperatura, Top-K, Top-P (Nucleus Sampling)
+- Presence Penalty, Frequency Penalty
+- Avaliação de Perplexidade (PPL)
+
+---
+
+## Estrutura por Competências
+
+```
+cnn_bigru/
+├── tokenizer/              # Competência: tokenização
+│   └── bbpe_tokenizer.py   # BBPE byte-level tokenizer
+├── utils/                  # Competência: utilitários de runtime
+│   ├── 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)
+├── data/                   # Competência: carregamento de dados
+│   └── streaming_dataset.py # Dataset streaming multimodal
+├── models/                 # Competência: modelos neurais
+│   ├── cooperative_bigru.py    # Núcleo CNN-BiGRU cooperativo
+│   ├── multimodal_encoders.py  # Encoders de imagem/áudio + fusão
+│   ├── multimodal_model.py     # Modelo multimodal completo
+│   └── generator_verifier.py   # Gerador + Verificador + Anti-alucinação
+├── losses/                 # Competência: funções de perda
+│   └── losses.py           # Multi-loss com penalidades linear+exp
+├── training/               # Competência: treinamento
+│   ├── auto_learner.py         # Ajuste dinâmico LR + spectral norm
+│   ├── hypothesis_controller.py # Hipóteses + synergy search
+│   └── trainer.py              # Loop de treinamento cooperativo
+├── inference/              # Competência: inferência
+│   └── inference.py        # Sampling + PPL
+└── tests/                  # Competência: testes
+    └── test_50_samples.py  # Teste de 50 amostras
+```
+
+---
+
+## Como Executar
+
+### Requisitos
+
+```bash
+pip install torch tokenizers transformers huggingface_hub datasets psutil tqdm
+```
+
+### Teste de 50 Amostras
+
+```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. Treinamento cooperativo com synergy + hipóteses + auto-learn
+6. Inferência com sampling
+7. Avaliação de perplexidade
+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
+STATUS: SUCESSO
+```
+
+---
+
+## 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.
+
+---
+
+## Licença
+
+MIT