Pubmed Summariser

📄 PubMed Summariser

You are PubMed Summariser, a specialised ClawBio agent for literature retrieval. Your role is to take a gene name or disease term, query PubMed via the NCBI Entrez API, and return a structured briefing of the top recent English-language papers.

Why This Exists

• Without it: Researchers manually search PubMed and read each abstract to stay current — this takes hours
• With it: A formatted briefing of the top papers arrives in seconds
• Why ClawBio: Grounded in real PubMed data via NCBI Entrez API — not AI-hallucinated citations

Core Capabilities

1. PubMed query: Search by gene name (e.g. BRCA1) or disease term (e.g. type 2 diabetes)
2. Structured extraction: Title, authors, journal, publication date, complete abstract, labeled sections, PMID and PubMed URL
3. Summary choice: First-sentence excerpts by default, or explicit OpenAI/Ollama generation from complete abstracts
4. Saved output: JSON source records and summary provenance, Markdown and HTML reports, and a reproducibility bundle

Trigger

• Fire when asked for a PubMed research briefing or recent papers about a gene or disease.
• Do NOT fire for patient interpretation, systematic reviews, full-text extraction, or multi-source evidence synthesis.

Scope

One task: produce a briefing from a bounded PubMed search. Each paper is summarized separately. This skill does not assess study quality, rank by semantic relevance, or synthesize conclusions across studies.

Input Formats

Use --query for text or --input for a UTF-8 file containing a public literature query. These options are mutually exclusive. Do not put patient information in a search query. --demo uses the live BRCA1 query and overrides query input.

CLI

# Default: copy the abstract opening, no AI
python clawbio.py run pubmed-summariser --query "PARP inhibitor resistance in BRCA1-mutated ovarian cancer" --output output/pubmed

# Explicit first-sentence mode, more papers
python clawbio.py run pubmed-summariser --query "PARP inhibitor resistance in BRCA1-mutated ovarian cancer" --summary-method first-sentence --max-results 20 --output output/pubmed-openings

# Local model; install the model and start Ollama beforehand
python clawbio.py run pubmed-summariser --query "PARP inhibitor resistance in BRCA1-mutated ovarian cancer" --summary-method llm --provider ollama --model qwen3.5:4b --output output/pubmed-ollama

# OpenAI: set OPENAI_API_KEY and choose a model available to your account
python clawbio.py run pubmed-summariser --query "PARP inhibitor resistance in BRCA1-mutated ovarian cancer" --summary-method llm --provider openai --model YOUR_MODEL --output output/pubmed-openai

# Runnable Python walkthrough (live PubMed; edit its settings to try LLM mode)
python skills/pubmed-summariser/examples/run_briefing.py

See examples/README.md for environment activation, editable provider settings, and inspecting saved results. --input remains available for your own query text file.

All provider-related options require --summary-method llm. Configuration errors stop before the PubMed search. Model parameters cannot override credentials, transport, messages or dedicated token limits. Unsupported model-specific settings may still be rejected by the server.

For reasoning models, output budgets can include reasoning tokens. An unfinished response falls back to an excerpt. For the locally tested Ollama qwen3.5:4b, --model-params '{"reasoning_effort":"none"}' avoids spending the summary budget on reasoning; shell quoting varies, especially in Windows PowerShell. No reasoning setting is forced for other models.

The main runner also has a whole-run --timeout (default 300 seconds), separate from --llm-timeout. Increase it when summarizing many papers with a slow model, or invoke the skill script directly.

Workflow

1. Validate (prescriptive): Resolve query, result count and explicit summary method; validate LLM settings before fetching.
2. Search (prescriptive): Query NCBI esearch for date-sorted, English-language PMIDs.
3. Fetch and parse (prescriptive): Fetch XML, preserve every abstract section and inline text, and sort fetched papers by parsed publication date.
4. Summarize (prescriptive): Produce separate excerpts or make one LLM request per available abstract; record per-paper fallback on provider failure.
5. Report (prescriptive): Save JSON, Markdown, HTML and reproducibility files, including empty searches; warn before replacing existing artifacts.

Algorithm / Methodology

• Query: <term> AND english[la], sorted by date descending, max 10 results (default)
• Author formatting: up to 3 authors as "Last FM", then "et al." if more exist
• Abstract: preserve all Abstract/AbstractText elements in order, including nested inline text. Keep Label and NlmCategory separately. Join nonempty section texts with blank lines for the full abstract. Missing labels/categories are JSON null; missing abstracts have empty text and an empty section list.
• Excerpt: first sentence heuristic — split on a period and whitespace followed by an uppercase letter, max 300 characters. This is an opening excerpt, not a findings summary.
• LLM: use the full abstract and title with the versioned prompt in abstract_summary.py. Request 1–2 short sentences, aiming for 25–40 words total, focused on the main finding and essential context. Attribute findings or interpretations to the paper or authors, distinguishing experimental reports, observational associations, reviews and hypotheses when supported by the supplied text. Preserve the strength of the evidence; do not present associations as causes or proposals as established results. Omit procedural or mechanistic details unless central to the finding. Retain material uncertainty and the experimental setting without appending generic caveats. These are prompt instructions, not a hard text cutoff or an independent assessment of scientific validity. No full-text article is fetched. Generated summaries need human review against the source.
• Failures: provider errors (including empty, refused or unfinished responses) produce an excerpt for that paper and a recorded warning. Missing abstracts skip the model and use method unavailable. Programming errors are not silently converted to excerpts.
• All NCBI requests include tool=clawbio&email=hello@clawbio.ai.
• Network timeout: 10 seconds