09-Building-Apps.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "1ccf7ea5-1abe-4401-a8c7-64bbfc057425",
   "metadata": {},
   "source": [
    "# Building the Backend and Frontend Applications"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "78574a83-1d13-4e99-be84-ddcc5f2c011e",
   "metadata": {},
   "source": [
    "In the previous notebook, we assembled all the functions and code required to create a robust Agent/Bot. Depending on the user's question, this Agent/Bot searches for answers in the available sources and tools.\n",
    "\n",
    "However, the question arises: **\"How can we integrate this code into a Bot application capable of supporting multiple channel deployments?\"** Our ideal scenario involves building the bot once and deploying it across various channels such as MS Teams, Web Chat, Slack, Alexa, Outlook, WhatsApp, Line, Facebook, and more.\n",
    "\n",
    "To achieve this, we need a service that not only aids in building the bot as an API but also facilitates the exposure of this API to multiple channels. This service is known as <u>Azure Bot Framework</u>.\n",
    "\n",
    "In this notebook, you will learn how to deploy the code you have developed so far as a Bot API using the Bot Framework API and Service."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "0a8858d8-c89c-4985-9164-b79cf9c530e3",
   "metadata": {},
   "source": [
    "## What is the Azure Bot Framework and Bot Service?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "3db318f3-f0f1-4328-a82e-9bb7f2a0eddf",
   "metadata": {},
   "source": [
    "Microsoft Bot Framework and Azure Bot Service are a collection of libraries, tools, and services that let you build, test, deploy, and manage intelligent bots.\n",
    "\n",
    "Bots are often implemented as a web application, hosted in Azure and using APIs to send and receive messages.\n",
    "\n",
    "Azure Bot Service and the Bot Framework include:\n",
    "\n",
    "- Bot Framework SDKs for developing bots in C#, JavaScript, Python, or Java.\n",
    "- CLI tools for help with end-to-end bot development.\n",
    "- Bot Connector Service, which relays messages and events between bots and channels.\n",
    "- Azure resources for bot management and configuration."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "e398cb34-3735-40ca-8dbf-3c50582e2213",
   "metadata": {},
   "source": [
    "So, in order to build our application we would use the **Bot Framework Python SDK to build the Web API**, and the **Bot Service to connect our API to mutiple channels**."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "f2905d00-c1c4-4fa8-8b4e-23c6fd0c1acc",
   "metadata": {},
   "source": [
    "## Architecture\n",
    "\n",
    "The image below shows:\n",
    "1) An Azure Web App hostoing the Bot API\n",
    "2) Azure Bot Service providing the connection between the Bot API, Channels and Application Insights"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "25987e8c-c5fe-45c2-8547-b0f66b3faf0d",
   "metadata": {},
   "source": [
    "![Botframework](./images/Bot-Framework.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "d31a7289-ca58-4bec-a977-aac3f755ea7f",
   "metadata": {},
   "source": [
    "# Backend - Azure Web App - Bot API"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "20c1936c-d084-4694-97eb-1ebd21fd5fe1",
   "metadata": {},
   "source": [
    "All the functions and prompts used in the prior notebook to create our brain Agent are located in `utils.py` and `prompts.py` respectively.\n",
    "So, what needs to be done is, basically, to do the same we did in the prior notebook but within the Bot Framework Python SDK classes.\n",
    "\n",
    "Within the `apps/backend/` folder, you will find three files: `app.py`, `bot.py` and `config.py`.\n",
    "- `app.py`: is the entrance main point to the application.\n",
    "- `bot.py`: is where our OpenAI-related code resides \n",
    "- `config.py`: declares the PORT the API will listen from and the App Service Principal var names\n",
    "\n",
    "We would only need to deal with `bot.py`, here is where all the logic code related to your Azure OpenAI application lives.\n",
    "\n",
    "in `apps/backend/README.md` you will find all the instructions on how to:\n",
    "1) Deploy the Azure web services: Azure Web App and Azure Bot Service\n",
    "2) Zip the code and uploaded to the Azure Web App\n",
    "3) Test your Bot API using the Bot Service in the Azure portal\n",
    "\n",
    "GO AHEAD NOW AND FOLLOW THE INSTRUCTIONS in `apps/backend/README.md`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "8ba1f125-2cc7-48ca-a047-5054f2f4ed37",
   "metadata": {},
   "source": [
    "# Frontend - Azure Web App - Streamlit "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "b9cb19fc-cd64-428c-8f2b-1963ff9fc4fb",
   "metadata": {},
   "source": [
    "Once you have the Backend Bot API app running and succesfully tested using the Bot Service Azure portal , we can proceed now to build a sample UI.\n",
    "\n",
    "In `apps/frontend/` folder you will find the files necesary to build a simple Streamlit application that will have:\n",
    "\n",
    "1) <u>A Search Interface</u>: Using `utils.py` and `prompts.py` and streamlit functions\n",
    "2) <u>A WebChat Interface</u>: Using the Bot Service Web Chat javascript library we can render the WebChat Channel inside Streamlit as an html component\n",
    "\n",
    "Notice that in (1) the logic code is running in the Frontend Web App, however in (2) the logic code is running in the Backend Bot API and the Frontend is just using the WebChat channel from the Bot Service.\n",
    "\n",
    "GO AHEAD NOW AND FOLLOW THE INSTRUCTIONS in `apps/frontend/README.md`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "e6f4abc9",
   "metadata": {},
   "source": [
    "# Build and deploy with GitHub Actions"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "c8cc7d8e",
   "metadata": {},
   "source": [
    "if you don't want to build and deploy all the components manually, a GitHub automated CI pipeline is provided in `.github/workflows/main_gptsmartsearch_apps.yml`. Some notes about the CI pipeline design:\n",
    "- It uses a \"branch per environment approach\". The deploy environment name is computed at 'runtime' based on a branch/env-name mapping logic in the \"set environment for branch\" step (line 29). The current implemented logic maps everything to a dev like environment. Therefore on each git push on the `main branch` the pipeline is triggered trying to deploy to an environment called `Development`. For more info about GitHub environments and how to set specific env variables and secrets read [here](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment).\n",
    "- GitHub environment variables and secrets are used to configure development environment specific configuration. They need to be configured manually in github repository settings:\n",
    "    - `secrets.AZUREAPPSERVICE_X_PUBLISHPROFILE` is used to store the azure app service publish profile configuration securely.\n",
    "    - `vars.AZURE_WEBAPP_X_NAME` is used to store the azure web app resource name generated during infra arm deployment.\n",
    "- Python dependencies installation is disabled during build phase as azure web apps are currently configured with SCM_DO_BUILD_DURING_DEPLOYMENT. There is an env properties that can be used to activate dependencies resolution during build job. Just set `DO_BUILD_DURING_DEPLOYMENT : false `.\n",
    "\n",
    "To properly configure automated build and deploy for both backend and frontend components follow below steps:\n",
    " \n",
    " 1. Go to your forked repository in GitHub and create an [environment]((https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)) called 'Development' (yes this exact name; don't change it). If you want to change the environment name, add new branches and environments  or change the current branch/env mapping you can do that, but make sure to change the pipeline code accordingly in `.github/workflows/main_gptsmartsearch_apps.yml` (starting line 29)\n",
    " 2. Create 'Development' environment [secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for both frontend and backend azure web apps [publish profiles]((https://learn.microsoft.com/en-us/visualstudio/azure/how-to-get-publish-profile-from-azure-app-service?view=vs-2022)). You'll need to copy paste the xml content from the .PublishSettings file into the secret value:\n",
    "     - Create a secret with name `AZUREAPPSERVICE_BACKEND_PUBLISHPROFILE` and set the Value field to publish profile of the azure web app you created using 'Deploy to Azure' button in `apps/backend/README.md`\n",
    "     - Create a secret with name `AZUREAPPSERVICE_FRONTEND_PUBLISHPROFILE` and set the Value field to publish profile of the azure web app you created using 'Deploy to Azure' button in `apps/frontend/README.md`\n",
    "3. Create 'Development' environment [variables](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-an-environment) for both frontend and backend azure web app resource names:\n",
    "    - Create a variable with name `AZURE_WEBAPP_BACKEND_NAME` and set the Value field to the azure web app resource name you created using 'Deploy to Azure' button in `apps/backend/README.md`\n",
    "    - Create a variable with name `AZURE_WEBAPP_FRONTEND_NAME` and set the Value field to the azure web app resource name you created using 'Deploy to Azure' button in `apps/frontend/README.md`\n",
    "4. For each commit you push check the status of the triggered pipeline in the GitHub Actions tab, you should see a pipeline has been triggered for the specific commit. If everything is ok you should see green checkmark on both build and deploy jobs in the pipeline detail like below:\n",
    "\n",
    "![pipeline success](./images/github-actions-pipeline-success.png)\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "e0301fa7-1eb9-492a-918d-5c36ca5cce90",
   "metadata": {},
   "source": [
    "# Reference"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "bdcdefab-7056-4990-b938-8e82b8dd9501",
   "metadata": {},
   "source": [
    "- https://learn.microsoft.com/en-us/azure/bot-service/bot-service-overview?view=azure-bot-service-4.0\n",
    "- https://github.com/microsoft/botbuilder-python/tree/main\n",
    "- https://github.com/microsoft/BotFramework-WebChat/tree/master"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "33ebcb0f-f620-4e1c-992c-c316466c3291",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10 - SDK v2",
   "language": "python",
   "name": "python310-sdkv2"
  },
  "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.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}