feat: add deterministic content extractor selector engine with F1 consensus

2026-08-20 22:09:43 -03:00
parent 6a45368cb0
commit ff7a50e0eb
46 changed files with 18503 additions and 2813 deletions
@@ -0,0 +1,66 @@
+# 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)
+```