pqai gateway

PQAI Gateway

This service provides a REST API to expose arbitrary functionalities for the end user.

To implement these functionalities, the service can use any or all of the other PQAI services.

Functionalities are wrapped into "plugins" that are independent pieces of code and can be hosted in different repositories.

The search functionality provided by PQAI API is an example of a plugin. It orchestrates different PQAI services such as pqai-db, pqai-encoder, pqai-index, etc. to return results for prior-art search queries.

New plugins can be created independently and used within the PQAI Gateway without needing any modifications in its codebase. All it requires is creating a new directory in the plugins folder and adding a routes.py file. This file should define API routes and provide their implementation. Plugins can have their own assets and any arbitrary modules. All of the PQAI's existing functionality is available to the plugins through the service dependencies of PQAI Gateway.

Code structure

root
  |-- core/
       |-- classifier_srv.py
       |-- db_srv.py
       |-- documents.py			
       |-- encoder_srv.py
       |-- index_srv.py
       |-- reranker_srv.py
       |-- snippet_srv.py
  |-- plugins/
       |-- search/			# the search plugin
       |-- cpc/				# the CPC plugin
  |-- tests/
  |
  |-- main.py				# Skeleton for REST API
  |-- config.ini			# Configuration file
  |
  |-- requirements.txt		# Python dependencies
  |
  |-- Dockerfile			# Docker files
  |-- docker-compose.yml

Core modules

The core modules in PQAI Gateway basically provide access points to other PQAI services:

classifier_srv: access point for PQAI Classifier
db_srv: access point for PQAI Storage
encoder_srv: access point for PQAI Encoder
index_srv: access point for PQAI Index
reranker_srv: access point for PQAI Reranker
snippet_srv: access point for PQAI Snippet

The above modules can be imported by plugins and used in any arbitrary manner to perform tasks.

Plugins

A plugin must reside in a separate directory within /plugins. The plugin will be identified by the name of the directory, say foo

Inside that directory, you must have a routes.py file, which should expose at least one route, like this:

from fastapi import APIRouter

router = APIRouter()

@router.get('/test/route')
async def do_something(param1, param2):
    output = process(param1, param2)
    return output

After this, the plugin has to be added to the /config.ini file to the list of active plugins:

[plugins]
active = foo, bar

In the above example, foo and bar are active plugins. When coming up, the Gateway service will import all the routes in /plugins/foo/routes.py and plugins/bar/routes.py.

Any plugins not mentioned explicitly in the config.ini file are omitted and remain unexposed.

Plugins can have their own assets in the respective plugin folders in an /assets directory. It is responsibility of the plugin's code to read these assets, so it's not necessary that this directory be named assets - but make sure to add the folder to .gitignore file so that those assets are not tracked in the git history.

API Authentication

The service provides a provision to require token-based authentication for serving requests.

Authentication can be enabled/disabled from the config.ini file. The same file also must contain a list of valid tokens.

[authentication]
enabled = true
tokens = token1,
         token2

Tokens must be passed in the HTTP request header, like so:

import requests

route = "/search/102"
payload = {"query": "drones"}
headers = {"Authorization": "Bearer token1"}
requests.post(route, json=payload, headers=headers)

Deployment

Prerequisites

The following deployment steps assume that you are running a Linux distribution and have Git and Docker installed on your system.

Setup

The easiest way to get this service up and running on your local system is to follow these steps:

Clone the repository

git clone https://github.com/pqaidevteam/pqai-gateway.git

Using the env template in the repository, create a .env file and set the environment variables.
```
cd pqai-gateway
cp env .env
nano .env
```
Run deploy.sh script.
```
chmod +x deploy.sh
bash ./deploy.sh
```

This will create a docker image and run it as a docker container on the port number you specified in the .env file.

Alternatively, after following steps (1) and (2) above, you can use the command python main.py to run the service in a terminal.

Service dependency

This service is dependent on the following other services:

pqai-db
pqai-encoder
pqai-index
pqai-reranker
pqai-snippet
pqai-classifier

Depending on which plugins are activated/deactivated in PQAI Gateway, some or all of the above dependencies may be omitted. However, the search plugin requires all of the above services.