Python SDK for katib (#1177)

* python SDK for katib with docs and examples * Update README.md * Update README.md * Update bayesianoptimization-katib-sdk.ipynb * Update bayesianoptimization-katib-sdk.ipynb * Update tfjob-katib-sdk.ipynb * Create OWNERS * Update bayesianoptimization-katib-sdk.ipynb * Update tfjob-katib-sdk.ipynb * Update bayesianoptimization-katib-sdk.ipynb * Update tfjob-katib-sdk.ipynb * Update bayesianoptimization-katib-sdk.ipynb * Update OWNERS * Update README.md * updated changes as per review comments * Update README.md * Update README.md * Added pip installation for katib sdk and removed status from get_optimal_hyperparamater API * Update README.md * Updated changes for delete_exp and removed unused imports
kubeflow · Jun 4, 2020 · c2c5288 · c2c5288
1 parent 2179c16
commit c2c5288
Show file tree

Hide file tree

Showing 134 changed files with 12,422 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -28,6 +28,7 @@ Table of Contents
       * [Katib](#katib)
       * [Running examples](#running-examples)
       * [Cleanups](#cleanups)
+  * [Katib SDK](#katib-sdk)      
   * [Quick Start](#quick-start)
   * [Who are using Katib?](#who-are-using-katib)
   * [CONTRIBUTING](#contributing)
@@ -339,6 +340,15 @@ kubectl -n kubeflow port-forward svc/katib-ui 8080:80
 
 You can access the Katib UI using this URL: ```http://localhost:8080/katib/```.
 
+### Katib SDK
+* Install the SDK
+  ```
+  pip install kubeflow-katib
+  ```
+* Get the Katib SDK documents from [here](sdk/python/README.md).
+
+* Follow the [example here](sdk/python/examples/bayesianoptimization-katib-sdk.ipynb) to use the Katib SDK to create, delete and get Hyperparameter values of experiment.
+
 ### Cleanups
 
 Delete installed components using `kubectl delete -f` on the respective folders. 

diff --git a/sdk/python/README.md b/sdk/python/README.md
@@ -0,0 +1,99 @@
+# Kubeflow Katib SDK 
+
+Python SDK for Kubeflow Katib
+
+## Requirements.
+
+Python 2.7 and 3.4+
+
+## Installation & Usage
+
+### pip install
+
+```sh
+pip install kubeflow-katib
+```
+
+Then import package:
+
+```python
+from kubeflow import katib
+```
+
+### Setuptools
+
+Install via [Setuptools](http://pypi.python.org/pypi/setuptools).
+
+```sh
+python setup.py install --user
+```
+(or `sudo python setup.py install` to install the package for all users)
+
+## Getting Started
+
+Please follow the [samples](examples/bayesianoptimization-katib-sdk.ipynb) to create, update, delete and get hyperparamaters of  Katib Experiment.
+
+## Documentation for API Endpoints
+
+Class | Method | Description
+------------ | -------------  | -------------
+[KatibClient](docs/KatibClient.md) | [create_experiment](docs/KatibClient.md#create_experiment) | Create Katib Experiment|
+[KatibClient](docs/KatibClient.md) | [get_experiment](docs/KatibClient.md#get_experiment)    | Get or watch the specified Experiment or all Experiment in the namespace |
+[KatibClient](docs/KatibClient.md) | [delete_experiment](docs/KatibClient.md#delete_experiment) | Delete specified Experiment |
+[KatibClient](docs/KatibClient.md) | [list_experiments](docs/KatibClient.md#list_experiments) | List all Experiments with status |
+[KatibClient](docs/KatibClient.md) | [get_experiment_status](docs/KatibClient.md#get_experiment_status) | Get Experiment status|
+[KatibClient](docs/KatibClient.md) | [is_experiment_succeeded](docs/KatibClient.md#is_experiment_succeeded) | Check if Experiment status is Succeeded |
+[KatibClient](docs/KatibClient.md) | [list_trials](docs/KatibClient.md#list_trials) | List all trials of specified Experiment |
+[KatibClient](docs/KatibClient.md) | [get_optimal_hyperparmeters](docs/KatibClient.md#get_optimal_hyperparmeters) | Get currentOptimalTrial with paramaterAssignments of an Experiment|
+
+
+## Documentation For Models
+
+ - [V1alpha3AlgorithmSetting](docs/V1alpha3AlgorithmSetting.md)
+ - [V1alpha3AlgorithmSpec](docs/V1alpha3AlgorithmSpec.md)
+ - [V1alpha3CollectorSpec](docs/V1alpha3CollectorSpec.md)
+ - [V1alpha3EarlyStoppingSetting](docs/V1alpha3EarlyStoppingSetting.md)
+ - [V1alpha3EarlyStoppingSpec](docs/V1alpha3EarlyStoppingSpec.md)
+ - [V1alpha3Experiment](docs/V1alpha3Experiment.md)
+ - [V1alpha3ExperimentCondition](docs/V1alpha3ExperimentCondition.md)
+ - [V1alpha3ExperimentList](docs/V1alpha3ExperimentList.md)
+ - [V1alpha3ExperimentSpec](docs/V1alpha3ExperimentSpec.md)
+ - [V1alpha3ExperimentStatus](docs/V1alpha3ExperimentStatus.md)
+ - [V1alpha3FeasibleSpace](docs/V1alpha3FeasibleSpace.md)
+ - [V1alpha3FileSystemPath](docs/V1alpha3FileSystemPath.md)
+ - [V1alpha3FilterSpec](docs/V1alpha3FilterSpec.md)
+ - [V1alpha3GoTemplate](docs/V1alpha3GoTemplate.md)
+ - [V1alpha3GraphConfig](docs/V1alpha3GraphConfig.md)
+ - [V1alpha3Metric](docs/V1alpha3Metric.md)
+ - [V1alpha3MetricsCollectorSpec](docs/V1alpha3MetricsCollectorSpec.md)
+ - [V1alpha3NasConfig](docs/V1alpha3NasConfig.md)
+ - [V1alpha3ObjectiveSpec](docs/V1alpha3ObjectiveSpec.md)
+ - [V1alpha3Observation](docs/V1alpha3Observation.md)
+ - [V1alpha3Operation](docs/V1alpha3Operation.md)
+ - [V1alpha3OptimalTrial](docs/V1alpha3OptimalTrial.md)
+ - [V1alpha3ParameterAssignment](docs/V1alpha3ParameterAssignment.md)
+ - [V1alpha3ParameterSpec](docs/V1alpha3ParameterSpec.md)
+ - [V1alpha3SourceSpec](docs/V1alpha3SourceSpec.md)
+ - [V1alpha3Suggestion](docs/V1alpha3Suggestion.md)
+ - [V1alpha3SuggestionCondition](docs/V1alpha3SuggestionCondition.md)
+ - [V1alpha3SuggestionList](docs/V1alpha3SuggestionList.md)
+ - [V1alpha3SuggestionSpec](docs/V1alpha3SuggestionSpec.md)
+ - [V1alpha3SuggestionStatus](docs/V1alpha3SuggestionStatus.md)
+ - [V1alpha3TemplateSpec](docs/V1alpha3TemplateSpec.md)
+ - [V1alpha3Trial](docs/V1alpha3Trial.md)
+ - [V1alpha3TrialAssignment](docs/V1alpha3TrialAssignment.md)
+ - [V1alpha3TrialCondition](docs/V1alpha3TrialCondition.md)
+ - [V1alpha3TrialList](docs/V1alpha3TrialList.md)
+ - [V1alpha3TrialSpec](docs/V1alpha3TrialSpec.md)
+ - [V1alpha3TrialStatus](docs/V1alpha3TrialStatus.md)
+ - [V1alpha3TrialTemplate](docs/V1alpha3TrialTemplate.md)
+
+
+## Documentation For Authorization
+
+ All endpoints do not require authorization.
+
+
+## Author
+
+prem0912
diff --git a/sdk/python/docs/KatibClient.md b/sdk/python/docs/KatibClient.md
@@ -0,0 +1,135 @@
+# KatibClient
+
+> KatibClient(config_file=None, context=None, client_configuration=None, persist_config=True)
+
+User can loads authentication and cluster information from kube-config file and stores them in kubernetes.client.configuration. Parameters are as following:
+
+parameter |  Description
+------------ | -------------
+config_file | Location of  kube-config file. Defaults to `~/.kube/config`. Note that the config_file is needed if user want to operate katib SDK in another remote cluster, user must set `config_file` to load kube-config file explicitly, e.g. `KatibClient(config_file="~/.kube/config")`. |
+context |Set the active context. If is set to None, current_context from config file will be used.|
+client_configuration | The kubernetes.client.Configuration to set configs to.|
+persist_config | If True, config file will be updated when changed (e.g GCP token refresh).|
+
+
+The APIs for KatibClient are as following:
+
+Class | Method | Description
+------------ | -------------  | -------------
+KatibClient | [create_experiment](#create_experiment) | Create Katib Experiment|
+KatibClient | [get_experiment](#get_experiment)    | Get or watch the specified experiment or all experiments in the namespace |
+KatibClient | [delete_experiment](#delete_experiment) | Delete specified experiment |
+KatibClient | [list_experiments](#list_experiments) | List all experiments with status |
+KatibClient | [get_experiment_status](#get_experiment_status) | Get experiment status|
+KatibClient | [is_experiment_succeeded](#is_experiment_succeeded) | Check if experiment status is Succeeded |
+KatibClient | [list_trials](#list_trials) | List all trials of specified experiment with status |
+KatibClient | [get_optimal_hyperparmeters](#get_optimal_hyperparmeters) | Get currentOptimalTrial with paramaterAssignments of an experiment|
+
+
+
+## create_experiment
+> create_experiment(experiment, namespace=None)
+
+### Parameters
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | -------------
+experiment | [V1alpha3Experiment](V1alpha3Experiment.md) | experiment definition| Required |
+namespace | str | Namespace for experiment deploying to. If the `namespace` is not defined, will align with experiment definition, or use current or default namespace if namespace is not specified in experiment definition.  | Optional |
+
+### Return type
+object
+
+## get_experiment
+> get_experiment(name=None, namespace=None)
+
+Get experiment in the specified namespace
+
+### Parameters
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | -------------
+name  | str | Experiment name. If the `name` is not specified, will get all experiments in the namespace.| Optional. |
+namespace | str | Experiment's namespace. Defaults to current or default namespace.| Optional |
+
+### Return type
+object
+
+## delete_experiment
+> delete_experiment(name, namespace=None)
+
+### Parameters
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | -------------
+name  | str | Experiment name.| Required |
+namespace | str | Experiment's namespace. Defaults to current or default namespace. | Optional|
+
+### Return type
+object
+
+## list_experiments
+> list_experiments(namespace=None)
+
+List all experiment with status
+
+### Parameters
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | -------------
+namespace | str | Experiment's namespace. Defaults to current or default namespace.| Optional |
+
+### Return type
+List
+
+## get_experiment_status
+> get_experiment_status(name, namespace=None)
+
+Returns experiment status, such as Running, Failed or Succeeded.
+
+### Parameters
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | -------------
+name  | str | Experiment name. | Required |
+namespace | str | Experiment's namespace. Defaults to current or default namespace.| Optional |
+
+### Return type
+Str
+
+## is_experiment_succeeded
+> is_experiment_succeeded(name, namespace=None)
+
+Returns True if Experiment succeeded; false otherwise.
+
+### Parameters
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | -------------
+name  | str | Experiment name.| Required |
+namespace | str | Experiment's namespace. Defaults to current or default namespace.| Optional |
+
+### Return type
+Bool
+
+## list_trials
+> list_trials(name, namespace=None)
+
+List all trials of an experiment with status
+
+### Parameters
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | -------------
+name  | str | Experiment name.| Required |
+namespace | str | Experiment's namespace. Defaults to current or default namespace.| Optional |
+
+### Return type
+List
+
+## get_optimal_hyperparmeters
+> get_optimal_hyperparmeters(name, namespace=None)
+
+Get currentOptimalTrial with paramaterAssignments of an experiment
+
+### Parameters
+Name | Type |  Description | Notes
+------------ | ------------- | ------------- | -------------
+name  | str | Experiment name.| Required |
+namespace | str | Experiment's namespace. Defaults to current or default namespace.| Optional |
+
+### Return type
+Dict
diff --git a/sdk/python/docs/V1alpha3AlgorithmSetting.md b/sdk/python/docs/V1alpha3AlgorithmSetting.md
@@ -0,0 +1,11 @@
+# V1alpha3AlgorithmSetting
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**name** | **str** |  | [optional] 
+**value** | **str** |  | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+
diff --git a/sdk/python/docs/V1alpha3AlgorithmSpec.md b/sdk/python/docs/V1alpha3AlgorithmSpec.md
@@ -0,0 +1,12 @@
+# V1alpha3AlgorithmSpec
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**algorithm_name** | **str** |  | [optional] 
+**algorithm_settings** | [**list[V1alpha3AlgorithmSetting]**](V1alpha3AlgorithmSetting.md) | Key-value pairs representing settings for suggestion algorithms. | 
+**early_stopping** | [**V1alpha3EarlyStoppingSpec**](V1alpha3EarlyStoppingSpec.md) |  | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+
diff --git a/sdk/python/docs/V1alpha3CollectorSpec.md b/sdk/python/docs/V1alpha3CollectorSpec.md
@@ -0,0 +1,11 @@
+# V1alpha3CollectorSpec
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**custom_collector** | [**V1Container**](V1Container.md) | When kind is \&quot;customCollector\&quot;, this field will be used | [optional] 
+**kind** | **str** |  | 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+
diff --git a/sdk/python/docs/V1alpha3EarlyStoppingSetting.md b/sdk/python/docs/V1alpha3EarlyStoppingSetting.md
@@ -0,0 +1,11 @@
+# V1alpha3EarlyStoppingSetting
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**name** | **str** |  | [optional] 
+**value** | **str** |  | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+
diff --git a/sdk/python/docs/V1alpha3EarlyStoppingSpec.md b/sdk/python/docs/V1alpha3EarlyStoppingSpec.md
@@ -0,0 +1,11 @@
+# V1alpha3EarlyStoppingSpec
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**early_stopping_algorithm_name** | **str** |  | [optional] 
+**early_stopping_settings** | [**list[V1alpha3EarlyStoppingSetting]**](V1alpha3EarlyStoppingSetting.md) |  | 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+
diff --git a/sdk/python/docs/V1alpha3Experiment.md b/sdk/python/docs/V1alpha3Experiment.md
@@ -0,0 +1,14 @@
+# V1alpha3Experiment
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**api_version** | **str** | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#resources | [optional] 
+**kind** | **str** | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds | [optional] 
+**metadata** | [**V1ObjectMeta**](V1ObjectMeta.md) |  | [optional] 
+**spec** | [**V1alpha3ExperimentSpec**](V1alpha3ExperimentSpec.md) |  | [optional] 
+**status** | [**V1alpha3ExperimentStatus**](V1alpha3ExperimentStatus.md) |  | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+
diff --git a/sdk/python/docs/V1alpha3ExperimentCondition.md b/sdk/python/docs/V1alpha3ExperimentCondition.md
@@ -0,0 +1,15 @@
+# V1alpha3ExperimentCondition
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**last_transition_time** | [**V1Time**](V1Time.md) | Last time the condition transitioned from one status to another. | [optional] 
+**last_update_time** | [**V1Time**](V1Time.md) | The last time this condition was updated. | [optional] 
+**message** | **str** | A human readable message indicating details about the transition. | [optional] 
+**reason** | **str** | The reason for the condition&#39;s last transition. | [optional] 
+**status** | **str** | Status of the condition, one of True, False, Unknown. | 
+**type** | **str** | Type of experiment condition. | 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+
diff --git a/sdk/python/docs/V1alpha3ExperimentList.md b/sdk/python/docs/V1alpha3ExperimentList.md
@@ -0,0 +1,13 @@
+# V1alpha3ExperimentList
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**api_version** | **str** | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#resources | [optional] 
+**items** | [**list[V1alpha3Experiment]**](V1alpha3Experiment.md) |  | 
+**kind** | **str** | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds | [optional] 
+**metadata** | [**V1ListMeta**](V1ListMeta.md) |  | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+
diff --git a/sdk/python/docs/V1alpha3ExperimentSpec.md b/sdk/python/docs/V1alpha3ExperimentSpec.md
@@ -0,0 +1,18 @@
+# V1alpha3ExperimentSpec
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**algorithm** | [**V1alpha3AlgorithmSpec**](V1alpha3AlgorithmSpec.md) | Describes the suggestion algorithm. | [optional] 
+**max_failed_trial_count** | **int** | Max failed trials to mark experiment as failed. | [optional] 
+**max_trial_count** | **int** | Max completed trials to mark experiment as succeeded | [optional] 
+**metrics_collector_spec** | [**V1alpha3MetricsCollectorSpec**](V1alpha3MetricsCollectorSpec.md) | For v1alpha3 we will keep the metrics collector implementation same as v1alpha1. | [optional] 
+**nas_config** | [**V1alpha3NasConfig**](V1alpha3NasConfig.md) |  | [optional] 
+**objective** | [**V1alpha3ObjectiveSpec**](V1alpha3ObjectiveSpec.md) | Describes the objective of the experiment. | [optional] 
+**parallel_trial_count** | **int** | How many trials can be processed in parallel. Defaults to 3 | [optional] 
+**parameters** | [**list[V1alpha3ParameterSpec]**](V1alpha3ParameterSpec.md) | List of hyperparameter configurations. | [optional] 
+**trial_template** | [**V1alpha3TrialTemplate**](V1alpha3TrialTemplate.md) | Template for each run of the trial. | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+