.. Firefly documentation master file, created by sphinx-quickstart on Wed Jun 21 11:32:55 2017. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. firefly ======= firefly is a function as a service framework which can be used to deploy functions as a web service. In turn, the functions can be accessed over a REST based API or RPC like client. In short, ``firefly`` puts your **functions on steroids**. Machine Learning models can even be deployed over ``firefly``. Installation ------------ ``firefly`` can be installed by using ``pip`` as: :: $ pip install firefly-python You can check the installation by using: :: $ firefly -h Basic Usage ----------- Create a simple python function: :: # funcs.py def square(n): return n**2 And then this function can run through ``firefly`` by the following: :: $ firefly funcs.square http://127.0.0.1:8000/ ... This function is now accessible at ``http://127.0.0.1:8000/square`` . An inbuilt ``Client`` is also provided to communicate with the ``firefly`` server. Example usage of the client: :: >>> import firefly >>> client = firefly.Client("http://127.0.0.1:8000/") >>> client.square(n=4) 16 Besides that, you can also use ``curl`` or any software through which you can do a POST request to the endpoint. :: $ curl -d '{"n": 4}' http://127.0.0.1:8000/square 16 ``firefly`` supports for any number of functions. You can pass multiple functions as: :: $ firefly funcs.square funcs.cube The functions ``square`` and ``cube`` can be accessed at ``127.0.0.1:8000/square`` and ``127.0.0.01:8000/cube`` respectively. Authentication -------------- ``firefly`` also supports token-based authentication. You will need to pass a token through the CLI or the config file. :: $ # CLI Usage $ firefly --token abcd1234 funcs.square http://127.0.0.1:8000/ The token now needs to be passed with each request. :: >>> import firefly >>> client = firefly.Client("http://127.0.0.1:8000/", auth_token="abcd1234") >>> client.square(n=4) 16 If you are using anything other than inbuilt-client, the ``Authorization`` HTTP header needs to be set in the POST request. :: $ curl -d '{"n": 4}' -H "Authorization: Token abcd1234" http://127.0.0.1:8000/square 16 Using a config file ------------------- ``firefly`` can also take a configuration file with the following schema: :: # config.yml version: 1.0 token: "abcd1234" functions: square: path: "/square" function: "funcs.square" cube: path: "/cube" function: "funcs.cube" ... You can specify the configuration file as: :: $ firefly -c config.yml http://127.0.0.1:8000/ ... Deploying a ML model -------------------- Machine Learning models can also be deployed by using ``firefly``. You need to wrap the prediction logic as a function. For example, if you have a directory as follows: :: $ ls model.py classifier.pkl where ``classifier.pkl`` is a ``joblib`` dump of a SVM Classifier model. :: # model.py from sklearn.externals import joblib clf = joblib.load('classifier.pkl') def predict(a): predicted = clf.predict(a) # predicted is 1x1 numpy array return int(predicted[0]) Invoke ``firefly`` as: :: $ firefly model.predict http://127.0.0.1:8000/ ... Now, you can access this by: :: >>> import firefly >>> client = firefly.Client("http://127.0.0.1:8000/") >>> client.predict(a=[5, 8]) 1 You can use any model provided the function returns a JSON friendly data type. Firefly with gunicorn --------------------- ``firefly`` applications can also be deployed using `gunicorn `_ . The arguments that are passed to ``firefly`` via CLI can be set as environment variables. :: $ gunicorn --preload firefly.main:app -e FIREFLY_FUNCTIONS="funcs.square" -e FIREFLY_TOKEN="abcd1234" [2017-07-19 14:47:57 +0530] [29601] [INFO] Starting gunicorn 19.7.1 [2017-07-19 14:47:57 +0530] [29601] [INFO] Listening at: http://127.0.0.1:8000 (29601) [2017-07-19 14:47:57 +0530] [29601] [INFO] Using worker: sync [2017-07-19 14:47:57 +0530] [29604] [INFO] Booting worker with pid: 29604 If you want to deploy multiple functions, pass them as a comma-seperated list. :: $ gunicorn --preload firefly.main.app -e FIREFLY_FUNCTIONS="funcs.square,funcs.cube" -e FIREFLY_TOKEN="abcd1234" Deployment on Heroku -------------------- ``firefly`` functions are deploying on any cloud platform. This section shows how you can deploy ML models to `Heroku `_ . There are two important files apart from your model code that you will need to have in your application root directory - ``Procfile`` and ``requirements.txt``. ``Procfile`` lets Heroku know what sort of process you want to run and what command it should run. ``requirements.txt`` specifies dependencies of your code. :: # requirements.txt firefly-python sklearn numpy scipy This ``Procfile`` tells Heroku to run ``firefly`` serving the ``predict`` function inside the ``model`` script. :: # Procfile web: gunicorn --preload firefly.main:app -e FIREFLY_FUNCTIONS="model.predict" :: $ ls model.py classifier.pkl requirements.txt Procfile Now that everything is setup on your machine, we can deploy the application to Heroku. :: $ git add . $ git commit -m "Added a Procfile." $ heroku login Enter your Heroku credentials. ... $ heroku create Creating intense-falls-9163... done, stack is cedar http://intense-falls-9163.herokuapp.com/ | git@heroku.com:intense-falls-9163.git Git remote heroku added $ git push heroku master ... -----> Python app detected ... -----> Launching... done, v7 https://intense-falls-9163.herokuapp.com/ deployed to Heroku For more information about deploying python applications to Heroku, go `here `_ .