Penelope is a completely open platform, which means that anyone can use existing components and interfaces and contribute new ones. This page explains the different steps that are involved in contributing components and interfaces.
Contributing components
Creating a component for the Penelope platform takes the following five steps:
- Develop a software tool in the programming language of your choice.
- Set it up as a service that can be queried through HTTP requests (see below for an example).
- Host the service on a publicly accessible server, or contact penelope@ai.vub.ac.be if you would like us to host it.
- Make an Open API specification that documents how to use the component (e.g. on Swaggerhub, see example below).
- Let us know that you have created the component by e-mailing the OpenAPI specification to penelope@ai.vub.ac.be. We will then add it to our list of available components.
Here are two examples of how a component can be made. The examples implement a demo component that provides the possibility to sort a list of words alphabetically. The first example implements the component in Python, the second example in R.
Python
####################
# Import libraries #
####################
# Here, you import a few functions from the flask library that is used for making the web application,
# and the json library that is used to make json objects.
from flask import Flask
from flask import request
import json
####################
# Name Application #
####################
# Here, you give a name to your component and initialize it.
sorter = Flask(__name__)
###############
# Define URLs #
###############
# Here, you specify a list of urls (called routes) to which requests will be send, and associate a function
# to each route. In this case, we only define a route /sort-alphabetically and associate it to the function
# sort_alphabetically. This means that if the application would be hosted on penelope.vub.be, users would need to
# send their requests to penelope.vub.be/sort-alphabetically.
@sorter.route("/sort-alphabetically", methods = ['POST'])
def sort_alphabetically():
# Get data from request
request_data = request.get_json(force=True)
list_of_strings = request_data['words']
# Sort the strings alphabetically
list_of_strings.sort()
# Return a JSON object containing the concatenated strings
return json.dumps({'sorted_words': list_of_strings})
############################
# Starting the application #
############################
# Start the application automatically when running this file using `$ python3 demo_component.py`
# By default, it listens to localhost:5000
if __name__ == '__main__':
sorter.run()
R
First, make a file that contains the functions you would like to have in the web API. Decorate the functions with the method type and the route. Call this file, for example, routes.R.
######################################
# Define URL and associated function #
######################################
#* @post /sort-alphabetically
function(words){
sort(words)
}
Then, create a file, for example run.R, that creates and starts the web service.
####################
# Import libraries #
####################
library(plumber)
####################
# Name Application #
####################
sorter <- plumb("~/Projects/Plumber/routes.R") # Where 'routes.R' is the location of the file shown above
############################
# Starting the application #
############################
sorter $run(port=5000)
Using the component
The component implemented in both examples can be called from most programming languages, or using the curl command line tool as demonstrated here:
curl http://localhost:5000/sort-alphabetically -d '{"words":["source", "world", "hello", "open"]}'
The OpenAPI specification of this component can be found here: https://app.swaggerhub.com/apis/EHAI/sort-alphabetically/1.0.0.
Contributing interfaces
Creating an interface for the Penelope platform takes the following steps:
- Develop the interface in the programming language of your choice, building on existing components as needed.
- Host the interface on a publicly accessible server, or contact penelope@ai.vub.ac.be if you would like us to host it.
- Document the way in which it can be used.
- Let us know that you have created the interface by e-mailing the link and a description to penelope@ai.vub.ac.be. We will then add it to our list of interfaces.