pubmed-summariser

Files (12)

• SKILL.md
• abstract_summary.py
• .env.example · examples/
• README.md · examples/
• run_briefing.py · examples/
• pubmed_api.py
• pubmed_summariser.py
• __init__.py · tests/
• sample_papers.json · tests/fixtures/
• test_pubmed_api.py · tests/
• test_pubmed_summariser.py · tests/
• test_workflow.py · tests/

SKILL.md (first lines)

# 📄 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

| Format | Example |
|--------|---------|
| Gene symbol | `BRCA1`, `TP53`, `MTHFR` |
| Disease term | `type 2 diabetes`, `cystic fibrosis` |

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

```bash
# 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](examples/README.md) for environment activation, editable provider settings, and inspecting saved results. `--input` remains available for your own query text file.

| Option | Behavior |
|---|---|
| `--summary-method first-sentence\|llm` | Default `first-sentence`: copies the abstract opening, up to 300 characters; no AI model is used |
| `--provider openai\|ollama` | Required with `llm`; rejected in first-sentence mode |
| `--model` | Model name; otherwise `OPENAI_MODEL` / `OLLAMA_MODEL`, then `CLAWBIO_MODEL` |
| `--base-url` | Optional API endpoint; defaults to provider environment setting or standard endpoint |
| `--llm-timeout` | Positive seconds per request; default 120 |
| `--summary-max-tokens` | Optional positive output budget; omitted means the model/server default |
| `--model-params` | JSON generation settings; no forced temperature |
| `--max-results` | Positive count, default 10, capped at 50 with a warning |

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

## Output Structure

```text
<output>/
  report.md
  report.html
  result.json
  reproducibility/
    commands.sh
    environment.yml
    checksums.sha256
```

Reports and terminal output use the labels **Abstract opening — no AI**, **AI summary — provider / model**, or **Abstract unavailable**. The saved method identifiers are `first-sentence`, `llm`, and `unavailable`. HTML provides expandable full abstracts and section labels.

`result.json` uses the shared ClawBio envelope (`skill`, `version`, `completed_at`, `input_checksum`, `datasets`, `summary`, `data`). `summary` contains paper and fallback counts. `data` contains the query, retrieval time, search settings, requested summary configuration, warnings and `papers`.

Each paper contains `title`, `authors` (display string), `journal`, `date`, `pmid`, `url`, **complete** `abstract`, `abstract_sections`, and `summary`. The summary object contains `text`, actual `method`, `provider`, `model`, `prompt_version`, token `usage`, and `fallback_reason`. Provider/model describe successful generation; on fallback they are null and the attempted configuration remains in `data.summary_config`.

**API change from 0.1.0:** `fetch_papers()` now returns full text in `abstract`; callers needing the old short text should use the separate excerpt function or the saved summary. Abstracts are never shortened in the API parser.

The reproducibility bundle records the resolved command and suggested dependencies, with output-relative checksums. It contains no API keys. Bash and the original checkout are required to execute `commands.sh`; paths may need adjustment on another machine. It repeats a live search, so PubMed records and LLM responses may change. Saved JSON preserves the source text and summaries from the original run.

## Example Output

Synthetic illustration of one paper's summary object:

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio