README.md

---
license: mit
---
# GRU-RING v13.9.2 — PowerMachine

Modelo neural GRU-RING 4-camadas cooperativas (GRU Bidirecional + Transformer)
treinado em datasets PT-BR. 16.36M parâmetros. Quantização W8A8 QOperator
opcional para inferência otimizada.

## Versão atual: v13.9.2-finetune-v3

Treinamento cumulativo em **12 datasets únicos** (350 optimizer steps no total):

| Stage | Dataset | Samples | Opt Steps | Notas |
|-------|---------|---------|-----------|-------|
| 1-8 | 8 datasets base (ultrachat_br, corpus-ptbr-v2, multimodal_175k, GigaVerbo, OpenMathReasoning, MathVision, OpenMathInstruct-2, restore-punctuation) | 100 each | 200 | Treino base v13.9.2 |
| 9 | carolina-c4ai/corpus-carolina | 200 | 50 | Fine-tune Carolina (workaround lxml.iterparse) |
| 10 | orion-research + cnmoro + strak2005 | 600 (200/ds) | 50 | v13.9.2-finetune-v2 |
| 11 | orion-research + cnmoro + strak2005 | 600 (200/ds) | 50 | **v13.9.2-finetune-v3** (format standardization) |

### v3 — Padronização ### Instruction:/### Response:

A versão v3 introduz padronização do formato de texto para os datasets com
estrutura de instrução/resposta:

- **orion-research/translations-en_US-pt_BR**:
  `### Instruction:\nTranslate the following text to Portuguese:\n{EN}\n\n### Response:\n{PT-BR}`
- **cnmoro/Instruct-PTBR-10M**:
  `### Instruction:\n{INSTRUCTION}\n\n### Response:\n{RESPONSE}`
- **strak2005/corpus-ptbr-v1**: mantido como texto puro (corpus sem estrutura
  de instrução — padronização não se aplica).

**Nenhum parâmetro ou elemento de arquitetura foi alterado**. Apenas o pré-
processamento de texto para os dois datasets instruction/response. Os 9
datasets base permanecem com o comportamento legado (concatenação simples).

## Métricas finais

| Versão | Best Loss | Final Loss | Final PPL | PPL Reduction |
|--------|-----------|------------|-----------|---------------|
| v13.9.2 base (8 ds) | 5.91 | 7.38 | 1794.71 | 89.44% |
| v13.9.2-carolina (9 ds) | 6.72 | 7.38 | 1794.71 | 89.44% |
| v13.9.2-finetune-v2 (12 ds) | 5.44 | 6.89 | 973.52 | 94.27% |
| **v13.9.2-finetune-v3 (12 ds + format)** | **6.06** | **6.38** | **588.59** | **96.54%** |

A redução de perplexidade final de 973.52 (v2) → 588.59 (v3) confirma que a
padronização ### Instruction:/### Response: melhora a coerência do modelo
em prompts estruturados.

## Arquitetura (congelada desde v13.9)

- **4 camadas cooperativas**: GRU Bidirecional + Bridge + MHA + 3 SwiGLU FFNs + Confidence Gate
- **Hypothesis Network**: 16 hipóteses com mapeamento de possibilidades
- **Trust Network**: TD-learning trust update com softmax normalization
- **RoPE** (Rotary Position Embeddings)
- **BidirectionalBridge** com constraint Banach (α+β+γ=1 via softmax)
- **Gradient checkpointing** para economia de RAM

## Quantização W8A8 QOperator

| Métrica | Valor |
|---------|-------|
| Camadas quantizadas | 128 |
| Camadas puladas (GRU/emb) | 0 |
| Erro médio | 0.49% |
| Erro máximo | 1.51% |
| Compressão | 1.44× |
| Tamanho fp32 | 62.5 MB |
| Tamanho W8A8 | 74.3 MB |

## Inferência

```python
import torch
from tokenizers import Tokenizer
from flexnet.gru_ring_v13_9 import create_gru_ring_v139

# fp32
model, config = create_gru_ring_v139()
state = torch.load("model_final/pytorch_model.bin", map_location="cpu")
model.load_state_dict(state)
model.eval()

tokenizer = Tokenizer.from_file("model_final/tokenizer/tokenizer.json")

# Geração
input_ids = torch.tensor([tokenizer.encode("O presidente anunciou que").ids])
out = model.generate(input_ids, max_new_tokens=32, top_k=50, repetition_penalty=1.2)
print(tokenizer.decode(out[0].tolist()))
```

## Scripts

- `scripts/train_from_v13_9_2.py` — Fine-tune script (aceita `--datasets`)
- `scripts/streaming_datasets_v13_9.py` — Streaming loaders (9 base + 4 PT-BR)
  - v3: `format_template="instruction_response"` em `_normalize_sample`

## Reproducibilidade

```bash
python scripts/train_from_v13_9_2.py \
  --model-path model_final/pytorch_model.bin \
  --tokenizer-path model_final/tokenizer/tokenizer.json \
  --datasets orion-research/translations-en_US-pt_BR,cnmoro/Instruct-PTBR-10M,strak2005/corpus-ptbr-v1 \
  --max-samples 200 --max-steps 50 --grad-accum 16 --lr 2e-5 --max-seq-len 64
```

---

## v13.9.2-finetune-v4 (2026-07-27)

**4ª passagem de fine-tuning** nos 3 datasets PT-BR, com **2.5× mais amostras**
(1500 vs 600 do v3) e **BUG-V4-1 corrigido** (empty HF_TOKEN causing auth
header failure).

### Mudanças desta versão

- **BUG-V4-1 fix** (train_from_v13_9_2.py): `hf_token = os.environ.get('HF_TOKEN') or None`
  — empty string `""` was being passed to huggingface_hub, causing
  `Illegal header value b'Bearer '`. Public datasets don't need auth.
- **Streaming timeout**: 180s → 600s (justificado por tool limitation para
  carregar 500+ amostras de strak2005 em conexões lentas).
- **NENHUMA mudança** de arquitetura, parâmetros, ou design do modelo.
- **NENHUMA** renomeação de arquivos no HF (congelamento respeitado).

### Treino

| Parâmetro              | v3 (anterior) | v4 (atual)        |
|------------------------|---------------|-------------------|
| Samples por dataset    | 200           | 500               |
| Total de amostras      | 600           | 1500 (2.5×)      |
| Optimizer steps        | 50            | 40                |
| Grad accum             | 16            | 16                |
| Learning rate          | 2e-5          | 1e-5 (mais baixo) |
| Micro-batches totais   | 800           | 640               |
| Tempo                  | 5.3 min       | 4.0 min           |

### Resultados

| Métrica              | v3         | v4 (canonical)   | Δ              |
|----------------------|------------|------------------|----------------|
| Best loss (stage)    | 6.06       | 5.74             | -5.3%          |
| Final loss (stage)   | 6.38       | 6.99 (step 40)   | (instabilidade)|
| Canonical ppl        | 588.59     | 507.81           | **-13.7%**     |
| Canonical source     | final      | step 20 best ckpt| (ver nota)     |
| W8A8 mean error      | 0.49%      | 0.50%            | estável        |
| W8A8 max error       | 1.51%      | 1.53%            | estável        |
| Compression ratio    | 1.44×      | 1.44×            | estável        |

**Nota sobre canonical source**: o script de treino salva o estado FINAL
(step 40), não o BEST. Em v4, o modelo degradou após step 30 (spike de loss
em step 35, provável bad batch no range cnmoro 500-1000). O **canonical
model** enviado ao HF é o **checkpoint do step 20** (loss 6.23, ppl 507.81),
que é melhor que o v3 final (ppl 588.59) em 13.7%.

### Acumulado (4 passagens)

- **15 stages** totais no training_report_v13_9_2.json
- **390 optimizer steps** acumulados (300 anteriores + 40 v4 + 50 v3 = 390)

  * 9 datasets v13.9.2 base (200 opt steps)
  * + carolina finetune (50 opt steps)
  * + 3 PT-BR datasets finetune-v2 (50 opt steps)
  * + 3 PT-BR datasets finetune-v3 (50 opt steps, com format standardization)
  * + 3 PT-BR datasets finetune-v4 (40 opt steps, 2.5× amostras, BUG-V4-1 fix)

- **Format standardization** `### Instruction:\n...\n### Response:\n...`
  aplicado a orion (tradução EN→PT) e cnmoro (instruções PT-BR).
- strak2005 mantido como texto puro (corpus sem estrutura instruction/response).

### Validação (inferência)

- fp32 load: 0 missing, 0 unexpected ✓
- Forward: 30.8 ms, sem NaN/Inf, logits shape (1, 64, 16384) ✓
- Geração 3 prompts PT-BR: 0.61-0.85s, sem collapse ✓
- W8A8 load: 0 missing, 0 unexpected ✓
- W8A8 erro mean 0.065%, max 0.009 (vs fp32) ✓
- Top-1 fp32 vs W8A8: **concordam** (token 17 = '.') ✓