Installation & Setup

Page Contents

Supported Systems: platforms and languages supported by prismAId
Toolkit Overview: the separate tools and access methods offered by prismAId
Step-by-Step Installation: instructions for installation on any platform
Additional Setup Information: supplementary guidance to help you get started

Supported Systems

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

Go Package: Full functionality for Go-based projects.
Binaries: Standalone executables for Windows, macOS, and Linux, requiring no coding skills.
Python Package on PyPI: For integration in Python scripts and Jupyter notebooks.
R Package on R-universe: Compatible with R and RStudio environments.
Julia Package from the Github repo: For integration in Julia workflows and Jupyter notebooks.

Toolkit Overview

prismAId offers several specialized tools to support systematic reviews:

Review Tool: Process systematic literature reviews based on TOML configurations
- Configure review criteria, AI model settings, and output formats
- Extract structured information from scientific papers
- Generate comprehensive review summaries
Download Tool: Acquire papers for your review
- Download PDFs directly from Zotero collections
- Download files from URL lists
Convert Tool: Transform documents into analyzable text
- Convert PDFs, DOCX, and HTML files to plain text
- Prepare documents for AI processing

Workflow Overview

AI Model Provider Account and API Key:
- Register for an account with OpenAI, GoogleAI, Cohere, or Anthropic and obtain an API key.
- Generate an API key from the provider’s dashboard.
Install prismAId:
- Follow the installation instructions below based on your preferred system.
Prepare Papers for Review:
- Download papers using the Download tool
- Convert papers to text format using the Convert tool
Define and Run the Review Project:
- Set up a configuration file (.toml) for your review project
- Use the Review tool to process your papers and extract information

Step-by-Step Installation

Option 1. Go Package

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

To add the prismaid Go package to your project:

Install with:

go get "github.com/open-and-sustainable/prismaid"

Import and use the toolkit in your code: ```go import “github.com/open-and-sustainable/prismaid”

// Run a systematic review err := prismaid.Review(tomlConfigString)

// Download papers from Zotero err := prismaid.DownloadZoteroPDFs(username, apiKey, collectionName, parentDir)

// Convert files to text err := prismaid.Convert(inputDir, “pdf,docx,html”)

Refer to full [documentation on pkg.go.dev](https://pkg.go.dev/github.com/open-and-sustainable/prismaid) for additional details.

### Option 2. Binaries

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

Download the appropriate executable for your OS from our [GitHub Releases](https://github.com/open-and-sustainable/prismaid/releases). No coding is required.

Use the command line interface to access all tools:

```bash
# Run a systematic review
./prismaid -project your_project.toml

# Download papers from Zotero (requires a TOML config file)
# First create a file zotero_config.toml with:
#   user = "your_username"
#   api_key = "your_api_key"
#   group = "Your Collection"
./prismaid -download-zotero zotero_config.toml

# Download papers from a URL list
./prismaid -download-URL paper_urls.txt

# Convert files to text (separate commands for each format)
./prismaid -convert-pdf ./papers
./prismaid -convert-docx ./papers
./prismaid -convert-html ./papers

# Initialize a new project configuration interactively
./prismaid -init

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 access to all prismAId tools:

import prismaid

# Run a systematic review
with open("project.toml", "r") as file:
    toml_config = file.read()
prismaid.review(toml_config)

# Download papers from Zotero
prismaid.download_zotero_pdfs("username", "api_key", "collection_name", "./papers")  # Full name

# Download from URL list
prismaid.download_url_list("urls.txt")

# Convert files to text
prismaid.convert("./papers", "pdf,docx,html")

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

Access all prismAId tools from R:

library(prismaid)

# Run a systematic review
toml_content <- paste(readLines("project.toml"), collapse = "\n")
RunReview(toml_content)  # Note the capitalization

# Download papers from Zotero
DownloadZoteroPDFs("username", "api_key", "collection_name", "./papers")  # Full name

# Download from URL list
DownloadURLList("urls.txt")

# Convert files to text
Convert("./papers", "pdf,docx,html")  # Note the capitalization

Option 5. Julia Package

(Supported: Linux and Windows AMD64, macOS Arm64)

Install the PrismAId package using Julia’s package manager:

using Pkg
Pkg.add("PrismAId")

Access all prismAId tools from Julia:

using PrismAId

# Run a systematic review
toml_config = read("project.toml", String)
PrismAId.run_review(toml_config)  # Correct function name

# Download papers from Zotero
PrismAId.download_zotero_pdfs("username", "api_key", "collection_name", "./papers")  # Full name

# Download from URL list
PrismAId.download_url_list("urls.txt")

# Convert files to text
PrismAId.convert("./papers", "pdf,docx,html")

Additional Setup Information

Initialize the Configuration File

prismAId offers multiple ways to create review configuration files:

Web Initializer: Use the browser-based tool on the Review Configurator page to create TOML configuration files through a user-friendly interface.
Command Line Initializer: Use the binary with the -init flag to create a configuration file through an interactive terminal:
```
./prismaid -init
```

Terminal app for drafting project configuration file

Use in Jupyter Notebooks

When using versions <= 0.6.6 it is not possible to disable the prompt asking the user’s confirmation 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)