# Quickstart: Deterministic Article Content Selection

**Branch**: `004-deterministic-content-selection` | **Date**: 2026-08-20 | **Spec**: [spec.md](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
```bash
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
```bash
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):

```bash
pytest tests/test_select_article_extractor.py -v
```

---

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

```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)
```