BaruqueRodrigues / llm-legislativo

# 🏛️ LLM Legislativo Brasileiro
> **Corpus Oficial em Larga Escala e Pré-treinamento de Modelo de Linguagem Causal (Transformer) Construído 100% do Zero em PyTorch Puro.**
---
## 📌 Visão Geral
O **LLM Legislativo Brasileiro** é um projeto de pesquisa e engenharia de inteligência artificial de ponta a ponta. Seu objetivo é estruturar o acervo histórico oficial do Congresso Nacional brasileiro (Câmara dos Deputados e Senado Federal) em dados abertos auditáveis e treinar um modelo de linguagem causal autônomo, **implementado do zero sem uso de pesos pré-treinados, sem dependência de APIs fechadas e sem caixas-pretas como o Hugging Face Trainer**.
Todo o pipeline foi concebido sob princípios estritos de **ciência aberta**, **reprodutibilidade**, **integridade criptográfica (SHA-256)** e **isolamento causal estrito (zero data leakage entre splits de treino e teste)**.
---
## 🚀 Destaques do Projeto
* 📦 **Volume de Dados Extraordinário:**
 * **+360 GiB** de dados oficiais em arquivos brutos (TARs compactados e documentos primários).
 * **Câmara dos Deputados:** 43 arquivos TARs catalogados (**311,38 GiB**, 856.902 registros internos verificados).
 * **Senado Federal:** 16 lotes documentais (**53,36 GiB**) com processos e diários.
 * **+930.000 documentos e versões substantivas** (Projetos de Lei, PLPs, PECs, emendas, votos, relatórios, pareceres de comissões, substitutivos, redações finais e anais).
* 🌐 **Ecossistema Público no Hugging Face Hub:**
 * Publicação aberta de **5 Datasets Oficiais** cobrindo desde os TARs brutos até as matrizes curadas em formato Apache Parquet.
 * Publicação aberta do **Modelo de Linguagem Causal** em formato `safetensors`, com metadados de treino, tokenizer e código de inferência autônomo.
* 🧠 **Tokenização Própria Byte-Level BPE:**
 * Tokenizer com vocabulário de **8.192 tokens**, treinado **estritamente sobre o split de treino** para evitar contaminação lexical. Round-trip exato UTF-8 garantido.
* ⚙️ **Transformer Decoder Educacional Explícito:**
 * Implementação matemática pura em PyTorch: multi-head causal self-attention, embeddings amarrados (*weight tying*), ativações GELU e projeções explícitas.
 * **Acumulação Exata de Gradientes:** Compensação analítica da perda por alvos válidos ($\sum CE_k / N_{\text{total}}$), neutralizando desvios induzidos por sequências heterogêneas com *padding*.
* ⚡ **Treinamento em Escala em GPU NVIDIA A100 (Google Colab):**
 * **173.209 passos de otimização (updates)** contínuos (~20h04 na GPU A100-SXM4-40GB).
 * **1.246.588.497 tokens vistos** ao longo do pré-treinamento integral.
 * Persistência resiliente com checkpoints criptograficamente auditados no Google Drive.
* 📊 **Avaliação Científica Rigorosa:**
 * Protocolo `byte_nll_v1` padronizado (0,729 nats/byte; 1,052 bits/byte no split de teste independente).
---
## 🗺️ Mapa de Artefatos no Hugging Face Hub
Todos os artefatos gerados pelo projeto estão disponibilizados publicamente para a comunidade de pesquisa:
| Tipo | Repositório no