docs: atualizar README para v8.1 + Gate (modelo oficial)

README.md

@@ -0,0 +1,280 @@
+---
+language:
+  - pt
+tags:
+  - legal
+  - portuguese
+  - juridico
+  - ratio
+  - gemma
+  - fine-tuning
+  - rag
+  - grounding
+task_categories:
+  - text-generation
+task_ids:
+  - question-answering
+  - text-classification
+library_name: transformers
+license: apache-2.0
+base_model: unsloth/gemma-3-4b-it-bnb-4bit
+---
+
+# ⚖️ RATIO v8.1 — Ratio Decidendi Engine
+
+<p align="center">
+  <strong>IA jurídica que <em>não</em> alucina — com gate arquitetural.</strong><br/>
+  100% local · 100% offline · 100% confidencial
+</p>
+
+<p align="center">
+  <a href="https://huggingface.co/CyberPaul/ratio-gemma3-4b-gguf-v8">GGUF</a> •
+  <a href="https://huggingface.co/CyberPaul/ratio-gemma3-4b-lora-v8">LoRA</a> •
+  <a href="https://huggingface.co/datasets/CyberPaul/ratio-dataset-v8.1">Dataset</a> •
+  <a href="https://github.com/CyberPaul/Projeto-RATIO">GitHub</a>
+</p>
+
+---
+
+## TL;DR
+
+O **RATIO v8.1** é um LLM de **3.9B params** (Gemma 3 4B) fine-tunado com **QLoRA** para responder perguntas jurídicas com base em documentos fornecidos — e **se abster** quando não tem documento. Combinado com um **gate arquitetural** (regex), atinge **zero alucinação** em cenários adversariais.
+
+| Métrica | v3 (produção) | v8 (LEGACY) | **v8.1 + Gate** | Threshold |
+|---------|:---:|:---:|:---:|:---:|
+| A1 Faithfulness | 0.985 | 0.987 | **0.983** | ≥ 0.85 ✅ |
+| A2 Citation Accuracy | 0.947 | 0.987 | **0.997** | ≥ 0.90 ✅ |
+| A3 Unsupported Claims | 0.091 | 0.071 | **0.058** | ≤ 0.10 ✅ |
+| A4 Tese Extraction | 1.000 | 0.990 | **0.995** | ≥ 0.80 ✅ |
+| A5 Format Compliance | 1.000 | 1.000 | **1.000** | ≥ 0.90 ✅ |
+| B1 Hallucination Rate | 0.020 | 0.000 | **0.000** | ≤ 0.10 ✅ |
+| B3 Utility Score | 0.960 | 0.980 | **0.940** | ≥ 0.70 ✅ |
+| **Smoke Test (adversarial)** | — | 8/10 | **10/10** | 10/10 ✅ |
+
+> **Veredicto: ✅ APROVADO PARA PRODUÇÃO** — Suite A (100/100) + Suite B (50/50) + Smoke Test (10/10 com gate)
+
+---
+
+## 📊 O que mudou vs v8
+
+| Dimensão | v8 | **v8.1** |
+|---|---|---|
+| Dataset | 1.000 exemplos | **1.259 exemplos** (+249 adversariais) |
+| Citation Accuracy | 0.987 | **0.997** (+1.0%) |
+| Alucinação c/ contexto | 0.071 | **0.058** (-18%) |
+| Armadilhas adversariais | 0/4 resolvidas | **4/4 resolvidas** (gate) |
+| Gate arquitetural | não existia | **25/25 FP + 23/23 cobertura** |
+| Utility | 0.980 | 0.940 (-2%, dentro do threshold) |
+
+---
+
+## 🏗️ Arquitetura
+
+```
+Usuário → Gate (regex) → [bloqueado?] → Resposta de abstenção
+                         ↓ [não bloqueado]
+                     LLM (ratio-v8.1)
+                         ↓
+                     garantir_fonte() → Fonte: STJ.
+```
+
+### Camadas de defesa
+
+1. **Dataset grounded** — 700 exemplos forçam leitura do documento
+2. **System prompt anti-alucinação** — condicional (com/sem documento)
+3. **Gate arquitetural** — intercepta armadilhas antes do LLM
+4. **Pós-processamento** — garante `Fonte:` no final de respostas RAG
+
+### Por que gate > retreino para modelos ≤4B
+
+Modelos de 3.9B params com Q4_K_M **sempre preferem gerar tese plausível** quando a pergunta menciona processo ou súmula específico. Isso é comportamento paramétrico do pré-treino — fine-tuning com exemplos adversariais não resolve (testado com 249 exemplos + oversample 3x). O gate resolve na **arquitetura**: determinístico, sem retreino, sem risco de regressão.
+
+---
+
+## 📁 Arquivos neste repo
+
+| Arquivo | Descrição | Tamanho |
+|---|---|---|
+| `ratio-v8.1-Q4_K_M.gguf` | Modelo quantizado (produção) | ~2.49 GB |
+| `gemma-3-4b-it.F16-mmproj.gguf` | Projetor multimodal (F16) | ~0.85 GB |
+
+### How to use
+
+```bash
+# Baixar o GGUF
+huggingface-cli download CyberPaul/ratio-gemma3-4b-gguf-v8 \
+    ratio-v8.1-Q4_K_M.gguf --local-dir .
+
+# Criar no Ollama
+cat > Modelfile << 'EOF'
+FROM ratio-v8.1-Q4_K_M.gguf
+TEMPLATE """{{ .System }}
+
+{{ .Prompt }}"""
+SYSTEM """Você é o RATIO, assistente jurídico especializado em direito brasileiro. Responda com base no documento fornecido."""
+PARAMETER temperature 0.1
+PARAMETER num_predict 400
+EOF
+
+ollama create ratio-v8.1 -f Modelfile
+ollama run ratio-v8.1
+```
+
+```python
+# Via Ollama Python
+import requests
+
+def ratio_v81(pergunta: str, documento: str) -> str:
+    prompt = f"DOCUMENTO:\n{documento}\n\nPERGUNTA:\n{pergunta}"
+    resp = requests.post("http://localhost:11434/api/generate", json={
+        "model": "ratio-v8.1",
+        "prompt": prompt,
+        "stream": False,
+        "options": {"temperature": 0.1, "num_predict": 400}
+    })
+    return resp.json()["response"]
+```
+
+---
+
+## 🧪 Protocolo de Avaliação
+
+### Suite A — RAG-context fidelity (100 exemplos)
+
+Input: pergunta + ementa no prompt + metadados reais (tribunal, processo, turma, data).
+
+| Métrica | O que mede | v8.1 |
+|---|---|:---:|
+| A1 Faithfulness | Afirmações suportadas pelo contexto | **0.983** |
+| A2 Citation Accuracy | Fonte citada bate com metadados reais | **0.997** |
+| A3 Unsupported Claims | Afirmações sem suporte (= alucinação) | **0.058** |
+| A4 Tese Extraction | Tese central capturada | **0.995** |
+| A5 Format Compliance | Template esperado (Fonte: STJ.) | **1.000** |
+
+### Suite B — No-context safety (50 exemplos)
+
+Perguntas SEM documento — detector local de citações inventadas.
+
+| Métrica | O que mede | v8.1 |
+|---|---|:---:|
+| B1 Hallucination Rate | Citação inventada ou "Fonte:" sem doc | **0.000** |
+| B3 Utility Score | Utilidade mesmo abstendo | **0.940** |
+
+### Smoke Test — Adversarial (10 perguntas)
+
+Perguntas que forçam o modelo a inventar processos e súmulas específicos.
+
+| Cenário | v8 s/ gate | v8.1 + gate |
+|---|:---:|:---:|
+| Perguntas RAG (1-5) | ✅ | ✅ |
+| Perguntas gerais (6-8) | ✅ | ✅ |
+| Armadilha processo (9) | ❌ inventou tese | **✅ gate** |
+| Armadilha súmula (10) | ❌ inventou redação | **✅ gate** |
+| **Score** | 8/10 | **10/10** |
+
+### Gate Arquitetural
+
+| Teste | Resultado |
+|---|---|
+| Falsos positivos (25 perguntas legítimas) | **25/25 ✅** |
+| Cobertura (23 variações de armadilha) | **23/23 ✅** |
+| Smoke test + gate (10 perguntas) | **10/10 ✅** |
+
+---
+
+## 📈 Evolução do Pipeline
+
+```
+v3 (produção)  →  v7 (reprovado)  →  v8 (aprovado)  →  v8.1 + Gate (OFICIAL)
+     │                 │                  │                    │
+  ROUGE/BLEU      A2=0.893           A2=0.987            A2=0.997
+  sem grounding   A3=0.151           A3=0.071            A3=0.058
+                  ❌ REPROVADO       ✅ APROVADO         ✅ APROVADO
+                                                    + gate arquitetural
+                                                    + 249 adversariais
+                                                    + zero armadilhas
+```
+
+### Lições aprendidas
+
+1. **Fine-tuning em dados errados só ensina fluência, não grounding** — o v7 provou
+2. **ROUGE/BLEU não medem grounding** — factualidade e suporte são KPIs centrais
+3. **O holdout precisa ser inédito** — split por hash, nunca por linha
+4. **Abstenção é comportamento treinável** — 20% do dataset = exemplos de abstenção
+5. **Gate arquitetural > retreino para modelos ≤4B** — determinístico, sem risco de regressão
+
+---
+
+## 📦 Datasets
+
+| Dataset | Exemplos | Descrição |
+|---|:---:|---|
+| [`CyberPaul/ratio-dataset-v8.1`](https://huggingface.co/datasets/CyberPaul/ratio-dataset-v8.1) | 1.259 | **OFICIAL** — v8 + 249 adversariais + 10 controles |
+| [`CyberPaul/ratio-dataset-v8`](https://huggingface.co/datasets/CyberPaul/ratio-dataset-v8) | 1.000 | LEGACY — dataset original |
+
+### Distribuição do dataset v8.1
+
+```
+rag_ancorado              700  (55.6%)  ← pergunta que exige o documento
+abstencao                 200  (15.9%)  ← sem doc → não inventar
+tese_geral                100  (7.9%)   ← conceitual, sem Fonte:
+adversarial_processo      150  (11.9%)  ← NOVO: abstenção com processo específico
+adversarial_sumula         39  (3.1%)   ← NOVO: abstenção com súmula
+adversarial_detalhe        30  (2.4%)   ← NOVO: placar/relator sem doc
+adversarial_ementa         30  (2.4%)   ← NOVO: transcrição sem doc
+controle_deve_responder    10  (0.8%)   ← NOVO: anti over-refusal
+```
+
+---
+
+## 🔧 Treino
+
+| Parâmetro | Valor |
+|---|---|
+| Base model | `unsloth/gemma-3-4b-it-bnb-4bit` |
+| Método | QLoRA (4-bit) |
+| LoRA rank | r=16, alpha=16 |
+| Épocas | 3 |
+| Learning rate | 2e-4 |
+| MAX_SEQ_LEN | 2048 |
+| Hardware | Kaggle T4 ×2 (14.6 GB cada) |
+| Framework | Unsloth + SFTTrainer |
+
+---
+
+## ⚠️ Limitações Conhecidas
+
+1. **Modelo de 3.9B** — não substitui um modelo grande para raciocínio jurídico complexo
+2. **Q4_K_M quantization** — alguma perda de precisão vs. FP16
+3. **Gate é regex** — adversários criativos podem contornar padrões (coberto nas variações testadas)
+4. **Utility -2% vs v8** — modelo absteve mais vezes (comportamento desejado, mas afeta UX)
+5. **Português brasileiro** — treinado exclusivamente em corpus jurídico PT-BR
+
+---
+
+## 🏢 Projeto
+
+Desenvolvido pela **Singularis Labs** — [singularislabs.com](https://singularislabs.com)
+
+- **Autor**: Paul (Singularis Labs)
+- **Agente de código**: Buffy (Freebuff/Mimo)
+- **Data de aprovação**: 19/08/2026
+- **Licença**: Apache 2.0
+
+> *"Fine-tuning em cima de dados errados só ensina fluência, não grounding.*
+> *O v8.1 resolve isso forçando o modelo a ler antes de responder — e*
+> *interceptando as perguntas que ele não consegue responder com segurança."*
+
+---
+
+## Citation
+
+```bibtex
+@software{ratio_v81,
+  title  = {RATIO: Ratio Decidendi Engine v8.1},
+  author = {Paul (Singularis Labs)},
+  year   = {2026},
+  url    = {https://huggingface.co/CyberPaul/ratio-gemma3-4b-gguf-v8},
+  note   = {Gemma 3 4B fine-tuned with QLoRA + architectural gate for adversarial abstention}
+}
+```