ChaokunHong / MetaScreener

MetaScreener Open-source multi-LLM ensemble for systematic review workflows --- 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 branch. Three ways to use MetaScreener | Method | Best for | What it looks like | |--------|----------|-------------------| | **Web UI** ( ) | Most users — point-and-click in your browser | A modern web application at | | **Interactive CLI** ( ) | Terminal users who prefer guided prompts | A step-by-step command-line wizard | | **Direct CLI** ( ) | 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: • Python 3.11 or higher **Check if you already have Python:** Open a terminal (see below) and type: If you see or higher (3.12, 3.13, etc.), you're good. Skip to Installation. If you see an older version, or , you need to install Python. **How to install Python:** • Go to https://www.python.org/downloads/ • Download Python 3.12 (or the latest 3.x version) • 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. • After installation, close and reopen your terminal, then verify: > **Windows users:** If still doesn't work after installing, try or . Windows sometimes uses different command names. • A terminal (command line) • **macOS:** Open **Terminal** (press , type "Terminal", press Enter) • **Windows:** Open **PowerShell** (press , select "Windows PowerShell") or **Command Prompt** (press , type , press Enter) • **Linux:** Open your distribution's terminal emulator (usually ) • **PyCharm:** Click **Terminal** tab at the bottom of the PyCharm window (see PyCharm section for details) • An internet connection MetaScreener calls cloud AI services to run its language models. You need internet access during screening, extraction, and quality assessment. • 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: **If this fails**, try one of these alternatives: **Verify the installation:** You should see output like: If you see this, MetaScreener is installed correctly. Skip to Configuration. **If you see "command not found":** If works but 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) • Open PyCharm • Go to **File → New Project** (or open your existing project) • Choose a location (e.g., ) • 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 • Click **Create** Step B2: Install MetaScreener in PyCharm **Method 1: Using PyCharm's built-in package manager** • Go to **PyCharm → Settings** (Mac: ) or **File → Settings** (Windows/Linux: ) • Navigate to **Project → Python Interpreter** • Click the **+** button (top-left of the packages list) • Search for **metascreener** • Click **Install Package** • Wait for installation to complete • Close the Settings dialog **Method 2: Using PyCharm's terminal** • Click the **Terminal** tab at the bottom of the PyCharm window • Type: • Press Enter and wait for installation to complete Step B3: Verify installation in PyCharm In PyCharm's Terminal tab, type: or: 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: **Option 2: Create a Run Configuration** • Go to **Run → Edit Configurations** • Click **+** → **Python** • Set: • **Name:** MetaScreener Web UI • **Module name:** (select "Module name" instead of "Script path") • *…