Merge pull request #4 from ml-cube/dev-update-notebooks

Notebook refactor and update

Author: GiovanniGiacometti

notebooks/0_company_project.ipynb

@@ -7,18 +7,18 @@
    "source": [
     "# ML cube Platform SDK - First Setup\n",
     "\n",
-    "In this notebook, you will see how to setup your account on ML cube Platform.\n",
-    "The first thing to do when your account is created is to create your `Company`, then, usually, you create new `User` for your team or for *service accounts* that will be integrated in your MLOps pipeline.\n",
-    "After that, you can create a `Project` and assign specific roles to other team member in order to define the right level of security.\n",
+    "In this notebook, we'll guide you through setting up your account on the ML Cube Platform.\n",
+    "Once your account is created, the first step is to set up your `Company`. Next, you can add new `Users`, either for your team members or for service accounts that will integrate into your MLOps pipeline.\n",
+    "\n",
+    "Afterward, you can create a `Project` and assign specific roles to your team members in order to define the appropriate level of security and access.\n",
     "\n",
     "**Requirements**:\n",
     "\n",
-    "1. Valid API Key provided by ML cube\n",
+    "A valid API Key provided by ML cube\n",
     "\n",
     "**User Input**\n",
     "\n",
-    "In the notebook you will need to complete variables and names to correctly run it.\n",
-    "Whenever you see the comment `# TO COMPLETE` you need to fill the empty string."
+    "You will need to provide some values for variables and names to ensure the notebook runs correctly. Whenever you see the comment `# TO COMPLETE`, make sure to fill the empty string accordingly.\n"
    ]
   },
   {
@@ -73,9 +73,10 @@
    "source": [
     "**Create Company**\n",
     "\n",
-    "The first user inside ML cube Platform you do not belong to any Company. \n",
-    "Thus, the first operation to do is creating it.\n",
-    "The user that creates the company becomes automatically the *owner* and has administration permissions, he can create new users and projects."
+    "The first user inside ML cube Platform does not belong to any Company. \n",
+    "Therefore, the first operation is to create the company.\n",
+    "\n",
+    "The user who creates the company becomes automatically the *owner* and has administration permissions. This allows them to manage users, create projects, and set permissions."
    ]
   },
   {
@@ -100,9 +101,10 @@
    "id": "517e7298-fd82-4212-92f0-928a849911db",
    "metadata": {},
    "source": [
-    "As you can see the method `create_company` returned the id of the entity you created.\n",
-    "ML cube Platform clients does this for every entity you create so that, you always know what you created and you can use this identifier for future interactions with ML cube Platform.\n",
-    "Differently from other entities inside ML cube Platform, the company is unique and it cannot be changed for the User, therefore, any operations you perform at company level does not need its identifier because we retrieve it directly from you user information."
+    "As you can see, the method `create_company` returns the id of the company just created.\n",
+    "The ML cube Platform Client follows this approach for every entity, ensuring that you always have the identifier of what you've created. The ID can then be used for any future interaction with the ML cube Platform.\n",
+    "\n",
+    "Differently from other entities inside ML cube Platform, the company is unique and it cannot be changed for the User. Therefore, any operation you perform at company level does not need its identifier, as we are able to retrieve it directly from the user information."
    ]
   },
   {
@@ -112,10 +114,10 @@
    "source": [
     "**Create User**\n",
     "\n",
-    "As owner of the company, you can create new users for you team. Each user has a `CompanyRole` that specifies its permissions.\n",
-    "The user can have associated a role also for each project inside the Company, in the following notebook cells you will se how to do it.\n",
+    "As the owner of the company, you can create new users for you team. Each user has a `CompanyRole` that specifies its permissions.\n",
+    "The user can also have a specific role for each project inside the Company. In the following cells you will see how to do it.\n",
     "\n",
-    "Please, complete the fields with the right information and choose the right user role."
+    "Please, complete the fields with the right information and choose the appropriate user role."
    ]
   },
   {
@@ -144,8 +146,9 @@
    "source": [
     "**User API Key**\n",
     "\n",
-    "After a User is created he can login to the web application and start working on it.\n",
-    "In order to use the SDK he needs to create his own api key on the web app, since you are the owner you can create an api key for him directly here.\n",
+    "After a User is created, he is able to log in the web application and start working on it.\n",
+    "\n",
+    "In order to use the SDK, he needs to create his own api key on the web app. Since you are the owner, you can create an api key for him directly here.\n",
     "This is particularly useful when you need to create service accounts that are used in your pipelines."
    ]
   },
@@ -191,9 +194,11 @@
    "source": [
     "**Create Project**\n",
     "\n",
-    "For now, you created a company, a new user for you colleague with his api key. It's time to create a project and start working for your models.\n",
+    "So far, you created a company and a new user for you colleague with his api key. \n",
+    "\n",
+    "It's time to create a project and start working on your models.\n",
     "A project needs a name, a description and the default storage policy.\n",
-    "You can read more details about what is a StoragePolicy on ML cube Platform documentation, in few words, it specifies if data can be stored inside ML cube Secure Storage or not."
+    "You can read more details about what is a StoragePolicy on the ML cube Platform documentation. In a few words, it specifies whether data can be stored inside ML cube Secure Storage or not."
    ]
   },
   {
@@ -219,8 +224,8 @@
    "source": [
     "**User Project Role**\n",
     "\n",
-    "Since, the user we created has role `COMPANY_USER`, he does not have permissions on this project.\n",
-    "Therefore, you need to assign a role to him."
+    "Since the user we created before has role `COMPANY_USER`, he does not have permissions on this project.\n",
+    "Therefore, you need to explicitly assign a role to him."
    ]
   },
   {
@@ -244,7 +249,7 @@
    "source": [
     "**Congratulations!**\n",
     "\n",
-    "In this notebook, you learned how to create your company, then you created a new user and a project. The created user has not admin role, thus, you assigned a project role to allow him to work on the project.o create your company, then you created a new user and a project. The created user has not admin role, thus, you assigned a project role to allow him to work on the project."
+    "In this notebook, you learned how to create your company, a new user and a project. Since the created user does not have an admin role, you assigned him a project role to allow him to work on the project."
    ]
   }
  ],

notebooks/1_task_and_model.ipynb

@@ -7,17 +7,16 @@
    "source": [
     "# ML cube Platform SDK - Task and Model creation\n",
     "\n",
-    "In this notebook, you will see how to create a Task and add models to it in order to start to monitor them.\n",
+    "In this notebook, you will see how to create a Task and how to add a model to start monitoring its performance.\n",
     "\n",
     "**Requirements**:\n",
     "\n",
     "1. API Key of a User with roles `COMPANY_ADMIN` or `PROJECT_ADMIN`\n",
-    "2. Id of the project\n",
+    "2. ID of the project\n",
     "\n",
     "**User Input**\n",
     "\n",
-    "In the notebook you will need to complete variables and names to correctly run it.\n",
-    "Whenever you see the comment `# TO COMPLETE` you need to fill the empty string."
+    "You will need to provide some values for variables and names to ensure the notebook runs correctly. Whenever you see the comment `# TO COMPLETE`, make sure to fill the empty string accordingly."
    ]
   },
   {
@@ -28,6 +27,29 @@
     "**Imports**"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": [
+    "import logging\n",
+    "logger = logging.getLogger(\"platform_tutorial\")"
+   ],
+   "id": "ac1dbec9a9146410"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": [
+    "from ml3_platform_sdk.client import ML3PlatformClient\n",
+    "from ml3_platform_sdk import enums as ml3_enums\n",
+    "from ml3_platform_sdk import models as ml3_models"
+   ],
+   "id": "c8bf440019a4ca24"
+  },
   {
    "cell_type": "markdown",
    "id": "26f67a46-cacf-4ca8-b67e-43388566b3c7",
@@ -54,45 +76,21 @@
    "id": "c6588f7a-488c-4d3b-bc57-ec5ddbb0f955",
    "metadata": {},
    "source": [
-    "If you don't remember the id of the projcet you can get the list of projects:\n",
+    "If you don't remember the id of the project you can get the list of your projects:\n",
     "```py\n",
     "projects: List[Project] = client.get_projects()\n",
     "logger.info(f'Projects inside the company are: {projects}')\n",
     "```"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "cd94e6fe",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import logging\n",
-    "logger = logging.getLogger(\"platform_tutorial\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "b808c779",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from ml3_platform_sdk.client import ML3PlatformClient\n",
-    "from ml3_platform_sdk import enums as ml3_enums\n",
-    "from ml3_platform_sdk import models as ml3_models"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "0c085046-a664-4085-b011-e4ff37d27ca5",
    "metadata": {},
    "source": [
-    "**Instantiace the Client**\n",
+    "**Instantiate the Client**\n",
     "\n",
-    "To interact with ML cube Platform you need to instantiate the client only the first time.\n",
-    "Then you will use its methods to perform requests.\n",
+    "To interact with ML cube Platform, you need to instantiate the client. You will then use its methods to perform requests.\n",
     "Please, insert the api key we provided you to instantiate the client."
    ]
   },
@@ -115,7 +113,9 @@
    "source": [
     "**Create Task**\n",
     "\n",
-    "To monitor your models you need to add them in a `Task`, it represents a AI problem like regression or classification over a dataset."
+    "To monitor your models you need to add them in a `Task`. \n",
+    "\n",
+    "A `Task` represents an AI problem, such as regression or binary classification, over a dataset."
    ]
   },
   {
@@ -149,12 +149,12 @@
    "source": [
     "**Data schema**\n",
     "\n",
-    "The data schema describes the data used in this task by your models.\n",
-    "It contains features, targets and a set of mandatory metadata required by ML cube Platform for a correct function.\n",
-    "Each sample is required to have associated a `timestamp` and an `identifier`: the timestamp is used to sort your data and the identifier to share information about data without transferring them.\n",
+    "The data schema defines the structure of the data used in this task.\n",
+    "It contains features, target and a set of mandatory metadata required by the ML cube Platform.\n",
+    "Each sample must have a `timestamp` and an `identifier`: the timestamp is used to sort your data chronologically and the identifier is used to share information about data without transferring them.\n",
     "\n",
-    "The data schema is specified by the class `DataSchema` that you find in the `models` package of our sdk.\n",
-    "In the following cell you can see an example of a DataSchema, as you can notice, the model's predictions are not mentioned. That's why they will be automatically added when you create a model for the task."
+    "The data schema is specified by the class `DataSchema` which can be found in the `models` package of our sdk.\n",
+    "In the following cell you can see an example of a DataSchema. As you can notice, the model predictions are not included. The reason is that they will be automatically added when a model is created within the task."
    ]
   },
   {
@@ -209,19 +209,19 @@
    "source": [
     "**Historical data**\n",
     "\n",
-    "Ok, now that you inserted the data schema for your Task you are able to upload data.\n",
+    "Now that you have inserted the data schema for your Task you are able to upload data.\n",
     "There are two classes of data: *historical* and *production*.\n",
-    "Historical data represents data you had before the model was in production while, production data are data that comes from the production environment.\n",
-    "Model reference data are selected from historical one by specifying the time range.\n",
+    "Historical data represent data you had before the model was in production, while production data are those coming from the production environment.\n",
+    "The reference data for the model are selected from the historical data by specifying a time range.\n",
     "\n",
     "This is the first time you send data to ML cube Platform, therefore, we have some things to explain:\n",
     "\n",
     "- data are composed of features, targets, predictions. You send each category separately since data can come from multiple sources;\n",
-    "- the operations of sending data belong to the category of operations that runs a pipeline inside ML cube Platform. In this case the pipeline is composed only by the data step that reads the data, validate them and then if the storing policy is MLCUBE it stores inside the ML cube Platform's Secure Storage;\n",
-    "- the pipeline is identified by a `job_id` and you can follow the execution status by asking to the client its information.\n",
+    "- the operation of sending data belong to the category of operations that runs a pipeline inside the ML cube Platform. In this case the pipeline is composed only by the data step that reads the data, validate them and then if the storing policy is MLCUBE it stores inside the ML cube Platform's Secure Storage;\n",
+    "- the pipeline is identified by a `job_id` and you can follow the execution status by asking the client its information. Additionally, you can wait for the completion of the job by calling the method `wait_job_completion(job_id)`.\n",
     "\n",
-    "In the cell below, we sends features using `LocalDataSource` beceause we have the file locally, and we use a `GCSDataSource` for the target because we have it on the cloud.\n",
-    "In order to use remote data sources you need to add credentials on ML cube Platform and then you specify them in the `DataSource` object."
+    "In the cell below, we send features using a `LocalDataSource`, since we have the file locally, and we use a `GCSDataSource` for the target because we have it on the cloud.\n",
+    "In order to use remote data sources you need to add credentials on the ML cube Platform. You can specify them in the `DataSource` object."
    ]
   },
   {
@@ -233,14 +233,12 @@
    "source": [
     "# TO COMPLETE\n",
     "inputs_data_source = ml3_models.LocalDataSource(\n",
-    "    data_structure=ml3_enums.DataStructure.TABULAR,\n",
     "    file_path=\"path/to/file.csv\",\n",
     "    file_type=ml3_enums.FileType.CSV,\n",
     "    is_folder=False,\n",
     "    folder_type=None\n",
     ")\n",
     "target_data_source = ml3_models.GCSDataSource(\n",
-    "    dataset_type=ml3_enums.DatasetType.TABULAR,\n",
     "    object_path=\"gs://path/to/file.csv\",\n",
     "    credentials_id='gcp_credentials_id',\n",
     "    file_type=ml3_enums.FileType.CSV,\n",
@@ -271,9 +269,9 @@
     "**Create Model**\n",
     "\n",
     "After the task is created, you can add AI models inside it.\n",
-    "A model is univoquely identified by the pair `name` and `version`.\n",
-    "The version identifies a specific trained instance of the model, whenever, you retrain your model, you will update its version on ML cube Platform.\n",
-    "The field `metric_name` represents the error or performance metric used inside ML cube Platform to show to you the statistics of the model or in the retraining report."
+    "A model is uniquely identified by the pair `name` and `version`.\n",
+    "The version identifies a specific trained instance of the model. Whenever you retrain your model, you will update its version on the ML cube Platform.\n",
+    "The metric_name field indicates the error or performance metric used in the ML Cube Platform to display the model's performance and it is also included in the retraining report."
    ]
   },
   {
@@ -287,7 +285,7 @@
     "model_id = ml3_client.create_model(\n",
     "    task_id=task_id,\n",
     "    name=\"model-name\",\n",
-    "    version=\"v0.2.1\",\n",
+    "    version=\"v0.0.1\",\n",
     "    metric_name=ml3_enums.ModelMetricName.RMSE,\n",
     "    preferred_suggestion_type=ml3_enums.SuggestionType.SAMPLE_WEIGHTS,\n",
     "    with_probabilistic_output=False,\n",
@@ -302,8 +300,8 @@
    "source": [
     "**Model reference**\n",
     "\n",
-    "In the previous cell you created the model but it is not complete because it misses the training dataset that in ML cube Platform is called *reference*.\n",
-    "Here you add the reference data of the model by specifying the time range, ML cube Platform automatically select from all the previously uploaded data the reference data."
+    "In the previous cell you created the model, but it still misses the training dataset. In the ML cube Platform, the training dataset is called *reference*.\n",
+    "You can add the reference data of the model by specifying the time range. The ML cube Platform will automatically select from the previously uploaded data the reference data specified."
    ]
   },
   {
@@ -336,7 +334,7 @@
    "source": [
     "**Congratulations!**\n",
     "\n",
-    "In this notebook, you learned how to create a task, add a model to this task and uploading to ML cube Platform both historical and reference data."
+    "In this notebook, you learned how to create a task, add a model to the task, and upload both historical and reference data to the ML Cube Platform."
    ]
   }
  ],