diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..aa9d37c7
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,127 @@
+# Hopsworks Model Management
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+HSML is the library to interact with the Hopsworks Model Registry and Model Serving. The library makes it easy to export, manage and deploy models.
+
+The library automatically configures itself based on the environment in which it runs.
+However, to connect from an external Python environment additional connection information, such as the Hopsworks hostname (or IP address) and port (if it is not port 443), is required. For more information about the setup from external environments, see the setup section.
+
+## Getting Started On Hopsworks
+
+Instantiate a connection and get the project model registry and serving handles
+```python
+import hsml
+
+# Create a connection
+connection = hsml.connection()
+# or connection = hsml.connection(host="my.hopsworks.cluster", project="my_project")
+
+# Get the model registry handle for the project's model registry
+mr = connection.get_model_registry()
+
+# Get the model serving handle for the current model registry
+ms = connection.get_model_serving()
+```
+
+Create a new model
+```python
+import tensorflow as tf
+
+
+export_path = "/tmp/model_directory"
+tf.saved_model.save(model, export_path)
+model = mr.tensorflow.create_model(
+ name="my_model",
+ metrics=metrics_dict,
+ model_schema=model_schema,
+ input_example=input_example,
+ description="Iris Flower Classifier"
+ )
+
+model.save(export_path) # "/tmp/model_directory" or "/tmp/model_file"
+```
+
+Download a model
+```python
+model = mr.get_model("my_model", version=1)
+
+model_path = model.download()
+```
+
+Delete a model
+```python
+model.delete()
+```
+
+Get best performing model
+```python
+best_model = mr.get_best_model('my_model', 'accuracy', 'max')
+
+```
+
+Deploy a model
+```python
+deployment = model.deploy()
+```
+
+Start a deployment
+```python
+deployment.start()
+
+# Get the logs from a running deployment
+deployment.logs()
+```
+
+Make predictions with a deployed model
+```python
+data = { "instances": model.input_example }
+
+predictions = deployment.predict(data)
+```
+
+You can find more examples on how to use the library in [examples.hopsworks.ai](https://examples.hopsworks.ai).
+
+## Documentation
+
+Documentation is available at [Hopsworks Model Management Documentation](https://docs.hopsworks.ai/).
+
+## Issues
+
+For general questions about the usage of Hopsworks Machine Learning please open a topic on [Hopsworks Community](https://community.hopsworks.ai/).
+
+Please report any issue using [Github issue tracking](https://github.com/logicalclocks/machine-learning-api/issues).
+
+
+## Contributing
+
+If you would like to contribute to this library, please see the [Contribution Guidelines](CONTRIBUTING.md).
diff --git a/python/hsml/connection.py b/python/hsml/connection.py
index a25fe83b..a1c3a24a 100644
--- a/python/hsml/connection.py
+++ b/python/hsml/connection.py
@@ -61,8 +61,8 @@ class Connection:
api_key_file='modelregistry.key', # The file containing the API key generated above
hostname_verification=True) # Disable for self-signed certificates
)
- mr = conn.get_model_registry() # Get the project's default model registry
- ms = conn.get_model_serving() # Uses the previous model registry
+ mr = conn.get_model_registry()
+ ms = conn.get_model_serving()
```
Clients in external clusters need to connect to the Hopsworks Model Registry and Model Serving using an
@@ -119,6 +119,12 @@ def get_model_registry(self, project: str = None):
"""Get a reference to a model registry to perform operations on, defaulting to the project's default model registry.
Shared model registries can be retrieved by passing the `project` argument.
+ !!! example
+ ```python
+ mr = conn.get_model_registry() # Get the project's default model registry
+ ```
+
+
# Arguments
project: The name of the project that owns the shared model registry,
the model registry must be shared with the project the connection was established for, defaults to `None`.
@@ -131,6 +137,11 @@ def get_model_registry(self, project: str = None):
def get_model_serving(self):
"""Get a reference to model serving to perform operations on. Model serving operates on top of a model registry, defaulting to the project's default model registry.
+ !!! example
+ ```python
+ ms = conn.get_model_serving()
+ ```
+
# Returns
`ModelServing`. A model serving handle object to perform operations on.
"""
diff --git a/python/hsml/model.py b/python/hsml/model.py
index f9b4ba55..d7b77ea0 100644
--- a/python/hsml/model.py
+++ b/python/hsml/model.py
@@ -84,18 +84,40 @@ def __init__(
self._model_engine = model_engine.ModelEngine()
def save(self, model_path, await_registration=480):
- """Persist this model including model files and metadata to the model registry."""
+ """Persist this model including model files and metadata to the model registry.
+
+ !!! example
+ ```python
+ model.save('model.pkl')
+ ```
+
+ """
return self._model_engine.save(
self, model_path, await_registration=await_registration
)
def download(self):
- """Download the model files to a local folder."""
+ """Download the model files to a local folder.
+
+ !!! example
+ ```python
+ model_dir = model.download()
+ ```
+
+ """
return self._model_engine.download(self)
def delete(self):
"""Delete the model
+ !!! example
+ ```python
+ # get model object of a specific version
+ model = mr.get_model("my_model", version=1)
+ # delete the model version
+ model.delete()
+ ```
+
!!! danger "Potentially dangerous operation"
This operation drops all metadata associated with **this version** of the
model **and** deletes the model files.
@@ -370,6 +392,11 @@ def set_tag(self, name: str, value: Union[str, dict]):
A tag consists of a pair. Tag names are unique identifiers across the whole cluster.
The value of a tag can be any valid json - primitives, arrays or json objects.
+ !!! example
+ ```python
+ model.set_tag(name="tag_name", value=42)
+ ```
+
# Arguments
name: Name of the tag to be added.
value: Value of the tag to be added.
@@ -382,6 +409,11 @@ def set_tag(self, name: str, value: Union[str, dict]):
def delete_tag(self, name: str):
"""Delete a tag attached to a model.
+ !!! example
+ ```python
+ model.delete_tag("tag_name")
+ ```
+
# Arguments
name: Name of the tag to be removed.
# Raises
@@ -392,6 +424,11 @@ def delete_tag(self, name: str):
def get_tag(self, name: str):
"""Get the tags of a model.
+ !!! example
+ ```python
+ tag_value = model.get_tag("tag_name")
+ ```
+
# Arguments
name: Name of the tag to get.
# Returns
@@ -404,6 +441,11 @@ def get_tag(self, name: str):
def get_tags(self):
"""Retrieves all tags attached to a model.
+ !!! example
+ ```python
+ tags = model.get_tags()
+ ```
+
# Returns
`Dict[str, obj]` of tags.
# Raises
@@ -415,6 +457,14 @@ def __repr__(self):
return f"Model(name: {self._name!r}, version: {self._version!r})"
def get_url(self):
+ """Returns URL of the specific model.
+
+ !!! example
+ ```python
+ model_url = model.get_url()
+ ```
+
+ """
path = (
"/p/"
+ str(client.get_instance()._project_id)
diff --git a/python/hsml/model_registry.py b/python/hsml/model_registry.py
index bea6a5a7..41e5cbca 100644
--- a/python/hsml/model_registry.py
+++ b/python/hsml/model_registry.py
@@ -63,6 +63,20 @@ def get_model(self, name: str, version: int = None):
Getting a model from the Model Registry means getting its metadata handle
so you can subsequently download the model directory.
+ !!! example
+ ```python
+ import hsml
+
+ # connect with Hopsworks
+ conn = hsml.connection()
+
+ # get Hopsworks Model Registry
+ mr = conn.get_model_registry(project="my_project")
+
+ # get model object
+ model = mr.get_model("my_model", version=1)
+ ```
+
# Arguments
name: Name of the model to get.
version: Version of the model to retrieve, defaults to `None` and will
@@ -94,6 +108,11 @@ def get_models(self, name: str):
Getting all models from the Model Registry for a given name returns a list of model entities, one for each version registered under
the specified model name.
+ !!! example
+ ```python
+ models = mr.get_models("my_model")
+ ```
+
# Arguments
name: Name of the model to get.
# Returns
@@ -114,6 +133,17 @@ def get_best_model(self, name: str, metric: str, direction: str):
name corresponding to one of the keys in the training_metrics dict of the model and a direction. For example to
get the model version with the highest accuracy, specify metric='accuracy' and direction='max'.
+ !!! example
+ ```python
+ EVALUATION_METRIC = "r2_score"
+ SORT_METRICS_BY = "max" # your sorting criteria
+
+ # get best model based on custom metrics
+ best_model = mr.get_best_model("citibike_mlp_model",
+ EVALUATION_METRIC,
+ SORT_METRICS_BY)
+
+ ```
# Arguments
name: Name of the model to get.
metric: Name of the key in the training metrics field to compare.
diff --git a/python/hsml/model_schema.py b/python/hsml/model_schema.py
index 13be1dd8..018ca6d4 100644
--- a/python/hsml/model_schema.py
+++ b/python/hsml/model_schema.py
@@ -23,6 +23,14 @@
class ModelSchema:
"""Create a schema for a model.
+ !!! example
+ ```python
+ from hsml.schema import Schema
+ from hsml.model_schema import ModelSchema
+
+ model_schema = ModelSchema(input_schema=Schema(X_train), output_schema=Schema(y_train))
+ ```
+
# Arguments
input_schema: Schema to describe the inputs.
output_schema: Schema to describe the outputs.
diff --git a/python/hsml/python/signature.py b/python/hsml/python/signature.py
index f572096a..95e1bb7b 100644
--- a/python/hsml/python/signature.py
+++ b/python/hsml/python/signature.py
@@ -35,6 +35,17 @@ def create_model(
):
"""Create a generic Python model metadata object.
+ !!! example
+ ```python
+ model = mr.python.create_model(
+ name="my_model",
+ metrics=metrics_dict,
+ model_schema=model_schema,
+ input_example=input_example,
+ description="Iris Flower Classifier"
+ )
+ ```
+
!!! note "Lazy"
This method is lazy and does not persist any metadata or uploads model artifacts in the
model registry on its own. To save the model object and the model artifacts, call the `save()` method with a
diff --git a/python/hsml/schema.py b/python/hsml/schema.py
index bad972a3..2e767403 100644
--- a/python/hsml/schema.py
+++ b/python/hsml/schema.py
@@ -25,6 +25,14 @@
class Schema:
"""Create a schema for a model input or output.
+ !!! example
+ ```python
+ from hsml.schema import Schema
+
+ input_schema = Schema(X_train)
+ output_schema = Schema(y_train)
+ ```
+
# Arguments
object: The object to construct the schema from.
diff --git a/python/hsml/sklearn/signature.py b/python/hsml/sklearn/signature.py
index 27adb6f5..ecc93817 100644
--- a/python/hsml/sklearn/signature.py
+++ b/python/hsml/sklearn/signature.py
@@ -35,6 +35,17 @@ def create_model(
):
"""Create an SkLearn model metadata object.
+ !!! example
+ ```python
+ model = mr.sklearn.create_model(
+ name="my_model",
+ metrics=metrics_dict,
+ model_schema=model_schema,
+ input_example=input_example,
+ description="Iris Flower Classifier"
+ )
+ ```
+
!!! note "Lazy"
This method is lazy and does not persist any metadata or uploads model artifacts in the
model registry on its own. To save the model object and the model artifacts, call the `save()` method with a
diff --git a/python/hsml/tensorflow/signature.py b/python/hsml/tensorflow/signature.py
index f1d1635f..dd68af19 100644
--- a/python/hsml/tensorflow/signature.py
+++ b/python/hsml/tensorflow/signature.py
@@ -35,6 +35,17 @@ def create_model(
):
"""Create a TensorFlow model metadata object.
+ !!! example
+ ```python
+ model = mr.tensorflow.create_model(
+ name="my_model",
+ metrics=metrics_dict,
+ model_schema=model_schema,
+ input_example=input_example,
+ description="Iris Flower Classifier"
+ )
+ ```
+
!!! note "Lazy"
This method is lazy and does not persist any metadata or uploads model artifacts in the
model registry on its own. To save the model object and the model artifacts, call the `save()` method with a
diff --git a/python/hsml/torch/signature.py b/python/hsml/torch/signature.py
index 32f359be..c77f01b8 100644
--- a/python/hsml/torch/signature.py
+++ b/python/hsml/torch/signature.py
@@ -35,6 +35,17 @@ def create_model(
):
"""Create a Torch model metadata object.
+ !!! example
+ ```python
+ model = mr.torch.create_model(
+ name="my_model",
+ metrics=metrics_dict,
+ model_schema=model_schema,
+ input_example=input_example,
+ description="Iris Flower Classifier"
+ )
+ ```
+
!!! note "Lazy"
This method is lazy and does not persist any metadata or uploads model artifacts in the
model registry on its own. To save the model object and the model artifacts, call the `save()` method with a