arxiv-to-beamer

turn an arxiv paper into an overleaf-ready beamer project. the skill extracts the paper's latex source, feeds it to an openrouter model to draft presentation slides, then packages everything as a .zip ready to upload.

intent

use this when a user provides an arxiv link or id and asks for slides, a beamer presentation, 演示文稿, 介绍, or equivalent. the skill handles both tex-source papers (preferred) and pdf-only submissions (fallback to mineru's pdf-to-markdown extraction). output is an overleaf-uploadable .zip containing a ready-to-compile beamer project.

inputs

required environment variables:

• OPENROUTER_API_KEY: your openrouter api key. if missing, the skill fails immediately and tells the user to export it.

optional environment variables:

• MINERU_API_TOKEN: mineru api token (get from https://mineru.net console). required only if the paper is pdf-only and you want the fallback. if missing and pdf-only paper is encountered, the skill asks the user to export it or pass --no-mineru-fallback.

required tools:

• python 3.9 or later (stdlib only, no external pip packages).

external apis:

• arxiv.org e-print endpoint: https://arxiv.org/e-print/<id>.
• mineru api (if pdf-only): https://mineru.net/api/v4/extract/task (post to create task, get to poll status).
• openrouter api: sends source text and receives beamer latex.

input parameters (via cli):

• arxiv id or url (required): e.g. 2603.19835, 2603.19835v2, hep-th/9901001, or full url like https://arxiv.org/abs/2603.19835.
• --output <path>: where to write the .zip (default: <arxiv_id>-beamer.zip in cwd).
• --model <name>: openrouter model id (default: anthropic/claude-sonnet-4.5).
• --language <lang>: language hint for slide generation (default: 中文).
• --keep-source: also save extracted source (tex or markdown) alongside the zip.
• --max-chars <n>: truncate source to this many bytes before sending to model (default: 200000). edge case: if source is shorter than this, send it all.
• --mineru-timeout <sec>: max seconds to wait for mineru pdf parsing (default: 900). edge case: if timeout reached, fail cleanly with exit code 2.
• --no-mineru-fallback: skip mineru entirely; exit with code 2 if paper is pdf-only.

procedure

1. parse arxiv id from input. accept formats: bare id (2603.19835, 2603.19835v2), legacy id (hep-th/9901001), or full urls (https://arxiv.org/abs/2603.19835, https://arxiv.org/pdf/2603.19835, https://arxiv.org/e-print/2603.19835). extract the canonical id and version (if present). output: normalized arxiv id.

2. download paper from arxiv. fetch https://arxiv.org/e-print/<id> (without version suffix). check response status: if 404, the id is invalid or paper is withdrawn (exit with code 2, message "no downloadable tex source"). if other http error, surface it and do not retry. output: raw bytes of downloaded file.

3. detect if pdf-only or tex-source. read first 4-8 bytes of downloaded file. if magic bytes match gzip (1f 8b), tar (ustar), or pdf (%PDF), classify accordingly. if pdf magic detected, set flag is_pdf_only = true. output: file type classification and raw file bytes.

4. if tex source present (not pdf-only): extract archive into temp directory. handle three formats: gzipped tar, plain tar, or single gzipped .tex file. if archive is malformed, fail with message "corrupt tar archive" (exit 1). recursively walk temp dir and collect all .tex and .bib files in original tree order. concatenate their contents into single source text. output: source text string and list of extracted files.

5. if pdf-only, invoke mineru fallback: check MINERU_API_TOKEN env var. if missing and --no-mineru-fallback not set, ask user to export token or pass flag (exit 1). if --no-mineru-fallback set, exit with code 2 and message "pdf-only paper and mineru fallback disabled". else, post request to https://mineru.net/api/v4/extract/task with json body containing arxiv pdf url. capture task_id from response. edge case: if http error from mineru, surface error message and exit 1. output: task_id string.

6. poll mineru task until done. poll GET https://mineru.net/api/v4/extract/task/<task_id> every 2-5 seconds. check response field state. if state == "done", extract full_zip_url and proceed. if state == "failed", exit 2 with message "mineru pdf parsing failed: ". if timeout reached (compare elapsed time to --mineru-timeout), exit 2 with message "mineru pdf parsing timeout". edge case: malformed json response triggers retry (up to 3 times) before failing. output: full_zip_url string.

7. download and extract mineru result. fetch full_zip_url, write to temp file, extract as zip. walk extracted dir, find all .md files, concatenate their contents in file order. output: source text string.

8. truncate source to max-chars limit. measure byte length of source text. if longer than --max-chars, truncate at char boundary (do not split multi-byte utf-8 sequences). append note "[source truncated]" to end. output: source text, at most --max-chars bytes.

9. build prompt for model. construct system prompt with formatting instructions (see decision points). user message: source text. request model to generate a beamer presentation slide set introducing the paper, respecting the --language hint. output: prompt (system + user).

10. call openrouter api. post to https://api.openrouter.ai/api/v1/chat/completions with model name, messages, max tokens (e.g. 8000), temperature (0.7). check response status. if 401/403, exit 1 with "openrouter auth failed". if 429, surface rate limit and exit 1 (do not retry silently). if 5xx, surface error but retry once after 5 seconds. output: response text (model's generated beamer code).

11. parse files from model response. scan response for recognized file markers, in order:

    • ===== FILE: <relpath> ===== blocks followed by fenced code: extract all such blocks, create file tree.
    • fenced code blocks with filename hint (```latex main.tex, ```python main.py): extract code, infer filename.
    • single fenced latex block: treat as main.tex.
    • fallback: if no recognized structure, dump entire response as main.tex. output: dict of filename -> file content.

12. build beamer project structure. ensure main.tex exists. if model did not produce it, create minimal beamer stub. gather any .bib files from model output. create standard beamer project layout: main.tex at root, supporting files (.bib, images, etc.) in subdirs if needed. output: file tree dict.

13. package as zip. create .zip at --output path. add all files from project tree, preserving relative paths. ensure zip is valid (can be unzipped without errors). output: path to .zip file.

14. optionally keep source. if --keep-source flag set, write extracted source (tex or markdown) to <arxiv_id>-source.tex or <arxiv_id>-source.md in same dir as zip. output: source file path or none.

15. report success. print absolute path of output .zip to stdout. exit with code 0.

decision points

if openrouter api key is missing: exit immediately (code 1), tell user to run export OPENROUTER_API_KEY=<key> before retrying.

if paper is pdf-only and mineru token is missing: either ask user to export MINERU_API_TOKEN, or advise them to pass --no-mineru-fallback to skip. do not guess or use a fallback token.

if arxiv id is invalid or paper withdrawn: exit 2, surface exact arxiv error. do not retry.

if mineru polling times out: exit 2 with "mineru parsing timeout". do not continue with stale data.

if model response is unparseable (no recognized file markers): treat entire response as main.tex and proceed. log a warning.

if model response contains multiple main.tex definitions: keep the first one, warn about duplicates.

if openrouter returns 429 (rate limit): surface the rate limit message and exit 1. do not retry automatically; user must wait and retry manually.

if zip creation fails (disk full, permission denied): surface the exact io error and exit 1.

output contract

• success: one .zip file at path specified by --output (or default <arxiv_id>-beamer.zip). zip must be valid (extractable), contain main.tex at root, and include any supporting files (.bib, custom styles, etc.) generated by the model. zip size should be < 50 mb (edge case: warn if > 10 mb). optional: if --keep-source set, also write <arxiv_id>-source.tex or .md in same dir.
• failure: exit with code 1 (recoverable error: missing env var, network timeout, model error) or code 2 (unrecoverable: pdf-only paper without token, invalid arxiv id, mineru task failed). stderr must contain human-readable error message (no stack traces to user unless --verbose set).
• file format: .zip must be compatible with overleaf's "upload project" flow. main.tex must be compilable with pdflatex or xelatex (no guaranted compilation, but structure must be valid beamer).

outcome signal

• user sees absolute path printed to stdout, e.g.: /home/user/2603.19835-beamer.zip.
• user can immediately download the .zip and upload it to overleaf.
• overleaf can unzip the project and user can compile it (or see clear latex errors if model output is malformed).
• if --keep-source was set, user also sees the extracted source file alongside the zip, useful for debugging or editing.
• if any step fails, user sees a clear message on stderr saying what went wrong (e.g., "openrouter api key not set", "mineru parsing timeout", "arxiv paper withdrawn"). exit code indicates whether retry is sensible (1) or not (2).