TextNLPClassifierApp/docs/prd_deterministic_content_selection.md

PRD — Seleção determinística da biblioteca de extração de conteúdo

Versão: 1.0
Data: 20/08/2026
Status: Pronto para implementação

1. Contexto

Cada artigo é processado pelas bibliotecas Trafilatura, Newspaper4k e Readability a partir do mesmo HTML. O resultado é consolidado em um arquivo JSON que contém, para cada artigo, as saídas das três bibliotecas.

É necessário escolher deterministicamente uma única biblioteca por artigo. A escolha deve ocorrer mesmo quando todos os resultados forem ruins. O processamento não pode retornar estado ambíguo nem deixar um artigo sem seleção.

2. Objetivo

Receber um arquivo JSON no formato do arquivo de referência, selecionar a melhor saída de extração disponível para cada artigo e gerar um novo arquivo JSON com os mesmos dados, acrescentando somente a chave selected_extractor em cada item de articles.

3. Escopo

3.1 Incluído

• Ler um arquivo JSON com uma coleção articles.
• Comparar as saídas de Trafilatura, Newspaper4k e Readability de cada artigo.
• Escolher obrigatoriamente uma das três bibliotecas.
• Adicionar selected_extractor em cada artigo.
• Gerar um novo arquivo JSON.
• Preservar os dados e a ordem dos artigos recebidos.

3.2 Fora do escopo

• Baixar ou renderizar páginas.
• Verificar se as bibliotecas receberam o mesmo HTML.
• Executar novamente as bibliotecas de extração.
• Limpar, recortar, combinar ou reescrever o conteúdo extraído.
• Gerar Markdown.
• Usar LLM, embeddings ou regras específicas por domínio.
• Alterar qualquer campo existente no JSON.
• Adicionar métricas, justificativas ou outras chaves ao arquivo de saída.

4. Premissas

• As três bibliotecas processaram exatamente o mesmo HTML.
• A entrada segue a estrutura do JSON de referência.
• A seleção é executada individualmente para cada artigo.
• O algoritmo deve sempre produzir uma escolha, inclusive em situações sem concordância entre as bibliotecas.

5. Entrada

5.1 Arquivo

• Formato: JSON válido.
• A raiz deve conter articles como uma lista.
• Cada item de articles representa um artigo.

5.2 Conteúdos comparados

Biblioteca	Campo usado na comparação
Trafilatura	trafilatura.text
Newspaper4k	newspaper4k.text
Readability	readability.cleaned_text

Os demais campos, incluindo título, descrição, resumo, palavras-chave, HTML estruturado e metadados, não participam da seleção.

5.3 Estado de um candidato

Para cada biblioteca, o candidato é classificado em um dos seguintes estados:

Estado	Condição
Utilizável	Campo de conteúdo é uma string não vazia após normalização e error é nulo
Degradado	Campo de conteúdo é uma string não vazia após normalização, mas error não é nulo
Indisponível	Campo ausente, nulo, de tipo diferente de string ou vazio após normalização

O campo de erro considerado é trafilatura.error, newspaper4k.error ou readability.error, conforme a biblioteca.

6. Saída

6.1 Arquivo

O arquivo de entrada nunca deve ser alterado. Deve ser criado um novo arquivo com o nome:

<nome_original_sem_extensão>_selected.json

Exemplo: river_plate_extracted(2).json gera river_plate_extracted(2)_selected.json.

6.2 Alteração permitida

Cada item de articles deve receber exatamente uma nova chave no mesmo nível de trafilatura, newspaper4k e readability:

selected_extractor

Valores permitidos:

• trafilatura
• newspaper4k
• readability

Não são permitidos null, string vazia, ambiguous ou qualquer outro valor.

6.3 Preservação da entrada

• Todas as chaves e valores existentes devem permanecer semanticamente idênticos.
• A ordem dos itens de articles deve ser preservada.
• Nenhum artigo pode ser adicionado ou removido.
• Espaçamento, indentação e ordem textual das chaves do JSON não fazem parte do contrato, pois o arquivo pode ser serializado novamente.
• Caso selected_extractor já exista, seu valor deve ser recalculado e substituído.

7. Algoritmo determinístico de seleção

7.1 Formar o conjunto ativo

Para cada artigo:

1. Identificar os candidatos utilizáveis.
2. Se existir pelo menos um utilizável, considerar somente os utilizáveis.
3. Se não existir utilizável, considerar os candidatos degradados.
4. Se não existir candidato utilizável nem degradado, selecionar newspaper4k pelo desempate final obrigatório.
5. Se o conjunto ativo possuir somente um candidato, selecioná-lo imediatamente.

7.2 Normalizar os conteúdos

A normalização serve apenas para comparação e não modifica o JSON de saída.

Para cada candidato ativo:

1. Decodificar entidades HTML.
2. Remover marcação HTML e Markdown, preservando o texto visível.
3. Em links, preservar o texto e remover o endereço.
4. Aplicar normalização Unicode NFKC.
5. Converter o texto para minúsculas.
6. Substituir toda sequência de espaços, tabulações ou quebras de linha por um único espaço.
7. Tokenizar mantendo letras e números Unicode.
8. Desconsiderar pontuação.

Nenhuma palavra ou trecho pode ser removido por interpretação semântica.

7.3 Gerar shingles

• Gerar a sequência ordenada de tokens de cada candidato.
• Formar o conjunto de todas as janelas consecutivas de cinco tokens.
• Quando o candidato possuir entre um e quatro tokens, usar a sequência completa como um único shingle.
• Candidato sem token é indisponível e não participa do conjunto ativo.

7.4 Construir o consenso

O consenso é o conjunto de shingles presentes em pelo menos dois candidatos ativos.

Para cada candidato ativo, calcular:

Cobertura:

coverage = quantidade de shingles do consenso presentes no candidato / quantidade total de shingles do consenso

Suporte:

support = quantidade de shingles do candidato presentes no consenso / quantidade total de shingles do candidato

Pontuação:

score = 2 × coverage × support / (coverage + support)

Quando coverage + support for zero, a pontuação será zero.

7.5 Selecionar quando existe consenso

1. Ordenar os candidatos por score, do maior para o menor.
2. Identificar o maior score.
3. Considerar empate técnico todo candidato cuja diferença para o maior score seja menor ou igual a 0,03.
4. Se houver apenas um candidato no empate técnico, selecioná-lo.
5. Se houver empate técnico, selecionar o candidato com a menor quantidade de shingles.
6. Se a quantidade de shingles também empatar, aplicar a prioridade final:
   1. newspaper4k
   2. readability
   3. trafilatura

A preferência pelo menor candidato ocorre somente no empate técnico. Nesse cenário, os candidatos possuem qualidade de concordância equivalente, e a decisão favorece menor conteúdo excedente.

7.6 Selecionar quando não existe consenso

Quando nenhum shingle aparece em pelo menos dois candidatos ativos:

• Com três candidatos ativos: selecionar o candidato com a quantidade mediana de shingles.
• Com dois candidatos ativos: selecionar o candidato com a maior quantidade de shingles.
• Com um candidato ativo: selecionar o único candidato.
• Em empate de quantidade: aplicar a prioridade newspaper4k, readability, trafilatura.
• Sem candidato ativo: selecionar newspaper4k.

Essas regras garantem uma escolha mesmo quando não existe concordância textual.

7.7 Gravar a escolha

Adicionar ou substituir selected_extractor no artigo com o identificador da biblioteca vencedora. Repetir o processo até que todos os itens de articles tenham sido processados.

8. Requisitos funcionais

ID	Requisito
FR-001	O sistema deve aceitar um arquivo JSON como entrada.
FR-002	O sistema deve validar que a raiz é um objeto e que articles é uma lista.
FR-003	O sistema deve processar todos os artigos, preservando sua ordem.
FR-004	O sistema deve usar exclusivamente os três campos de conteúdo definidos no PRD para calcular a escolha.
FR-005	O sistema deve executar a normalização e a comparação conforme o algoritmo deste PRD.
FR-006	O sistema deve selecionar exatamente uma biblioteca por artigo.
FR-007	O sistema nunca deve produzir resultado ambíguo.
FR-008	O sistema deve adicionar somente selected_extractor em cada artigo.
FR-009	O valor de selected_extractor deve pertencer ao catálogo fechado de valores permitidos.
FR-010	O sistema deve preservar todas as chaves e valores recebidos.
FR-011	O sistema deve gerar um novo arquivo e manter o arquivo original inalterado.
FR-012	O sistema deve produzir a mesma seleção sempre que receber exatamente a mesma entrada.
FR-013	O sistema deve recalcular selected_extractor quando a chave já existir.

9. Tratamento de erros

Situação	Comportamento obrigatório
JSON inválido	Encerrar o processamento e não gerar arquivo de saída
Raiz diferente de objeto	Encerrar o processamento e não gerar arquivo de saída
articles ausente ou diferente de lista	Encerrar o processamento e não gerar arquivo de saída
articles vazio	Gerar arquivo com lista vazia e sem outras alterações
Estrutura de uma biblioteca ausente	Tratar seu candidato como indisponível
Campo de conteúdo com tipo inválido	Tratar seu candidato como indisponível
Todas as bibliotecas indisponíveis	Selecionar newspaper4k
Falha ao gravar o arquivo	Não deixar arquivo de saída parcialmente gravado

Um erro em um artigo não pode impedir a seleção dos demais artigos, desde que o JSON e a lista articles sejam válidos.

10. Requisitos não funcionais

ID	Requisito
NFR-001	O processamento deve ser totalmente determinístico.
NFR-002	O processamento não deve realizar chamadas de rede.
NFR-003	O processamento não deve depender de LLM, embeddings ou serviços externos.
NFR-004	O processamento deve operar somente sobre os dados do arquivo recebido.
NFR-005	A gravação do arquivo deve ser atômica: sucesso completo ou ausência do arquivo de saída.

11. Critérios de aceite

1. Dado o JSON de referência com 20 artigos, o arquivo de saída contém os mesmos 20 artigos na mesma ordem.
2. Cada artigo contém exatamente um selected_extractor válido.
3. Nenhum artigo contém selected_extractor nulo, vazio ou ambíguo.
4. Todas as chaves e valores anteriores permanecem semanticamente idênticos.
5. Nenhuma chave adicional, além de selected_extractor, é criada.
6. O arquivo original permanece inalterado.
7. Duas execuções sobre o mesmo arquivo produzem os mesmos valores de selected_extractor.
8. A seleção usa somente trafilatura.text, newspaper4k.text e readability.cleaned_text.
9. Quando todas as saídas estiverem vazias ou indisponíveis, selected_extractor recebe newspaper4k.
10. Quando não houver consenso, o desempate segue exatamente as regras da seção 7.6.
11. Quando houver empate técnico, o desempate segue exatamente as regras da seção 7.5.
12. Um JSON inválido ou sem articles válido não produz arquivo parcial.

12. Casos obrigatórios de teste

Caso	Condição	Resultado esperado
CT-001	Três candidatos com consenso e um vencedor claro	Selecionar o maior score
CT-002	Dois ou mais candidatos dentro de 0,03 do maior score	Selecionar o de menor quantidade de shingles
CT-003	Empate técnico e mesma quantidade de shingles	Aplicar prioridade final
CT-004	Três candidatos sem consenso	Selecionar a quantidade mediana de shingles
CT-005	Dois candidatos sem consenso	Selecionar a maior quantidade de shingles
CT-006	Somente um candidato utilizável	Selecionar esse candidato
CT-007	Nenhum utilizável, mas existe candidato degradado	Executar o algoritmo somente com os degradados
CT-008	Todos os candidatos indisponíveis	Selecionar newspaper4k
CT-009	Readability retorna apenas um fragmento pequeno enquanto os outros concordam	O fragmento perde por baixa cobertura do consenso
CT-010	Um candidato contém o conteúdo comum e muito conteúdo excedente	O candidato perde suporte e reduz sua pontuação
CT-011	Um candidato contém somente parte do conteúdo comum	O candidato perde cobertura e reduz sua pontuação
CT-012	A entrada já contém selected_extractor	Recalcular e substituir somente essa chave
CT-013	articles está vazio	Gerar saída válida com articles vazio
CT-014	JSON inválido	Não gerar saída

13. Definition of Done

• Todos os requisitos funcionais foram implementados.
• Todos os casos obrigatórios de teste foram automatizados e aprovados.
• O JSON de referência com 20 artigos é processado integralmente.
• A saída contém somente a inclusão de selected_extractor em cada artigo.
• O arquivo original permanece inalterado.
• Execuções repetidas sobre a mesma entrada produzem as mesmas escolhas.
• Não existe caminho de execução que produza ambiguous, null ou artigo sem seleção.