This PR provides Jupyter Notebooks to illustrate the inference-contac…

…t family use-case.

The Notebooks' structure, installation, execution patterns are same as those used by the
Noteboks provided for the Exchange contract family. Please note that the inference guardian service
must be started prior to executing the notebooks. Please see inference-contract/README.md for instructions.

Some of the additional features offered by this PR taking advantage of recent commits to the contracts repo:

1. It is possible to use the inference contract jupyter notebook via docker (using features from PR 23)
2. When using docker, the inference guardian will run in a separate container (using features from PR 27)
3. The notebooks are constructed using jupytext python modules (using features from PR 29)

Signed-off-by: Prakash Narayana Moorthy <[email protected]>

docs/notebooks/index.md

@@ -51,9 +51,10 @@ The Digital Assets contract family implements a basic digital asset for bitmap i
 ### Inference
 
 
-The Inference contract family provides contracts for creating a confidentiality preserving policy-wrapper around the usage of a machine learning (ML) model. At its core, the implementation uses a token contract to  specify and enforce policies to be followed while using the ML model for inferecing operations. 
+The Inference contract family provides contracts for creating a confidentiality
+preserving policy-wrapper around the usage of a machine learning (ML) model.
+At its core, the implementation uses a token contract to  specify and enforce
+policies to be followed while using the ML model for inferecing operations.
 
-At this point in time, there are no corresponding notebooks available yet. However, you can explore these contracts using the standard pdo command-line tools. The corresponding contract code is in the `inference-contract` sub-directory.
-```python
-
-```
+To experiment with inference contracts, explore the
+[Inference Contract Family notebook](inference/index.ipynb)

exchange-contract/pdo/contracts/jupyter.py

@@ -246,6 +246,7 @@ def create_download_link(filename : str, label : str = 'Download File') :
 # -----------------------------------------------------------------
 _contract_families_ = {
     'exchange' : 'ex',
+    'inference' : 'ml',
 }
 
 for cf, cs in _contract_families_.items() :

inference-contract/CMakeLists.txt

@@ -45,6 +45,14 @@ ADD_SHELL_TEST(inference script SCRIPT test/script_test.sh)
 # is significant and should not be removed; it prevents the notebooks
 # directory being prepended to the copied name
 # -----------------------------------------------------------------
+
+INCLUDE(Jupyter)
+FILE(GLOB_RECURSE NOTEBOOK_SOURCES docs/notebooks/*.py docs/notebooks/*.md)
+
+CONVERT_JUPYTEXT(INFERENCE_NOTEBOOKS ${NOTEBOOK_SOURCES})
+
+ADD_CUSTOM_TARGET(inference-notebooks ALL DEPENDS ${INFERENCE_NOTEBOOKS})
+
 INSTALL(DIRECTORY docs/notebooks/
   DESTINATION "${PDO_JUPYTER_ROOT}/inference"
   FILES_MATCHING PATTERN "*.ipynb")

inference-contract/MANIFEST

@@ -30,6 +30,7 @@ MANIFEST.in
 ./pdo/inference/scripts/__init__.py
 ./pdo/inference/scripts/guardianCLI.py
 ./pdo/inference/scripts/scripts.py
+./pdo/inference/jupyter.py
 ./scripts/gs_stop.sh
 ./scripts/gs_start.sh
 ./scripts/gs_status.sh

inference-contract/README.md

@@ -107,3 +107,19 @@ the inferencing operations.
 cd $PDO_CONTRACTS_SOURCE_ROOT/inference-contract/test/
 ./script_test.sh
 ```
+
+## Jupyter Notebooks for the Inference Contract ##
+
+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:
+
+```bash
+cd $PDO_CONTRACTS_SOURCE_ROOT/inference-contract/test/
+./guardian_frontend.sh
+```

inference-contract/docs/notebooks/.gitignore

@@ -0,0 +1 @@
+*.ipynb

inference-contract/docs/notebooks/documents/overview.md

@@ -0,0 +1,61 @@
+---
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.16.1
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+# 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) 
+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
+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
+overall architecture of how a PDO token object gets used to manage an
+asset deployed via an asset guardian service is largely similar to the
+one used within the [Digital Asset Contract Family](https://github.com/hyperledger-labs/pdo-contracts/tree/main/digital-asset-contract). Note that the
+digital asset contract family in turn relies on the
+[Exchange Contract Family ](../exchange/documents/overview.ipynb)
+for the foundational secure communication protocols between the Token
+Object and the Asset Guardian Service.
+
+The asset guardian service here is implemented as a web service
+containing a frontend and backend portions.The backend of the guardian
+service implements the OpenVINO model server capable of performing
+inferencing operations using the OpenVINO IR model. The frontend of
+the guardian service at a high level performs two
+functions: 1. Processes the capability package generated by the token
+object and generates/invokes the API for the backend. The capability
+package may be thought of the asset-usage approval generated by the
+token object smart contract. 2. Implements any input preprocessing and
+output postprocessing (collectively referred to as model scoring) as
+determined necessary by the original asset owner.
+
+The token object, as well as the asset guardian service are deployed
+by the asset owner, as part of the deployment sequence. The asset
+owner in addition authors the model scoring script that is executed as
+part of the guardian service frontend. Note that the asset owner may
+use the token object to control key parameters used by the scoring
+script, and thus ensuring tight binding between the token object
+contract and the model usage.
+
+We note that while the Token Object smart contract is executed within
+Intel SGX enclaves (via PDO), the asset guardian service in this
+impelementation is not protected by TEEs. A prospective asset-user
+(token owner) relies on the asset owner for the trustworthiness of the
+guardian service. However, it is entirely possible to extend the
+protocols and implementation here to offer increased protection by
+leveraging HW TEEs for the guardian service as well. Opensourcing of
+additional security features is left for future work.

inference-contract/docs/notebooks/factories/token-issuer.py

@@ -0,0 +1,69 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.16.1
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+
+# %% [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 
+# 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
+# who gets to use the ML model subject to the policies bound to the token.
+
+
+# %%
+import os
+import pdo.contracts.jupyter as pc_jupyter
+import IPython.display as ip_display
+
+pc_jupyter.load_ipython_extension(get_ipython())
+
+
+# %% [markdown]
+# ## Configure Token Information
+#
+# 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`.
+
+
+# %% 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]: ')
+
+
+# %% [markdown]
+# ## Create the Token Issuer Notebook
+#
+# Create a new token issuer notebook with the specific token identified.
+#
+
+
+# %%
+instance_parameters = {
+    'token_owner' : identity,
+    'token_class' : token_class,
+    'service_host' : service_host,
+}
+
+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)))

inference-contract/docs/notebooks/index.md

@@ -0,0 +1,33 @@
+---
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.16.1
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+# Inference Contract Family
+
+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. This directory contains sample 
+Jupyter notebooks that can be used to create and interact with contract
+objects in the Inference contract family. The structure of notebooks follows 
+the pattern followed by the notebooks used to illustrate the exchange contracts
+family.
+
+More detailed information about the inference contract family is available in the
+[Inference Contract Family Overview](documents/overview.ipynb).
+
+## Factories
+
+The links below connect you to "factories" for creating contract objects in the Inference contract family.
+
+* [Create and mint tokens for policy-based usage of an ML model](factories/token-issuer.ipynb)