paper-summary

name	paper-summary
description	Deterministic PDF-to-markdown paper summarization for papercli workflows. Given one paper PDF or a directory of paper PDFs, produce schema-conformant markdown summaries and optionally update summarized_ids.txt.
homepage	https://github.com/jimezsa/papercli
metadata	{"opencolab":{"emoji":"📄","os":["linux","darwin"],"requires":{"bins":["python3"]}}}

Paper Summary Skill

Use this skill when PDFs have already been downloaded and the next step is to create deterministic <run-folder>/pdf/<safe_id>.md summaries from those PDFs.

For precise follow-up QA after the summaries exist, switch to the shared pageindex-grounded skill instead of stretching this skill into ad hoc question answering.

This skill is the canonical summary step for:

• SKILLS/fast-research/SKILL.md
• SKILLS/pro-research/SKILL.md
• SKILLS/deep-research/SKILL.md

Update This Skill

Only do this if the user explicitly asks to update this skill from the GitHub repo.

To refresh this skill directly from the GitHub repo:

curl -fsSL https://raw.githubusercontent.com/jimezsa/papercli/main/SKILLS/paper-summary/SKILL.md \
  -o SKILLS/paper-summary/SKILL.md
curl -fsSL https://raw.githubusercontent.com/jimezsa/papercli/main/SKILLS/paper-summary/references/summary_schema.md \
  -o SKILLS/paper-summary/references/summary_schema.md
curl -fsSL https://raw.githubusercontent.com/jimezsa/papercli/main/SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  -o SKILLS/paper-summary/scripts/gemini_parallel_summary.py

Mission

Given one paper PDF or a directory of paper PDFs:

1. Read the PDFs directly with Gemini.
2. Produce one markdown summary per paper that follows the canonical schema in references/summary_schema.md.
3. Write each summary as <safe_id>.md, next to <safe_id>.pdf, unless an explicit output directory is provided.
4. Optionally append original paper IDs to <run-folder>/meta/summarized_ids.txt.

Prerequisites

• python3 is installed and available in PATH.
• google-genai is installed: python3 -m pip install google-genai
• GEMINI_API_KEY is set in the environment.
• Network access is available when running the Gemini script.
• The PDFs already exist locally.
• Optional metadata JSON files exist in <run-folder>/meta/<safe_id>.json.

Required Inputs

• A single PDF via --pdf, or a directory of PDFs via --pdf-dir.
• Optional --metadata-dir so the script can recover original paper IDs and metadata fallbacks.
• Optional --summarized-ids file to append successful original paper IDs.
• Optional --failures-tsv file to record summary failures in the same ledger used by the research skills.
• The active research run folder, normally research/<YYYY-MM-DD>-<topic-slug>/, when this is called from fast-research, pro-research, or deep-research.

Hard Requirements

• Use the canonical schema from references/summary_schema.md unchanged.
• Output markdown only. Do not wrap the summary in code fences.
• Keep figures, tables, equations, captions, and page anchors as first-class evidence.
• Use metadata only as fallback and label it clearly.
• If evidence is missing, preserve the required missing-evidence labels instead of guessing.
• Do not silently skip failures. Either rerun the paper or record the failure upstream.

Workflow

1. Confirm local inputs

• Verify the target PDF exists.
• When possible, keep PDF names aligned with the safe_id convention already used by the research skills.
• If metadata exists, keep the matching JSON at <run-folder>/meta/<safe_id>.json.

2. Run the Gemini batch summarizer

When this skill is called from a research run, set RUN_ROOT to the active run folder first:

RUN_ROOT="research/<YYYY-MM-DD>-<topic-slug>"

Single paper:

python3 SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  --pdf "$RUN_ROOT/pdf/<safe_id>.pdf" \
  --metadata-dir "$RUN_ROOT/meta" \
  --summarized-ids "$RUN_ROOT/meta/summarized_ids.txt" \
  --failures-tsv "$RUN_ROOT/meta/failures.tsv"

Batch mode:

python3 SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  --pdf-dir "$RUN_ROOT/pdf" \
  --metadata-dir "$RUN_ROOT/meta" \
  --summarized-ids "$RUN_ROOT/meta/summarized_ids.txt" \
  --failures-tsv "$RUN_ROOT/meta/failures.tsv" \
  --concurrency 4

Useful flags:

• --model <name>: override the default Gemini model.
• --output-dir <dir>: write summaries somewhere other than next to the PDFs.
• --overwrite: regenerate existing .md summaries.
• --concurrency <n>: lower this if the API starts rate limiting.

3. Review outputs

• Each successful run should create <run-folder>/pdf/<safe_id>.md.
• Check that the output preserves the canonical headings and evidence anchors.
• If a paper failed, inspect stderr, then rerun just that paper or keep the failure recorded in <run-folder>/meta/failures.tsv.

Output Contract

• One markdown summary per processed PDF.
• Each summary follows the canonical schema in references/summary_schema.md.
• Successful runs may append the original paper ID to <run-folder>/meta/summarized_ids.txt when metadata is available.

Canonical Assets

• Summary schema: SKILLS/paper-summary/references/summary_schema.md
• Batch summarizer: SKILLS/paper-summary/scripts/gemini_parallel_summary.py