app.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8c68f03e-620c-46a9-a7ec-a6cde27043cd",
   "metadata": {},
   "source": [
    "# Hugging Face Spaces\n",
    "\n",
    "> A demo of using nbdev with Hugging Face Spaces\n",
    "\n",
    "Hugging Face spaces require that your python script is named `app.py`, so your first cell should be this, which will make sure code is exported to a file named `app.py`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c3463e8e-454a-48b8-ae21-8308703d2275",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|default_exp app"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96483373-4ae1-49b2-85ed-ceee8456df19",
   "metadata": {},
   "source": [
    "# Create a Gradio-enabled Space on Hugging Face\n",
    "\n",
    "The first step is to create a space and select the appropriate sdk (which is Gradio in this example), per [these instructions](https://huggingface.co/docs/hub/spaces-overview#creating-a-new-space):"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b34d7ec6-69b8-48c4-a68b-fad6db3c2fab",
   "metadata": {},
   "source": [
    "![](./create_space.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c25e8e7a-52d9-4305-a107-ba03e3d6a5f3",
   "metadata": {},
   "source": [
    "After you are done creating the space, **clone the repo to the root of your nbdev project.**  In this example, I ran the command `git clone https://huggingface.co/spaces/hamel/hfspace_demo` from the root of this repository."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff26114c-329b-4a97-98b5-c652554b0114",
   "metadata": {},
   "source": [
    "## Make an app with Gradio"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14a884fc-36e2-43ec-8e42-ca2903aaa4de",
   "metadata": {},
   "source": [
    "Below, we will create a [gradio](https://gradio.app/) in a notebook and show you how to deploy it to [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces).\n",
    "\n",
    "First, lets specify the libraries we need, which in this case are gradio, and the nbdev project which in this case is `nbdev_spaces_demo`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e5e5d597-19ad-46e5-81ad-8f646d8a1c21",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "import gradio as gr\n",
    "from nbdev_spaces_demo import hfsize "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ff9f84d-7744-46ad-80ed-2cf1fa6d0643",
   "metadata": {},
   "source": [
    "As a reminder, `hfsize` can be used to check the size of a Hugging Face Dataset. For example, we can check the size of [tglcourse/CelebA-faces-cropped-128](https://huggingface.co/datasets/tglcourse/CelebA-faces-cropped-128) like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "95bc32b8-d8ff-4761-a2d7-0880c51d0a42",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'5.49 GB'"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hfsize(\"tglcourse/CelebA-faces-cropped-128\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb13747b-ea48-4146-846d-deb9e855d32d",
   "metadata": {},
   "source": [
    "You can construct a simple UI with the `gradio.interface` and then call the `launch` method of that interface to display a preview in a notebook.  This is a great way to test your app to see if it works"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7b20e2a1-b622-4970-9069-0202ce10a2ce",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Running on local URL:  http://127.0.0.1:7860\n",
      "\n",
      "To create a public link, set `share=True` in `launch()`.\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div><iframe src=\"http://127.0.0.1:7860/\" width=\"500\" height=\"500\" allow=\"autoplay; camera; microphone; clipboard-read; clipboard-write;\" frameborder=\"0\" allowfullscreen></iframe></div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "(<gradio.routes.App>, 'http://127.0.0.1:7860/', None)"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|export\n",
    "iface = gr.Interface(fn=hfsize, inputs=gr.Text(value=\"tglcourse/CelebA-faces-cropped-128\"), outputs=\"text\")\n",
    "iface.launch(width=500)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "59926b18-a9af-4387-9fcc-f88e588da577",
   "metadata": {},
   "source": [
    "Note how running the `launch()` method in a notebook runs a webserver in the background.  Below, we call the `close()` method to close the webserver."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39d7be72-9389-42cf-91b1-78e8f4bbd083",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Closing server running on port: 7860\n"
     ]
    }
   ],
   "source": [
    "# this is only necessary in a notebook\n",
    "iface.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "249b2cd7-3123-45bf-945f-882b8a964cf5",
   "metadata": {},
   "source": [
    "## Converting This Notebook Into A Gradio App"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5c18ca6e-8de8-49e1-b95a-304070bbc171",
   "metadata": {},
   "source": [
    "In order to host this code on Hugging Faces spaces, we need to do the following:\n",
    "\n",
    "1. Export parts of this notebook to a script named `app.py`\n",
    "2. Create a `requirements.txt` file specifying all the dependencies of the gradio app which is inferred from `settings.ini`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1971847f-8d70-429b-8dd2-292d3e329266",
   "metadata": {},
   "source": [
    "We can achieve this with the below code, note how we are exporting the code to the `hfspace_demo/` directory, which is the repo we cloned in the first step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6706d92c-5785-4f09-9773-b9a944c493a5",
   "metadata": {},
   "outputs": [],
   "source": [
    "from nbdev.export import nb_export\n",
    "from nbdev.release import write_requirements\n",
    "\n",
    "app_dir = 'hfspace_demo/'\n",
    "nb_export('app.ipynb', app_dir)\n",
    "write_requirements(app_dir)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "662a58d6-a907-4a7f-962e-35859687a1e4",
   "metadata": {},
   "source": [
    "We can vendor in our python library generated with nbdev (named `nbdev_spaces_demo`) into the directory as well like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "128b042e-7a8a-4485-94af-46e7efee8557",
   "metadata": {},
   "outputs": [],
   "source": [
    "from nbdev.config import get_config\n",
    "!cp -r {str(get_config().lib_path)} {app_dir}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0182403f-d1d6-48c0-8e66-46aefb23a9ab",
   "metadata": {},
   "source": [
    "<div>\n",
    "<link rel=\"stylesheet\" href=\"https://gradio.s3-us-west-2.amazonaws.com/2.6.5/static/bundle.css\">\n",
    "<div id=\"target\"></div>\n",
    "<script src=\"https://gradio.s3-us-west-2.amazonaws.com/2.6.5/static/bundle.js\"></script>\n",
    "<script>\n",
    "launchGradioFromSpaces(\"abidlabs/question-answering\", \"#target\")\n",
    "</script>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84d5fd19-7880-459c-8382-b3574ed11141",
   "metadata": {},
   "source": [
    "### Understanding what is generated"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f0b783f0-cd5a-4092-b19c-8d05a978ce3c",
   "metadata": {},
   "source": [
    "The contents of the hfspace_demo/ folder will contain these assets:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a8d6b05f-1d17-4000-b82a-7fd4eb3092c5",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "README.md         app.py            \u001b[1m\u001b[36mnbdev_spaces_demo\u001b[m\u001b[m requirements.txt\n"
     ]
    }
   ],
   "source": [
    "!ls hfspace_demo/"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ea562e7-b67a-45df-b822-2f4528a307c2",
   "metadata": {},
   "source": [
    "Notice how the contents of app.py only contains the exported cells from this notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4bae6a5c-58bc-4a0f-9aac-34c092150fdc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[0;31m# AUTOGENERATED! DO NOT EDIT! File to edit: ../app.ipynb.\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;31m# %% auto 0\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0m__all__\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m[\u001b[0m\u001b[0;34m'iface'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;31m# %% ../app.ipynb 7\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;32mimport\u001b[0m \u001b[0mgradio\u001b[0m \u001b[0;32mas\u001b[0m \u001b[0mgr\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;32mfrom\u001b[0m \u001b[0mnbdev_spaces_demo\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mhfsize\u001b[0m \u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;31m# %% ../app.ipynb 11\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0miface\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mgr\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mInterface\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mfn\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mhfsize\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0minputs\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0mgr\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mText\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mvalue\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;34m\"tglcourse/CelebA-faces-cropped-128\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0moutputs\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;34m\"text\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0miface\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mlaunch\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mwidth\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;36m500\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%pycat hfspace_demo/app.py"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aadb4817-0671-4d05-9abc-d16776e2bec7",
   "metadata": {},
   "source": [
    "Similarly, the contents of requirements.txt contain all dependencies listed in `settings.ini` from the `requirments` and `pip_requirements` fields (which in this case is just `fastcore`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "831333c4-5e67-46fd-bd73-81a61cbcbd86",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "fastcore\n"
     ]
    }
   ],
   "source": [
    "!cat hfspace_demo/requirements.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f15d9c78-1f55-449e-8058-9af1832367a0",
   "metadata": {},
   "source": [
    "## Launching Your Gradio App\n",
    "\n",
    "To launch your gradio app, you need to commit the changes in the Hugging Face repo.  \n",
    "\n",
    "First, change directories to your huggingface repo (in this case its a directory called `hfspace_demo/`:\n",
    "\n",
    "`cd hfspace_demo`\n",
    "\n",
    "Then commit all changes\n",
    "\n",
    "```\n",
    "git add -A; git commit -m \"Add application files\"; git push\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa661f93-73b4-465a-9c22-cc38197505cb",
   "metadata": {},
   "source": [
    "## Voilà!  Enjoy your Gradio App"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b20ff94-6842-4078-9ec1-be740944e721",
   "metadata": {},
   "source": [
    "After a couple of minutes, you will see your app published!  "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}