pysyrev 0.1.5

pysyrev (PYthon SYstematic REView) is an automated, LLM-assisted PRISMA workflow for systematic literature reviews. It covers the full pipeline — from raw bibliographic records to screened, deduplicated, and thematically structured corpora — and produces a PDF report at the end.

Features

• Multi-source ingestion — Web of Science (file or REST API), OpenAlex (file or REST API), Scopus, PubMed
• Automatic deduplication — fuzzy title matching across sources
• LLM-based title/abstract screening — multi-reviewer workflows with majority or mean voting, powered by any provider supported by LiteLLM (Anthropic, OpenAI, Ollama, LiteLLM proxy…)
• Bibliographic network analysis — bibliographic coupling and co-citation graphs exported as GraphML
• Topic modelling — BERTopic-based clustering with UMAP + HDBSCAN grid search, ranked by coherence scores
• PDF report generation — declarative, theme-aware PDF engine built on ReportLab

Pipeline stages

All sections are optional — only the stages declared in the config file are executed. Each stage auto-detects the most recent output of the previous one when run standalone.

Installation

Prerequisite: Python ≥ 3.10.

From PyPI

pip install pysyrev

To enable Plotly figure embedding in PDF reports:

pip install "pysyrev[plotly]"

From source

git clone <repo-url>
cd pysyrev
pip install -e .

Documentation

Documentation is available from here

Quick start

CLI

# Check the installed version
pysyrev --version

# Run all configured stages (only stages present in the config are executed)
pysyrev config.yaml

# Run a single stage
pysyrev config.yaml --stage bib
pysyrev config.yaml --stage review
pysyrev config.yaml --stage bib-network
pysyrev config.yaml --stage topic-model
pysyrev config.yaml --stage topic-report

If the pysyrev command is not available (e.g. editable install not yet registered), use python -m pysyrev as a drop-in replacement.

Python API

from pysyrev import Pipeline

# Full pipeline in one call — runs only the stages declared in the config
pipeline = Pipeline.from_config("config.yaml")
pipeline.run()

# Or stage by stage — results persist on the instance between calls
pipeline.run(stages=["bib"])
pipeline.run(stages=["review"])        # uses pipeline.bib.dataset automatically
pipeline.run(stages=["topic-report"])  # generates the PDF report

# Access results
df_all    = pipeline.bib.dataset          # pd.DataFrame — all collected documents
df_kept   = pipeline.review.included_docs # pd.DataFrame — LLM-screened inclusions
network   = pipeline.network              # BibNetwork
topic     = pipeline.topic                # TopicModel
report    = pipeline.report               # TopicReport

Report-only run

A config containing only the topic_report (and optionally report and llm) sections is valid. This lets you generate or regenerate a report from a previous topic-model run without re-running the full pipeline:

# report_only.yaml
topic_report:
  run_dir: /path/to/topic_modeling/run_2026-05-01T120000/  # or leave blank to auto-detect
  model_index: 0
  export_to: /path/to/output/report/

pysyrev report_only.yaml

Configuration

A single YAML file controls all stages. Copy pysyrev/config_examples/config_template.yaml and fill in the sections you need. Sections not present in the file are simply skipped.

Key auto-detection rules (when fields are left blank):

Getting started

See the tutorials/ folder for step-by-step Jupyter notebooks and annotated configuration examples covering each pipeline stage.

Contributing

Development and improvement

• Benjamin Pillot
• Théo Chamarande
• Kevin Chapuis

Conceptualization and Coordination

• Benjamin Pillot