analise-artigo/README.md

analise-artigo

Projeto de análise de artigos acadêmicos escritos em LaTeX (ABNT/abntex2). É 100% Python puro (biblioteca padrão), sem dependências externas — roda em qualquer máquina com Python ≥ 3.10.

O que ele analisa

• Estrutura e conformidade ABNT (NBR 10520 / 6022 / 14724)
  • título, autores, local/data, resumo (150–500 palavras), palavras-chave
  • presença de seções: Introdução, Metodologia, Revisão de Literatura, Conclusão
• Citações e referências
  • citações no corpo vs. entradas do .bib (detecta órfãs e não citadas)
  • referências mais citadas e distribuição por ano
• Métricas textuais
  • palavras, frases, média de tamanho de frase, vocabulário único
  • legibilidade (Flesch adaptado ao português)
  • distribuição de palavras por seção
• Qualidade de prosa (heurísticas)
  • palavras repetidas / redundâncias (de de, que que, mas mas …)
  • frases > 60 palavras e parágrafos > 160 palavras
  • expressões mais repetidas no corpo do artigo

Como usar

# a partir da raiz do projeto
python -m analise_artigo artigos/rumo-a-eficiencia

# ou apontando direto para o .tex (o .bib é descoberto automaticamente)
python -m analise_artigo artigos/rumo-a-eficiencia/main.tex

# saída em outro diretório
python -m analise_artigo caminho/do/artigo --out relatorios/

Saídas geradas no diretório de saída (padrão relatorios/):

Arquivo	Conteúdo
relatorio.md	relatório legível em Markdown
relatorio.json	dados estruturados (para plotar/automatizar)

Código de saída do processo: 0 quando não há verificações em fail, 2 quando há, 1 em erro de uso/entrada.

Estrutura do projeto

analise-artigo/
├── analise_artigo/
│   ├── __init__.py      # API pública do pacote
│   ├── texparse.py      # LaTeX → texto (seções, resumo, citações)
│   ├── bib.py           # parser .bib (BibTeX), sem dependências
│   ├── analyze.py       # métricas + checklist ABNT + heurísticas
│   ├── report.py        # geração do .md e do .json
│   └── __main__.py      # CLI
├── artigos/
│   └── rumo-a-eficiencia/   # o artigo analisado (main.tex + referencias.bib)
├── relatorios/              # saída gerada
├── requirements.txt
└── README.md

Usando como biblioteca

from analise_artigo import parse_article, parse_bib, analyze, write_reports
from pathlib import Path

artigo = parse_article("artigos/rumo-a-eficiencia/main.tex")
refs   = parse_bib("artigos/rumo-a-eficiencia/referencias.bib")
an     = analyze(artigo, refs)

print(an.metrics["flesch"], an.metrics["flesch_faixa"])
for c in an.checks:
    print(c.icon, c.code, c.detail)

Limitações conhecidas

• O parser é orientado a abntex2/ABNT; documentos em outras classes (article, report com nomenclatura própria) exigem pequenas adaptações em texparse.py.
• Uma frase/parágrafo por linha: as heurísticas de sentença/travessão e de "parágrafo extenso" presumem que cada parágrafo do .tex ocupe uma linha (convenção verificada nas fontes analisadas). Textos com parágrafos múltiplos de linha tendem a ser fragmentados.
• Flesch adaptado (pt-BR): usa a fórmula 206,835 − 1,015·MPF − 84,6·VMP com sílabas estimadas por grupos de vogais (resultado clamped em 0–100). Texto acadêmico técnico costuma pontuar baixo (p. ex. 0–15) — o índice reflete vocabulário denso, não um "erro".
• "se se" excluído da detecção de palavras repetidas: é uso pronominal legítimo ("avaliou-se se cada estudo…").
• Simplificação de .bib: nomes com escapes LaTeX recebem diacríticos removidos para exibição (Ki\vs\vs\, M. → Kiss), apenas na apresentação — o arquivo original não é modificado.
• Heurísticas de prosa não substituem revisão humana ou ferramentas como LanguageTool.

Ideias de evolução

• Exportar relatório em HTML com gráficos (referências por ano, palavras por seção) a partir do relatorio.json
• Suporte a bibliografia biblatex (.bbx) e listas de referências manualmente digitadas no corpo do .tex
• Detecção de consistência terminológica (ex.: "agentes pedagógicos" vs. "agente pedagógico")
• Integração com LanguageTool via CLI para correção gramatical completa