litreviewR

Organize a revisão; mantenha o pesquisador no controle. litreviewR é um pacote R para organizar referências, preparar corpora textuais e apoiar extração e classificação estruturadas em revisões de literatura. Ele combina ferramentas tradicionais de análise de texto com instrumentos configuráveis e adaptadores para modelos de linguagem e classificação JEV.

O pacote foi pensado para cientistas sociais e políticos que precisam tornar mais sistemática a triagem, a codificação e a síntese de um corpus. Também oferece interfaces legíveis por scripts e agentes: esquemas JSON, contratos explícitos, resultados estruturados e validação de citações permitem encaixá-lo em fluxos automatizados sem delegar decisões científicas ao modelo.

Estado do projeto: versão de desenvolvimento 0.1.0. Resultados de LLM e JEV são candidatos a codificação e precisam de revisão humana. O pacote não substitui protocolo de revisão sistemática nem valida conclusões substantivas por conta própria.

O que você pode fazer

• Ler referências BibTeX, normalizar e localizar DOIs, consultar metadados Crossref e registrar possíveis duplicatas.
• Importar coleções e PDFs do Zotero local com IDs persistentes, proveniência e manifesto, mantendo a biblioteca original intacta.
• Preparar PDFs e textos identificados, extrair resumos para triagem e criar uma matriz documento-termo com registro de exclusões.
• Explorar corpus com LDA ou STM, inspecionar termos por tópico e agrupar tópicos por anotação humana ou por similaridade lexical TF-IDF.
• Definir suas próprias dimensões de revisão, categorias, escopos e regras em um esquema JSON editável, sem assumir uma taxonomia universal.
• Usar JEV para classificar dimensões categóricas e modelos compatíveis com Chat Completions para extrair campos estruturados.
• Validar contratos e verificar se citações ocorrem literalmente nas passagens fornecidas; registrar uso informado pelas APIs.

Por que usar em pesquisas sociais e políticas

Em ciência política, o pesquisador pode estruturar um corpus sobre gastos de campanha, por exemplo, e configurar campos para país, eleição, cargo, unidade de análise, definição de despesa, categorias de gasto, método, resultados e limitações. Em outras áreas das ciências sociais, as dimensões podem ser substituídas pelas variáveis e conceitos pertinentes à pergunta de pesquisa.

Isso ajuda a aplicar o mesmo formulário a muitos artigos, identificar campos faltantes, separar texto-fonte de inferências, manter IDs estáveis e exportar resultados que possam ser conferidos. LDA/STM ajudam a explorar vocabulário e padrões do corpus; JEV ajuda a aplicar categorias definidas pelo pesquisador; um LLM pode preencher campos ou sugerir trechos para verificação. Nenhum desses passos decide, por si só, o que conta como evidência ou como interpretar um achado.

Uso em fluxos com agentes

litreviewR é uma biblioteca que agentes podem chamar por meio de R ou de um wrapper apropriado. O pacote não instala nem hospeda agentes. Um agente pode, por exemplo, receber um esquema JSON definido pela equipe, processar um artigo por vez, chamar extrai_dimensoes() ou classifica_dimensoes(), validar os objetos com contrato_validar() e verificar trechos com valida_evidencia_trecho(). O pesquisador pode revisar casos ambíguos, alterar o instrumento e controlar quais resultados seguem para a síntese.

A divisão entre instrumento, entrada, chamada e resposta estruturada facilita a integração com agentes diferentes e torna o fluxo mais auditável do que prompts livres sem contrato. Agentes continuam sujeitos a erros de seleção, extração e interpretação; guarde a versão do esquema, o modelo, os parâmetros, os resultados brutos e as decisões humanas.

Instalação

Instale a versão de desenvolvimento pelo GitHub:

install.packages("remotes")
remotes::install_github("BaruqueRodrigues/litreviewR")
library(litreviewR)

Alguns recursos usam dependências opcionais: shiny para o editor de instrumentos, text2vec para agrupamento TF-IDF e cld2 para detecção de idioma dos resumos. LDA e STM usam as dependências listadas em DESCRIPTION.

Um primeiro fluxo: textos nomeados e exploração de tópicos

Os nomes do vetor viram IDs estáveis. Para um estudo real, use textos suficientemente longos e examine os documentos excluídos e os termos dos tópicos antes de interpretá-los.

textos <- c(
  artigo_001 = paste(rep("eleições campanha gastos partidos candidatos votos ", 20), collapse = ""),
  artigo_002 = paste(rep("despesas campanha propaganda candidatos desempenho eleitoral ", 20), collapse = ""),
  artigo_003 = paste(rep("instituições partidos representação política eleições ", 20), collapse = "")
)
dtm <- cria_dtm(textos = textos, idioma = "portuguese", min_freq = 1)
dtm_obter_exclusoes(dtm)

analise <- roda_analise_topicos(
  dtm = dtm,
  k = 2,
  method = "lda",
  seed = 1234
)
analise$topicos
analise$associacao_documento_topico

Importar uma coleção do Zotero local

Habilite “Allow other applications on this computer to communicate with Zotero” nas preferências avançadas e mantenha o aplicativo aberto. As funções abaixo consultam a API local; não alteram itens nem arquivos do Zotero.

config <- zotero_config(backend = "local", library_type = "user", library_id = "0")
zotero_status(config)
colecoes <- zotero_list_collections(config)
# Substitua pela chave de oito caracteres da coleção escolhida:
previa <- zotero_import_collection(config, "COLL1234", "corpus-zotero")
# A simulação não grava arquivos. Para efetuar a importação:
resultado <- zotero_import_collection(
  config, "COLL1234", "corpus-zotero", include_pdfs = TRUE, dry_run = FALSE
)

A chave de coleção do exemplo é sintética. A importação considera somente a coleção selecionada, registra anexos indisponíveis e preserva IDs na reimportação. PDFs são copiados para o corpus, sem mover os originais. Quando uma versão antiga do Zotero não fornece identidade da biblioteca ou instância, informe instance_id persistente na configuração. Consulte contratos da integração para detalhes de identidade, limites e layout do corpus.

O backend Web reutiliza o mesmo transporte HTTP, os limites e os erros tipados do cliente local. A chave Web é lida pela variável indicada em api_key_env; ela não fica no objeto de configuração. O servidor MCP expõe cinco ferramentas por stdio e aceita apenas IDs de perfis de biblioteca e corpus configurados pelo operador. Veja a vignette Zotero e o contrato 1.0.0. O fluxo automatizado usa fixtures sintéticas; o piloto com uma biblioteca real continua pendente. Para executar o servidor MCP, use o checkout do repositório: instalar apenas o pacote R não instala os arquivos Python na biblioteca R.

Instrumentos próprios para sua revisão

schema_padrao() cria um ponto de partida. Edite dimensões para sua área, valide a estrutura e salve-a em JSON. O editor Shiny local é opcional.

instrumento <- schema_padrao()
schema_validar(instrumento)
# Abrir o editor em uma sessão interativa:
# instrumento <- configura_revisao(instrumento)
schema_escrever(instrumento, "instrumento.json")

A extração e a classificação usam serviços externos e exigem credenciais configuradas no ambiente R. Nenhuma chave deve ser gravada no esquema ou no repositório. Leia as vignettes antes de enviar textos de pesquisa a um provedor, considerando privacidade, consentimento, licença e regras da sua instituição.

# Exemplos de chamadas reais (requer credenciais e acesso de rede):
# saida <- extrai_dimensoes(
#   conteudo = texto_do_artigo,
#   schema = instrumento,
#   unidade = list(scope = "article", unit_id = "artigo_001"),
#   provider = "deepseek"
# )
# rotulos <- classifica_dimensoes(
#   conteudo = texto_do_artigo,
#   schema = instrumento,
#   unidade = list(scope = "article", unit_id = "artigo_001")
# )

Vignettes e referência das funções

As vignettes cobrem todas as funções exportadas, agrupadas por etapa do trabalho. Após instalar, abra-as no R com browseVignettes("litreviewR").

• Referências e aquisição: gera_referencias(), funções DOI/Crossref e baixa_pdf_*().
• Corpus e tópicos: resumos para anotação, DTM, LDA/STM e agrupamento.
• Instrumentos e classificação: esquema configurável, contratos, JEV e categorias.
• Extração e evidências: adaptadores LLM, extração estruturada e validação de trechos.

Consulte também help(package = "litreviewR") e a documentação de cada função com ?nome_da_funcao.

Limites e uso responsável

• A aquisição depende de fontes externas. baixa_pdf_aberto() atualmente reconhece a rota SciELO; outros portais abertos ainda podem não ser cobertos. O backend Sci-Hub é opcional e configurável, mas disponibilidade, termos de uso, direitos autorais e regras locais devem ser verificados pelo usuário.
• LDA e STM são métodos exploratórios; a escolha de pré-processamento e número de tópicos afeta resultados. NMF está suspenso nesta versão.
• JEV produz classificação inferida e não fornece evidência documental independente. Um LLM pode retornar campos incorretos ou citações inadequadas.
• A validação literal só confirma que uma citação está presente no texto da passagem fornecida; não confirma que a citação sustenta a interpretação.
• Serviços externos podem mudar modelos, preços, limites e formatos de API. Estimativas de custo do pacote não são faturas do provedor.
• Testes automatizados verificam a implementação em dados controlados; não demonstram validade científica em um corpus real.

Desenvolvimento

Para rodar testes e verificações locais:

devtools::test()
devtools::check()

Licença

MIT. Veja LICENSE.