arxiv-to-beamer

Turn an arxiv paper into an Overleaf-ready Beamer project, using an OpenRouter

model to draft the slides from the paper's own LaTeX source — or, when arxiv

has no TeX source, from a Markdown rendering produced by MinerU.

Prerequisites

• Env var OPENROUTER_API_KEY must be exported in the shell.
• Env var MINERU_API_TOKEN should be exported when the paper might be

PDF-only (used for the MinerU fallback). Get one from

→ console → API.

• Python 3.9+ on PATH (only stdlib is used — no pip install needed).

If OPENROUTER_API_KEY is not set, stop and ask the user to export it before

running anything. If a paper turns out to be PDF-only and MINERU_API_TOKEN

is missing, ask the user to export that too (or pass --no-mineru-fallback

to skip the fallback entirely).

Usage

Invoke the bundled script with the arxiv id (e.g. 2603.19835) or any

arxiv URL (abs/, pdf/, e-print/). Always prefer the

${CLAUDE_PROJECT_DIR} variable so the path resolves regardless of cwd:

python "${CLAUDE_PROJECT_DIR:-.}/.claude/skills/arxiv-to-beamer/scripts/arxiv_to_beamer.py" <arxiv_id_or_url>

Optional flags:

• --output — output zip path (default -beamer.zip in cwd).
• --model — OpenRouter model id (default anthropic/claude-sonnet-4.5).
• --language — slide language hint passed to the model (default 中文).
• --keep-source — also copy the extracted arxiv source (or MinerU

markdown output) next to the zip.

• --max-chars — cap source bytes sent to the model (default 200000).
• --mineru-timeout — how long to wait for MinerU PDF parsing

(default 900s).

• --no-mineru-fallback — skip the MinerU fallback when arxiv is PDF-only

(script then exits with code 2 instead).

What the script does

1. Parses the arxiv id from the input (supports 2603.19835, 2603.19835v2,

the legacy hep-th/9901001 form, and full URLs).

1. Downloads https://arxiv.org/e-print/. Detects PDF-only submissions

via magic bytes.

1. If TeX source is present: extracts the archive (gzipped tar, plain

tar, or a single gzipped .tex) into a temp dir and gathers every

.tex / .bib file.

1. If PDF-only: falls back to the MinerU API:
• POST https://mineru.net/api/v4/extract/task with

{"url": "https://arxiv.org/pdf/", ...}.

• Polls GET .../extract/task/ until state == "done".
• Downloads the result zip (full_zip_url), extracts it, and

concatenates every .md file as the source text.

• Aborts (exit 2) if MinerU is unreachable, the task fails or times

out, or MINERU_API_TOKEN is not set.

1. Builds a prompt containing the collected source (truncated to

--max-chars) and asks the model: "帮我做一个 beamer 来介绍一下这个

研究工作", with formatting instructions so the response is parseable.

1. Parses files from the response. Recognised forms, in order:
• ===== FILE: ===== blocks (preferred, multi-file).
• Fenced code blocks with a filename hint (` `latex main.tex `).
• A single fenced LaTeX block → main.tex.
• Anything else → dumped verbatim into main.tex.
2. Writes everything into -beamer.zip. Upload that zip via

Overleaf → New Project → Upload Project.

When invoked

• Run the script in the foreground; do not background it.
• Surface the script's stdout/stderr to the user.
• Report the absolute path of the produced .zip.
• If the script exits with code 2:
• Check the stderr message: it will say either "TeX source missing and

MINERU_API_TOKEN not set" (ask the user to export the token, or rerun

with --no-mineru-fallback), "MinerU PDF parsing failed" (network /

quota issue — surface the detail), or "no downloadable TeX source"

(paper is withdrawn). Do not blindly retry.

• If OpenRouter returns an HTTP error, surface the message; do not retry

silently more than once.