Merge pull request #51 from scailable/develop

Update to version 0.1.10

Author: robinvanemden

LICENSE

@@ -16,4 +16,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -1,187 +1,155 @@
 # sclblpy
 
-[![PyPI Release](https://github.com/scailable/sclblpy/workflows/PyPI%20Release/badge.svg)](https://pypi.org/project/sclblpy/)
-
-
-Changelog: the package is currently being refactored. As such, it is currently a stub, as Scailable has changed its focus from Scikit Learn to ONNX, Scikit Learn support has been removed.
-1. Removal of support for additional packages - most importantly in the 'upload()' function which now will throw an error if `model_type` isn't onnx
-2. the `run()` function is going to be replaced by a function that allows the user to test their local setup; and as such is a stub
-
-
-`sclblpy` is the core python package provided by Scailable for interacting with our API. The scope of this package is (roughly):
-1. upload an `.onnx` model to the admin console
-2. Assign and deploy the uploaded model to a device that has previously been installed with the Scailable runtime and registered
-3. (upcoming) test device deployment
-
-
-
-
-Also, there will probably be breaking changes in the API in one of the upcoming releases, for more information see [our API documentation](https://docs.sclbl.net/).
-
+`sclblpy` is the core python package provided by Scailable for interacting with our API. 
 
 `sclblpy` is only functional in combination with a valid Scailable user account.
 
 - **Website:** [https://www.scailable.net](https://www.scailable.net)
 - **Docs:**
    - On GitHub (you are here): [https://github.com/scailable/sclblpy](https://github.com/scailable/sclblpy/blob/master/README.md)
-   - On pypi: [https://docs.sclbl.net/sclblpy](https://docs.sclbl.net/sclblpy)
    - API docs Scailable: [https://docs.sclbl.net](https://docs.sclbl.net)
-- **Get an account:** [https://admin.sclbl.net/signup.html](https://admin.sclbl.net/signup.html) 
-- **Install the AI manager:**
-   - On any Linux device: [https://github.com/scailable/sclbl-tutorials/tree/master/solutions-manuals/sclbl-local-ai-manager](https://github.com/scailable/sclbl-tutorials/tree/master/solutions-manuals/sclbl-local-ai-manager)
-   - On an Advantech device: [https://github.com/scailable/sclbl-tutorials/tree/master/solutions-manuals](https://github.com/scailable/sclbl-tutorials/tree/master/solutions-manuals)
 
-## Background
-The sclblpy package allows users with a valid scailable account (get one at [https://admin.sclbl.net/signup.html](https://admin.sclbl.net/signup.html)) 
-to upload fitted ML / AI models to the Scailable toolchain server. This will result in:
+The scope of this package is:
+
+## Manage scailable account (auth.py)
+1. Create an account in the scailable plateform
+2. Sign in to an existing account
+3. Reset password or set a new password
+4. Get account information
+
+## Manage models (compute.py)
+1. Upload an `.onnx` model to the Scailable
+2. Update an existing model
+3. Delete a model
+4. Get model's details
+5. Get all the models accessible to your organisation.
+6. Add a catalogue (set of models) to your organisation
+7. Update an existing catalogue
+8. Delete a catalogue
+9. Get catalogue's details
+10. Get all the catalogues accessible for your organisation.
+11. Get the configured parameters for service
+12. Get statistics of all models for your organisation
+
+## Manage devices (device.py)
+1. Add a device to your organisation
+2. Update a device
+3. Get device's details
+4. Assign a model to a device
+5. Delete a device
+6. Get devices statistics
+7. Get all devices accessible for your organisation
+8. Get all groups accessible for your organisation
+9. Delete a group
+10. Add a device to a group
+11. Delete a device from a group
 
-1. The model being tested for errors on the client side.
-2. The model being uploaded to Scailable, tested again, and if all test pass it will be converted to [WebAssembly](https://webassembly.org).
-3. The model being made available to deploy to a preregistered (link on how to do that) device
-4. (upcoming) The model being testable through test_run(example_input, device_id)
 
 ## Getting started
 
-The following functions are likely most used:
+### Get a Scailable account
 
-### `sp.upload_onnx()` can be used to create model:
+To create a Scailable account you can use `register_()` function or sign up at [https://admin.sclbl.net/register](https://admin.sclbl.net/register) 
 ```python
-def upload_onnx(path, example="", docs={}, email=True) -> bool:
-    """upload_onnx uploads a fitted onnx model to Scailable.
-
-    - The function first checks if the supplied path indeed references a .onnx file
-    - Next, the docs are checked; if none are provided a warning is issued and a simple
-    name is provided based on the model type.
-    - Finally the onnx file and the supporting docs are uploaded to the toolchain.
-
-    Note: This method prints user-feedback by default. This feedback can be suppressed by calling the
-        stop_print() method.
 
-    Args:
-        path: The path referencing the onnx model location (i.e., the .onnx file location).
-        example: String example input for the onnx file.
-        docs: A dict{} containing the fields 'name' and 'documentation'.
-        email: Bool indicating whether a confirmation email of a successful conversion should be send. Default True.
-
-    Returns:
-        False if upload failed, true otherwise
+def register_(name: str, company: str, email: str, password: str, job_title: str,
+               phone_number: str, newsletter_optIn: bool = True, accept_eula: bool = True) -> bool:
+    """Performs the sign-up of a user.
+    The function register performs a sign-up of a new user.
+    It returns a boolean value indicating whether the sign-up was successful.
+        Args:
+            name: A string (name of the user)
+            company: A string (name of the user's company)
+            email: A string (email)
+            password: A string (password)
+            job_title: A string (job of the user)
+            phone_number: A string (user's phone number)
+            newsletter_optIn: Bool (whether to add this email address to the newsletter)
+            accept_eula: Bool (Agreement to the EULA)
+
+        Returns:
+            True if sign-up is successful.
+   """
+```
 
-    Raises  (in debug mode):
-        UploadModelError if unable to successfully bundle and upload the model.
+You already have a Scailable account? then you can sign in to your account using `log_in` function.
+```python
+def log_in(email: str, password: str) -> bool:
+    """Performs the sign in of a user.
+        The function _log_in performs a log in of a user based
+        on the email (str) and password (str). It returns
+        a boolean value indicating whether the log in was successful.
+        Args:
+            email: A string (email) to log in the user
+            password: A string (password) for login
+        Returns:
+            True if sign in is successful.
     """
 ```
-`sp.models()` lists all created models, and `sp.delete_model()` can be used to delete a model. Finally, `sp.update()` can be used to
-overwrite / update an existing model.
 
-### `sp.assign()` can be used to assign a model to a device:
-```python
-def assign(cfid, did, rid, _verbose=True):
-    """ Assign a model to a device.
+The following functionalities are likely most used:
 
-    Using the global JWT string this function assigns a model (using its cfid) to a device (using its did).
+### Upload an `onnx` model
 
-    Args:
-        cfid: String identifying the model / compute-function
-        did: String identifying the device
-        rid: String identifying the registration ID of the device (not, run "devices"
+To upload your models to Scailable, you can use `_upload_model`. (only models with onnx format are accepted)
 
-    Returns:
-        Boolean indicating whether the assignment was successful.
+```python
+def upload_model(name: str, documentation: str, input_driver: str = "", input_driver_details: dict = {},
+                  output_driver: str = "", output_driver_details: dict = {},
+                  alias: str = "", path: str = "", source_name=None, source_url=None) -> bool:
+    """_upload_model uploads a fitted onnx model to Scailable.
+
+        - The function first checks if the supplied path indeed references a .onnx file
+        - Next the onnx file and the supporting docs are uploaded.
+
+        Args:
+            name: Name of the model to upload
+            input_driver:
+            input_driver_details:
+            output_driver:
+            output_driver_details:
+            alias: Alias of the model
+            documentation: Documentation of the model
+            path: The path referencing the onnx model location (i.e., the .onnx file location).
+            source_name:
+            source_url:
+        Returns:
+            False if upload failed, True otherwise
     """
-``` 
-`sp.assignments()` can be used to list current assignments, whereas `sp.delete_assignment()` can be used to delete an assignment. 
-
+```
 
-## A simple `.onnx` example
+### Add a device
 
-The following code can be used to upload a stored `.onnx` model:
+To add a device to Scailable, you can use `add_device`.
 ```python
-
-# Add docs
-docs = {}
-docs['name'] = "Name of ONNX model"
-docs['documentation'] = "A long .md thing...."
-check = upload_onnx("PATH-TO-MODEL/FILE-NAME.onnx", "", docs, email=True)
+def add_device(name: str, registration_token: str = "", runtime: str = "", serial: str = "", type: str = "") -> bool:
+    """Add device to user's organisation.
+        Args:
+            name: Name of the model to upload
+            registration_token:
+            runtime:
+            serial:
+            type:
+        Returns:
+            True if device added, False otherwise
+    """
 ```
 
-Note that the file will be send to the Scailable platform; after it has been transpiled to WebAssembly you will receive an email (by default), but you can choose not to, by setting ``email=False``
-
-## Additional functionality
-Next to the main ``upload_onnx()`` function, the package also exposes the following functions to administer endpoints:
+### Assign a model to a device
 
-````
-# List all models owned by the current user:
-sp.models()
-
-# Remove an endpoint:
-sp.delete_models(cfid)  # Where cfid is the compute function id
-
-# Update an existing endpoint:
-sp.update(mod, fv, cfid, docs)  # Where cfid is the compute function id
-
-# Update an existing ednpoint without updating the docs:
-sp.update(mod, fv, cfid) 
-
-# Update only the docs of an existing endpoint:
-sp.update_docs(cfid, docs)
-
-# See all devices:
-sp.devices(offset=0, limit=20, _verbose=True, _return=False)
-
-# Delete device:
-sp.delete_device(did)
-
-# See all assignments:
-sp.assignments(offset=0, limit=20, _verbose=True, _return=False)
-
-# Create an assignment:
-sp.assign(cfid, did, rid, _verbose=True)
-
-# Remove an assignment:
-sp.delete_assignment(aid) 
-````
-
-Additionally, the following methods are available:
-
-````
-# List all models currently supported by our toolchains:
-sp.list_models()  
-
-# Prevent any user feedback from being printed:
-sp.stop_print()  
-
-# Turn user feedback back on:
-sp.start_print()  
-
-# Remove locally stored user credentials:
-sp.remove_credentials()
-
-````
-
-## Supported `.onnx` files
-
-We currently support `ONNX` version 1.8 (and below) in full. However, if you encounter any problems
-converting `.onnx` files please let us know.
-
-## Dependencies
+To assign a model to your device, you can use `_assign_model_to_device`.
+```python
+def assign_model_to_device(uuid: str, function_uuid: str) -> bool:
+    """Assign a model to a device.
+            Args:
+                uuid: UUID of the device
+
+            Returns:
+                True if model assigned, False otherwise
+        """
+```
 
-sclblpy needs python 3, and has been tested on python `> 3.7`. Furthermore, dependent on usage, sclblpy will import
-the following packages:
 
-* `numpy`
-* `requests`
-* `uuid`
 
-No `onnx` packages are
-necessary for the `sclblpy` package to run.
 
-## Notes:
 
-* We try to stick to the naming conventions in [http://google.github.io/styleguide/pyguide.html](http://google.github.io/styleguide/pyguide.html).
-* The methods `_set_toolchain_URL(string)` and `_set_usermanager_URL(string)` can be used to change the default location of
-the toolchain and user-management function. These are useful when running the Scailable stack locally. Also the method `_toggle_debug_mode()` can
-be used for troubleshooting (this will raise exceptions and provide a trace upon errors).
-* Docs generated using `pdoc3 --force --html --output-dir docs sclblpy/main.py`
-* We are actively developing our stack; we try to list changes from one version to the next as clearly as possible. If you find any errors or issues please add an issue to this repo."
-If you are having trouble using the `sclblpy` package, please [submit an issue to our github](https://github.com/scailable/sclblpy/issues/new), 
-we will try to fix it as quickly as possible!