Generic RESTful Recommender Service

The ideas behind recalot.com are to build a RESTFul recommender system that can be used for all sorts of applications, can easily be extended, can be used for offline as well as online evaluations and can be adjusted for scientific as well as industrial applications. Therefor we decide to build the API with the help of Apache Felix, which is an OSGi Framework. This allows a modular development, modules can easily be replaced in runtime and modules with new functionality can easily be added to the system. Currently the system is in alpha phase and documentation and tutorials are coming soon.

If you have any comments or suggestions for improvement, feel free to contact us info@recalot.com

The architecture of recalot.com is following the MVC pattern and distinguishes furthermore between data, recommendations and evaluation affiliation.

The API consists of the following OSGi bundles:

Furthermore the following OSGi bundles are also part of the project, but represent unit tests, tools or demos.

The quick install guide will show how to install the "Experiments Portal" bundle, that comes with all available bundles, with an minimal effort. However, we would recommend to install the following bundles as well:

• Apache Felix File Install (org.apache.felix.fileinstall)
• Apache Felix Web Console (org.apache.felix.webconsole)

• Download Apache Felix
• Run Felix in your favorite bash

  java -jar bin\felix.jar 

• Install the following bundles:
  • Metatype (org.apache.felix.metatype)

    obr:deploy org.apache.felix.metatype

  • Jetty (org.apache.felix.http.jetty)

    obr:deploy  org.apache.felix.http.jetty

• Add the recalot.com Repository

  obr:repos add http://api.recalot.com/repo/repo.xml

• Install "Recalot.com - Experiments Portal" (com.recalot.portal)

  obr:deploy com.recalot.portal

• Take a look at the bundles and start everything you need.
  • List Bundles:

    lb

  • Start Bundles:

    start {bundle-id}

The webservice uses a jetty as a webserver and under the default configuration the jetty listens to port 8080 on your local machine. Try to call http://localhost:8080/sources to list all data sources, that are available, connected or are currently connecting. The default output format is json.

Take a look at /portal/. You will there a solution with an overview of a variety of possible API requests. I did not put much effort in the building of the portal. It was just a testing device for me, but works pretty good so i uploaded it as well.

Before the training of a recommender it is necessary to connect a data source. You can use one of the predefined data source builders or write your own one. So far the following data source builders exists:

• MySQL Source Builder
• MovieLens File Source Builder

More builders are coming soon.

Each builder has this own configurations. Before you connect a data source you can access the configuration of the builder by sending a GET request to /sources/{data-source-id}. The result contains an configuration object with an array of configuration items. e.g. MySQL Data Builder:

configuration: [
{key: "sql-database", requirement: "Required", type: "String", value: ""},
{key: "sql-password", requirement: "Required", type: "String", value: ""},
{key: "sql-username", requirement: "Required", type: "String", value: ""},
{key: "data-builder-id", requirement: "Hidden", type: "String", value: "mysql"},
{key: "source-id", requirement: "Required", type: "String", value: ""},
{key: "sql-server", requirement: "Required", type: "String", value: ""}
]

For a detailed description of the data schema take a look at the swagger documentation. Link coming soon.

This configuration object shows which configuration items the data source needs. The field "requirement" provides information about the requirement of the configuration item. Items with the value "Hidden" and "Required" are required and must be send within the request body. For the connection of a data source, send a PUT request with the necessary configuration items to /sources e.g. MySQL:

Request URL:http://localhost:8080/sources
Request Method:PUT
Form Data
    sql-database:default
    sql-password:password
    sql-username:admin
    data-builder-id:mysql
    source-id:chosenid
    sql-server:mysql://localhost:3306

The MySQL Data Source will automatically create all necessary tables. Take a look at the "Experiments Portal" (/portal/), a lot of requests can be done there with help of a user interface.

You need to have a connected data source. If not, please read "Connect Data Source". A well as the data source builders, every recommender builder has its own configuration. Call /train?state=AVAILABLE to get an overview over all available recommender builders. e.g.:

[
    {"id":"rec-builder-wallpaper-mp","state":"AVAILABLE"},
    {"id":"rec-builder-cosine-user-knn","state":"AVAILABLE"},
    {"id":"rec-builder-bprmf","state":"AVAILABLE"},
    {"id":"rec-builder-wallpaper-survey","state":"AVAILABLE"},
    {"id":"rec-builder-funk-svd","state":"AVAILABLE"},
    {"id":"rec-builder-mp","state":"AVAILABLE"}
]

Get the configuration of the recommender, you want to train, by calling a GET request to /train/{recommender-id}. The request will return an json object which contains the configuration (analogical to the data source connection). e.g. (rec-builder-funk-svd):

{
"configuration":[
    {"key":"numFeatures","options":[],"requirement":"Optional","type":"Integer","value":"50"},
    {"key":"id","options":[],"requirement":"Required","type":"String","value":""},
    {"key":"initialSteps","options":[],"requirement":"Optional","type":"Integer","value":"50"},
    {"key":"source-id","options":["movielens"],"requirement":"Required","type":"Options","value":""},
    {"key":"rec-builder-id","options":[],"requirement":"Hidden","type":"String","value":"funk-svd"}],
 "description":"",
 "id":"rec-builder-funk-svd",
 "key":"funk-svd",
 "state":"AVAILABLE"
}

To start the training of a recommender, you have to send a PUT request to /train with the required configuration items.

e.g (Funk-SVD for the movielens data set):

Request URL:http://localhost:8080/train
Request Method:PUT
Form Data
    id:movielens-funksvd
    source-id:movielens
    rec-builder-id:funk-svd

Here again, you can use the Experiments Portal. It simplifies the task by generating a form of the configuration object.

coming soon

coming soon

coming soon

• Write more tests
• Write more documentation and tutorials
• Add code comments
• Add more functionality
• Build website
• Add more demos

Copyright (C) 2015 Matthäus Schmedding

recalot.com is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

recalot.com is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with recalot.com. If not, see http://www.gnu.org/licenses/.

• TROVE Website License
• Uncommons Maths Website License
• Apache Mahout Website License
• Recommender101 Website License