enhancement/extensibility + readme/ml_streaming (#128)

* add ML model to init param of PyMiloServer

* add init option to run pymilo server CLI

* add testcase of init PyMiloServer with ML model

* remove trailing whitespaces

* start adding `ML Streaming` to the `README.md`

* update docstring

* `README.md` updated

* `README.md` updated

* `CHANGELOG.md` updated

* apply autopep8.sh + refactorings

* apply refactorings to scenario3

* `README.md` updated

* doc : README.md mlstreaming section updated

* doc : README.md mlstreaming section updated

* doc : README.md mlstreaming section minor bug fixed

* doc : README.md mlstreaming section minor bug fixed

* doc : PymiloServer docstring updated

* doc : README.md mlstreaming section minor bug fixed

* rollback to str since it is more convenient

---------

Co-authored-by: sepandhaghighi <[email protected]>

Author: AHReccese

CHANGELOG.md

@@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - `ML Streaming` RESTful testcases
 - `streaming-requirements.txt`
 ### Changed
+- `README.md` updated
 - `ML Streaming` RESTful testcases
 - `attribute_call` function in `RESTServerCommunicator`
 - `AttributeCallPayload` class in `RESTServerCommunicator`

README.md

@@ -78,6 +78,7 @@ PyMilo is an open source Python package that provides a simple, efficient, and s
 
 
 ## Usage
+### Import/Export
 Imagine you want to train a `LinearRegression` model representing this equation: $y = x_0 + 2x_1 + 3$. You will create data points (`X`, `y`) and train your model as follows.
 ```pycon
 >>> import numpy as np
@@ -149,15 +150,66 @@ Now let's load it back. You can do it easily by using PyMilo `Import` class.
 ```
 This loaded model is exactly the same as the original trained model.
 
+### ML streaming
+You can easily serve your ML model from a remote server using `ML streaming` feature of PyMilo.
+
+⚠️ `ML streaming` feature exists in versions `>=1.0`
+
+⚠️ In order to use `ML streaming` feature, make sure you've installed the `streaming` mode of PyMilo
+
+#### Server
+Let's assume you are in the remote server and you want to import the exported JSON file and start serving your model!
+```pycon
+>>> from pymilo import Import
+>>> from pymilo.streaming import PymiloServer
+>>> my_model = Import("model.json").to_model()
+>>> communicator = PymiloServer(model=my_model, port=8000).communicator
+>>> communicator.run()
+```
+Now `PymiloServer` runs on port `8000` and exposes REST API to `upload`, `download` and retrieve **attributes** either **data attributes** like `model._coef` or **method attributes** like `model.predict(x_test)`.
+
+#### Client
+By using `PymiloClient` you can easily connect to the remote `PymiloServer` and execute any functionalities that the given ML model has, let's say you want to run `predict` function on your remote ML model and get the result:
+```pycon
+>>> from pymilo.streaming import PymiloClient
+>>> pymilo_client = PymiloClient(mode=PymiloClient.Mode.LOCAL, server_url="SERVER_URL")
+>>> pymilo_client.toggle_mode(PymiloClient.Mode.DELEGATE)
+>>> result = pymilo_client.predict(x_test)
+```
+
+ℹ️ If you've deployed `PymiloServer` locally (on port `8000` for instance), then `SERVER_URL` would be `http://127.0.0.1:8000`
+
+You can also download the remote ML model into your local and execute functions locally on your model.
+
+Calling `download` function on `PymiloClient` will sync the local model that `PymiloClient` wraps upon with the remote ML model, and it doesn't save model directly to a file.
+
+```pycon
+>>> pymilo_client.download()
+```
+If you want to save the ML model to a file in your local, you can use `Export` class.
+```pycon
+>>> from pymilo import Export
+>>> Export(pymilo_client.model).save("model.json")
+```
+Now that you've synced the remote model with your local model, you can run functions.
+```pycon
+>>> pymilo_client.toggle_mode(mode=PymiloClient.Mode.LOCAL)
+>>> result = pymilo_client.predict(x_test)
+```
+`PymiloClient` wraps around the ML model, either to the local ML model or the remote ML model, and you can work with `PymiloClient` in the exact same way that you did with the ML model, you can run exact same functions with same signature.
+
+ℹ️ Through the usage of `toggle_mode` function you can specify whether `PymiloClient` applies requests on the local ML model `pymilo_client.toggle_mode(mode=Mode.LOCAL)` or delegates it to the remote server `pymilo_client.toggle_mode(mode=Mode.DELEGATE)`
+
+
 ## Supported ML models
 | scikit-learn | PyTorch | 
 | ---------------- | ---------------- | 
 | Linear Models ✅ | - | 
-| Neural networks ✅ | -  | 
+| Neural Networks ✅ | -  | 
 | Trees ✅ | -  | 
 | Clustering ✅ | -  | 
 | Naïve Bayes ✅ | -  | 
-| Support vector machines (SVMs) ✅ | -  | 
+| Support Vector Machines (SVMs) ✅ | -  | 
 | Nearest Neighbors ✅ | -  |  
 | Ensemble Models ✅ | - | 
 | Pipeline Model ✅ | - |

pymilo/streaming/__init__.py

@@ -2,4 +2,4 @@
 """PyMilo ML Streaming."""
 from .pymilo_client import PymiloClient
 from .pymilo_server import PymiloServer
-from .compressor import Compression
+from .compressor import Compression

pymilo/streaming/pymilo_server.py

@@ -11,17 +11,19 @@
 class PymiloServer:
     """Facilitate streaming the ML models."""
 
-    def __init__(self, port=8000, compressor=Compression.NULL):
+    def __init__(self, model=None, port=8000, compressor=Compression.NULL):
         """
         Initialize the Pymilo PymiloServer instance.
 
+        :param model: the ML model which will be streamed
+        :type model: any
         :param port: the port to which PyMiloServer listens
         :type port: int
         :param compressor: the compression method to be used in client-server communications
         :type compressor: pymilo.streaming.compressor.Compression
         :return: an instance of the PymiloServer class
         """
-        self._model = None
+        self._model = model
         self._compressor = compressor.value
         self._encryptor = DummyEncryptor()
         self.communicator = RESTServerCommunicator(ps=self, port=port)

tests/test_ml_streaming/run_server.py

@@ -1,14 +1,33 @@
 import argparse
-from pymilo.streaming import Compression
-from pymilo.streaming import PymiloServer
+from sklearn.linear_model import LinearRegression
+from pymilo.streaming import PymiloServer, Compression
+from pymilo.utils.data_exporter import prepare_simple_regression_datasets
 
 
 def main():
     parser = argparse.ArgumentParser(description='Run the Pymilo server with a specified compression method.')
-    parser.add_argument('--compression', type=str, choices=['NULL', 'GZIP', 'ZLIB', 'LZMA', 'BZ2'], default='NULL',
-                        help='Specify the compression method (NULL, GZIP, ZLIB, LZMA, or BZ2). Default is NULL.')
+    parser.add_argument(
+        '--compression',
+        type=str,
+        choices=['NULL', 'GZIP', 'ZLIB', 'LZMA', 'BZ2'],
+        default='NULL',
+        help='Specify the compression method (NULL, GZIP, ZLIB, LZMA, or BZ2). Default is NULL.'
+        )
+    parser.add_argument(
+        '--init',
+        action="store_true",
+        default=False,
+        help='the `init` command specifies whether or not initializing the PyMilo Server with a ML model.',
+    )
     args = parser.parse_args()
-    communicator = PymiloServer(compressor=Compression[args.compression]).communicator
+    communicator = None
+    if args.init:
+        x_train, y_train, _, _ = prepare_simple_regression_datasets()
+        linear_regression = LinearRegression()
+        linear_regression.fit(x_train, y_train)
+        communicator = PymiloServer(model=linear_regression, port=9000, compressor=Compression[args.compression]).communicator
+    else:
+        communicator = PymiloServer(port=8000, compressor=Compression[args.compression]).communicator
     communicator.run()
 
 if __name__ == '__main__':

tests/test_ml_streaming/scenarios/scenario1.py

@@ -1,12 +1,12 @@
 import numpy as np
-from pymilo.streaming import Compression
-from pymilo.streaming import PymiloClient
+from pymilo.streaming import PymiloClient, Compression
 from sklearn.metrics import mean_squared_error
 from sklearn.linear_model import LinearRegression
 from pymilo.utils.data_exporter import prepare_simple_regression_datasets
 
 
 def scenario1(compression_method):
+    # [PyMilo Server is not initialized with ML Model]
     # 1. create model in local
     # 2. train model in local
     # 3. calculate mse before streaming

tests/test_ml_streaming/scenarios/scenario2.py

@@ -1,12 +1,12 @@
 import numpy as np
-from pymilo.streaming import Compression
-from pymilo.streaming import PymiloClient
+from pymilo.streaming import PymiloClient, Compression
 from sklearn.metrics import mean_squared_error
 from sklearn.linear_model import LinearRegression
 from pymilo.utils.data_exporter import prepare_simple_regression_datasets
 
 
 def scenario2(compression_method):
+    # [PyMilo Server is not initialized with ML Model]
     # 1. create model in local
     # 2. upload model to server
     # 3. train model in server

tests/test_ml_streaming/scenarios/scenario3.py

@@ -0,0 +1,34 @@
+import numpy as np
+from sklearn.metrics import mean_squared_error
+from pymilo.streaming import PymiloClient, Compression
+from pymilo.utils.data_exporter import prepare_simple_regression_datasets
+
+
+def scenario3(compression_method):
+    # [PyMilo Server is initialized with ML Model]
+    # 1. calculate mse in server
+    # 2. download model in local
+    # 3. calculate mse in local
+    # 4. compare results
+
+    # 1.
+    _, _, x_test, y_test = prepare_simple_regression_datasets()
+    client = PymiloClient(
+        mode=PymiloClient.Mode.LOCAL,
+        compressor=Compression[compression_method],
+        server_url="http://127.0.0.1:9000",
+        )
+    client.toggle_mode(PymiloClient.Mode.DELEGATE)
+    result = client.predict(x_test)
+    mse_server = mean_squared_error(y_test, result)
+
+    # 2.
+    client.download()
+
+    # 3.
+    client.toggle_mode(mode=PymiloClient.Mode.LOCAL)
+    result = client.predict(x_test)
+    mse_local = mean_squared_error(y_test, result)
+
+    # 4.
+    return np.abs(mse_server-mse_local)

tests/test_ml_streaming/test_streaming.py

@@ -5,9 +5,11 @@
 from sys import executable
 from scenarios.scenario1 import scenario1
 from scenarios.scenario2 import scenario2
+from scenarios.scenario3 import scenario3
+
 
 @pytest.fixture(scope="session", params=["NULL", "GZIP", "ZLIB", "LZMA", "BZ2"])
-def prepare_server(request):
+def prepare_bare_server(request):
     compression_method = request.param
     path = os.path.join(
         os.getcwd(),
@@ -26,10 +28,39 @@ def prepare_server(request):
     yield (server_proc, compression_method)
     server_proc.terminate()
 
-def test1(prepare_server):
-    _, compression_method = prepare_server
+
+@pytest.fixture(scope="session")
+def prepare_ml_server():
+    compression_method = "ZLIB"
+    path = os.path.join(
+        os.getcwd(),
+        "tests",
+        "test_ml_streaming",
+        "run_server.py",
+        )
+    server_proc = subprocess.Popen(
+        [
+            executable,
+            path,
+            "--compression", compression_method,
+            "--init",
+        ],
+        )
+    time.sleep(2)
+    yield (server_proc, compression_method)
+    server_proc.terminate()
+
+
+def test1(prepare_bare_server):
+    _, compression_method = prepare_bare_server
     assert scenario1(compression_method) == 0
 
-def test2(prepare_server):
-    _, compression_method = prepare_server
+
+def test2(prepare_bare_server):
+    _, compression_method = prepare_bare_server
     assert scenario2(compression_method) == 0
+
+
+def test3(prepare_ml_server):
+    _, compression_method = prepare_ml_server
+    assert scenario3(compression_method) == 0