From 676abb5a925410ce80e1ac43d819865f7d6e2625 Mon Sep 17 00:00:00 2001 From: Prakash Narayana Moorthy Date: Fri, 12 Apr 2024 19:49:24 +0000 Subject: [PATCH] address review comments on PR Signed-off-by: Prakash Narayana Moorthy --- inference-contract/README.md | 37 ++++- .../docs/notebooks/documents/overview.md | 6 +- .../docs/notebooks/factories/token-issuer.py | 15 +- .../docs/notebooks/templates/token-issuer.py | 40 +++-- .../docs/notebooks/templates/token.py | 40 +++-- inference-contract/test/guardian_frontend.sh | 138 ------------------ inference-contract/test/script_test.sh | 2 + 7 files changed, 78 insertions(+), 200 deletions(-) delete mode 100755 inference-contract/test/guardian_frontend.sh diff --git a/inference-contract/README.md b/inference-contract/README.md index d25f451..3403c1b 100644 --- a/inference-contract/README.md +++ b/inference-contract/README.md @@ -112,14 +112,35 @@ cd $PDO_CONTRACTS_SOURCE_ROOT/inference-contract/test/ We provide [Jupyter Notebooks](./docs/notebooks/README.md) that can be executed in an interactive manner to illustrate the functionality of the inference -contract family. The notebooks assume that the pdo services, -pdo ledger as well the asset guardian service are running prior to executing -notebook commands. As noted earlier, the guardian backend is the OpenVINO -model server; the `docker run` command provided above is used to deploy the -backend. The frontend can be deployed (on bare-metal) using the following -command: +contract family. We support jupyter notebook deployment via both docker containers +as well as bare-metal. For docker, please invoke the `make test_jupyter` command +from within the docker folder contained within this repo. This command deploys the +pdo ledger, pdo services, guardian frontend as well as the openvino containers in +addition to the container that hosts the jupyter server for interaction. If bare-metal +deployment of jupyter server is desired, please ensure that pdo services, pdo ledger +as well the asset guardian service are running prior to starting the jupyter server +on bare-metal. Note that these services may be deployed either on bare-metal or docker, +even though the jupyter server is deployed on bare-metal. Please consult the +`https://github.com/hyperledger-labs/private-data-objects/tree/main` repo for deploypment +options for pdo ledger and services. Regarding deployment of the model guardian, +the guardian backend is the OpenVINO model server; the `docker run` command provided above +is used to deploy the backend. Deploying openvino model server without docker is possible; +please consult `https://docs.openvino.ai/2022.3/ovms_what_is_openvino_model_server.html` +for instructions. For deploying the guardian front end on bare-metal, please use the following +commands to sequentially deploy the guardian storage service first, and then the guardian websevice. ```bash -cd $PDO_CONTRACTS_SOURCE_ROOT/inference-contract/test/ -./guardian_frontend.sh +${PDO_HOME}/contracts/inference/scripts/ss_start.sh -c -o ${PDO_HOME}/logs -- \ + --loglevel debug \ + --config guardian_service.toml \ + --config-dir ${PDO_HOME}/etc/contracts \ + --identity guardian_sservice + +${PDO_HOME}/contracts/inference/scripts/gs_start.sh -c -o ${PDO_HOME}/logs -- \ + --loglevel debug \ + --config guardian_service.toml \ + --config-dir ${PDO_HOME}/etc/contracts \ + --identity guardian_service \ + --bind host ${PDO_HOSTNAME} \ + --bind service_host ${PDO_HOSTNAME} ``` diff --git a/inference-contract/docs/notebooks/documents/overview.md b/inference-contract/docs/notebooks/documents/overview.md index bba47fe..f9fc812 100644 --- a/inference-contract/docs/notebooks/documents/overview.md +++ b/inference-contract/docs/notebooks/documents/overview.md @@ -14,12 +14,12 @@ jupyter: # Inference contracts using PDO # -The Inference contract family is a suite of contracts that extend the -capabilities of the [Exchange Contract Family ](../exchange/documents/overview.ipynb) +The Inference contract family is a suite of contracts that extend the +capabilities of the [Exchange Contract Family ](../exchange/documents/overview.ipynb) in order to create a confidentiality preserving policy-wrapper around the usage of a machine learning (ML) model. At its core, the implementation contains a Token Object PDO contract that specifies and checks the -policies to be followed while using the ML model for inferecing +policies to be followed while using the ML model for inferencing operations. In this implementation, the ML Model is assumed to be an [OpenVINO based IR](https://docs.openvino.ai/2023.2/openvino_ir.html) model. The model itself is deployed via an asset guardian service; the diff --git a/inference-contract/docs/notebooks/factories/token-issuer.py b/inference-contract/docs/notebooks/factories/token-issuer.py index b1f47ec..934b5c7 100644 --- a/inference-contract/docs/notebooks/factories/token-issuer.py +++ b/inference-contract/docs/notebooks/factories/token-issuer.py @@ -16,8 +16,8 @@ # %% [markdown] # # Token Family Factory # -# This notebook simplifies the creation of an instance of a token issuer. -# Update the token configuration information then evaluate the notebook to +# This notebook simplifies the creation of an instance of a token issuer. +# Update the token configuration information then evaluate the notebook to # create a new token issuer. That token issuer will be able to mint tokens # for the underlying ML model for which policy-based inferencing need to be # enabled. The created token is then exchanged to a prospective model user @@ -35,20 +35,21 @@ # %% [markdown] # ## Configure Token Information # -# This section enables customization of the token that will be minted. +# This section enables customization of the token that will be minted. # Edit the variables in the section below as necessary. # # * identity : the identity of the token creator # * token_class : the name of tokens that will be generated # -# Note that the notebook assumes that there is a key file for the identity of -# the form: `${keys}/${identity}_private.pem`. +# Note that the notebook assumes that there is a key file for the identity of +# the form: `${keys}/${identity}_private.pem`. Please use the /documents/key_manager.ipynb +# notebook to create desired keys. # %% tags=["parameters"] identity = input('Identity of the token issuer: ') token_class = input('Name of the class of tokens to issue: ') -service_host = input('Service host [localhost]: ') +service_host = input('Service host: ') or 'localhost' # %% [markdown] @@ -66,4 +67,4 @@ } instance_file = pc_jupyter.instantiate_notebook_from_template(token_class, 'token-issuer', instance_parameters) -ip_display.display(ip_display.Markdown('[Token Issuer]({})'.format(instance_file))) +ip_display.display(ip_display.Markdown('[Newly created token issuer]({})'.format(instance_file))) diff --git a/inference-contract/docs/notebooks/templates/token-issuer.py b/inference-contract/docs/notebooks/templates/token-issuer.py index f6d989f..5e28a59 100644 --- a/inference-contract/docs/notebooks/templates/token-issuer.py +++ b/inference-contract/docs/notebooks/templates/token-issuer.py @@ -14,26 +14,24 @@ # %% [markdown] # # Token Issuer Notebook -# This section enables customization of the token that will be minted. Edit the variables in the section below as necessary. +# This section enables customization of the token that will be minted. Edit the variables in the section below as necessary. +# +# * token_owner : the identity of the token creator +# * token_class : the name of tokens that will be generated, this is only used to simplify local access (e.g. context file name) +# * token_description : a description of the asset associated with the minted tokens +# * token_metadata : additional information about the token +# * count : the number of tokens to mint for the asset +# *service_host : the host for the eservice where tokens will be minted, this will use the default service group # -# identity : the identity of the token creator -# service_host : the host for the eservice where tokens will be minted, this will use the default service group -# token_class : the name of tokens that will be generated, this is only used to simplify local access (e.g. context file name) -# token_description : a description of the asset associated with the minted tokens -# token_metadata : additional information about the token -# count : the number of tokens to mint for the asset - # Note that the notebook assumes that there is a key file for the identity of the form: `${keys}/${identity}_private.pem`. # %% tags=["parameters"] -token_owner = 'user1' -token_class = 'mytoken' token_description = 'this is my token' -token_metadata = 'created by {}'.format(token_owner) +token_metadata = 'additional token metadata' count = 1 -service_host = 'localhost' -instance_identifier = '' +# rest of the parameters such as token_owner, token_class, service_host, and instance_identifier will get auto filled from factory via papermill +# note that papermill places the parameters cell after first paramters cell in this notebook # %% [markdown] #
@@ -52,8 +50,8 @@ # ### Initialize the PDO Environment # # Initialize the PDO environment. This assumes that a functional PDO configuration -# is in place and that the PDO virtual environment has been activated. In particular, -# ensure that the groups file and eservice database have been configured correctly. +# is in place and that the PDO virtual environment has been activated. In particular, +# ensure that the groups file and eservice database have been configured correctly. # If you do not have a service groups configuration, you can create it for a single # service host by running the following: @@ -83,8 +81,8 @@ # ### Initialize the Contract Context # # The contract context defines the configuration for a collection of contract objects -# that interact with one another. By default, the context file used in this notebook -# is specific to the token. If you prefer to use a common context file, edit the +# that interact with one another. By default, the context file used in this notebook +# is specific to the token. If you prefer to use a common context file, edit the # `context_file` variable below. # # For the most part, no other modifications should be required. @@ -114,10 +112,10 @@ # %% [markdown] # ### Create the Token Issuer Contract # -# The process of creating the token issuer will also create an asset type contract object, -# a vetting organization contract object, and the guardian contract object. -# The asset type and vetting organization contract objects are principally used -# to complete the canonical asset interface that enables transparent value exchanges +# The process of creating the token issuer will also create an asset type contract object, +# a vetting organization contract object, and the guardian contract object. +# The asset type and vetting organization contract objects are principally used +# to complete the canonical asset interface that enables transparent value exchanges # with tokens and other digital assets. # %% diff --git a/inference-contract/docs/notebooks/templates/token.py b/inference-contract/docs/notebooks/templates/token.py index 6cb6b86..adb47d8 100644 --- a/inference-contract/docs/notebooks/templates/token.py +++ b/inference-contract/docs/notebooks/templates/token.py @@ -104,7 +104,12 @@ # %% [markdown] -# ### Invoke Inference Operation +# ## Operations that can be performed on the Token +# Below we illustrate some of the operations that a token owner can perform on the token. +# Note that what is permissible is entirely dependant on the policies +# implemented by the token contract +# +# ### Operation 1. Invoke Inference Operation # # The model is an image classfication model. Use the following cell to # provide input to the classification oepration. Current token object policy @@ -115,9 +120,9 @@ # via the contracts docker container, copy your test image to # `$PDO_CONTRACTS_SRC_ROOT/docker/xfer/client/` folder and # provide the value `/project/pdo/xfer/client` for the input `path`. -# -# Also, please note that `$PDO_CONTRACTS_SRC_ROOT/inference-contract/data` folder -# contains the sample image `zebra_wiki.jpg` that may be used for testing +# A sample test image `zebra_wiki.jpg` can be found at +# `$PDO_CONTRACTS_SRC_ROOT/inference-contract/data`. + # %% tags=["parameters"] image_name = input('Name of the image file') @@ -131,7 +136,7 @@ # %% [markdown] -# ### Transfer Ownership to a New User +# ### Operation 2. Transfer Ownership (and hence the right to perform inference) to a New User # # User1 now transfers ownership of the token object (and hence its capabilities) # to a new user. Note that the notebook assumes that user1 knows the public key @@ -147,35 +152,24 @@ state, token_context, new_owner=new_user_identity) # %% [markdown] -# ### Test Ownership -# -# Let's ensure that user1 can no longer perform operations on the asset. -# The following asset usage command should fail: - -# %% -inference_result = pc_jupyter.pcommand.invoke_contract_cmd( - pc_jupyter.ml_inference_token_object.cmd_do_inference, - state, token_context, image=image_name, search_path=[path]) - -# %% [markdown] -# ### New User Performs Operations on the Asset +# ### Operation 3.New User Performs Operations on the Asset # -# Let's also ensure that user2 can indeed perform operations on the asset. # Note that in the following command, we explicitly pass the identity of the caller +# The old token owner after ownership transfer can longer invoke inference oeprations. # %% inference_result = pc_jupyter.pcommand.invoke_contract_cmd( pc_jupyter.ml_inference_token_object.cmd_do_inference, - state, token_context, image=image_name, search_path=[path], identity='user2') + state, token_context, image=image_name, search_path=[path], identity=new_user_identity) # %% [markdown] -# ### Onwership Transfer Is Still Possible, But now done by user2! +# ### Operation 4. Re-transfer of ownership to a 3rd user Test Ownership # -# User2 is the current owner of the token, and can transfer asset-usage rights to -# a third person, say user3. +# The token policy in this example permits re-transfer of ownership. + # %% -current_owner_identity = new_user_identity #user2 +current_owner_identity = new_user_identity new_user_identity = 'user3' pc_jupyter.pcommand.invoke_contract_cmd( pc_jupyter.ml_inference_token_object.cmd_transfer_assets, diff --git a/inference-contract/test/guardian_frontend.sh b/inference-contract/test/guardian_frontend.sh deleted file mode 100755 index bd9c159..0000000 --- a/inference-contract/test/guardian_frontend.sh +++ /dev/null @@ -1,138 +0,0 @@ -#!/bin/bash - -# Copyright 2023 Intel Corporation -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# ----------------------------------------------------------------- -# ----------------------------------------------------------------- -: "${PDO_LEDGER_URL?Missing environment variable PDO_LEDGER_URL}" -: "${PDO_HOME?Missing environment variable PDO_HOME}" -: "${PDO_SOURCE_ROOT?Missing environment variable PDO_SOURCE_ROOT}" - -# ----------------------------------------------------------------- -# ----------------------------------------------------------------- - -source ${PDO_HOME}/bin/lib/common.sh -check_python_version - -if ! command -v pdo-shell &> /dev/null ; then - yell unable to locate pdo-shell - exit 1 -fi - - -# ----------------------------------------------------------------- -# ----------------------------------------------------------------- -if [ "${PDO_LEDGER_TYPE}" == "ccf" ]; then - if [ ! -f "${PDO_LEDGER_KEY_ROOT}/networkcert.pem" ]; then - die "CCF ledger keys are missing, please copy and try again" - fi -fi - -# ----------------------------------------------------------------- -# Process command line arguments -# ----------------------------------------------------------------- -SCRIPTDIR="$(dirname $(readlink --canonicalize ${BASH_SOURCE}))" -SOURCE_ROOT="$(realpath ${SCRIPTDIR}/..)" - -F_SCRIPT=$(basename ${BASH_SOURCE[-1]} ) -F_SERVICE_HOST=${PDO_HOSTNAME} -F_GUARDIAN_HOST=${PDO_HOSTNAME} -F_LEDGER_URL=${PDO_LEDGER_URL} -F_LOGLEVEL=${PDO_LOG_LEVEL:-info} -F_LOGFILE=${PDO_LOG_FILE:-__screen__} -F_CONTEXT_FILE=${SOURCE_ROOT}/test/test_context.toml -F_CONTEXT_TEMPLATES=${PDO_HOME}/contracts/inference/context -F_EXCHANGE_TEMPLATES=${PDO_HOME}/contracts/exchange/context - -F_USAGE='--host service-host | --ledger url | --loglevel [debug|info|warn] | --logfile file' -SHORT_OPTS='h:l:' -LONG_OPTS='host:,ledger:,loglevel:,logfile:' - -TEMP=$(getopt -o ${SHORT_OPTS} --long ${LONG_OPTS} -n "${F_SCRIPT}" -- "$@") -if [ $? != 0 ] ; then echo "Usage: ${F_SCRIPT} ${F_USAGE}" >&2 ; exit 1 ; fi - -eval set -- "$TEMP" -while true ; do - case "$1" in - -h|--host) F_SERVICE_HOST="$2" ; shift 2 ;; - -1|--ledger) F_LEDGER_URL="$2" ; shift 2 ;; - --loglevel) F_LOGLEVEL="$2" ; shift 2 ;; - --logfile) F_LOGFILE="$2" ; shift 2 ;; - --help) echo "Usage: ${SCRIPT_NAME} ${F_USAGE}"; exit 0 ;; - --) shift ; break ;; - *) echo "Internal error!" ; exit 1 ;; - esac -done - -F_SERVICE_GROUPS_FILE=${SOURCE_ROOT}/test/${F_SERVICE_HOST}_groups.toml -F_SERVICE_DB_FILE=${SOURCE_ROOT}/test/${F_SERVICE_HOST}_db - -_COMMON_=("--logfile ${F_LOGFILE}" "--loglevel ${F_LOGLEVEL}") -_COMMON_+=("--ledger ${F_LEDGER_URL}") -_COMMON_+=("--bind service_host ${F_SERVICE_HOST}") -_COMMON_+=("--service-groups ${F_SERVICE_GROUPS_FILE}") -_COMMON_+=("--service-db ${F_SERVICE_DB_FILE}") -_COMMON_+=("--context-file ${F_CONTEXT_FILE}") -OPTS=${_COMMON_[@]} - -F_KEY_FILES=() -KEYGEN=${PDO_SOURCE_ROOT}/build/__tools__/make-keys - -if [ ! -f ${PDO_HOME}/keys/guardian_service.pem ]; then - yell create keys for the guardian service - ${KEYGEN} --keyfile ${PDO_HOME}/keys/guardian_service --format pem - F_KEY_FILES+=(${PDO_HOME}/keys/guardian_service.pem) - - ${KEYGEN} --keyfile ${PDO_HOME}/keys/guardian_sservice --format pem - F_KEY_FILES+=(${PDO_HOME}/keys/guardian_sservice.pem) -fi - -# ----------------------------------------------------------------- -function cleanup { - rm -f ${F_SERVICE_GROUPS_FILE} - rm -f ${F_SERVICE_DB_FILE} ${F_SERVICE_DB_FILE}-lock - rm -f ${F_CONTEXT_FILE} - for key_file in ${F_KEY_FILES[@]} ; do - rm -f ${key_file} - done - - yell "shutdown guardian and storage service" - ${PDO_HOME}/contracts/inference/scripts/gs_stop.sh - ${PDO_HOME}/contracts/inference/scripts/ss_stop.sh -} - -trap cleanup EXIT - -# ----------------------------------------------------------------- -# Start the guardian service and the storage service -# ----------------------------------------------------------------- -try ${PDO_HOME}/contracts/inference/scripts/ss_start.sh -c -o ${PDO_HOME}/logs -- \ - --loglevel debug \ - --config guardian_service.toml \ - --config-dir ${PDO_HOME}/etc/contracts \ - --identity guardian_sservice - -sleep 3 - -try ${PDO_HOME}/contracts/inference/scripts/gs_start.sh -c -o ${PDO_HOME}/logs -- \ - --loglevel debug \ - --config guardian_service.toml \ - --config-dir ${PDO_HOME}/etc/contracts \ - --identity guardian_service \ - --bind host ${F_GUARDIAN_HOST} \ - --bind service_host ${F_SERVICE_HOST} - -read -p "Guardian Service Frontend Running. Press any key to exit" -exit diff --git a/inference-contract/test/script_test.sh b/inference-contract/test/script_test.sh index 513c43a..6fb40df 100755 --- a/inference-contract/test/script_test.sh +++ b/inference-contract/test/script_test.sh @@ -222,4 +222,6 @@ fi try inference_token do_inference ${OPTS} --identity token_holder1 \ --contract token.test1.token_object.token_1 --image "zebra_wiki.jpg" +#sleep for 10s + exit