Merge pull request #67 from open-and-sustainable/42-add-pipeline-to-p…

…ublish-prismaid-as-python-package

42 add pipeline to publish prismaid as python package

.github/workflows/build_shared.yml

@@ -0,0 +1,163 @@
+name: Build and Deploy Shared Libraries
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build-linux:
+    name: Build Linux Shared Library
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Build shared library for Linux
+        working-directory: python
+        run: |
+          go build -buildmode=c-shared -o package/libprismaid_linux_amd64.so export.go
+
+      - name: Upload Linux shared library artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: linux-shared-library
+          path: python/package/libprismaid_linux_amd64.so
+
+  build-windows:
+    name: Build Windows Shared Library
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Build shared library for Windows
+        working-directory: python
+        shell: pwsh
+        run: |
+          go build -buildmode=c-shared -o package/libprismaid_windows_amd64.dll .\export.go
+
+      - name: Upload Windows shared library artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-shared-library
+          path: python/package/libprismaid_windows_amd64.dll
+
+  build-macos:
+    name: Build macOS Shared Library
+    runs-on: macos-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Build shared library for macOS
+        working-directory: python
+        run: |
+          go build -buildmode=c-shared -o package/libprismaid_darwin_amd64.dylib export.go
+
+      - name: Upload macOS shared library artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-shared-library
+          path: python/package/libprismaid_darwin_amd64.dylib
+
+  # Package the Python Project Locally
+  package-python:
+    name: Package Python Project with All Shared Libraries
+    runs-on: ubuntu-latest
+    needs: [build-linux, build-windows, build-macos]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 
+
+      - name: Copy files for Build
+        run: |
+          cp README.md python/README.md
+          cp LICENSE python/LICENSE   
+                 
+      # Download artifacts from build jobs
+      - name: Download macOS shared library artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: macos-shared-library
+          path: python/prismaid/
+
+      - name: Download Linux shared library artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: linux-shared-library
+          path: python/prismaid/
+
+      - name: Download Windows shared library artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: windows-shared-library
+          path: python/prismaid/
+
+      - name: Install build tools
+        working-directory: ./python
+        run: |
+          python -m pip install --upgrade pip setuptools wheel build
+
+      - name: Build Python package
+        working-directory: ./python
+        run: |
+          python -m build
+
+      - name: Upload Python Package Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: prismaid-python-package
+          path: python/dist/*.whl
+
+  publish-to-pypi:
+    name: Publish Python distribution to PyPI
+    needs: package-python  # Ensure it waits for the packaging job
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download Python Package Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: prismaid-python-package
+          path: dist/
+
+      - name: Install Twine
+        run: python -m pip install --upgrade twine
+
+      - name: Publish distribution to PyPI
+        env:
+          TWINE_USERNAME: "__token__"
+          TWINE_PASSWORD: "${{ secrets.PYPY_API_TOKEN }}"
+        run: |
+          twine upload --repository-url https://pypi.org/legacy/ dist/*
+

.github/workflows/go.yml

@@ -1,4 +1,4 @@
-name: Go CI
+name: Go Module CI
 
 # Trigger the workflow on push to the main branch and on pull requests
 on:

CHANGELOG

@@ -9,11 +9,13 @@ Removed: For features removed in this release.
 Fixed: For any bug fixes.
 Security: For vulnerabilities.
 
-## [0.5.6] - forthcoming
+## [0.6.0] - 2024-10-25
 ### Added
-- release as Go package at github.com/Open-and-Sustainable/prismAId
+- release of the project as Go package at github.com/Open-and-Sustainable/prismAId
+- release of Python package at https://pypi.org/project/prismaid/
 ### Fixed
 - updated documentation to include Go package download and installation
+- updated documentation to include Python package
 
 ## [0.5.5] - 2024-10-23
 ### Added

CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 title: prismAId - Open Science AI Tools for Systematic, Protocol-Based Literature Reviews
 message: >-
-  v0.5.5 - added unit testing
-  Added unit testing of each package, CI/CD automation, and light code refactoring for API testing
+  v0.6.0 - added Go and Python package release
+  Added Go module and Python wrapper package updated through CI/CD automation
 type: software
 doi: 10.5281/zenodo.11210796
 authors:

README.md

@@ -18,7 +18,7 @@ No coding skills are required to use prismAId.
 
 ## Specifications
 - **Review protocol**: Designed to support any literature review protocol with a preference for [Prisma 2020](https://www.prisma-statement.org/prisma-2020), which inspired our project name.
-- **Distribution**: As Go [package](https://pkg.go.dev/github.com/open-and-sustainable/prismaid) or 'no-coding' binaries compatible with Windows, MacOS, and Linux operating systems on AMD64 and ARM64 platforms.
+- **Distribution**: Go [package](https://pkg.go.dev/github.com/open-and-sustainable/prismaid), Python [package](https://pypi.org/project/prismaid/), and 'no-coding' [binaries](https://github.com/open-and-sustainable/prismaid/releases) compatible with Windows, MacOS, and Linux operating systems on AMD64 and ARM64 platforms.
 - **Supported LLMs**: 
     1. **OpenAI**: GPT-3.5 Turbo, GPT-4 Turbo, GPT-4o, and GPT-4o Mini.
     2. **GoogleAI**: Gemini 1.0 Pro, Gemini 1.5 Pro, and Gemini 1.5 Flash.

docs/for-developers.md

@@ -36,54 +36,6 @@ Our architecture is designed to be robust yet simple, ensuring that the tool rem
 - **Open Source**: We embrace an open-source model, encouraging community contributions and transparency in development.
 - **Continuous Integration/Continuous Deployment (CI/CD)**: We utilize CI/CD pipelines to maintain high standards of quality and reliability, automatically testing and deploying new versions as they are developed.
 
-## Software Dependencies
-
-```text
-command-line-arguments
-  ├ flag
-  ├ fmt
-  ├ io
-  ├ log
-  ├ os
-  ├ path/filepath
-  ├ prismAId/config
-    ├ os
-    └ github.com/BurntSushi/toml
-  ├ prismAId/cost
-    ├ bufio
-    ├ fmt
-    ├ log
-    ├ os
-    ├ strings
-    ├ github.com/pkoukk/tiktoken-go
-    ├ github.com/sashabaranov/go-openai
-    ├ github.com/shopspring/decimal
-    └ prismAId/config
-  ├ prismAId/llm
-    ├ context
-    ├ encoding/json
-    ├ fmt
-    ├ log
-    ├ github.com/sashabaranov/go-openai
-    ├ prismAId/config
-    └ prismAId/cost
-  ├ prismAId/prompt
-    ├ encoding/json
-    ├ fmt
-    ├ log
-    ├ os
-    ├ path/filepath
-    ├ sort
-    ├ strings
-    └ prismAId/config
-  └ prismAId/results
-    ├ bytes
-    ├ encoding/csv
-    ├ encoding/json
-    ├ log
-    ├ os
-    └ strings
-```
 
 <div id="wcb" class="carbonbadge"></div>
 <script src="https://unpkg.com/website-carbon-badges@1.1.3/b.min.js" defer></script>

docs/getting-started.md

@@ -41,12 +41,16 @@ Most AI tools for systematic literature reviews focus on the literature search p
   - prismAId processes the JSON files returned by the AI model, converting the extracted information into the user-specified format.
   - To facilitate cost management, prismAId tokenizes each single-shot prompt and estimates the execution cost, allowing users to understand the total review cost before proceeding.
 
-## Installation
-To use prismAId, you have two options.
+## Installation and Use
+To utilize prismAId, there are multiple options available:
 
-### Option 1. Binaries 
-Download the appropriate executable for your operating system and platform from our [GitHub Releases](https://github.com/open-and-sustainable/prismaid/releases) page. Using executables does not require any coding skill.
-### Option 2. Go Package
+1. Go Package: Developed in Go, prismAId offers its complete functionalities through a Go package, ideal for integration within Go projects.
+
+2. Python Package: For users preferring Python, prismAId is also available as a Python package, facilitating use within Python scripts and Jupyter notebooks.
+
+3. Binaries: Standalone binaries are available for all operating systems and platforms, providing a versatile option for users across different environments.
+
+### Option 1. Go Package
 You can download the prismAId Go package for developing your own software or review project. To add the package to yoru project:
 ```bash
 go get "github.com/open-and-sustainable/prismaid"
@@ -56,7 +60,41 @@ Once added, it can be imported when needed with:
 import "github.com/open-and-sustainable/prismaid"
 ```
 The package documentation is available on [pkg.go.dev](https://pkg.go.dev/github.com/open-and-sustainable/prismaid).
-## Running prismAId binaries
+
+### Option 2. Python Package
+You can download and install the prismAId Python package from [PYPI](https://pypi.org/project/prismaid/):
+```bash
+pip install prismaid
+```
+
+The prismAId Python package provides a convenient interface for Python users by wrapping a C shared library. This integration allows users to manipulate project configurations and manage review processes directly within Python scripts and Jupyter notebooks. Users can configure input parameters for reviews and analyze the outputs, making it an effective tool for handling the review results all within the Python ecosystem.
+
+Once installed, prismAId can be imported and used, for instance:
+```python
+import prismaid  # Import the package, which automatically loads the correct shared library for the OS
+from ctypes import c_char_p
+
+# As an example, load the project example of review project configuration
+with open("proj_test.toml", "r") as file:
+    input_str = file.read()
+
+# Call the RunReviewPython function from the prismaid package
+error_ptr = prismaid.RunReviewPython(input_str.encode('utf-8'))
+
+if error_ptr:
+    # An error occurred, retrieve and display the error message
+    error_message = error_ptr.decode('utf-8')
+    print("Error:", error_message)
+    # Free the allocated error message string if necessary
+    prismaid.lib.FreeCString(error_ptr)
+else:
+    # No error occurred
+    print("RunReview completed successfully")
+```
+
+### Option 3. Binaries 
+Download the appropriate executable for your operating system and platform from our [GitHub Releases](https://github.com/open-and-sustainable/prismaid/releases) page. Using executables does not require any coding skill.
+
 The tool uses humaly readable project configuration files (.toml) to configure and run the reviews.
 
 You can find a template and an example on the [GitHub repository](https://github.com/open-and-sustainable/prismaid/tree/main/projects).

docs/index.md

@@ -10,7 +10,7 @@ prismAId uses generative AI models to extract data from scientific literature. I
 
 ## Specifications
 - **Review protocol**: Designed to support any literature review protocol with a preference for [Prisma 2020](https://www.prisma-statement.org/prisma-2020), which inspired our project name.
-- **Distribution**: As Go [package](https://pkg.go.dev/github.com/open-and-sustainable/prismaid) or 'no-coding' binaries compatible with Windows, MacOS, and Linux operating systems on AMD64 and ARM64 platforms.
+- **Distribution**: Go [package](https://pkg.go.dev/github.com/open-and-sustainable/prismaid), Python [package](https://pypi.org/project/prismaid/), and 'no-coding' [binaries](https://github.com/open-and-sustainable/prismaid/releases) compatible with Windows, MacOS, and Linux operating systems on AMD64 and ARM64 platforms.
 - **Supported LLMs**: 
     1. **OpenAI**: GPT-3.5 Turbo, GPT-4 Turbo, GPT-4o, and GPT-4o Mini.
     2. **GoogleAI**: Gemini 1.0 Pro, Gemini 1.5 Pro, and Gemini 1.5 Flash.

docs/project-setup.md

@@ -9,18 +9,8 @@ layout: default
 1. **AI Model Provider Account and API Key:**
     - Create an account at [OpenAI](https://www.openai.com/) or [GoogleAI](https://aistudio.google.com) or [Cohere](https://cohere.com/).
     - Generate an API key from the the provider dashboard.
-2. **Download Executable or Go Package:**
-    - Visit the [releases](https://github.com/open-and-sustainable/prismaid/releases) section of the prismAId GitHub repository.
-    - Download the appropriate executable for your operating system and platform.
-    - If you prefer, you can add the package to your software with
-    ```bash
-    go get "github.com/Open-and-Sustainable/prismaid"
-    ```
-    and then import it when needed with
-    ```go
-    import "github.com/Open-and-Sustainable/prismaid"
-    ```
-    Its documentation is available on [pkg.go.dev](https://pkg.go.dev/github.com/open-and-sustainable/prismaid).
+2. **Install the Software:**
+    - Follow instructions in [Getting Started](getting-started).
 3. **Prepare Papers for Review:**
     - Ensure that all papers to be reviewed are in .txt format.
     - prismAId offers the ability to automatically convert files in PDF, DOCX, and HTML formats into plain text. To enable this conversion, use the `input_conversion` flag in the `[project.configuration]` section of the review project configuration. Once activated, files are converted to `.txt` format, allowing for further processing and inspection. Since the conversion results are saved as `.txt` files, there is no need to rerun the conversion multiple times.

python/MANIFEST.in

@@ -0,0 +1,7 @@
+# MANIFEST.in
+include README.md
+include LICENSE
+include prismaid/libprismaid_linux_amd64.so
+include prismaid/libprismaid_windows_amd64.dll
+include prismaid/libprismaid_darwin_amd64.dylib
+