Metadata-Version: 2.4
Name: pluto-enem
Version: 0.5.2
Summary: Pluto (biblioteca educacional), Minos (recuperação/geração/validação) e ARTEMIS (PDF) para provas no padrão ENEM
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: Pillow
Requires-Dist: reportlab>=4.0
Provides-Extra: progresso
Requires-Dist: tqdm; extra == "progresso"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pypdf>=4; extra == "dev"
Requires-Dist: build; extra == "dev"

# Pluto ENEM

Biblioteca Python para consultar questões do ENEM. Sem informar um caminho, a biblioteca baixa o SQLite versionado no dataset do Pluto e mantém apenas um cache local para executar consultas rápidas.

```python
from pluto import PlutoLibrary

biblioteca = PlutoLibrary()
print(biblioteca.years())
print(biblioteca.count())

for questao in biblioteca.sample(5, discipline="matematica", seed=42):
    print(questao.year, questao.number, questao.full_text)
    for imagem in questao.images:
        print(imagem.file)
```

O dataset padrão é:

```text
https://github.com/Ykll27/pluto-dataset
```

O banco é baixado para `~/.cache/pluto-enem/pluto.db` apenas uma vez. Para atualizar:

```python
biblioteca.refresh_dataset()
```

## Redações

Redações usam o mesmo objeto `PlutoLibrary` e o mesmo SQLite:

```python
from pluto import PlutoLibrary

pluto = PlutoLibrary()
redacao = pluto.random_redacao()
resultados = pluto.search_redacoes("educação")
coletanea = pluto.get_coletanea(redacao.id) if redacao else None
comentarios = pluto.get_comentarios(redacao.id) if redacao else None
repertorios = pluto.get_repertorio("educação")
```

O importador UOL é determinístico e opt-in. Ele rejeita páginas sem exatamente
quatro textos motivadores, em vez de inventar conteúdo:

```bash
python -m pluto.import_uol --url https://educacao.uol.com.br/bancoderedacoes/redacoes/educacao-e-convivio.htm
```

Use `--allow-incomplete` somente para guardar rascunhos que serão revisados
manualmente. Respeite direitos autorais, termos de uso e atribuição da fonte.

## Fluxo offline antes do GitHub

O banco deve ser criado e revisado localmente. Nenhuma API é necessária para
quem instala a biblioteca. Depois de terminar a importação ENEM e UOL:

```bash
python -m pluto.importar_dataset --database Pluto/database/pluto.db
```

Para apenas validar o banco ENEM já existente:

```bash
python -m pluto.importar_dataset --sem-uol --database Pluto/database/pluto.db
```

O comando executa o `PRAGMA integrity_check`, mostra contagens e não faz push.
Após revisar o resultado, publique a pasta `Pluto` com o publicador GitHub.

Para usar um banco local existente:

```python
biblioteca = PlutoLibrary("Pluto/database/pluto.db")
```

As imagens remotas retornam URLs do dataset e não são copiadas para o projeto do usuário. Para instalar a versão remota publicada:

```bash
python -m pip install --upgrade pluto-enem==0.5.0
```

Antes de redistribuir o dataset, confirme as permissões aplicáveis ao conteúdo e às imagens.

## Minos e governança do Pluto

O `PlutoLibrary` é a fonte de verdade. O `Minos` recupera contexto dessa
biblioteca e bloqueia uma geração quando não há contexto recuperado:

```python
from pluto import Minos, PlutoLibrary

minos = Minos(PlutoLibrary())
contexto = minos.require_context("educação e tecnologia")
```

Atualizações externas nunca escrevem diretamente no banco oficial. O
importador de notícias cria `Pluto/database/pluto.staging.db`:

```bash
python -m pluto.importar_noticias --database Pluto/database/pluto.db
```

O serviço local de coleta pode executar uma vez ou permanecer em ciclo:

```bash
python -m pluto.minos_background --once --database Pluto/database/pluto.db
```

O staging deve ser revisado antes de ser promovido. O módulo
`pluto.governance` fornece `diff_databases()` e `promote_staging(...,
approved=True)`. A promoção nunca ocorre automaticamente. Notícias são
armazenadas como metadados e resumo do feed, não como cópia integral de
artigos.

O catálogo inclui os feeds oficiais atuais da Agência Brasil, gov.br e Câmara
Notícias. Se o gov.br responder HTML no lugar do XML RSS, o importador registra
a fonte como indisponível naquela execução e continua com as demais fontes;
ele não interpreta HTML como se fosse um feed válido.

Para gerar/revisar o relatório e não promover nada:

```bash
python -m pluto.promover_staging --database Pluto/database/pluto.db
```

Somente depois da revisão humana:

```bash
python -m pluto.promover_staging --database Pluto/database/pluto.db --aprovar
```

Antes do push, gere e verifique o manifesto (o publicador recusa banco sem manifesto válido):

```bash
python -m pluto.manifesto --database Pluto/database/pluto.db             # versão AAAA.MM.DD
python -m pluto.manifesto --database Pluto/database/pluto.db --verificar
```

## Novidades da 0.5.0 (resumo)

Detalhes em `CHANGELOG.md`, `docs/MIGRACOES.md`, `LICENCAS.md` e `DATASET_POLICY.md`.

### Atualizar um banco existente

```bash
python -m pluto.migrar --banco Pluto/database/pluto.db --dry-run
python -m pluto.migrar --banco Pluto/database/pluto.db --deduplicar-questoes
python -m pluto.migrar --banco Pluto/database/pluto.db
```

### Busca ranqueada (FTS5/BM25)

```python
pluto = PlutoLibrary("Pluto/database/pluto.db")
for hit in pluto.search_content("mudanças climáticas agricultura brasileira",
                                kinds=["questao", "noticia"], disciplina="ciencias-humanas", limit=10):
    print(hit.key, hit.title, hit.matched_terms, hit.source)
```

Filtros: `disciplina`, `area`, `tema`, `habilidade`, `ano`, `dificuldade`, `categoria`,
`fonte`, `tags`. Sem FTS5 a busca usa um fallback equivalente.

### Fluxo completo

```text
pluto_import.py / import_uol / importar_noticias  →  pluto.staging.db
python -m pluto.promover_staging [--aprovar]      →  pluto.db (backup + integridade)
python -m pluto.minos ...                         →  pacote JSON auditável (+ versões A/B)
python -m pluto.revisar ...                       →  revisão do professor (memória separada)
python -m artemis pacote.json --pdf ...           →  PDF da prova, gabarito e folha de redação
```

### Desenvolvimento

```bash
python -m pip install -e ".[dev]"
python -m pytest                          # ou: python -m unittest discover -s tests -t .
ruff check pluto artemis tests scripts
python scripts/validar_banco_sintetico.py
```
