SWIM Recommender API

Current Version: 2.0
Language: Python

Introduction

The SWIM Recommender API provides a flexible web service infraestructure that leverages the python-based LightFM library. This API facilitates data storage, pre-processing, training, evaluation and usage of the available recommendation algorithms.

The recommendation models can be trained with a separate or combined use of strategies such as content-based, implicit and explicit feedback. By default the SWIM platform handles recommendations for user groups which are classified by their water-related roles. Each type of role receives a recommended list of model outputs as a result of the recommendation model that is requested. Each scientific model integrated on the platform has a one to one relationship with a SWIM recommendation model.

Swagger UI

The Swagger UI provides documentation and samples to access the SWIM Recommender API endpoints. The documentation interface is available by clicking below:

SWIM Recommender API - Swagger Docs

Data Model View

The SWIM Recommender data model conforms to a relational database schema. The entity-relationship digram below depicts the primary representation of the database.

ER Diagram

Table Catalog

Name Description
hush stores values of secret keys used for encryption purposes
model identifiying information of a recommendation model with optional context URI for semantic enhancement
training contains metadata regarding last training execution of a recommendation model
category classification of an item
item list of unique items from a specific model
item_keyword keyword tags for content based recommendations of items
explicit_log log of explicit scores of an item by users
implicit_log log of user interactions with items
role group or individual list of users shared among all recommendation models
role_keyword group or user tags used for content based recommendations


Uses View

The following representation depicts the use of external python packages and decomposition of internal packages in the SWIM Recommender project structure. Each package accounts as a folder that holds one or multiple class files. Only explicitly imported dependencies are shown on the diagram, external packages might use additional dependencies.

Uses Diagram

Internal Packages

  • controller: This package contains the definition of the webservice endpoints also referred to as routes.
  • handler: This package contains the core functionalities of the application. This includes data pre-processing and model training.
  • model: This package refers to data model definitions, and contains the object mappings to relational database tables.
  • service: This package provides the methods that are directly linked to a webservice route. CRUD operations and route responses are defined here.
  • util: This package defines the data type requirements of JSON inputs for the different webservices routes or endpoints.

External Packages

  • Flask*: This package includes the flask core and other flask extensions. Flask is a lightweight web application framework and acts as the foundation of the SWIM recommender API restful structure.
  • lightfm: LightFM is a library that provides a number of popular recommendation algorithms. It supports the use of both implicit and explicit feedback as well as incorporating both item and user metadata into the traditional matrix factorization algorithms.
  • numpy: This package provides a set of numerical computing tools that are used to pre-process weight calculations for our recommender inputs.
  • pandas: Pandas is used as a data manipulation tool that provides the necessary data pipelines to transform the raw training data into inputs for the lightfm library.
  • sqlalchemy: SQLAlchemy is an Object-Relational-Mapper with support for different relational database managers. Used to interact with the default MySQL schema stablished for the tool.

Security

The SWIM Recommender API uses JSON Web Tokens (JWT) to provide authorization to most of its API endpoints. The token needs to be added as an Authentication header on the HTTP request to each of the required endpoints. It should be formated as "Bearer <"Token">".

There are three levels of security that grant access to different endpoints.

  1. Administrator Level: This level allows access to all API endpoints with the added function of training recommendations models.

  2. App Level: This level allows access to database CRUD operations for training data and setting up user and item listings.

  3. Open Access Level: This level does not require a security token it allows requests of model information, model evaluation and recommendation rankings.

Note: Additional information on how to request access tokens will be available soon on the auth-api service documentation.

Docker Deployment

The SWIM Recommender API is packaged as a Docker container for easy server deployment. The diagram below shows the docker-compose structure.

Docker Diagram

Containers:

1. SWIM-recomm-docker: The SWIM Recommender API runs as a python-based restful webservice. For the base OS uses CentOS 8. The application runs over Python 3. The application is exposed over port 5000 via uWSGI webservice gateway.
2. MySQL-docker: This image contains a MySQL Database Manager. The SWIM Recommender application connects to MySQL via SQLAlchemy to perform database transactions. Other database managers can be used as long as the driver is properly defined for SQLAlchemy on the connection string.

Volumes:

1. swim_recomm_db: This volume maintains persistence of all the MySQL database instances.
2. r_models: This volume maintains persistence of trained recommendation models.

Scripts:

1. 01_user_db_sample.sql: This script creates a sample database instance to store user credentials for the recommender system. The script will create one admnistrator and one application level account.
2. 02_recommender_db_v2.sql: This script creates an empty database instance with the SWIM recommender schema.
3. 03_set_key.sh: This script stores secret encription key on the database.
4. 04_recommender_db_v2_wdata.sh: This script creates a database instance with sample data from the SWIM platform for Demo purposes.

Environment Settings:

1. MySQL-docker: Environment variables for MySQL root password and secret token key.
2. SWIM-recomm-docker: Sets database connection strings, execution environment (e.g production) and administrator credentials for model training scripts.

For additional information consult repository README and docker-compose.yml.

References

[1] Kula, M., Metadata Embeddings for User and Item Cold-start Recommendations. Proceedings of the 2nd Workshop on New Trends on Content-Based Recommender Systems co-located with 9th ACM Conference on Recommender Systems (RecSys 2015), Vienna, Austria, September 16-20, 2015.