Merge pull request #1 from MassBank/dev

Merge dev to main

.github/workflows/create-docker.yml

@@ -0,0 +1,51 @@
+name: Create Docker Container
+
+on:
+  push:
+    branches:
+      - 'main'
+      - 'dev'
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-push-images:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - dockerfile: ./similarity-service-cosine/Dockerfile
+            image: ipbhalle/massbank3-similarity-service-cosine
+            context: ./similarity-service-cosine
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ipbhalle/massbank3-similarity-service
+          tags: |
+            # tag event
+            type=ref,event=tag
+            # set latest tag for main branch and tags
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') }}
+            # set dev tag for dev branch
+            type=raw,value=dev,enable=${{ github.ref == 'refs/heads/dev' }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -159,4 +159,6 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
+
+openapi-generator/

Dockerfile

@@ -0,0 +1,22 @@
+FROM maven:3.9-eclipse-temurin-21
+RUN apt-get update && apt-get install -y --no-install-recommends jq && rm -rf /var/lib/apt/lists/*
+
+COPY generate.sh config-openapi.yaml openapi.yaml /usr/src/app/
+
+WORKDIR /usr/src/app
+RUN bash generate.sh
+
+FROM python:3.12-slim-bookworm
+WORKDIR /usr/src/app
+COPY requirements.txt /usr/src/app/
+RUN pip3 install --root-user-action=ignore --upgrade pip && pip3 install --root-user-action=ignore --no-cache-dir -r requirements.txt
+
+COPY --from=0 /usr/src/app/openapi.yaml /usr/src/app/openapi.yaml
+COPY --from=0 /usr/src/app/gen /usr/src/app/gen
+COPY similarity_service_impl /usr/src/app/similarity_service_impl
+
+ENV PYTHONPATH=/usr/src/app/gen
+
+EXPOSE 8080/tcp
+ENTRYPOINT ["/usr/local/bin/waitress-serve"]
+CMD ["--port=8080", "similarity_service_impl.app:app"]

README.md

@@ -1,2 +1,46 @@
 # MassBank3-similarity-service
-A REST interface wrapping matchms/matchms 
+A REST interface wrapping [matchms](https://github.com/matchms/matchms) for MassBank3.
+
+This server was generated by the [OpenAPI Generator](https://openapi-generator.tech) project and uses
+the [Connexion](https://github.com/zalando/connexion) library on top of Flask.
+
+## Requirements
+Tested on Python 3.12
+
+## Configuration
+This microservice is configured with environment variables. The reference
+spectra are initialized from a local file. The file location needs to be
+configured in the environment variable `MSP`. For MassBank we configure the
+service with the latest MassBank-data release in msp format.
+```bash
+wget https://github.com/MassBank/MassBank-data/releases/latest/download/MassBank_NIST.msp
+export MSP="./MassBank_NIST.msp"
+```
+
+## Usage
+To run the server, install the requirements, generate the server code 
+and start the server like this:
+```bash
+pip3 install -r requirements.txt
+bash generate.sh
+PYTHONPATH=gen python3 -m similarity_service_impl
+```
+You can find the swagger ui at http://localhost:8080/ui/ and the
+OpenAPI definition at http://localhost:8080/openapi.json in your browser.
+
+## Running with Docker
+To run the server in a Docker container,  execute the following commands:
+
+```bash
+# building the image
+docker build -t massbank3-similarity-service .
+
+# download reference data
+wget https://github.com/MassBank/MassBank-data/releases/latest/download/MassBank_NIST.msp
+
+# starting up a container
+docker run -p 8080:8080 \
+-v $(pwd)/MassBank_NIST.msp:/MassBank_NIST.msp \
+-e MSP='/MassBank_NIST.msp' \
+massbank3-similarity-service
+```

config-openapi.yaml

@@ -0,0 +1,9 @@
+generatorName: python-flask
+outputDir: gen
+inputSpec: openapi.yaml
+apiDocs: true
+modelDocs: true
+apiTests: true
+modelTests: true
+packageName: similarity_service
+packageVersion: 0.1.0

generate.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+mkdir -p ${SCRIPT_DIR}/openapi-generator
+OPENAPI_GENERATOR=${SCRIPT_DIR}/openapi-generator/openapi-generator-cli.sh
+#export OPENAPI_GENERATOR_VERSION=7.8.0
+curl https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator-cli.sh > ${OPENAPI_GENERATOR}
+chmod +x ${OPENAPI_GENERATOR}
+export PYTHON_POST_PROCESS_FILE=="yapf -i"
+rm -r ${SCRIPT_DIR}/gen
+${OPENAPI_GENERATOR} generate -c ${SCRIPT_DIR}/config-openapi.yaml

openapi.yaml

@@ -0,0 +1,192 @@
+openapi: 3.0.3
+info:
+  title: Similarity score api for MassBank3
+  description:
+    This similarity score api for MassBank3 calculates the spectral similarity
+    between the spectrum defined in the query peak list and the reference spectra
+    list.
+  version: "0.1"
+servers:
+  - url: http://localhost:8080
+    description: Local server
+paths:
+  /version:
+    get:
+      summary: Get the version string of the implementation.
+      x-openapi-router-controller: similarity_service_impl.similarity_service_impl_controller
+      operationId: version_get
+      responses:
+        "200":
+          description: version string
+          content:
+            application/json:
+              schema:
+                type: string
+              example: similarity service 0.1
+  /similarity:
+    post:
+      summary: Create a new similarity calculation.
+      x-openapi-router-controller: similarity_service_impl.similarity_service_impl_controller
+      operationId: similarity_post
+      requestBody:
+        description: a similarity job
+        required: true
+        x-body-name: similarity_calculation
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/similarity_calculation"
+
+      responses:
+        "200":
+          description: Similarity job successfully calculated.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/similarity_score_list"
+        "400":
+          description: The server can not process the input.
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/error"
+        "503":
+          description: The server is not ready to handle the request.
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/error"
+        "500":
+          description: The server encountered an unexpected condition.
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/error"
+
+components:
+  schemas:
+    peak:
+      description: a peak with m/z and intensity
+      title: peak
+      type: object
+      properties:
+        mz:
+          type: number
+        intensity:
+          type: number
+      required:
+        - mz
+        - intensity
+      example:
+        mz: 147.063
+        intensity: 121.684
+
+    peak_list:
+      title: peak_list
+      type: object
+      properties:
+        peak_list:
+          type: array
+          items:
+            $ref: "#/components/schemas/peak"
+          example:
+            - mz: 147.063
+              intensity: 121.684
+            - mz: 303.050
+              intensity: 10000.000
+            - mz: 449.108
+              intensity: 657.368
+            - mz: 465.102
+              intensity: 5884.210
+            - mz: 611.161
+              intensity: 6700.000
+
+    reference_spectra_list:
+      description: the reference spectra list, list of ACCESSION strings
+      title: reference_spectra_list
+      type: object
+      properties:
+        reference_spectra_list:
+          type: array
+          items:
+            type: string
+          example:
+            - MSBNK-IPB_Halle-PB001341
+            - MSBNK-IPB_Halle-PB006202
+            - MSBNK-IPB_Halle-PB006203
+            - MSBNK-IPB_Halle-PB001342
+            - MSBNK-IPB_Halle-PB001343
+
+    similarity_fn:
+      description: a supported similarity function
+      title: similarity_fn
+      type: object
+      properties:
+        similarity_fn:
+          type: string
+          enum:
+            - cosine
+          example: cosine
+      required:
+        - similarity_fn
+
+    similarity_calculation:
+      description: a similarity calculation
+      title: similarity_calculation
+      allOf:
+        - $ref: "#/components/schemas/peak_list"
+        - $ref: "#/components/schemas/reference_spectra_list"
+        - $ref: "#/components/schemas/similarity_fn"
+
+    similarity_score:
+      description: the similarity score to a reference spectrum
+      title: similarity_score
+      type: object
+      properties:
+        accession:
+          type: string
+        similarity_score:
+          type: number
+      example:
+        accession: MSBNK-IPB_Halle-PB001341
+        similarity_score: 0.3
+
+    similarity_score_list:
+      description: the similarity score list, result of a similarity calculation
+      title: similarity_score_list
+      type: object
+      properties:
+        similarity_score_list:
+          type: array
+          items:
+            $ref: "#/components/schemas/similarity_score"
+          example:
+            - accession: MSBNK-IPB_Halle-PB001341
+              similarity_score: 0.3
+            - accession: MSBNK-IPB_Halle-PB006202
+              similarity_score: 0.5
+            - accession: MSBNK-IPB_Halle-PB006203
+              similarity_score: 0.5
+            - accession: MSBNK-IPB_Halle-PB001342
+              similarity_score: 0.9
+            - accession: MSBNK-IPB_Halle-PB001343
+              similarity_score: 0.8
+
+    error:
+      description: an error response
+      title: error
+      type: object
+      properties:
+        status:
+          type: number
+        title:
+          type: string
+        detail:
+          type: string
+        type:
+          type: string
+      example:
+        status: 500
+        title: "Database Error"
+        detail: "connection failed: connection to server at \"127.0.0.1\", port 5432 failed: Connection refused\n\tIs the server running on that host and accepting TCP/IP connections?"
+        type: "about:blank"

requirements.txt

@@ -0,0 +1,8 @@
+connexion[swagger-ui] == 2.14.2
+python-dateutil >= 2.6.0
+setuptools >= 21.0.0
+Flask < 2.3
+waitress >= 3.0.0
+
+matchms >= 0.27.0
+numpy

similarity_service_impl/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+
+import similarity_service_impl.app
+
+
+if __name__ == '__main__':
+    similarity_service_impl.app.serve_app()

similarity_service_impl/app.py

@@ -0,0 +1,14 @@
+import connexion
+
+from similarity_service import encoder
+from waitress import serve
+
+app = connexion.App(__name__, specification_dir='..')
+app.app.json_encoder = encoder.JSONEncoder
+app.add_api('openapi.yaml',
+            arguments={'title': 'Similarity score api for MassBank3'},
+            pythonic_params=True)
+
+
+def serve_app():
+    serve(app, listen='*:8080')