prismAId

Installation & Workflow

Supported Systems

prismAId is accessible across multiple platforms, offering flexibility based on user preference and system requirements:

  1. Go Package: Full functionality for Go-based projects.

  2. Binaries: Standalone executables for Windows, macOS, and Linux, requiring no coding skills.

  3. Python Package on PyPI: For integration in Python scripts and Jupyter notebooks.

  4. R Package on R-universe: Compatible with R and RStudio environments.

  5. Julia Package from the Github repo: For integration in Julia workflows and Jupyter notebooks.

Workflow Overview

  1. AI Model Provider Account and API Key:
    • Register for an account with OpenAI, GoogleAI, Cohere, or Anthropic and obtain an API key from your provider’s dashboard.
    • Generate an API key from the the provider dashboard.
  2. Install prismAId:
    • Follow the installation instructions below based on your preferred system from the Supported Systems section.
  3. Prepare Papers for Review:
    • Ensure papers are in .txt format, or use prismAId input_conversion flag in [project.configuration] to convert PDF, DOCX, and HTML files to plain text.
  4. Define the Review Project:
    • Set up a configuration file (.toml) specifying project parameters, including the AI model, input data, and output preferences. This configuration defines the scope and details of your systematic review.

Step-by-Step Installation

Option 1. Go Package

(Supported: Linux, macOS, Windows; AMD64, Arm64)

To add the prismaid Go package to your project:

  1. Install with: 
    go get "github.com/open-and-sustainable/prismaid"
  2. Import when needed: 
    import "github.com/open-and-sustainable/prismaid"

Refer to full documentation on pkg.go.dev for additional details.

Option 2. Binaries

(Supported: Linux, macOS, Windows; AMD64, Arm64)

Download the appropriate executable for your OS from our GitHub Releases. No coding is required.

prismAId uses a human-readable .toml project configuration file for setup. You can find a template and example in the GitHub repository. Once your .toml file is ready, execute the project with:

# For Windows
./prismAId_windows_amd64.exe -project your_project.toml

Option 3. Python Package

(Supported: Linux and Windows AMD64, macOS Arm64)

Install the prismaid package from PYPI with:

pip install prismaid

This Python package provides an interface that wraps a C shared library, allowing configuration and review processing within Python scripts or Jupyter notebooks. Once installed, import prismAId and use it to load and execute review projects, as shown in the example below:

import prismaid

# Example usage: load and run a review project configuration
with open("proj_test.toml", "r") as file:
    input_str = file.read()
error_ptr = prismaid.RunReviewPython(input_str.encode('utf-8'))

# Handle errors if they occur
if error_ptr:
    print("Error:", error_ptr.decode('utf-8'))
else:
    print("RunReview completed successfully")

NOTE: when using prismAId legacy versions <= 0.6.6 in Jupyter notebooks follow instructions presented below to run single model reviews.

Option 4. R Package

(Supported: Linux AMD64, macOS Arm64)

Install the prismaid R package from R-universe using:

install.packages("prismaid", repos = c("https://open-and-sustainable.r-universe.dev", "https://cloud.r-project.org"))

All inputs and outputs are file-based. For example, to load and run a review configuration:

library(prismaid)
toml_content <- paste(readLines("proj_test.toml"), collapse = "\n")
RunReview(toml_content)

Option 5. Julia Package

(Supported: Linux and Windows AMD64, macOS Arm64)

Install the PrismAId package using Julia’s package manager and running the following commands in your Julia REPL. This will add the PrismAId package directly from the Julia General registry:

using Pkg
Pkg.add("PrismAId")

This Julia package provides an interface that wraps a C shared library, allowing configuration and review processing within Julia workflows and Jupyter notebooks. Once installed, import PrismAId and use it to load and execute review projects, as shown in the example below:

# Load the package
using PrismAId
# Input a review project configuration
toml_test = """
       [project]
       name = "Test of prismAId"
       ...
       """
# Run the review
PrismAId.run_review(toml_test)

Additional Setup Information

Initialize the Configuration File

prismAId binaries and Go module offer an interactive terminal application to help create draft configuration files. Use the -init flag to start the setup:

# For Linux on Intel
./prismAId_linux_amd64 -init

Terminal app for drafting project configuration file

A web-based initializer is also availeble on the Review Configurator page.

Literature Preparation

Follow documented protocols for literature search and identification, such as PRISMA 2020. You may remove non-essential sections, like reference lists, abstracts, and introductions, which typically do not contribute relevant information. Exercise caution when including review articles unless necessary, as they can complicate analysis.

Removing unnecessary content helps reduce costs and resource usage and may improve model performance, as excessive information can negatively affect analysis outcomes.

Additionally, the tool supports integration with Zotero, allowing you to incorporate collections and groups of literature manuscripts directly into the review process. For more details on this feature, see the Zotero Integration section.

ATTENTION: This tool provides methods to convert PDFs and other manuscript formats into text. However, due to limitations inherent in the PDF format, these conversions might be imperfect. Please manually check any converted manuscripts for completeness before further processing. Special attention may be required to ensure accuracy.

Use in Jupyter Notebooks

When using versions <= 0.6.6 it is not possible to disable the prompt asking the user’s confirmatiom to proceed with the review, leading Jupyter notebooks to crash the python engine and to the impossibility to run reviews with single models (in ensemble reviews, on the contrary, confirmation requests are automatically disabled).

To overcome this problem, it is possible to intercept the IO on the terminal as it follows:

import pty
import os
import time
import select

def run_review_with_auto_input(input_str):
    master, slave = pty.openpty()  # Create a pseudo-terminal

    pid = os.fork()
    if pid == 0:  # Child process
        os.dup2(slave, 0)  # Redirect stdin
        os.dup2(slave, 1)  # Redirect stdout
        os.dup2(slave, 2)  # Redirect stderr
        os.close(master)
        import prismaid
        prismaid.RunReviewPython(input_str.encode("utf-8"))
        os._exit(0)

    else:  # Parent process
        os.close(slave)
        try:
            while True:
                rlist, _, _ = select.select([master], [], [], 5)
                if master in rlist:
                    output = os.read(master, 1024).decode("utf-8", errors="ignore")
                    if not output:
                        break  # Process finished

                    print(output, end="")

                    if "Do you want to continue?" in output:
                        print("\n[SENDING INPUT: y]")
                        os.write(master, b"y\n")
                        time.sleep(1)
        finally:
            os.close(master)
            os.waitpid(pid, 0)  # Ensure the child process is cleaned up

# Load your review (TOML) configuration
with open("config.toml", "r") as file:
    input_str = file.read()

# Run the review function
run_review_with_auto_input(input_str)