README.md

<p align="center">
  <img src="logo.png" alt="RATIO" width="100">
</p>

<h1 align="center">RATIO — Ratio Decidendi Engine</h1>

<p align="center"><em>ratio decidendi</em> — o raciocínio jurídico por trás das decisões</p>

<p align="center">
  <em>Inteligência jurídica com seus dados sob seu controle.</em><br/>
  <strong>100% local • 100% offline • 100% confidencial</strong>
</p>

<p align="center">
  <a href="#-planos-e-preços">Planos</a> •
  <a href="#-funcionalidades">Funcionalidades</a> •
  <a href="#-instalação">Instalação</a> •
  <a href="#-arquitetura">Arquitetura</a> •
  <a href="#-licenciamento">Licenciamento</a>
</p>

---

> **RATIO** (/ˈrɑː.ti.oʊ/) — do latim *ratio decidendi*, o raciocínio jurídico que fundamenta uma decisão judicial.

O **RATIO** é um sistema de RAG (Retrieval-Augmented Generation) jurídico, **local-first e 100% offline**, projetado para advogados e escritórios de advocacia que demandam máxima confidencialidade no tratamento de seus documentos. O sistema extrai e analisa informações de múltiplos formatos de arquivos, permitindo interações em linguagem natural e rastreando de forma precisa a fundamentação legal de cada resposta diretamente no documento original.

---

## 🚀 v1.0.0 — Lançamento Oficial (Agosto 2026)

| Componente | Status | URL |
|------------|:------:|-----|
| **Software Desktop** | ✅ | `RATIO_Setup_v1.0.exe` |
| **License Server** | ✅ | `api.singularislabs.com.br` |
| **Landing Page** | ✅ | `ratio.singularislabs.com.br` |
| **Hotmart (4 planos)** | ✅ | `pay.hotmart.com/*` |
| **Email** | ✅ | `contato@singularislabs.com.br` |
| **Google Search Console** | ✅ | Verificado |
| **Google Analytics 4** | ✅ | `G-K7TG5J8G7L` |
| **Google Business Profile** | ✅ | Singularis Labs |
| **HuggingFace** | ✅ | 3 modelos publicados |
| **SEO (7 páginas)** | ✅ | Pillar pages + comparativos |
| **INPI Registro** | ⏳ | GRU paga, aguardando e-CNPJ |

### 📊 Métricas de Produção

| Métrica | Valor |
|---------|:-----:|
| **Testes automatizados** | 622 (441 core + 180 license-server + 1 landing) |
| **Bugs críticos** | 0 |
| **Camadas de segurança** | 13 |
| **Páginas SEO indexáveis** | 7 |
| **Modelos HuggingFace** | 3 (BERT + LoRA + GGUF) |

---

## 🤖 IA Treinada — Classificador de Ratio Decidendi

| | |
|---|---|
| **Modelo** | [`CyberPaul/ratio-bert-jurisprudencia-pt`](https://huggingface.co/CyberPaul/ratio-bert-jurisprudencia-pt) |
| **Base** | BERTimbau (`neuralmind/bert-base-portuguese-cased`) |
| **Tarefa** | Classificação binária: a sentença é *ratio decidendi* ou não? |
| **Dados** | 20.266 sentenças balanceadas de 634.368 acórdãos do STJ e STF |
| **F1-Score** | **99,55%** (em sentenças) — estimativa de 93–97% em documentos inéditos |
| **Licença** | Apache 2.0 |

### 🛡️ Filtro de qualidade no pipeline

O classificador é integrado como **guardião de qualidade** da extração (`processors/bert_ratio_filter.py`). Cada sentença extraída é validada — cabeçalhos, relatórios, votações e dados processuais são removidos. Roda em lotes de 32 com detecção automática de device (DirectML → CUDA → CPU).

---

## 🧠 Fine-Tune Generativo — RATIO v8.2 + Gate

| | |
|---|---|
| **Base** | `unsloth/gemma-3-4b-it-bnb-4bit` (QLoRA 4-bit) |
| **Dataset** | 1.259 exemplos (700 RAG + 200 abstenção + 249 adversariais) |
| **LoRA** | [`CyberPaul/ratio-gemma3-4b-lora-v8`](https://huggingface.co/CyberPaul/ratio-gemma3-4b-lora-v8) (277 MB) |
| **GGUF** | [`CyberPaul/ratio-gemma3-4b-gguf-v8`](https://huggingface.co/CyberPaul/ratio-gemma3-4b-gguf-v8) (Q4_K_M 2.49 GB) |
| **Gate arquitetural** | `scripts/gate_rag.py` — intercepta armadilhas antes do LLM |

### 📊 Protocolo de Avaliação

| Métrica | v8.2 + Gate | Threshold | Status |
|---------|:-----------:|:---------:|:------:|
| Faithfulness | **0.983** | ≥ 0.85 | ✅ |
| Citation Accuracy | **0.997** | ≥ 0.90 | ✅ |
| Unsupported Claims | **0.058** | ≤ 0.10 | ✅ |
| Hallucination Rate | **0.000** | ≤ 0.10 | ✅ |
| Utility Score | **0.940** | ≥ 0.70 | ✅ |

> **Gate: ✅ APROVADO PARA PRODUÇÃO** — Suite A (100/100) + Suite B (50/50) + Smoke Test (10/10)

### Deploy no Ollama

```bash
python scripts/deploy_gguf_ollama.py
ollama list | grep ratio-gemma3
```

---

## 🌐 Landing Page Comercial

A landing page está online em **[ratio.singularislabs.com.br](https://ratio.singularislabs.com.br/)**. Código-fonte em `landing-page/RATIOlanding2/`.

- **Verificador de Compatibilidade de Hardware** — sliders de RAM/VRAM + seletor de SO
- **Showcase da IA treinada** — métricas reais (99,55% F1)
- **Planos, FAQ e Trial** — tudo pronto para conversão
- **SEO otimizado** — meta tags, Open Graph e conteúdo semântico

### 🧪 Testes da landing page (Vitest)

A landing page possui **36 testes automatizados** com cobertura de **~91%**.

```bash
cd landing-page/RATIOlanding2
npm test
```

---

## 🎯 Planos e Preços

| Recurso | 🌱 TRIAL | ⚡ SOLO | 🏢 ESCRITÓRIO | 🏛️ ENTERPRISE |
|---------|:--------:|:------:|:------------:|:-------------:|
| **Preço** | **Grátis** | **R$ 197/mês** ou **R$ 1.970/ano** | **R$ 497/mês** ou **R$ 4.970/ano** | **Sob consulta** |
| **Duração** | 14 dias | Mensal/Anual | Mensal/Anual | Perpétuo |
| **Usuários** | 1 | 1 | Até 5 | Ilimitado |
| **Bases** | Até 3 | Ilimitadas | Ilimitadas | Ilimitadas |
| **RAG completo** | ✅ | ✅ | ✅ | ✅ |
| **Exportar PDF** | ✅ | ✅ | ✅ | ✅ |
| **OCR em imagens** | ✅ | ✅ | ✅ | ✅ |
| **Suporte prioritário** | — | ✅ | ✅ | ✅ |
| **Multi-usuário** | — | — | ✅ | ✅ |
| **API access** | — | — | — | ✅ |
| **Suporte dedicado** | — | — | — | ✅ |

### 🎁 Trial Grátis

Na primeira execução, o RATIO cria automaticamente uma licença **TRIAL de 14 dias** com todas as funcionalidades básicas. Sem necessidade de cartão de crédito.

---

## ✨ Funcionalidades

### 🔒 Privacidade Primeiro
- **100% offline** — Seus documentos nunca saem do seu computador
- **Sem APIs de terceiros** — Todo processamento é local via Ollama
- **LGPD compliant** — Arquitetura desenhada para conformidade desde a fundação
- **Hardware binding** — Licença vinculada à máquina, sem risco de uso não autorizado

### 🧠 RAG Jurídico Inteligente
- **Busca Híbrida** — Busca semântica vetorial + BM25 para precisão máxima
- **Chunking Semântico Jurídico** — Divisão por Artigos, Parágrafos, Incisos e Cláusulas
- **Streaming Token a Token** — Respostas em tempo real via WebSocket
- **Citação de Fontes** — Referência exata ao documento e página
- **Filtro BERT** — IA própria que valida cada sentença extraída (99,55% F1)

### 📄 Ingestão Multi-Formato
- **PDF** (texto nativo + OCR para escaneados)
- **DOCX, XLSX, PPTX** (Word, Excel, PowerPoint)
- **Imagens** (PNG, JPG — OCR automático)
- **URLs e YouTube** (web scraping e transcrição automática)
- **Google Drive** (importação via OAuth2)
- **OneDrive** (importação via OAuth2)

### 🖥️ Interface Premium
- **Onboarding interativo** — Wizard de 5 passos na primeira execução
- **Visualizador de PDF** com highlight automático da página citada
- **Chat com streaming** e cards de fonte clicáveis
- **Exportação de consultas em PDF**
- **Tema dark/light** — Alternável com um clique

---

## 🏗️ Arquitetura

```text
Projeto RATIO/
├── core/                    # Núcleo (auth, license, chunker, rag_engine, retriever)
├── engine/                  # Motor de inferência (llm_client, modelo_installer, exportador)
├── processors/              # Processadores (bert_ratio_filter, ratio_extractor)
├── scripts/                 # Pipeline de dados, treino e publicação
├── frontend/                # Interface React + TypeScript
├── tests/                   # 622 testes automatizados
├── license-server/          # Central de Licenças (webhook Hotmart, emails, painel)
├── landing-page/            # Landing page comercial (React + Vite)
├── installer/               # Instalador Windows (Inno Setup 6.3+)
├── api.py                   # Ponto de entrada FastAPI (HTTP + WebSocket)
├── iniciar.bat              # Execução com 1 clique
└── build_ratio.bat          # Build do instalador
```

---

## 🚀 Instalação

### 🖥️ Compatibilidade

| Sistema Operacional | Status | Método |
|---------------------|:------:|--------|
| **Windows 10/11** | ✅ | Instalador (.exe) — `RATIO_Setup_v1.0.exe` |
| **macOS 12+** | ✅ | Script de instalação (bash) |
| **Linux** | ✅ | Script de instalação (bash) |

### 🔧 Setup Automático (Recomendado)

| SO | Comando |
|----|---------|
| **Windows** | `setup_ratio.bat` |
| **macOS** | `chmod +x install_mac.sh && ./install_mac.sh` |
| **Linux** | `chmod +x install_linux.sh && ./install_linux.sh` |

### ⚙️ Setup Manual

#### 1. Pré-requisitos

- **Python 3.10+** — [python.org](https://python.org)
- **Node.js 18+** — [nodejs.org](https://nodejs.org)
- **Ollama** — [ollama.com](https://ollama.com)
- **Tesseract OCR** (opcional, para PDFs escaneados)

#### 2. Configurar Backend

```bash
pip install -r requirements.txt
copy .env.example .env
```

Edite o `.env`:

```ini
RATIO_API_KEY=sua_chave_secreta_aqui
OLLAMA_BASE_URL=http://localhost:11434
RATIO_MODELO=gemma3:4b
RATIO_NUM_CTX=4096
RATIO_HOST=127.0.0.1
RATIO_PORT=8000
RATIO_LICENSE_SERVER=https://api.singularislabs.com.br
```

#### 3. Executar

**Método recomendado:** execute `iniciar.bat` — sobe Ollama, backend e frontend automaticamente.

**Modo manual:**

```bash
make run-api      # Terminal 1 — Backend (porta 8000)
make run-frontend  # Terminal 2 — Frontend (porta 5173)
```

Acesse: **http://localhost:5173** 🎉

---

## 🔐 Licenciamento

O RATIO tem licenciamento local (trial, ativação, hardware binding) com validação
opcional contra a **Central de Licenças** (`api.singularislabs.com.br`).

### Como funciona

1. **Primeira execução** → Trial de 14 dias criado automaticamente
2. **Compra (Hotmart)** → webhook cria a licença e a chave é enviada por email
3. **Ativação** → inserir chave na tela de licenciamento
4. **Validação** → integridade (checksum SHA256), hardware (MAC + username), data de expiração

### Central de Licenças

| Recurso | Detalhe |
|---|---|
| **Webhook Hotmart** | Venda cria licença, cancelamento/reembolso revoga |
| **Emails automáticos** | Chave pro cliente · aviso pro admin · lembretes de renovação |
| **Ativação** | `POST /v1/activate` — valida chave + hardware |
| **Heartbeat** | `POST /v1/check` — vigência/revogação em tempo real |
| **Painel admin** | `/admin` — vendas, receita, vencimentos, cadastro manual |

### Tipos de licença

| Prefixo | Tipo | Duração | Recursos |
|:-------:|------|:-------:|----------|
| `RATIO-TRIAL-...` | TRIAL | 14 dias | Funcionalidades básicas |
| `S...` | SOLO | 365 dias | RAG completo, bases ilimitadas |
| `E...` | ESCRITÓRIO | 365 dias | Multi-usuário, prompts customizados |
| `P...` | ENTERPRISE | **Perpétuo** | API access, suporte dedicado |

---

## 🔒 Segurança e Privacidade

- **LGPD compliant** — Dados nunca saem da máquina do usuário
- **API Key timing-safe** — Comparação em tempo constante (`secrets.compare_digest`)
- **WebSocket autenticado** — Validação de token no handshake
- **Hardware binding** — Licença vinculada ao hardware
- **Grace period 72h** — Cache encriptado para funcionar offline
- **Rate limiting** — 5 tentativas de ativação por hora
- **Gate arquitetural** — Intercepta perguntas que pedem confirmação de processo sem documento
- **Dashboard de segurança** — Monitoramento de tentativas de cracking em tempo real

---

## 🧪 Testes

```bash
# Toda a suíte (622 testes)
pytest tests/ -v

# Suíte completa com 1 clique (Windows)
run_tests.bat

# Testes específicos
pytest tests/test_license.py -v        # 26 testes de licenciamento
pytest tests/test_bert_filter.py -v    # Testes do filtro BERT
pytest tests/test_citation_checker.py -v  # Citation checker
```

---

## 🛠️ Comandos

| Comando | Descrição |
|---------|-----------|
| `setup_ratio.bat` | Configuração completa do ambiente |
| `build_ratio.bat` | Build: frontend + PyInstaller + Inno Setup |
| `iniciar.bat` | Execução com 1 clique (recomendado) |
| `make run-api` | Inicia backend FastAPI (porta 8000) |
| `make run-frontend` | Inicia frontend Vite (porta 5173) |
| `run_tests.bat` | Roda toda a suíte de testes |

---

## 📞 Contato

| Canal | Link |
|-------|------|
| **Site** | [ratio.singularislabs.com.br](https://ratio.singularislabs.com.br) |
| **Email** | [contato@singularislabs.com.br](mailto:contato@singularislabs.com.br) |
| **GitHub** | [Churinti/singularis-labs](https://github.com/Churinti/singularis-labs) (privado) |
| **HuggingFace** | [CyberPaul](https://huggingface.co/CyberPaul) |
| **Hotmart** | [pay.hotmart.com](https://pay.hotmart.com/U107349593U) |

---

## 📜 Licença

O código-fonte do RATIO é proprietário. Os modelos publicados no HuggingFace possuem licenças específicas:

| Modelo | Licença |
|--------|---------|
| `ratio-bert-jurisprudencia-pt` | Apache 2.0 |
| `ratio-gemma3-4b-lora-v8` | Gemma Terms of Use |
| `ratio-gemma3-4b-gguf-v8` | Gemma Terms of Use |
| `ratio-dataset-v8.1` | Apache 2.0 |

---

<p align="center">
  <strong>Singularis Labs</strong> • São Gonçalo, RJ • CNPJ: 68.801.082/0001-07<br/>
  <a href="https://ratio.singularislabs.com.br">ratio.singularislabs.com.br</a>
</p>