MetaScreener

<p align="center"> <h1 align="center">MetaScreener</h1> <p align="center"> Open-source multi-LLM ensemble for systematic review workflows </p> </p> <p align="center"> <a href="https://pypi.org/project/metascreener/"><img alt="PyPI" src="https://img.shields.io/pypi/v/metascreener?include_prereleases&color=blue"></a> <a href="https://hub.docker.com/r/chaokunhong/metascreener"><img alt="Docker" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fhub.docker.com%2Fv2%2Frepositories%2Fchaokunhong%2Fmetascreener%2Ftags%2Flatest&query=name&label=docker&color=blue"></a> <a href="https://github.com/ChaokunHong/MetaScreener/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ChaokunHong/MetaScreener/actions/workflows/ci.yml/badge.svg"></a> <a href="https://opensource.org/licenses/Apache-2.0"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg"></a> <a href="https://www.python.org/downloads/"><img alt="Python" src="https://img.shields.io/badge/python-3.11%2B-blue.svg"></a> </p>

---

What is MetaScreener?

MetaScreener is a free, open-source tool that helps researchers do systematic reviews faster using AI.

A systematic review is a type of research where you search for all published studies on a topic, decide which ones are relevant (screening), pull out the key data (extraction), and assess quality (risk-of-bias). This process normally takes weeks or months of manual work. MetaScreener automates the tedious parts using 4 AI language models that work together to make decisions — while keeping a human in the loop for uncertain cases.

In plain terms: You give MetaScreener your search results (e.g., from PubMed), tell it what you're looking for, and it reads each paper's title and abstract and tells you which ones are relevant. It can also extract data from PDFs and assess study quality.

Note: Looking for MetaScreener v1? See the v1-legacy branch.

Three ways to use MetaScreener

| Method | Best for | What it looks like | |--------|----------|-------------------| | Web UI (metascreener serve) | Most users — point-and-click in your browser | A modern web application at http://localhost:8000 | | Interactive CLI (metascreener) | Terminal users who prefer guided prompts | A step-by-step command-line wizard | | Direct CLI (metascreener screen ...) | Power users, scripting, and automation | One-line commands with flags |

All three methods use the same underlying AI engine and produce identical results.

---

Table of Contents

• Prerequisites — What You Need Before Starting
• Installation (Step by Step)
  • Option A: Install with pip (recommended)
  • Option B: Install in PyCharm
  • Option C: Install with Docker (no Python needed)
  • Option D: Install from source (for developers)
• Configuration — Get Your API Key
  • Step 1: Get a free API key
  • Step 2: Set the API key
  • Setting the API key in PyCharm
  • Step 3: Verify it works
• Quick Start — Your First Screening
• User Guide: Web UI
• User Guide: Command Line
• Command Reference
• How It Works
• Supported File Formats
• Reproducibility
• Troubleshooting
• FAQ
• Development
• Citation
• License

---

Prerequisites — What You Need Before Starting

Before installing MetaScreener, make sure you have:

1. Python 3.11 or higher

Check if you already have Python:

Open a terminal (see below) and type:

python --version

If you see Python 3.11.x or higher (3.12, 3.13, etc.), you're good. Skip to Installation.

If you see an older version, or command not found, you need to install Python.

How to install Python:

1. Go to https://www.python.org/downloads/
2. Download Python 3.12 (or the latest 3.x version)
3. Run the installer
   • IMPORTANT (Windows): Check the box that says "Add Python to PATH" at the bottom of the installer. If you miss this, MetaScreener commands won't work.
   • macOS: The installer handles PATH automatically.
4. After installation, close and reopen your terminal, then verify: python --version

Windows users: If python --version still doesn't work after installing, try python3 --version or py --version. Windows sometimes uses different command names.

2. A terminal (command line)

• macOS: Open Terminal (press Cmd + Space, type "Terminal", press Enter)
• Windows: Open PowerShell (press Win + X, select "Windows PowerShell") or Command Prompt (press Win + R, type cmd, press Enter)
• Linux: Open your distribution's terminal emulator (usually Ctrl + Alt + T)
• PyCharm: Click Terminal tab at the bottom of the PyCharm window (see PyCharm section for details)

3. An internet connection

MetaScreener calls cloud AI services to run its language models. You need internet access during screening, extraction, and quality assessment.

4. An API key (free)

MetaScreener uses open-source AI models hosted by cloud providers. You need a free API key from OpenRouter or Together AI. We'll set this up in the Configuration section.

---

Installation (Step by Step)

Option A: Install with pip (recommended)

This is the simplest method. Open a terminal and run:

pip install metascreener

If this fails, try one of these alternatives:

# Some systems use pip3 instead of pip
pip3 install metascreener

# If you get a "permission denied" error
pip install --user metascreener

# If you use Python 3 explicitly
python3 -m pip install metascreener

Verify the installation:

metascreener --help

You should see output like:

Usage: metascreener [OPTIONS] COMMAND [ARGS]...

  MetaScreener — AI-assisted systematic review tool.

Commands:
  assess-rob  Assess risk of bias for included studies.
  evaluate    Evaluate screening performance against gold-standard labels.
  export      Export results in various formats.
  extract     Extract structured data from PDFs.
  init        Generate structured review criteria using AI.
  screen      Screen literature against review criteria using HCN.
  serve       Launch the MetaScreener Web UI.
  ui          Launch the Streamlit evaluation dashboard.

If you see this, MetaScreener is installed correctly. Skip to Configuration.

If you see "command not found":

# Try running as a Python module
python -m metascreener --help

# Or python3
python3 -m metascreener --help

If python -m metascreener --help works but metascreener --help doesn't, it means Python's scripts directory is not in your system PATH. See Troubleshooting for how to fix this.

---

Option B: Install in PyCharm

If you use PyCharm (a popular Python IDE), follow these steps:

Step B1: Create a new project (or open your existing project)

1. Open PyCharm
2. Go to File → New Project (or open your existing project)
3. Choose a location (e.g., ~/my-review-project)
4. Under Python Interpreter, select Python 3.11 or higher
   • If you don't see Python 3.11+, click the gear icon and select Add Interpreter → System Interpreter, then browse to your Python installation
5. Click Create

Step B2: Install MetaScreener in PyCharm

Method 1: Using PyCharm's built-in package manager

1. Go to PyCharm → Settings (Mac: Cmd + ,) or File → Settings (Windows/Linux: Ctrl + Alt + S)
2. Navigate to Project → Python Interpreter
3. Click the + button (top-left of the packages list)
4. Search for metascreener
5. Click Install Package
6. Wait for installation to complete
7. Close the Settings dialog

Method 2: Using PyCharm's terminal

1. Click the Terminal tab at the bottom of the PyCharm window
2. Type:

   pip install metascreener
   

3. Press Enter and wait for installation to complete

Step B3: Verify installation in PyCharm

In PyCharm's Terminal tab, type:

metascreener --help

or:

python -m metascreener --help

You should see the command list. If not, make sure PyCharm is using the correct Python interpreter (the one where you installed MetaScreener).

Step B4: Set the API key in PyCharm

See Setting the API key in PyCharm below.

Step B5: Run MetaScreener in PyCharm

Option 1: Use the Terminal tab

Click the Terminal tab at the bottom of PyCharm and type commands directly:

metascreener serve                 # Launch Web UI
metascreener screen --help         # See screening options

Option 2: Create a Run Configuration

1. Go to Run → Edit Configurations
2. Click + → Python
3. Set:
   • Name: MetaScreener Web UI
   • Module name: metascreener.cli (select "Module name" instead of "Script path")
   • Parameters: serve
   • Environment variables: OPENROUTER_API_KEY=sk-or-v1-your-key-here
   • Working directory: your project folder
4. Click OK
5. Click the green Run button (or press Shift + F10)

This launches the Web UI. Open http://localhost:8000 in your browser.

---

Option C: Install with Docker (no Python needed)

Docker packages