papercheck

Um harness de auditoria reproduzível para artigos matemáticos em LaTeX.

O papercheck extrai a estrutura de um artigo, registra descobertas em registros validados por esquema que são verificados contra o texto-fonte exato e executa uma etapa final que informa se o artigo está pronto. Ele funciona como ferramenta de linha de comando ou como servidor MCP que um agente (Claude Code, Codex, Cursor ou similar) conduz enquanto você fornece o julgamento matemático.

O ponto é disciplina. Em vez de pedir a um único modelo que "revise o artigo", o papercheck segmenta o manuscrito, inventaria as afirmações, executa auditorias hostis e estreitas, verifica cada descoberta contra a fonte, adjudica, corrige apenas o que foi aceito e aplica as etapas de controle. As etapas são impostas em código: um agente não pode corrigir antes da adjudicação, e uma descoberta cuja citação não aparece na fonte nunca entra no registro.

O pipeline em etapas — segmentar, orçar, revisão especializada, sintetizar, adjudicar — segue a abordagem descrita na ferramenta Paper Assistant Tool (PAT) do Google Research [1], adaptada em um harness pequeno, aberto e agnóstico de modelo que não executa modelos próprios.

O que é

Um núcleo Python determinístico com duas interfaces — uma CLI e um servidor MCP. O papercheck em si nunca chama um modelo; o raciocínio vive no agente ou em suas mãos na CLI. O que o núcleo fornece:

• Extração de estrutura LaTeX-AST (teoremas, rótulos, referências, citações, equações, marcadores de rascunho) em structure.json.
• Registros de problemas validados por esquema, cada descoberta vinculada a um arquivo e linha.
• Verificação de citações na entrada: se o texto citado de uma descoberta não estiver na fonte, ela é rejeitada como REJECTED_SOURCE_TARGET_INVALID antes de chegar ao registro proposto.
• Uma máquina de estados com etapas (INIT → SCANNED → … → ADJUDICATED → … → GATED) que recusa operações fora de ordem.
• Uma CLI, um servidor MCP (29 ferramentas) e uma interface web local.

Por quê

Um único prompt "revise meu artigo" tende a falhar de três maneiras. O papercheck lida com cada uma em código, não em prompts:

Início rápido

pipx install papercheck        # or: pip install papercheck

papercheck scan     path/to/paper     # extract structure.json
papercheck segments path/to/paper     # propose audit segments and budgets
papercheck gate     path/to/paper --mechanical-only
papercheck report   path/to/paper     # self-contained HTML report
papercheck serve    path/to/paper     # local web UI

Execute no exemplo incluído (imprime ==== READY ====):

papercheck gate examples/toy_clean_paper --mechanical-only

Conduzindo a partir de um agente (MCP)

O papercheck inclui um servidor FastMCP expondo 29 ferramentas mais o pacote de prompts de auditoria. Registre-o uma vez:

claude mcp add papercheck -- papercheck-mcp

Depois peça ao agente para auditar um artigo. Ele percorre o fluxo de trabalho pelas ferramentas MCP — init_audit, run_scan, propose_segments, submit_issue, adjudicate_issue, run_gate — sob as mesmas etapas impostas em código que a CLI.

papercheck packs scaffold --paper-root ./paper            # deterministic draft from the scan
papercheck packs create draft.json --paper-root ./paper   # validated -> Paper_Audit/domain_pack.json

Como funciona

flowchart LR
    A[INIT] --> B[SCANNED] --> C[SEGMENTED] --> D[INVENTORIED] --> E[AUDITING]
    E --> F[SYNTHESIZED] --> G[ADJUDICATED] --> H[PATCH_PLANNED]
    H --> I[PATCHING] --> J[REGRESSED] --> K[GATED]

    E -. submit_issue .-> V{quote and label verified?}
    V -- no --> X[REJECTED_SOURCE_TARGET_INVALID]
    V -- yes --> L[PROPOSED ledger]
    style X fill:#7f1d1d,stroke:#ef4444,color:#fff
    style K fill:#14532d,stroke:#22c55e,color:#fff

Um núcleo determinístico, duas interfaces, sem chamadas de LLM dentro do harness. O papercheck permanece estritamente um servidor MCP e CLI — sem adaptadores de provedor, sem auto-orquestração — então funciona com qualquer modelo e não faz chamadas de rede próprias.

Comandos

Para um repositório de artigos, docs/ci.md descreve uma GitHub Action mecânica, sem LLM, que executa scan e gate --mechanical-only em cada pull request e não envia nada a nenhum provedor de modelo.

Limitações

Veja docs/limitations.md para a versão completa.

• O papercheck não é um provador de teoremas nem um substituto para revisão por pares.
• Detectar um erro semântico depende inteiramente do modelo condutor. O papercheck mantém o processo disciplinado e rastreável, mas descobertas de IA devem ser verificadas de forma independente.
• O papercheck não faz chamadas de rede. O agente com o qual você o conduz pode transmitir seu manuscrito ao provedor de modelo, então revise os termos de dados relevantes antes de auditar trabalho não publicado (docs/privacy.md).

Sobre

Construído por Christian Garry.

Contribuindo

Contribuições são bem-vindas — veja CONTRIBUTING.md. A arquitetura é fixa para a linha 0.x: estritamente MCP e CLI, JSON como fonte da verdade, etapas impostas em código. Mudanças de prompts são protegidas pelos fixtures de avaliação descritos em docs/agent_eval.md.

Referências

1. Rajesh Jayaram, Drew Tyler, David Woodruff, Corinna Cortes, Yossi Matias, Vahab Mirrokni e Vincent Cohen-Addad. Towards Automating Scientific Review with Google's Paper Assistant Tool. arXiv:2606.28277, 2026. https://arxiv.org/abs/2606.28277

O BibTeX para o acima está em docs/references.bib.

Licença

MIT — veja LICENSE. Se o papercheck for útil no seu trabalho, cite-o via CITATION.cff.