Create Tune API in the Katib SDK (#1951)

* Create Tune API in the Katib SDK

* Add Final to consts
Modify packages_to_install doc
Create validate objective function

* Add GPU TF Image
Change k8s version package

* Create search module

* Fix link in README

Co-authored-by: Yuki Iwai <yuki.iwai.tz@gmail.com>

* Fix licence date

Co-authored-by: Yuki Iwai <yuki.iwai.tz@gmail.com>

README.md

@@ -189,10 +189,51 @@ katib-ui-5767cfccdc-pwg2x           1/1     Running     0          36s
 
 For the Katib Experiments check the [complete examples list](./examples/v1beta1).
 
+# Quickstart
+
+You can run your first HyperParameter Tuning Experiment using [Katib Python SDK](./sdk/python/v1beta1).
+
+In the following example we are going to maximize a simple objective function:
+$F(a,b) = 4a - b^2$. The bigger $a$ and the lesser $b$ value, the bigger the function value $F$.
+
+```python
+import kubeflow.katib as katib
+
+# Step 1. Create an objective function.
+def objective(parameters):
+    # Import required packages.
+    import time
+    time.sleep(5)
+    # Calculate objective function.
+    result = 4 * int(parameters["a"]) - float(parameters["b"]) ** 2
+    # Katib parses metrics in this format: <metric-name>=<metric-value>.
+    print(f"result={result}")
+
+# Step 2. Create HyperParameter search space.
+parameters = {
+    "a": katib.search.int(min=10, max=20),
+    "b": katib.search.double(min=0.1, max=0.2)
+}
+
+# Step 3. Create Katib Experiment.
+katib_client = katib.KatibClient()
+name = "tune-experiment"
+katib_client.tune(
+    name=name,
+    objective=objective,
+    parameters=parameters,
+    objective_metric_name="result",
+    max_trial_count=12
+)
+
+# Step 4. Get the best HyperParameters.
+print(katib_client.get_optimal_hyperparameters(name))
+```
+
 # Documentation
 
-- Run your first Katib Experiment in the
-  [getting started guide](https://www.kubeflow.org/docs/components/katib/hyperparameter/#example-using-random-algorithm).
+- Check
+  [the Katib getting started guide](https://www.kubeflow.org/docs/components/katib/hyperparameter/#example-using-random-search-algorithm).
 
 - Learn about Katib **Concepts** in this
   [guide](https://www.kubeflow.org/docs/components/katib/overview/#katib-concepts).

hack/gen-python-sdk/post_gen.py

@@ -37,10 +37,17 @@ def _rewrite_helper(input_file, output_file, rewrite_rules):
             if not any(l in line for l in IGNORE_LINES):
                 lines.append(line)
 
-    # Add Katib client to init file.
+    # Add Katib APIs to the init file.
     if (output_file == "sdk/python/v1beta1/kubeflow/katib/__init__.py"):
         lines.append("# Import Katib API client.\n")
         lines.append("from kubeflow.katib.api.katib_client import KatibClient\n")
+        lines.append("# Import Katib helper functions.\n")
+        lines.append("import kubeflow.katib.api.search as search\n")
+        lines.append("# Import Katib helper constants.\n")
+        lines.append("from kubeflow.katib.constants.constants import BASE_IMAGE_TENSORFLOW\n")
+        lines.append("from kubeflow.katib.constants.constants import BASE_IMAGE_TENSORFLOW_GPU\n")
+        lines.append("from kubeflow.katib.constants.constants import BASE_IMAGE_PYTORCH\n")
+        lines.append("from kubeflow.katib.constants.constants import BASE_IMAGE_MXNET\n")
 
     # Add Kubernetes models to proper deserialization of Katib models.
     if (output_file == "sdk/python/v1beta1/kubeflow/katib/models/__init__.py"):

sdk/python/v1beta1/.gitignore

@@ -0,0 +1,2 @@
+# Distribution / packaging
+dist/

sdk/python/v1beta1/kubeflow/katib/__init__.py

@@ -71,3 +71,10 @@
 
 # Import Katib API client.
 from kubeflow.katib.api.katib_client import KatibClient
+# Import Katib helper functions.
+import kubeflow.katib.api.search as search
+# Import Katib helper constants.
+from kubeflow.katib.constants.constants import BASE_IMAGE_TENSORFLOW
+from kubeflow.katib.constants.constants import BASE_IMAGE_TENSORFLOW_GPU
+from kubeflow.katib.constants.constants import BASE_IMAGE_PYTORCH
+from kubeflow.katib.constants.constants import BASE_IMAGE_MXNET