README.md

---
title: Des-abrasileirador pt-PT
emoji: ✍️
colorFrom: green
colorTo: red
sdk: gradio
sdk_version: 6.19.0
app_file: app.py
hardware: zero-a10g
---

# 🇵🇹 Des-abrasileirador (pt-PT)

Reescreve texto em **português europeu** correto com o modelo
[AMALIA-9B](https://hf.co/amalia-llm/AMALIA-9B-0626-SFT) e mede a
"portugalidade" do resultado com um índice determinístico.

## O que faz

1. **Corrigir** — envia o texto ao AMALIA-9B (com *streaming*) e devolve a versão
   em pt-PT, com o IPT antes/depois. Opção de "modo explicado" que lista as
   alterações a partir de JSON, e botão para interromper a geração.
2. **Comparar modelos (IPT)** — corre o mesmo texto por vários modelos e ordena-os
   pelo **Índice de Portugalidade**.
3. **Analisar (IPT)** — mede a portugalidade de qualquer texto instantaneamente
   (determinístico, sem GPU) e lista os marcadores brasileiros encontrados.

## Índice de Portugalidade (IPT)

Métrica determinística, sem GPU, definida em [`portugality.py`](portugality.py):

```
IPT = 100 * exp(-6 * densidade_ponderada_de_marcadores)
```

Conta marcadores brasileiros (léxico, ortografia pré-AO90, gerúndio, tratamento
`você`/`a gente`, próclise inicial), pondera-os e normaliza pelo número de
palavras. `0` marcadores → `100`; muito pt-BR → valor baixo. Como não usa nenhum
LLM como juiz, é auditável e não é circular.

O **delta** de cada modelo é calculado contra a **referência** (por omissão o
`EuroLLM-9B`): mesma base e dimensão do AMALIA mas sem afinação pt-PT, pelo que a
diferença de IPT isola o efeito dessa afinação.

## Ficheiros

| Ficheiro | Papel |
| --- | --- |
| `app.py` | Interface Gradio (correção + comparação) |
| `inference.py` | Registo de modelos e geração (cache de um modelo de cada vez) |
| `portugality.py` | Cálculo do IPT (determinístico) |
| `system_prompt.txt` | Instruções do revisor pt-PT |

## Hardware

Um modelo de 9B **não** corre no Space CPU grátis. Este Space usa **ZeroGPU**
(`@spaces.GPU`, `hardware: zero-a10g`), que requer conta HF PRO. Vários 9B não
cabem em simultâneo num A10G (24 GB), por isso o `inference.py` mantém apenas
**um modelo carregado de cada vez** e a comparação corre-os em série.

O `inference.py` deteta o hardware automaticamente:

| Ambiente | Modo |
| --- | --- |
| GPU com ≥ 20 GB VRAM (A10G/ZeroGPU) | bf16 (fp16 em placas pré-Ampere) |
| GPU com < 20 GB VRAM (ex.: RTX 2060 6 GB) | 4-bit nf4 + *offload* do excedente para RAM |
| Sem CUDA | CPU float32 (apenas modelos pequenos) |

Podes forçar com `LOAD_IN_4BIT=1` ou `LOAD_IN_4BIT=0`.

## Correr localmente (Windows/Linux com GPU NVIDIA)

```bash
python -m venv .venv
.venv\Scripts\activate            # Linux: source .venv/bin/activate
pip install -r requirements.txt
# o torch do PyPI é CPU-only; troca pela build CUDA:
pip install torch --index-url https://download.pytorch.org/whl/cu126
python app.py                     # http://127.0.0.1:7860
```

Numa GPU de 6 GB os modelos de 9B **não cabem** (mesmo em 4-bit precisam de
~6,3 GB só de pesos — a app recusa com uma mensagem clara em vez de rebentar).
Usa o **Qwen2.5-3B** (~2 GB em 4-bit) como modelo de correção local; o
Tucano-2B serve apenas de baseline pt-BR no benchmark.

## Modelos *gated*

`meta-llama/Llama-3.1-8B-Instruct` e `google/gemma-2-9b-it` exigem aceitar a
licença no Hugging Face. Define o segredo `HF_TOKEN` no Space (Settings →
Secrets) para os poderes usar; caso contrário, esses modelos são ignorados na
comparação com um aviso.

## Teste local rápido

```bash
python portugality.py   # imprime um ranking de exemplo, sem descarregar modelos
```