Quickstart: Deterministic Article Content Selection

Branch: 004-deterministic-content-selection | Date: 2026-08-20 | Spec: spec.md

1. Pré-requisitos

Python 3.10+
Ambiente virtual configurado com dependências do projeto instaladas (pip install -r requirements.txt).

2. Execução Rápida via CLI

Cenário 1: Selecionar o melhor extrator para uma extração existente

python scripts/select_article_extractor.py out/river_plate_extracted.json

Resultado esperado:

Arquivo out/river_plate_extracted_selected.json gerado contendo todos os 20 artigos com a chave selected_extractor devidamente preenchida (trafilatura, newspaper4k ou readability).
O arquivo original out/river_plate_extracted.json permanece inalterado.

Cenário 2: Especificar caminho de saída customizado e modo verboso

python scripts/select_article_extractor.py out/river_plate_extracted.json -o out/meu_resultado.json --verbose

Resultado esperado:

Logs detalhados no stderr mostrando as pontuações e a regra acionada (ex: highest_score, technical_tie, etc.).

3. Execução dos Testes Automatizados

Para rodar a suíte completa de testes unitários e de integração (cobrindo os casos CT-001 a CT-014):

pytest tests/test_select_article_extractor.py -v

4. Validação Programática / Uso como Módulo Python

from scripts.select_article_extractor import select_article_extractor

article_data = {
    "trafilatura": {"text": "El Club Atlético River Plate venció 2-0 anoche.", "error": None},
    "newspaper4k": {
        "text": "El Club Atlético River Plate venció 2-0 anoche en el Monumental.",
        "error": None,
    },
    "readability": {
        "cleaned_text": "El Club Atlético River Plate venció 2-0 anoche.",
        "error": None,
    },
}

result = select_article_extractor(article_data)
print("Extrator selecionado:", result.selected_extractor.value)
print("Motivo da escolha:", result.selection_reason)
# Output esperado:
# Extrator selecionado: newspaper4k (ou readability dependendo do desempate de shingles)
# Motivo da escolha: technical_tie_smallest_shingles (ou highest_score)

2.2 KiB Raw Blame History