Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Python SDK for katib #1177

Merged
merged 20 commits into from
Jun 4, 2020
Merged

Python SDK for katib #1177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
1865ab2
python SDK for katib with docs and examples
prem0912 May 5, 2020
5c31a6f
Update README.md
prem0912 May 5, 2020
c4f30eb
Update README.md
prem0912 May 5, 2020
6146524
Update bayesianoptimization-katib-sdk.ipynb
prem0912 May 5, 2020
c402cd8
Update bayesianoptimization-katib-sdk.ipynb
prem0912 May 5, 2020
5df0ada
Update tfjob-katib-sdk.ipynb
prem0912 May 5, 2020
e769bd4
Create OWNERS
prem0912 May 5, 2020
cc4147f
Update bayesianoptimization-katib-sdk.ipynb
prem0912 May 5, 2020
28d10d4
Update tfjob-katib-sdk.ipynb
prem0912 May 5, 2020
d8d9e6e
Update bayesianoptimization-katib-sdk.ipynb
prem0912 May 5, 2020
0c1c2b9
Update tfjob-katib-sdk.ipynb
prem0912 May 5, 2020
6bf76b4
Update bayesianoptimization-katib-sdk.ipynb
prem0912 May 5, 2020
0cb08e8
Update OWNERS
prem0912 May 5, 2020
d892866
Update README.md
prem0912 May 8, 2020
5f9e854
updated changes as per review comments
prem0912 May 8, 2020
d3d0108
Update README.md
prem0912 May 8, 2020
ff005ec
Update README.md
prem0912 May 8, 2020
c42af35
Added pip installation for katib sdk and removed status from get_opti…
prem0912 Jun 2, 2020
ac3228b
Update README.md
prem0912 Jun 2, 2020
d19149d
Updated changes for delete_exp and removed unused imports
prem0912 Jun 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand Down
99 changes: 99 additions & 0 deletions sdk/python/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# Kubeflow Katib SDK
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we also link this SDK page from the main Katib Readme file?

Copy link
Contributor Author

@prem0912 prem0912 May 8, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated main Readme file


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add script to update models?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will add it in next PR


- [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
135 changes: 135 additions & 0 deletions sdk/python/docs/KatibClient.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
11 changes: 11 additions & 0 deletions sdk/python/docs/V1alpha3AlgorithmSetting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)


12 changes: 12 additions & 0 deletions sdk/python/docs/V1alpha3AlgorithmSpec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)


11 changes: 11 additions & 0 deletions sdk/python/docs/V1alpha3CollectorSpec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# V1alpha3CollectorSpec

## Properties
Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**custom_collector** | [**V1Container**](V1Container.md) | When kind is \"customCollector\", 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)


11 changes: 11 additions & 0 deletions sdk/python/docs/V1alpha3EarlyStoppingSetting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)


11 changes: 11 additions & 0 deletions sdk/python/docs/V1alpha3EarlyStoppingSpec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)


14 changes: 14 additions & 0 deletions sdk/python/docs/V1alpha3Experiment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)


15 changes: 15 additions & 0 deletions sdk/python/docs/V1alpha3ExperimentCondition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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'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)


13 changes: 13 additions & 0 deletions sdk/python/docs/V1alpha3ExperimentList.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)


18 changes: 18 additions & 0 deletions sdk/python/docs/V1alpha3ExperimentSpec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)


Loading