templates/ml-online/README.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1ad52e52",
   "metadata": {
    "papermill": {
     "duration": 0.054636,
     "end_time": "2021-10-28T01:36:02.903902",
     "exception": false,
     "start_time": "2021-10-28T01:36:02.849266",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "To run this locally, [install Ploomber](https://docs.ploomber.io/en/latest/get-started/quick-start.html) and execute: `ploomber examples -n templates/ml-online`\n",
    "\n",
    "Found an issue? [Let us know.](https://github.com/ploomber/projects/issues/new?title=templates/ml-online%20issue)\n",
    "\n",
    "Questions? [Ask us on Slack.](https://ploomber.io/community/)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e972f684",
   "metadata": {
    "papermill": {
     "duration": 0.100447,
     "end_time": "2021-10-28T01:36:03.067809",
     "exception": false,
     "start_time": "2021-10-28T01:36:02.967362",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "# Machine Learning pipeline with online API\n",
    "\n",
    "<!-- start description -->\n",
    "Load data, generate features, train a model, and deploy model with flask.\n",
    "<!-- end description -->\n",
    "\n",
    "Note: all commands must be executed in the `ml-online/` directory.\n",
    "\n",
    "## Setup\n",
    "\n",
    "```sh\n",
    "pip install --editable \".[dev]\"\n",
    "```\n",
    "\n",
    "## File layout\n",
    "\n",
    "`src/ml_online`:\n",
    "\n",
    "1. `pipeline-features.yaml`: feature engineering YAML spec\n",
    "2. `pipeline.yaml`: training pipeline\n",
    "3. `infer.py`: converts training pipeline to an inference pipeline\n",
    "4. `service.py`: uses inference pipeline to serve predictions using Flask\n",
    "\n",
    "## Training pipeline"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "6bebd5e7",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:03.349716Z",
     "iopub.status.busy": "2021-10-28T01:36:03.347924Z",
     "iopub.status.idle": "2021-10-28T01:36:32.267677Z",
     "shell.execute_reply": "2021-10-28T01:36:32.270503Z"
    },
    "papermill": {
     "duration": 29.073336,
     "end_time": "2021-10-28T01:36:32.270938",
     "exception": false,
     "start_time": "2021-10-28T01:36:03.197602",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "name        Ran?      Elapsed (s)    Percentage\n",
      "----------  ------  -------------  ------------\n",
      "get         True         0.008928      0.140824\n",
      "sepal-area  True         0.029916      0.471875\n",
      "petal-area  True         0.032396      0.510992\n",
      "features    True         0.03546       0.559322\n",
      "fit         True         6.23312      98.317\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Building task 'fit':  80%|████████  | 4/5 [00:16<00:04,  4.40s/it]       \n",
      "Executing:   0%|          | 0/11 [00:00<?, ?cell/s]\u001b[A\n",
      "Executing:   9%|▉         | 1/11 [00:01<00:15,  1.54s/cell]\u001b[A\n",
      "Executing:  18%|█▊        | 2/11 [00:03<00:13,  1.52s/cell]\u001b[A\n",
      "Executing:  36%|███▋      | 4/11 [00:03<00:04,  1.65cell/s]\u001b[A\n",
      "Executing:  45%|████▌     | 5/11 [00:03<00:02,  2.22cell/s]\u001b[A\n",
      "Executing:  64%|██████▎   | 7/11 [00:03<00:01,  3.69cell/s]\u001b[A\n",
      "Executing:  82%|████████▏ | 9/11 [00:03<00:00,  5.32cell/s]\u001b[A\n",
      "Executing: 100%|██████████| 11/11 [00:04<00:00,  2.52cell/s]\u001b[A\n",
      "Building task 'fit': 100%|██████████| 5/5 [00:23<00:00,  4.64s/it]\n"
     ]
    }
   ],
   "source": [
    "%%sh\n",
    "ploomber build"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "272117ed",
   "metadata": {
    "papermill": {
     "duration": 0.100536,
     "end_time": "2021-10-28T01:36:32.443967",
     "exception": false,
     "start_time": "2021-10-28T01:36:32.343431",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "Output from the training pipeline saved in the `products/` folder."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "86019c26",
   "metadata": {
    "papermill": {
     "duration": 0.091692,
     "end_time": "2021-10-28T01:36:32.621597",
     "exception": false,
     "start_time": "2021-10-28T01:36:32.529905",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "## Online API\n",
    "\n",
    "Copy the trained model inside the project's package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "5572bac5",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:32.823846Z",
     "iopub.status.busy": "2021-10-28T01:36:32.821817Z",
     "iopub.status.idle": "2021-10-28T01:36:32.918694Z",
     "shell.execute_reply": "2021-10-28T01:36:32.919523Z"
    },
    "papermill": {
     "duration": 0.198654,
     "end_time": "2021-10-28T01:36:32.919926",
     "exception": false,
     "start_time": "2021-10-28T01:36:32.721272",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%sh\n",
    "cp products/model.pickle src/ml_online/model.pickle"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69bf86f1",
   "metadata": {
    "papermill": {
     "duration": 0.052228,
     "end_time": "2021-10-28T01:36:33.078491",
     "exception": false,
     "start_time": "2021-10-28T01:36:33.026263",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "Start web application:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "62ce9e31",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:33.190366Z",
     "iopub.status.busy": "2021-10-28T01:36:33.189629Z",
     "iopub.status.idle": "2021-10-28T01:36:33.191409Z",
     "shell.execute_reply": "2021-10-28T01:36:33.191994Z"
    },
    "papermill": {
     "duration": 0.05972,
     "end_time": "2021-10-28T01:36:33.192268",
     "exception": false,
     "start_time": "2021-10-28T01:36:33.132548",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from os import environ\n",
    "import subprocess\n",
    "\n",
    "def start_flask():\n",
    "    \"\"\"Start Flask and wait until it's ready\n",
    "    \"\"\"\n",
    "    proc = subprocess.Popen(['flask', 'run'],\n",
    "                        env=dict(environ, FLASK_APP='ml_online.service'),\n",
    "                        stdout=subprocess.PIPE,\n",
    "                        stderr=subprocess.STDOUT)\n",
    "    \n",
    "    while True:\n",
    "        out = proc.stdout.readline()\n",
    "        print(out.decode().strip())\n",
    "    \n",
    "        if b'5000' in out:\n",
    "            break\n",
    "    \n",
    "    return proc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "d00f64ac",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:33.295052Z",
     "iopub.status.busy": "2021-10-28T01:36:33.294153Z",
     "iopub.status.idle": "2021-10-28T01:36:36.488493Z",
     "shell.execute_reply": "2021-10-28T01:36:36.489139Z"
    },
    "papermill": {
     "duration": 3.251237,
     "end_time": "2021-10-28T01:36:36.489414",
     "exception": false,
     "start_time": "2021-10-28T01:36:33.238177",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "* Serving Flask app 'ml_online.service' (lazy loading)\n",
      "* Environment: production\n",
      "WARNING: This is a development server. Do not use it in a production deployment.\n",
      "Use a production WSGI server instead.\n",
      "* Debug mode: off\n",
      "/Users/Edu/dev/ploomber/src/ploomber/spec/dagspec.py:336: UserWarning: The following placeholders are declared in the environment but unused in the spec: {'sample'}\n",
      "warnings.warn('The following placeholders are declared in the '\n",
      "100%|██████████| 5/5 [00:00<00:00, 2607.10it/s]\n",
      "* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)\n"
     ]
    }
   ],
   "source": [
    "proc = start_flask()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b149dfa",
   "metadata": {
    "papermill": {
     "duration": 0.049515,
     "end_time": "2021-10-28T01:36:36.593136",
     "exception": false,
     "start_time": "2021-10-28T01:36:36.543621",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "*Note:* `start_flask()` is the same as executing the following a terminal:\n",
    "\n",
    "```sh\n",
    "export FLASK_APP=ml_online.service\n",
    "flask run\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0eaf11c",
   "metadata": {
    "papermill": {
     "duration": 0.044694,
     "end_time": "2021-10-28T01:36:36.683212",
     "exception": false,
     "start_time": "2021-10-28T01:36:36.638518",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "Open a new terminal to make predictions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "c9cde258",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:36.788941Z",
     "iopub.status.busy": "2021-10-28T01:36:36.788057Z",
     "iopub.status.idle": "2021-10-28T01:36:36.845139Z",
     "shell.execute_reply": "2021-10-28T01:36:36.845694Z"
    },
    "papermill": {
     "duration": 0.118292,
     "end_time": "2021-10-28T01:36:36.845958",
     "exception": false,
     "start_time": "2021-10-28T01:36:36.727666",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "import requests"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "1e243af8",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:36.945143Z",
     "iopub.status.busy": "2021-10-28T01:36:36.944320Z",
     "iopub.status.idle": "2021-10-28T01:36:36.946475Z",
     "shell.execute_reply": "2021-10-28T01:36:36.947017Z"
    },
    "papermill": {
     "duration": 0.055855,
     "end_time": "2021-10-28T01:36:36.947342",
     "exception": false,
     "start_time": "2021-10-28T01:36:36.891487",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "def make_request(data):\n",
    "    \"\"\"Hit the prediction endpoint\n",
    "    \"\"\"\n",
    "    response = requests.post('http://127.0.0.1:5000/',\n",
    "                             data=data,\n",
    "                             headers={'Content-Type': 'application/json'})\n",
    "    return response.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "8ff25982",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:37.049766Z",
     "iopub.status.busy": "2021-10-28T01:36:37.048946Z",
     "iopub.status.idle": "2021-10-28T01:36:37.087164Z",
     "shell.execute_reply": "2021-10-28T01:36:37.087945Z"
    },
    "papermill": {
     "duration": 0.095579,
     "end_time": "2021-10-28T01:36:37.088283",
     "exception": false,
     "start_time": "2021-10-28T01:36:36.992704",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'prediction': 0}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "make_request('{\"sepal length (cm)\": 5.1, \"sepal width (cm)\": 3.5, \"petal length (cm)\": 1.4, \"petal width (cm)\": 0.2}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0b41c25",
   "metadata": {
    "papermill": {
     "duration": 0.048476,
     "end_time": "2021-10-28T01:36:37.187176",
     "exception": false,
     "start_time": "2021-10-28T01:36:37.138700",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "*Note: The previous command is equivalent to running the following on the terminal*\n",
    "\n",
    "```sh\n",
    "curl -d  '{\"sepal length (cm)\": 5.1, \"sepal width (cm)\": 3.5, \"petal length (cm)\": 1.4, \"petal width (cm)\": 0.2}' -H 'Content-Type: application/json' http://127.0.0.1:5000/\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "8daefbed",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:37.290040Z",
     "iopub.status.busy": "2021-10-28T01:36:37.289357Z",
     "iopub.status.idle": "2021-10-28T01:36:37.305039Z",
     "shell.execute_reply": "2021-10-28T01:36:37.305613Z"
    },
    "papermill": {
     "duration": 0.072048,
     "end_time": "2021-10-28T01:36:37.305883",
     "exception": false,
     "start_time": "2021-10-28T01:36:37.233835",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'prediction': 2}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "make_request('{\"sepal length (cm)\": 5.9, \"sepal width (cm)\": 3.0, \"petal length (cm)\": 5.1, \"petal width (cm)\": 1.8}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac137b34",
   "metadata": {
    "papermill": {
     "duration": 0.047882,
     "end_time": "2021-10-28T01:36:37.401423",
     "exception": false,
     "start_time": "2021-10-28T01:36:37.353541",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "*Note: The previous command is equivalent to running the following on the terminal*\n",
    "\n",
    "```sh\n",
    "curl -d  '{\"sepal length (cm)\": 5.9, \"sepal width (cm)\": 3.0, \"petal length (cm)\": 5.1, \"petal width (cm)\": 1.8}' -H 'Content-Type: application/json' http://127.0.0.1:5000/\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15cc285f",
   "metadata": {
    "papermill": {
     "duration": 0.047902,
     "end_time": "2021-10-28T01:36:37.496367",
     "exception": false,
     "start_time": "2021-10-28T01:36:37.448465",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "Note: Ploomber exports a Python object that encapsulates the entire inference pipeline (pre-processing + feature engineering + model inference). You can deploy it with any framework."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "62924a76",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:37.600040Z",
     "iopub.status.busy": "2021-10-28T01:36:37.599103Z",
     "iopub.status.idle": "2021-10-28T01:36:37.601256Z",
     "shell.execute_reply": "2021-10-28T01:36:37.601863Z"
    },
    "papermill": {
     "duration": 0.057478,
     "end_time": "2021-10-28T01:36:37.602125",
     "exception": false,
     "start_time": "2021-10-28T01:36:37.544647",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# terminate flask app\n",
    "proc.kill()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d7783ee",
   "metadata": {
    "papermill": {
     "duration": 0.049204,
     "end_time": "2021-10-28T01:36:37.699708",
     "exception": false,
     "start_time": "2021-10-28T01:36:37.650504",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "## Testing\n",
    "\n",
    "The example contains some basic unit tests. To run them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "c6dc0500",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-10-28T01:36:37.805925Z",
     "iopub.status.busy": "2021-10-28T01:36:37.805151Z",
     "iopub.status.idle": "2021-10-28T01:36:52.172762Z",
     "shell.execute_reply": "2021-10-28T01:36:52.174770Z"
    },
    "papermill": {
     "duration": 14.428235,
     "end_time": "2021-10-28T01:36:52.175144",
     "exception": false,
     "start_time": "2021-10-28T01:36:37.746909",
     "status": "completed"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "============================= test session starts ==============================\n",
      "platform darwin -- Python 3.9.7, pytest-6.2.5, py-1.10.0, pluggy-1.0.0\n",
      "rootdir: /Users/Edu/dev/projects-ploomber/templates/ml-online\n",
      "plugins: Faker-9.2.0, anyio-3.3.3\n",
      "collected 5 items\n",
      "\n",
      "tests/test_infer.py ..                                                   [ 40%]\n",
      "tests/test_service.py .                                                  [ 60%]\n",
      "tests/test_train.py .                                                    [ 80%]\n",
      "tests/test_wheel.py .                                                    [100%]\n",
      "\n",
      "============================== 5 passed in 13.10s ==============================\n"
     ]
    }
   ],
   "source": [
    "%%sh\n",
    "pytest -p no:warnings"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b09fbeee",
   "metadata": {
    "papermill": {
     "duration": 0.122058,
     "end_time": "2021-10-28T01:36:52.391451",
     "exception": false,
     "start_time": "2021-10-28T01:36:52.269393",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "\n",
    "## Packaging\n",
    "\n",
    "This project is a Python package. You can generate a distribution archive (`tar.gz`) or a built distribution (`.whl`) for deployment:\n",
    "\n",
    "\n",
    "```sh\n",
    "python -m build\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "153b0365",
   "metadata": {
    "papermill": {
     "duration": 0.178655,
     "end_time": "2021-10-28T01:36:52.706410",
     "exception": false,
     "start_time": "2021-10-28T01:36:52.527755",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "The previous command creates a `.whl` and a `.tar.gz` file in the `dist/` directory; both contain all the necessary pieces to serve predictions: dependencies, pre-processing code, and model file."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.1"
  },
  "papermill": {
   "default_parameters": {},
   "duration": 51.688162,
   "end_time": "2021-10-28T01:36:53.248144",
   "environment_variables": {},
   "exception": null,
   "input_path": "templates/ml-online/_build/readme_preprocessed.ipynb",
   "output_path": "templates/ml-online/README.ipynb",
   "parameters": {},
   "start_time": "2021-10-28T01:36:01.559982",
   "version": "2.3.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}