Model Registry as a Service (MRaaS)
===================================

This repository contains the source code and relevent documentation for the Model Registry as a Service (MRaaS).
The MRaaS allows users to manage artifacts, and metadata associated to a registered machine learning (ML) model. This service also retreives project and model data from a specified Intel® Geti™ server instance.
The model registry acts as a storage resource that holds a model's metadata and artifacts for easy retrieval by an application or service. Without the service, tracking models deployed to an edge environment would be more difficult and the likelihood models are served with applications or services instead of managed independently is higher.
The model registry service is intended to improve the management and utilization of ML models on the edge.

Table of Contents
-----------------


* `Introduction <#model-as-a-service>`__
* `Requirements <#requirements>`__

  * `Software <#software>`__

* `Setup <#setup>`__

  * `Local Development <#local-development>`__
  * `Production <#production>`__

* `Configuration <#configuration>`__

  * `Required Variables <#required-variables>`__
  * `Example .env file <#example-env-file>`__

* `Usage <#usage>`__
* `Testing <#testing>`__
* `License <#license>`__
* `Contact <#contact>`__

Requirements
------------

This microservice requires the following to run:

Software:
^^^^^^^^^

**Operating System:**


* Linux (tested on Debian 12)

**Programming Language:**


* Python 3.9

**Dependencies:**


* geti-sdk (1.5.8)
* mlflow (2.7.1)
* psycopg2-binary (2.9.7)
* boto3 (1.28.44)
* minio (7.1.16)
* fastapi (0.104.1)
* uvicorn (0.24.0.post1)
* python-multipart (0.0.6)
* pydantic (2.3.0)
* pydantic_core (2.6.3)

**Data management solutions:**


* PostgreSQL (13.0)
* MinIO (2020-12-12T08-39-07Z)

**Development and Deployment resources**


* Docker and Docker Compose
* A code editor or IDE supporting Python

Setup
-----

Local Development
^^^^^^^^^^^^^^^^^

*Steps based on Linux*


#. **Clone repository**
   .. code-block::

      git clone https://github.com/intel-innersource/applications.services.esh.model-registry-as-a-service.git

#. **Install Python 3.9**
   .. code-block::

      sudo apt-get install python3.9

#. **Create virtual environment**
   ```
   cd applications.services.esh.model-registry-as-a-service

virtualenv -p /usr/bin/python3.9 myenv

.. code-block::

   3. **Activate virtual environment**

source myenv/bin/activate

.. code-block::

   4. **Install dependencies**

pip install -r requirements.txt

.. code-block::

   5. **Configure environment variables**
       * Update the environment variables with missing values
       * Update `DEV_MODE=true` to enable non-encrypted connection between services
       * Update the following environment variables in the `.env` file in the project's root directory to enable access to a Geti server workspace's projects and models:
           * `GETI_HOST`: The url for a Geti Server instance
           * `GETI_TOKEN`: Your access token for a Geti Server instance
   6. **Run the microservice**

cd app/
python main.py

.. code-block::

   ### Production
   1. Configure environment variables
       * Update environment variables as needed
           *  See [Local Development > 5. Configure environment variables](#local-development) for details
       * Update the `DEV_MODE=false` to enable SSL for the model registry and an encrypted connection between services
   1. Create certificates and keys

.. code-block::

   ./ssl_certs_setup.sh
   ```


#. Build Docker image(s)
   .. code-block::

       docker compose build

#. Create SSL certificates and keys for SSL and encrypted communication
   .. code-block::

       ./ssl_certs_setup.sh

#. Create and start Docker containers
   .. code-block::

       docker compose up -d

Configuration
-------------

This microservice uses environment variables for configuration.

Required Variables:
^^^^^^^^^^^^^^^^^^^


* ``DEV_MODE``\ : Set to ``true`` for development mode. Security and encryption are disabled in this mode. Otherwise, ``false`` for production mode. Security and encryption are enabled in this mode.
* ``MINIO_ACCESS_KEY``\ : Your access key for a MinIO object storage server
* ``MINIO_SECRET_KEY``\ : Your secret key for a MinIO object storage server
* ``PKG_SRC``\ : The url where the nightly packages are released
* ``USER_PASSWORD``\ : The password used for root or admin accounts
* ``EII_USER_NAME``\ : The user name for the user within the Docker container
* ``EII_UID``\ : The ID for the user within the Docker container
* ``GETI_HOST``\ : The url for a Geti Server instance
* ``GETI_TOKEN``\ : Your access token for a Geti Server instance
* ``GETI_VERIFY_CERT``\ : Set to ``0`` to disable certificate validation; Otherwise ``1`` to enable certificate validation
* ``MRAAS_PSQL_HOSTNAME``\ : The host name for the PostgreSQL service
* ``MRAAS_PSQL_USER``\ : The user name for the PostgreSQL database
* ``MRAAS_PSQL_PASSWORD``\ : The password associated to the ``MRAAS_PSQL_USER``
* ``MRAAS_PSQL_DATABASE``\ : The name of the PostgreSQL database
* ``MRAAS_PSQL_PORT``\ : The listening port for PostgreSQL server
* ``MRAAS_MINIO_BUCKET_NAME``\ : The name of the bucket where model artifacts are stored in MinIO Object Storage
* ``MRAAS_MINIO_HOSTNAME``\ : The host name for the MinIO service
* ``MRAAS_MINIO_SERVER_PORT``\ : The server port for the MinIO service
* ``MRAAS_VERSION``\ : The version of the MRaaS
* ``MRAAS_MIN_LOG_LEVEL``\ : The minimum threshold for log message

  * The support values are NOTSET, DEBUG, INFO, WARNING, ERROR, and CRITICAL
  * These levels are listed from least to most severe

* ``MRAAS_SERVER_PORT``\ : The server port for the MRaaS
* ``MRAAS_DEBUGPY_PORT``\ : The Debugpy port for the MRaaS
* ``MRAAS_MLFLOW_S3_ENDPOINT_URL``\ : The S3 endpoint URL to use for artifact operations

Example .env file:
^^^^^^^^^^^^^^^^^^

.. code-block::

   # -------------------------------------------
   # MRaaS environment variables

   DEV_MODE=true

   # DEB pacakges source location
   PKG_SRC=http://eii-nightly-devops.iind.intel.com/latest

   USER_PASSWORD=

   # Docker security
   EII_USER_NAME=eiiuser
   EII_UID=1999

   # Intel Geti Server details
   GETI_HOST=
   GETI_TOKEN=
   GETI_VERIFY_CERT=0

   #PostgreSQL service & client adapter
   MRAAS_PSQL_HOSTNAME=mraas_postgres
   MRAAS_PSQL_USER=
   MRAAS_PSQL_PASSWORD=
   MRAAS_PSQL_DATABASE=model_registry_db
   MRAAS_PSQL_PORT=5432

   # MinIO service & client
   MRAAS_MINIO_ACCESS_KEY=
   MRAAS_MINIO_SECRET_KEY=
   MRAAS_MINIO_BUCKET_NAME=model-registry
   MRAAS_MINIO_HOSTNAME=mraas_minio
   MRAAS_MINIO_SERVER_PORT=8000

   # Model Registry service
   MRAAS_VERSION=1.0
   MRAAS_MIN_LOG_LEVEL=INFO
   MRAAS_SERVER_PORT=5002
   MRAAS_DEBUGPY_PORT=5678

   # MLflow
   MRAAS_MLFLOW_S3_ENDPOINT_URL=http://127.0.0.1:8000

Usage
-----

You can interact with the model registry through its REST API.

After successfully launching the service, documentation describing each API endpoint can be found at http://{ip-address}:{MRAAS_SERVER_PORT}/docs

**Note**\ : All API endpoints requires authentication to access. Please follow the steps below to obtain a JSON Web Token (JWT). The JWT is used as a Bearer token when making a request:


#. **Login**\ : Make a POST request to the ``/login`` endpoint with your ``username`` and ``password``. The supported user names are ``admin`` and ``root``. The ``password`` is the same as the ``USER_PASSWORD`` environment variable set in the ``.env`` file
#. **Receive JWT**\ : The successful response from the ``/login`` endpoint will include an access token in the Response body.
#. **Include Token in Requests**\ : For subsequent API calls, include the obtained Bearer token in the Authorization header of your requests.

Example:

.. code-block::

   Authorization: Bearer <your_token_here>

Testing
-------

``pytest`` is used to test the core functionality of individual modules and functions.

**Prerequiste**\ : Install pytest and other relevant dependencies

.. code-block::

   source myenv/bin/activate

   pip install -r tests/requirements-tests.txt


#. Run tests

   * ``pytest --cov=app tests/`` - Generate a code coverage report for all tests 
   * ``pytest --cov=app --cov-report html`` - Generate a HTML report of the code coverage
   * ``pytest tests/unit_tests/file.py`` - Run the tests in a specific file
   * ``pytest tests/unit_tests/test_main.py::test_function_name`` - Run a specific test function

License
-------


* Proprietary

Contact
-------


* Elroy Ashtian (elroy.ashtian@intel.com)