giveLit: give me literature is a Typer-powered CLI that keeps laboratory teams up to date with the latest, most relevant papers from the journals they care about. It queries the Europe PMC literature service for the chosen journals, scores candidates using the supplied keywords, and renders either a sleek terminal table or a minimalist HTML report with clickable cards.

• pixi 0.48 or newer (dependency manager)

All runtime dependencies are specified in pixi.toml. No pip steps required.

# Solve the environment once
pixi install

# Show usage information
pixi run givelit --help

# Scan the default journals with a 30-day window and CLI output
pixi run givelit

$ pixi run givelit --keyword metagenomics --journal "Nature Microbiology" --limit 2 --days 30

giveLit — give me literature
✦ Keywords: "metagenomics"                  ✦ Days window: last 30 days
✦ Limit: 2                                  ✦ Sort: Score
✦ Coverage: All                             ✦ Journals searched (1) [Nature Microbiology]

Coverage: Full (all 1 keyword matched)

Journal             Date                  Score   Days ago   Title
Nature Microbiology Wednesday, 2025-10-22 18.69   13         Long-read metagenomics for strain tracking after faecal microbiota transplant.
Nature Microbiology Thursday, 2025-10-30  12.17   5          Human immunodeficiency virus and antiretroviral therapies exert distinct influences across diverse gut microbiomes.

Generate the exact same search as a neon HTML report (keywords and journal included) with:

pixi run givelit \
  --keyword metagenomics \
  --journal "Nature Microbiology" \
  --limit 2 \
  --days 30 \
  --format web \
  --output givelit-reports/metagenomics.html

Prefer the default naming? Omit --output and giveLit will drop timestamped files such as giveLit-output__metagenomics__20250130-153000.html into the current directory.

Peek at the neon HTML cards via this live preview (renders the bundled sample HTML with clickable DOI links and giveLit scores). The cards look like:

HTML report sneak peek

• Journal: Trends in Microbiology
• Date: Tuesday, 2025-10-28
• Days ago: 7
• giveLit score: 22.60
• Authors: Tabugo SR.
• Summary: Mangroves are known worldwide but their concealed network of microbiomes is poorly understood...

# CLI output (non-interactive runs default to 244 cols; override with GIVELIT_CONSOLE_WIDTH)
docker run --rm astrogenomics/givelit:latest --keyword "gut microbiome" --journal all --limit 10

# Generate an HTML report and persist it on the host
docker run --rm \
  -v "$(pwd)/givelit-reports:/app/givelit-reports" \
  astrogenomics/givelit:latest \
  --keyword metagenomics \
  --journal "Nature Microbiology" \
  --limit 5 \
  --format web \
  --output givelit-reports/metagenomics.html

# pull the Docker Hub image into Shifter (note the docker: prefix)
shifterimg pull docker:astrogenomics/givelit:latest

# invoke the container entrypoint directly so the pixi env is activated
shifter --image=docker:astrogenomics/givelit:latest -- /app/entrypoint.sh --help
shifter --image=docker:astrogenomics/givelit:latest -- /app/entrypoint.sh \
  --keyword "gut microbiome" \
  --journal all \
  --limit 10

# grab the Docker image and convert it into a local SIF
apptainer pull givelit_latest.sif docker://astrogenomics/givelit:latest
apptainer pull docker://astrogenomics/givelit:latest

# execute the bundled entrypoint so the pixi environment loads automatically
apptainer exec givelit_latest.sif /app/entrypoint.sh --help
apptainer exec givelit_latest.sif /app/entrypoint.sh \
  --keyword "gut microbiome" \
  --journal all \
  --limit 10

• Add more keywords by repeating --keyword/-k.
• Choose journals by repeating --journal/-j with either the predefined keys (see table below) or any journal title recognised by Europe PMC (e.g. "The ISME Journal").
• Use --journal all to include every built-in journal in a single run.
• Control freshness with --days/-d (0 disables the date filter).
• Choose the ordering strategy with --sort (score, recency, or journal).
• Trim the list with --limit/-n.
• Generate a minimalist HTML report with --format web --output path/to/report.html.
• Results always include the requested keywords; papers with zero keyword matches are filtered out automatically.
• Use --coverage full when you only want papers that match every keyword.
• Use --skip-journal/-skip to exclude specific journals (handy with --journal all).
• Add --include-preprints to pull in arXiv and bioRxiv alongside the selected journals (including --journal all). You can also target them directly with --journal arxiv or --journal biorxiv.

Example:

pixi run givelit \
  --keyword metagenomics \
  --journal nature-microbiology \
  --journal cell-systems \
  --limit 10 \
  --days 60 \
  --format web \
  --output givelit-reports/metagenomics.html

All built-in journals in one go:

pixi run givelit \
  --keyword metagenomics \
  --journal all \
  --limit 10 \
  --days 20 \
  --sort score \
  --coverage all \
  --format web \
  --output givelit-reports/metagenomics.html

All journals plus the preprint servers for a specific topic:

pixi run givelit \
  --keyword "gut microbiome" \
  --journal all \
  --include-preprints \
  --limit 10 \
  --days 10

Optional preprint sources (enabled with --include-preprints or by specifying them explicitly):

Preprint lookups are still backed by the Europe PMC API, using the publisher feed to respect your --days window.

giveLit blends three signals for each returned article:

1. Keyword density, with extra weight when terms appear in the title or abstract.
2. Europe PMC's relevance score for the underlying query.
3. A recency boost that depends on how many days ago the work was published.

The precise scoring function is:

S = 6 * T + 2.5 * B + 4 * M + (R / 10) + 6 * F + 4 / (1 + D)

Where:

• T = number of keyword hits in the title.
• B = number of keyword hits in the title + abstract (case-insensitive).
• M = number of distinct query keywords that appear at least once.
• R = Europe PMC relevance score from the API response (0 when unavailable).
• D = days since publication (0 for same-day releases; if unknown, the recency terms are omitted).
• F = max(0, 1 - min(D, W) / W) with W = max(requested_days, 30) - a freshness factor bounded between 0 and 1.

The final score is rounded to two decimals. Scores and the associated D ("days ago") are displayed in both the CLI and HTML reports.

By default, giveLit sorts by decreasing score and, within ties, by increasing D. Use --sort recency to prioritise fresher items or --sort journal to group by journal name.

Articles are grouped per journal and interleaved to guarantee that every requested journal is represented before the overall limit is reached. Remaining slots (if any) are backfilled by the highest-scoring papers regardless of journal.

• giveLit uses the Europe PMC REST API to perform (keyword1 OR keyword2 ...) AND JOURNAL:"name" searches with an optional publication date window.
• Returned metadata (title, authors, abstract, DOI, relevance score) is normalised and stored locally in memory only.
• Europe PMC requires no API keys, but we ship a descriptive User-Agent so that traffic is easy to attribute.

• The project stays Python-only for maximum portability. Contributions are welcome!

For questions or feedback, reach out to Juan at juanv@linux.com

docker login -u astrogenomics

docker buildx build --push \
  --platform linux/amd64,linux/arm64 \
  --tag astrogenomics/givelit:latest .

docker pull astrogenomics/givelit:latest

docker run --rm -it astrogenomics/givelit:latest --help

docker run --rm astrogenomics/givelit:latest --keyword "gut microbiome" --journal all --limit 10

docker run --rm \
  -v "$(pwd)/givelit-reports:/app/givelit-reports" \
  astrogenomics/givelit:latest \
  --keyword metagenomics \
  --journal "Nature Microbiology" \
  --limit 5 \
  --format web \
  --output givelit-reports/metagenomics.html