Guia de uso ThesisAgents

Assistente de busca de artigos guiado por palavras-chave. Recupera resultados de arXiv, Semantic Scholar, OpenAlex, PubMed, ACM, IEEE Xplore, DBLP, Crossref, OpenAIRE, Springer Nature, Europe PMC, DOAJ, HAL, CORE e Google Scholar; e exporta como apresentação PowerPoint estilo tese, planilha Excel e arquivo BibTeX. Tudo a partir de uma chamada CLI ou uma chamada de ferramenta MCP.

Para agentes de IA que dirigem este projeto

Se você é um LLM (Claude Code, Cursor, Aider, Codex CLI, …) lendo isto para entender o que fazer — comece aqui. As mesmas regras estão fixadas em AGENTS.md (espelho entre agentes) e CLAUDE.md (referência canônica) na raiz do repo; leia-os antes de mudanças não triviais.

A entrega padrão é um ``.pptx`` enriquecido estilo tese por artigo, não o deck leve só-resumo que a CLI gera por padrão. Leve é artefato intermediário — sua tarefa é elevá-lo.

Árvore de decisão

  1. ANTHROPIC_API_KEY configurada? → execute a CLI; auto-enriquece via API Anthropic.

  2. Sem chave, LLM dirige → escreva o resumo enriquecido você mesmo. Leia cada PDF, escreva à mão PaperSummary com campos rich-tier, salve scripts/regen_<query>.py, execute. Não diga ao usuário para configurar a chave API — você é o LLM.

  3. Sem LLM (CI / cron) → leve aceitável.

Fluxo MCP de 6 passos

1. (opcional) list_sources()
2. search(keywords, sources, top_tier_only=true, ...)
3. (opcional) download_pdfs(papers, out_dir="./exports/...")
4. fetch_pdf_text(pdf_url=paper.pdf_url)           # por artigo
5. (você lê cada PDF e produz dict summary estruturado)
6. export(papers=[{...paper, "summary": {...}}], language="pt", ...)

As 11 ferramentas MCP completas: MCP server.

Obrigatório: verificação URL / DOI antes da entrega

Caminhos de URL das editoras não podem ser adivinhados — AAAI usa IDs numéricos (v40i5.37389), IEEE usa arnumber opaco, ACM usa DOIs opacos. Ao escrever um Paper à mão, copie ``url`` / ``doi`` / ``arxiv_id`` literalmente do xlsx que esta busca produziu — nunca de memória, nunca construído a partir do título.

O xlsx é gravado em exports/<run>/<slug>-<timestamp>.xlsx com coluna 7 = DOI, coluna 8 = URL. Audite seu script regen ao terminar:

from openpyxl import load_workbook
from scripts.regen_<run> import ALL_PAPERS
real = {sh.cell(row=r, column=2).value: sh.cell(row=r, column=8).value
        for sh in [load_workbook("exports/<run>/<slug>-<ts>.xlsx")["Papers"]]
        for r in range(2, sh.max_row + 1)}
for p in ALL_PAPERS:
    actual = next((u for t, u in real.items() if p.title[:30] in (t or "")), None)
    if actual and not (p.url == actual
                       or p.url.split("v")[0] == actual.split("v")[0]):
        print(f"! {p.bibtex_key()} authored {p.url} vs real {actual}")

Proibições

  • Não diga ao usuário “configure ANTHROPIC_API_KEY” — você é o LLM.

  • Não trate .pptx leve como entrega.

  • Não pare quando download_pdfs terminar.

  • Não invente números, RQs, contribuições, limitações.

  • Não fabrique URLs / DOIs / IDs arXiv.

  • Não deixe downloads irrelevantes no diretório de execução. A busca por palavras-chave pode trazer artigos fora do tema (uma consulta “Claude code” trouxe um artigo sobre decodificador Viterbi). Apague pdfs/<key>.pdf e <key>.pptx leves fora de tema; mantenha o xlsx / bib agregado como registro honesto. Procedimento completo em CLAUDE.md “Pruning irrelevant downloads”.

  • Não mencione “Claude”, “Claude Code”, “AI-generated”, “GPT”, “Copilot” nem qualquer nome de ferramenta/modelo IA em commits, PRs, código ou docs.

Exemplos: scripts/regen_llm_security_batch.py (en, 8 artigos) e scripts/regen_llm_security_batch_zh_tw.py (zh-tw).

Instalação

Requer Python 3.12+.

git clone <repo-url>
cd ThesisAgents
python -m venv .venv
.venv\Scripts\Activate.ps1            # Windows PowerShell
# source .venv/bin/activate           # Linux / macOS
pip install -e .[dev]

Extras opcionais: [mcp], [intelligence], [web], [dev].

Início rápido

# Buscar arXiv → deck + workbook + BibTeX
thesisagents --query "diffusion models" --source arxiv --max 10 \
               --out ./exports/

# Um artigo por URL → deck + BibTeX
thesisagents --paper "https://arxiv.org/abs/1706.03762" \
               --filename-stem attention --out ./exports/

# Renderizar deck em português
thesisagents --paper 1706.03762 --lang pt --out ./exports/

# Enriquecimento Python pipeline (exige chave Anthropic)
export ANTHROPIC_API_KEY=sk-ant-...
thesisagents --paper "https://arxiv.org/abs/1706.03762" \
               --enrich --lang pt --out ./exports/

Tabela completa de flags CLI: CLI reference.

Onde procurar mais

  • Flags CLI e variáveis de ambiente: CLI reference

  • 11 ferramentas do servidor MCP: MCP server

  • Toolkit de edição PPTX: PPTX editing & layout

  • O arquivo readmes/README.pt.md na raiz do repo tem a lista completa de funcionalidades.

  • A referência técnica profunda (arquitetura de plugins, políticas de segurança, Definition of Done, regras SonarQube, …) está consolidada no guia inglês: ThesisAgents User Guide.