revise documentation

Author: questcollector

website/docs/topics/code-execution/kubernetes-pod-commandline-code-executor.ipynb

@@ -11,17 +11,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The `PodCommandLineCodeExecutor` of the autogen.coding.kubernetes module is to execute a code block using a pod in Kubernetes.\n",
-    "It is like DockerCommandLineCodeExecutor, but creates container on kubernetes Pod.\n",
+    "The `PodCommandLineCodeExecutor` in the `autogen.coding.kubernetes` module is designed to execute code blocks using a pod in Kubernetes.\n",
+    "It functions similarly to the `DockerCommandLineCodeExecutor`, but specifically creates container within Kubernetes environments.\n",
     "\n",
     "There are two condition to use PodCommandLineCodeExecutor.\n",
-    "- accessible to kubernetes cluster\n",
-    "- install autogen with extra feature kubernetes\n",
+    "- Access to a Kubernetes cluster\n",
+    "- installation `autogen` with the extra requirements `'pyautogen[kubernetes]'`\n",
     "\n",
-    "This documents uses minikube cluster on local environment.\n",
-    "You can refer to the link below for installation and execution of minikube.\n",
+    "For local development and testing, this document uses a Minikube cluster.\n",
     "\n",
-    "https://minikube.sigs.k8s.io/docs/start/"
+    "Minikube is a tool that allows you to run a single-node Kubernetes cluster on you local machine. \n",
+    "You can refer to the link below for installation and setup of Minikube.\n",
+    "\n",
+    "🔗 https://minikube.sigs.k8s.io/docs/start/"
    ]
   },
   {
@@ -37,9 +39,9 @@
    "source": [
     "There are four options PodCommandLineCodeExecutor to access kubernetes API server.\n",
     "- default kubeconfig file path: `~/.kube/config`\n",
-    "- To provide kubeconfig file path to `kube_config_file` argument of `PodCommandLineCodeExecutor`.\n",
-    "- To provide kubeconfig file path to `KUBECONFIG` environment variable.\n",
-    "- To provide token from kubernetes ServiceAccount which has enough permissions"
+    "- Provide a custom kubeconfig file path using the `kube_config_file` argument of `PodCommandLineCodeExecutor`.\n",
+    "- Set the kubeconfig file path using the `KUBECONFIG` environment variable.\n",
+    "- Provide token from Kubernetes ServiceAccount with sufficient permissions"
    ]
   },
   {
@@ -48,7 +50,7 @@
    "source": [
     "Generally, if kubeconfig file is located in `~/.kube/config`, there's no need to provide kubeconfig file path on parameter or environment variables.\n",
     "\n",
-    "the Tutorial of providing ServiceAccount Token is in the last section"
+    "The tutorial of providing ServiceAccount Token is in the last section"
    ]
   },
   {
@@ -57,8 +59,25 @@
    "source": [
     "## Example\n",
     "\n",
-    "In order to use kubernetes Pod based code executor, kubernetes python sdk is required.\n",
-    "It can be installed by `pip install 'kubernetes>=27'` or with the extra kubernetes"
+    "In order to use kubernetes Pod based code executor, you need to install Kubernetes Python SDK.\n",
+    "\n",
+    "You can do this by running the following command:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pip install 'kubernetes>=27'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Alternatively, you can install it with the extra features for Kubernetes:"
    ]
   },
   {
@@ -67,9 +86,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install 'pyautogen[kubernetes]'\n",
-    "# or\n",
-    "# pip install pyautogen 'kubernetes>=27'"
+    "pip install 'pyautogen[kubernetes]'"
    ]
   },
   {
@@ -85,10 +102,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# import os\n",
-    "# # If kubeconfig file is not located on ~/.kube/config but other path, \n",
-    "# # you can set path of kubeconfig file on KUBECONFIG environment variables \n",
-    "# os.environ[\"KUBECONFIG\"] = \"kubeconfig/file/path\""
+    "import os\n",
+    "# Set the KUBECONFIG environment variable \n",
+    "# if the kubeconfig file is not in the default location(~/.kube/cofig).\n",
+    "os.environ[\"KUBECONFIG\"] = \"path/to/your/kubeconfig\""
    ]
   },
   {
@@ -121,6 +138,7 @@
     "    ) as executor:\n",
     "    print(\n",
     "        executor.execute_code_blocks(\n",
+    "            # Example of executing a simple Python code block within a Kubernetes pod.\n",
     "            code_blocks=[\n",
     "                CodeBlock(language=\"python\", code=\"print('Hello, World!')\"),\n",
     "            ]\n",
@@ -132,9 +150,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "With context manager(with statement), the pod created by PodCommandLineCodeExecutor deleted automatically after tasks done.\n",
+    "Using a context manager(the `with` statement), the pod created by `PodCommandLineCodeExecutor` is automatically deleted after the tasks are completed.\n",
     "\n",
-    "To delete the pod manually, you can use `stop()` method"
+    "Although the pod is automatically deleted when using a context manager, you might sometimes need to delete it manually. You can do this using `stop()` method, as shown below:"
    ]
   },
   {
@@ -162,7 +180,8 @@
    ],
    "source": [
     "%%bash\n",
-    "# default pod name is autogen-code-exec-{uuid.uuid4()}\n",
+    "# This command lists all pods in the default namespace. \n",
+    "# The default pod name follows the format autogen-code-exec-{uuid.uuid4()}.\n",
     "kubectl get pod -n default"
    ]
   },
@@ -181,7 +200,8 @@
    ],
    "source": [
     "%%bash\n",
-    "# default container image is python:3-slim\n",
+    "# This command shows container's image in the pod.\n",
+    "# The default container image is python:3-slim\n",
     "kubectl get pod autogen-code-exec-afd217ac-f77b-4ede-8c53-1297eca5ec64 -o jsonpath={.spec.containers[0].image}"
    ]
   },
@@ -198,11 +218,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you use another container image for code executor pod, you can provide image tag to `image` argument.\n",
+    "To use a different container image for code executor pod, specify the desired image tag using `image` argument.\n",
     "\n",
-    "PodCommandLineCode Executor has default execution policy that allows python and shell script code blocks.\n",
-    "\n",
-    "It can be allowed other languages with `execution_policies` argument."
+    "`PodCommandLineCodeExecutor` has a default execution policy that allows Python and shell script code blocks. You can enable other languages with `execution_policies` argument."
    ]
   },
   {
@@ -220,11 +238,11 @@
    ],
    "source": [
     "with PodCommandLineCodeExecutor(\n",
-    "    image=\"node:22-alpine\", # you can provide runtime environments through container image\n",
+    "    image=\"node:22-alpine\", # Specifies the runtime environments using a container image\n",
     "    namespace=\"default\",\n",
-    "    work_dir=\"./app\", # workspace directory for code block files\n",
-    "    timeout=10, # timeout(seconds) value for waiting pod creation, execution of code blocks. default is 60 seconds\n",
-    "    execution_policies = {\"javascript\": True} # allowed execution languages can be updated with execution_policy dictionary\n",
+    "    work_dir=\"./app\", # Directory within the container where code block files are stored\n",
+    "    timeout=10, # Timeout in seconds for pod creation and code block execution (default is 60 seconds)\n",
+    "    execution_policies = {\"javascript\": True} # Enable execution of Javascript code blocks by updating execution policies\n",
     ") as executor:\n",
     "    print(\n",
     "        executor.execute_code_blocks(\n",
@@ -239,10 +257,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you want to give custom settings for executor pod, such as annotations, environment variables, commands, volumes etc., \n",
-    "you can provide custom pod specification with `kubernetes.client.V1Pod` format.\n",
+    "If you want to apply custom settings for executor pod, such as annotations, environment variables, commands, volumes etc., \n",
+    "you can provide a custom pod specification using `kubernetes.client.V1Pod` format.\n",
     "\n",
-    "`container_name` argument should also be provided because PodCommandLineCodeExecutor do not automatically recognize a container where code blocks will be executed "
+    "The `container_name` argument should also be provided because `PodCommandLineCodeExecutor` does not automatically recognize the container where code blocks will be executed."
    ]
   },
   {
@@ -261,7 +279,7 @@
     "        containers=[client.V1Container(\n",
     "            args=[\"-c\", \"while true;do sleep 5; done\"],\n",
     "            command=[\"/bin/sh\"],\n",
-    "            name=\"abcd\", # container name where code blocks will be executed should be provided to `container_name` argument\n",
+    "            name=\"abcd\", # container name where code blocks will be executed should be provided using `container_name` argument\n",
     "            image=\"python:3.11-slim\",\n",
     "            env=[\n",
     "                client.V1EnvVar(\n",
@@ -299,7 +317,7 @@
    "source": [
     "with PodCommandLineCodeExecutor(\n",
     "    pod_spec=pod, # custom executor pod spec\n",
-    "    container_name=\"abcd\", # If custom executor pod spec is provided, container_name where code block will be executed should be specified\n",
+    "    container_name=\"abcd\", # To use custom executor pod spec, container_name where code block will be executed should be specified\n",
     "    work_dir=\"/autogen\",\n",
     "    timeout=60,\n",
     ") as executor:\n",
@@ -331,7 +349,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "PodCommandLineCodeExecutor can be integrated with Agents."
+    "`PodCommandLineCodeExecutor` can be integrated with Agents."
    ]
   },
   {
@@ -427,7 +445,7 @@
     "from autogen import ConversableAgent\n",
     "\n",
     "# The code writer agent's system message is to instruct the LLM on how to\n",
-    "# use the Jupyter code executor with IPython kernel.\n",
+    "# use the code executor with python or shell script code\n",
     "code_writer_system_message = \"\"\"\n",
     "You have been given coding capability to solve tasks using Python code.\n",
     "In the following cases, suggest python code (in a python coding block) or shell script (in a sh coding block) for the user to execute.\n",
@@ -585,11 +603,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If a PodCommandLineCodeExecutor instance executes on inside of kubernetes Pod, instance can use token which is generated from ServiceAccount to access kubernetes API server.\n",
+    "If a `PodCommandLineCodeExecutor` instance runs inside of Kubernetes Pod, it can use a token generated from a ServiceAccount to access Kubernetes API server.\n",
     "\n",
-    "PodCommandLineCodeExecutor needs permissions of verbs `create`, `get`, `delete` on resource `pods`, and verb `get` for resources `pods/status`, `pods/exec`.\n",
+    "The `PodCommandLineCodeExecutor` requires the following permissions:\n",
+    "the verbs `create`, `get`, `delete` for `pods` resource, and the verb `get` for resources `pods/status`, `pods/exec`.\n",
     "\n",
-    "You can make ServiceAccount, ClusterRole and RoleBinding with kubectl."
+    "You can create a ServiceAccount, ClusterRole and RoleBinding with `kubectl` as shown below:"
    ]
   },
   {
@@ -607,7 +626,7 @@
    ],
    "source": [
     "%%bash\n",
-    "# create ServiceAccount on default namespace\n",
+    "# Create ServiceAccount on default namespace\n",
     "kubectl create sa autogen-executor-sa"
    ]
   },
@@ -626,7 +645,7 @@
    ],
    "source": [
     "%%bash\n",
-    "# create ClusterRole\n",
+    "# Create ClusterRole that has sufficient permissions\n",
     "kubectl create clusterrole autogen-executor-role \\\n",
     "    --verb=get,create,delete --resource=pods,pods/status,pods/exec"
    ]
@@ -646,7 +665,7 @@
    ],
    "source": [
     "%%bash\n",
-    "# create RoleBinding\n",
+    "# Create RoleBinding that binds ClusterRole and ServiceAccount\n",
     "kubectl create rolebinding autogen-executor-rolebinding \\\n",
     "    --clusterrole autogen-executor-role --serviceaccount default:autogen-executor-sa"
    ]
@@ -655,7 +674,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Pod with serviceAccount created before can be launched by below"
+    "A pod with a previously created ServiceAccount can be launched using the following command."
    ]
   },
   {
@@ -683,7 +702,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Execute PodCommandLineCodeExecutor in autogen-executor Pod"
+    "You can execute `PodCommandLineCodeExecutor` inside the Python interpreter process from `autogen-executor` Pod.\n",
+    "\n",
+    "It creates new pod for code execution using token generated from `autogen-executor-sa` ServiceAccount."
    ]
   },
   {