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")

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

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.

Cost Estimation at Startup

After loading the project configuration, prismAId provides an estimated cost (in USD) to run the review using the specified OpenAI model. This estimate primarily reflects the input processing cost, which is typically the largest component in review projects.

To proceed, the user must confirm by entering ‘y’; otherwise, the process exits without making API calls, ensuring no cost is incurred:

Total cost (USD - $): 0.0035965
Do you want to continue? (y/n): 

Note: Cost estimation is only available when a single model is configured; ensemble reviews do not include this feature.