Tarefa 1 - Bandits.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Imgur](https://i.imgur.com/ELdqWFi.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h2 align=\"center\">💸 Falindo o Cassino de Monte Carlo 💸</h2>\n",
    "\n",
    "Imagine que, após uma bem sucedida corrida no *Circuito de Mônaco*, você decidiu dar uma pausa na adrenalina do asfalto e passar em outra renomada atração turística da cidade, o famoso **Cassino de Monte Carlo**.\n",
    "\n",
    "Por conta de sua excentricidade e luxúria, os caça-níqueis (às vezes chamados de *one-armed bandits* em inglês) desse cassino funcionavam de uma maneira diferente que a de costume: cada máquina possuía 10 alavancas, com cada alavanca tendo uma certa chance de devolver uma certa quantidade de dinheiro. Como essas máquinas eram muito diferentes daquelas com que você estava acostumado, você decidiu observar um pouco alguns apostadores antes de participar do jogo. Com isso você observou que na média algumas alavancas devolviam mais dinheiro do que outras.\n",
    "\n",
    "Com sua astúcia, você logo percebeu que poderia aplicar um algoritmo de aprendizado por reforço para conseguir maximizar a quantidade de dinheiro recebida, possivelmente até falindo o cassino.\n",
    "\n",
    "![Imagem de um k-armed bandit](https://i.imgur.com/TxC4YwW.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Escrevendo a máquina caça-níquel em código\n",
    "\n",
    "A seguir vamos definir o que seria o ambiente (*enviroment* em inglês) do nosso algoritmo. Nesse caso, ele é a máquina caça-níquel (vamos começar a chamar de *bandit* daqui para frente), na qual você quer aprender qual é a melhor alavanca a se puxar para receber a maior quantidade de dinheiro."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OBS: recomendamos, sempre que possível, utilizar a biblioteca numpy nas suas implementações, não só nesse notebook mas também nos projetos em geral de RL. Dizemos isso porque o numpy possui otimizações específicas para operações matemáticas diversas, serve como uma forma de interface/padronização (inclusive com outras bibliotecas) e oferece métodos convenientes para várias operações que podemos desejar fazer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Bandit():\n",
    "\n",
    "    def __init__(self, k_arms=10):\n",
    "        # gera k números aleatórios uniformemente distribuídos entre -3 e 3\n",
    "        self.bandits_expectations = np.random.uniform(-3, 3, k_arms)\n",
    "    \n",
    "    def gamble(self, action):\n",
    "        \"\"\"ação(int) -> recompensa(int)\n",
    "        Recebe uma ação representando a alavanca que será acionada, \n",
    "        que devolve uma recompensa baseada em uma distribuição normal \n",
    "        de média definida no init e desvio padrão 1.\n",
    "        \"\"\"\n",
    "        return np.random.normal(self.bandits_expectations[action], 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Deixamos o código em orientação a objetos porque é o mais comum para ambientes em Python.\n",
    " - `__init__` é o construtor do objeto. Nesse caso ele inicializa o objeto gerando *k* números aleatórios uniformemente distribuídos entre -3 e 3. Cada um desses valores será o valor esperado de retorno de cada alavanca.\n",
    " - `gamble` realiza uma das ações possíveis no ambiente e retorna a recompensa obtida. Para cada uma das *k* alavancas o agente pode escolher qual delas irá puxar. Por exemplo, se a ação escolhida for o `0` ele puxará a alavanca de índice `0`, que possui valor esperado definido aleatoriamente pelo `__init__`.\n",
    "\n",
    "Vamos brincar um pouco com nosso ambiente para entender ele melhor:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(31415)\n",
    "env = Bandit(5) # inicializa um bandit de 5 alavancas"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Alavanca 0 tem valor esperado 0.8749116354525284\n",
      "Alavanca 1 tem valor esperado 1.0510450191080096\n",
      "Alavanca 2 tem valor esperado 2.824223916292027\n",
      "Alavanca 3 tem valor esperado 2.308826185839571\n",
      "Alavanca 4 tem valor esperado 2.454395056308611\n"
     ]
    }
   ],
   "source": [
    "# Vamos ver os valores esperados de cada uma das alavancas\n",
    "for i in range(len(env.bandits_expectations)):\n",
    "  print(f\"Alavanca {i} tem valor esperado {env.bandits_expectations[i]}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2.770138095051762"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "env.gamble(2) # puxar a alavanca de índice 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualizando as distribuições do Bandit\n",
    "Por conta de como estão distribuídos os valores esperados, com certeza teremos alguma alavanca que possuí o maior valor esperado. Podemos visualizar isso construindo um gráfico que mostra como os valores estão distribuídos para cada alavanca:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAApcAAAG5CAYAAADbIh9KAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjguMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy81sbWrAAAACXBIWXMAAAsTAAALEwEAmpwYAABbUUlEQVR4nO3deXxkVZk//s9TS1LZ00nve7M23TRri+AGiiiyKeIIDiKLft0GB2f057ihOG5fRxxxRkZxHAEBEcUNmXEQGRAURr+NAiIICvTedKezJ5VKbc/vj1vVVJJKUpXUrXvuOZ/36xVI59Zybt2qus99zjnPEVUFEREREVEtRIJuABERERHZg8ElEREREdUMg0siIiIiqhkGl0RERERUMwwuiYiIiKhmGFwSERERUc0wuCQygIh8XUSurNFjrRaRERGJFv59n4i8Y46P9VER+WaFt71bRH5VeP4fzuX5pnncObe/hm3YKiKv9uFxbxCRz9T6cU0gIpeIyK+CbsdkInKViNxc7+ea/Lkkslks6AYQ2U5EtgJYAiALIAfgCQDfBvANVc0DgKq+u4rHeoeq/mK626jqdgCt82v1gcf6XIXt6gKwE8DNAH4A4B9r8fxEtpj8uRSR+wDcrKoVXbwRhQmDS6L6OFtVfyEiHQBOBvAVAC8GcGktn0REYqqareVjVkJV+/DCvryo3s9PRETmYLc4UR2p6qCq3gHgfAAXi8iRwMTuURFZKCJ3isiAiPSJyAMiEhGRmwCsBvDTQvfah0RkrYioiLxdRLYD+J+Sv5VePB4sIr8VkSER+Ukh0wgROUVEdpa2sbQLeHIXooi8TEQeLLRth4hcUvj7mSLy+8Lj7xCRqyY95jki8sfC/e4TkSOme41E5DQR+ZOIDIrIVwHIpO2XiciTItIvIneJyJoZHmuu7b1IRLaJSK+IfGzSthNE5KHCY+4Rka+KSMMMbfi+iDxf2J/7RWTjNLdbUDjuPYV9u1NEVha2nS8iWybd/u9E5I7Z9qfk/XCxiGwXkf2l+yQiUfGGPzwjIsMi8rCIrCps+0rh8YYKf3/5DPvZLSJ3FG77WwAHT9q+XryhE30i8pSIvHmGx5owDEEmdi8X9+fSQtv6ReTdIvIiEXmscFy+Ot1jFyRE5LbC/v5ORI4uea4Pl7wWT4jIuSXbLhFv6MfVhed9TkReV7J9nYj8snDfuwEsLHMcYiLyWQAvB/BV8T7Ls7WXKFQYXBIFQFV/C68budzJ+gOFbYvgdad/1LuLXgRgO7wsaKuq/lPJfU4GcASA107zlG8DcBmAZfC65/+l2jYXgrifAfjXQtuOAfBIYfNo4Tk6AZwJ4D0i8obC/Q4DcCuA9xfu91/wAuQpAZmILATwQwAfh3difgbAS0u2vx7e6/HGwmM9UHjsWrZ3A4CvAbgIwHIA3QBWljx0DsDfFdp3EoBTAby3XBsKfgbgUACLAfwOwC3T3C4C4HoAa+BdRIwBKAYdPwVwuIgcWnL7vwbwndn2p8TLABxeaO8n5IUA/+8BvAXAGQDa4b1PkoVt/w/e69ZVeK7vi0himvZfCyAF7z12WeEHACAiLQDuLjzGYgAXAPi3wms9Vy+G97qeD+AaAB8D8GoAGwG8WUROnuG+rwfwfbywXz8WkXhh2zPwPpcdAD4F4GYRWTbpeZ+Cd/z/CcB/iEjxAug7AB4ubPs0gIvLPbmqfgzee/fywmf58sp3m8h8DC6JgrMb3sltsgy8E/QaVc2o6gOqqrM81lWqOqqqY9Nsv0lVH1fVUQBXwjv5Vjux4K8B/EJVby20q1dVHwEAVb1PVf+gqnlVfQxewFc8uZ8P4D9V9W5VzQC4GkATgJeUeY4zAPxRVW8v3PYaAM+XbH83gM+r6pOF7v/PAThGymcv59reNwG4U1XvV9XxwuuVLz6oqj6sqv+rqllV3QrgupL7TqGq31LV4cJjXQXgaPGGR0y+Xa+q/kBVk6o6DOCzxcdV1SSAn8ALAlEIMtcDuKOC/Sn6lKqOqeqjAB4FUMzWvQPAx1X1KfU8qqq9hce9udCurKp+CUAjvAB1gsJ76TwAnyi8Dx8HcGPJTc4CsFVVry881u/hjc39q+letwp8WlVTqvpzeMH1raq6T1V3wQvcjp3hvg+XvMf+GUACwImFff6+qu4uvJa3AfgzgBNK7rtNVf9dVXOFfVwGYImIrIY3JORKVR1X1fvhXRQQOYfBJVFwVgDoK/P3LwL4C4Cfi8izIvLhCh5rRxXbtwGIo6TLrkKr4GV1phCRF4vIvYUu3UF4QWDx8ZcXnhMAUJjEtAPe/k+2vLSthaC6tO1rAHyl0PU5AO/1k2keaz7tLW3DKIDekvseVuiyfl5EhuAFuGVfy0KX8/8tdLMOAdha2DTl9iLSLCLXidcdPwTgfgCdJRcB30EhuIQXOP+4EHTOtj9FpUF6Ei9MLpnpdfqgeEMQBguvd8c0+7oI3hj+ye+zojUAXlw8boXHuhDA0nLPW6G9Jb+Plfn3TJPaSo9vHl5PwXIAEJG3icgjJe08EhP3+fmS+xYzvK2F+/cX3i9Fpa8BkTMYXBIFQEReBC8gmlKqpZDl+oCqHgTgHAB/LyKnFjdP85CzZTZXlfy+Gl52dD+8jE9zSbui8AKFcnZg0ji6Et+Bl0VbpaodAL6OF8ZK7oYXXBSfQwrt2VXmcfaUtrXktqVteJeqdpb8NKnqgzVs7+Q2NMPrGi/6GoA/AThUVdvhddNPGBda4q/hdcG+Gl5gtrb4sGVu+wF4WcEXFx73FZNuezeARSJyDLwg8zsl951pf2ZT9nUSb3zlhwC8GcACVe0EMDjN4/bAG24x+X1W+hy/nHTcWlX1PdO0acL7EvMLQsspPb4ReMMedhcy4P8O4HIA3YV9fhyVvZZ7ACwoDAEoWj3djTH7Z5YotBhcEtWRiLSLyFkAvguvDMkfytzmLBE5pBBYDcIb41fslt0L4KA5PPVbRWRDIVD6RwC3F7r1noY3ueHMwpizj8Pr+iznFgCvFpE3FyYldBcCHQBoA9CnqikROQFeUFX0PQBnisiphef4AIBxAOUCwv8EsFFE3ijehKS/xcTA4usAPiKFSTEi0iEi03WtzrW9twM4S7zJQA2F16v0u7INwBCAERFZD2C6AKl423F4mc9meFnOmW47BmBAvAlXnyzdWOjC/T68zHYXvGCz9L7T7c9svgng0yJyqHiOEpHuwmNm4QWOMRH5BLwxmVMU3ks/BHBVIQO7ARPHG94J4DDxJkrFCz8vkukndj0C4ILC7TbDG6pQS8eXvMfeD+8Y/S+AFnhBXw8AiMil8DKXs1LVbQC2APiUiDSIyMsAnD3DXeb6WSYyHoNLovr4qYgMw8vgfAzeOK/pyhAdCuAXAEYAPATg31T13sK2zwP4eKHL7oNVPP9NAG6A16WXgBe0QVUH4U1G+Sa8TOIovC7CKdSr03cGvOAwAy+jUxy3914A/1jYx0/ACyiL93sKwFvhTazZD++Ee7aqpss8x3544/D+L7yA7FAAvy7Z/iMAXwDw3ULX8eMAXjf5ccq0tw9ewFJJe/8I4G/gZQP3AOif9Jp8EF7wNgwvy3Vbuecv+Da8rtFd8Oqb/u8Mt70G3ljU/YXb/XeZ23wHXhb0+zqx5NS0+1OBfy7c/ufwgub/KLTjrkIbni7sQwozD7+4HF738PPw3mvXFzcUxpC+Bt5Ent2F23wB01/IXAkvm9oPb1LNd6a53Vz9BN5Y4H54E7feWBiX+wSAL8H73O0FsAkl778K/DW8CT998C4Ovj3Dbb8C4E3izTqveoIdkclk9nkCREQTichFABpU9T+CbgsREZmFmUsiqoqItMIrifTKoNtCRETmYXBJRNW6Hl6JlZ8F3RAiIjIPu8WJiIiIqGaYuSQiIiKimonNfhNzLFy4UNeuXRt0M4iIiIic9/DDD+9X1Sm1kUMVXK5duxZbtmwJuhlEREREzhORsqtQsVuciIiIiGqGwSURERER1QyDSyIiIiKqmVCNuSQiIgqbTCaDnTt3IpVKBd0UojlJJBJYuXIl4vF4RbdncElEROSjnTt3oq2tDWvXroWIBN0coqqoKnp7e7Fz506sW7euovuwW5yIiMhHqVQK3d3dDCwplEQE3d3dVWXeGVwSERH5jIElhVm1718Gl0RERERUMwwuiYiILCcieOtb33rg39lsFosWLcJZZ5014/22bNmCv/3bv/W7eQds3boVRx55ZN2er16uuuoqXH311b489o4dO/DKV74SGzZswMaNG/GVr3yl7O0GBwdx9tln4+ijj8bGjRtx/fXXAwAeeeQRnHTSSdi4cSOOOuoo3HbbbfNuEyf0EBERWa6lpQWPP/44xsbG0NTUhLvvvhsrVqyY9X6bN2/G5s2bK36ebDaLWKx+oUW9n8+U5y4Vi8XwpS99CccddxyGh4dx/PHH47TTTsOGDRsm3O7aa6/Fhg0b8NOf/hQ9PT04/PDDceGFF6K5uRnf/va3ceihh2L37t04/vjj8drXvhadnZ1zbhMzl0RERA4444wz8J//+Z8AgFtvvRVvectbDmz77W9/i5NOOgnHHnssXvKSl+Cpp54CANx3330Hspt9fX14wxvegKOOOgonnngiHnvsMQBeVu6iiy7CS1/6Ulx00UUTnvOCCy448JwAcMkll+D222/H1q1b8fKXvxzHHXccjjvuODz44INT2ptKpXDppZdi06ZNOPbYY3HvvfcCAG644Qacc845eNWrXoVTTz11yv1uvvlmnHDCCTjmmGPwrne9C7lcDrlcDpdccgmOPPJIbNq0CV/+8pcBAKeccgquuOIKHHPMMTjyyCPx29/+FgAwOjqKyy67DCeccAKOPfZY/OQnPyn73CMjIzj11FNx3HHHYdOmTQduBwCf/exncdhhh+FlL3vZgdcT8DKFJ554Io466iice+656O/vr+j4TWfZsmU47rjjAABtbW044ogjsGvXrim3ExEMDw9DVTEyMoKuri7EYjEcdthhOPTQQwEAy5cvx+LFi9HT0zOvNkFVQ/Nz/PHHKxERUZg88cQTE/9w8slTf6691ts2Olp++/XXe9t7eqZuq0BLS4s++uijet555+nY2JgeffTReu+99+qZZ56pqqqDg4OayWRUVfXuu+/WN77xjaqqE25z+eWX61VXXaWqqvfcc48effTRqqr6yU9+Uo877jhNJpNTnveHP/yhvu1tb1NV1fHxcV25cqUmk0kdHR3VsbExVVV9+umntXh+f+6553Tjxo2qqnr11VfrpZdeqqqqTz75pK5atUrHxsb0+uuv1xUrVmhvb++U53viiSf0rLPO0nQ6raqq73nPe/TGG2/ULVu26Ktf/eoDt+vv71dV1ZNPPlnf8Y53qKrqL3/5ywPP/ZGPfERvuummA7c99NBDdWRkZMpzZzIZHRwcVFXVnp4ePfjggzWfz+uWLVv0yCOP1NHRUR0cHNSDDz5Yv/jFL6qq6qZNm/S+++5TVdUrr7xSr7jiiin7cfPNN+vRRx895ee8886bcttSzz33nK5atepAm0oNDQ3pKaecokuXLtWWlha98847p9zmN7/5ja5fv15zuVzZ13YyAFu0TLwWfD6XiIiIfHfUUUdh69atuPXWW3HGGWdM2DY4OIiLL74Yf/7znyEiyGQyU+7/q1/9Cj/4wQ8AAK961avQ29uLoaEhAMA555yDpqamKfd53etehyuuuALj4+P47//+b7ziFa9AU1MTBgcHcfnll+ORRx5BNBrF008/Xfb53ve+9wEA1q9fjzVr1hy43WmnnYaurq4p97nnnnvw8MMP40UvehEAYGxsDIsXL8bZZ5+NZ599Fu973/tw5pln4jWvec2B+xQzuK94xSswNDSEgYEB/PznP8cdd9xxYJxkKpXC9u3bpzy3quKjH/0o7r//fkQiEezatQt79+7FAw88gHPPPRfNzc0HXp/i6zwwMICTTz4ZAHDxxRfjr/7qr6bsx4UXXogLL7xwyt9nMjIygvPOOw/XXHMN2tvbp2y/6667cMwxx+B//ud/8Mwzz+C0007Dy1/+8gO33bNnDy666CLceOONiETm17HN4JKIiKie7rtv+m3NzTNvX7hw5u2zOOecc/DBD34Q9913H3p7ew/8/corr8QrX/lK/OhHP8LWrVtxyimnVPW4LS0tZf+eSCRwyimn4K677sJtt92GCy64AADw5S9/GUuWLMGjjz6KfD6PRCJRk+dTVVx88cX4/Oc/P2Xbo48+irvuugtf//rX8b3vfQ/f+ta3AEwtsyMiUFX84Ac/wOGHHz5h229+85sJz33LLbegp6cHDz/8MOLxONauXVuTlZhuueUWfPGLX5zy90MOOQS33377lL9nMhmcd955uPDCC/HGN76x7GNef/31+PCHPwwRwSGHHIJ169bhT3/6E0444QQMDQ3hzDPPxGc/+1mceOKJ824/x1wSERE54rLLLsMnP/lJbNq0acLfBwcHD0zwueGGG8re9+UvfzluueUWAN5YzIULF5bNkE12/vnn4/rrr8cDDzyA008//cDzLVu2DJFIBDfddBNyudyMz/f0009j+/btU4K9yU499VTcfvvt2LdvHwBvnOi2bduwf/9+5PN5nHfeefjMZz6D3/3udwfuU5wd/atf/QodHR3o6OjAa1/7Wvzrv/4rvJ5f4Pe//33Z5xscHMTixYsRj8dx7733Ytu2bQC8LOiPf/xjjI2NYXh4GD/96U8BAB0dHViwYAEeeOABAMBNN910IItZ6sILL8Qjjzwy5adcYKmqePvb344jjjgCf//3fz/ta7N69Wrcc889AIC9e/fiqaeewkEHHYR0Oo1zzz0Xb3vb2/CmN71pxte3UsxcEhFV6fzrHprzffOqiMyjoPZt7zppzvclWrlyZdnSQh/60Idw8cUX4zOf+QzOPPPMsve96qqrcNlll+Goo45Cc3Mzbrzxxoqe8zWveQ0uuugivP71r0dDQwMA4L3vfS/OO+88fPvb38bpp59eNhP53ve+F+95z3uwadMmxGIx3HDDDWhsbJzxuTZs2IDPfOYzeM1rXoN8Po94PI5rr70WTU1NuPTSS5HP5wFgQmYzkUjg2GOPRSaTOZDNvPLKK/H+978fRx11FPL5PNatW4c777xzyvNdeOGFOPvss7Fp0yZs3rwZ69evBwAcd9xxOP/883H00Udj8eLFB7rpAeDG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",
      "text/plain": [
       "<Figure size 792x504 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "samples = [[env.gamble(0) for i in range(1000)],\n",
    "           [env.gamble(1) for i in range(1000)],\n",
    "           [env.gamble(2) for i in range(1000)],\n",
    "           [env.gamble(3) for i in range(1000)],\n",
    "           [env.gamble(4) for i in range(1000)]]\n",
    "\n",
    "plt.figure(figsize=(11,7))\n",
    "\n",
    "max_e = np.max(env.bandits_expectations)\n",
    "\n",
    "plt.title(\"Distribuição de cada alavanca de um bandit\")\n",
    "plt.violinplot(samples, [0,1,2,3,4])\n",
    "plt.axline((0,max_e), slope=0, ls=\"--\",c=\"red\", label=f\"Maior valor esperado = {max_e:.2f}\")\n",
    "plt.legend(loc=\"best\")\n",
    "plt.xlabel(\"Ação\")\n",
    "plt.ylabel(\"Recompensa\")\n",
    "plt.show()        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Assim, com o gráfico podemos ver que realmente, a melhor alavanca a se puxar com o intuito de ganhar a maior quantidade de dinheiro é a de número 2. Porém, como podemos fazer com que o agente aprenda que essa é a melhor alavanca a se puxar também? Veremos isso na próxima seção."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 🥣 Criando um Algoritmo Guloso (*Greedy*)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Estimando  o valor esperado *Q*\n",
    "\n",
    "No nosso problema de $k$-Armed Bandits dizemos que para cada $k$ ações há uma recompensa média esperada; esse valor esperado geralmente é chamado de valor da ação. Ou seja, definimos o valor de uma ação arbitrária $a$, denotado de $q^{*}(a)$, como uma recompensa em um tempo $t$ ($R_t$) dado que a ação em $t$ ($A_t$) foi a como:\n",
    "\n",
    "$$q^*(a) = \\mathbb{E}[R_t | A_t=a]$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> (Esse $\\mathbb{E}$ significa o valor esperado, é como se fosse a “recompensa média” — a recompensa com maior probabilidade de acontecer dado $a$.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Se nosso agente soubesse todos os valores esperados, o problema seria facilmente resolvido: ele simplesmente escolheria a ação com o maior valor. O problema é justamente que ele não sabe esses valores. Para obter alguma estimativa para esses valores, denotaremos as estimativas com a letra $Q$ maiúscula, já que normalmente em Aprendizado por Reforço nós usamos letras maiúsculas para representar algo aleatório ou um valor estimado.\n",
    "\n",
    "Como estamos buscando um valor esperado — ou seja, a recompensa média — basta calcularmos a média das recompensas recebidas por nosso agente naquela ação:\n",
    "$$Q_{n+1} = \\frac{1}{n}\\sum_{i=1}^{n}R_i$$\n",
    "\n",
    "Porém, como na computação seria custoso executar uma somatória toda vez que gostaríamos de atualizar Q podemos fazer algumas manipulações algébricas e cair na seguinte equação:\n",
    "$$Q_{n+1} = Q_n + \\frac{1}{n}(R_n - Q_n) $$\n",
    "\n",
    "Que é a equação que iremos usar em nosso algoritmo! Lembre-se que $n$, nesse caso, vai ser o número de vezes que aquela ação ocorreu. **Então teremos um $n$ e um $Q$ para cada ação**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A função argmax\n",
    "\n",
    "Agora que já sabemos como estimar os valores $Q$ temos que criar alguma função capaz de escolher a ação com o maior valor estimado. Essa é a função argmax!\n",
    "\n",
    "Ela é definida da seguinte maneira:\n",
    " - Recebe uma lista de valores\n",
    " - Verifica qual é o maior valor dessa lista\n",
    " - Retorna o **índice** desse valor\n",
    " - Em caso de empates, ela retorna o índice de um dos maiores valores aleatoriamente\n",
    "\n",
    "![diagrama da argmax](https://i.imgur.com/B3HJC6P.png)\n",
    "\n",
    "Seu primeiro exercício será implementar essa função!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercício 1, implementando a função argmax\n",
    "Complete o código abaixo para implementar a função argmax especificada a cima."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def argmax(lista):\n",
    "    \"\"\" (lista) -> índice de maior valor(int)\n",
    "    Recebe uma lista dos valores Q e retorna o índice do maior valor.\n",
    "    Por definição, resolve empates escolhendo um deles aleatoriamente.\n",
    "    \"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Definindo o agente\n",
    "Agora que já sabemos como podemos estimar os valores de $Q$ e como podemos escolher as ações de maior valor com a função argmax, podemos definir nosso **agente guloso**. Ele deverá ser composto da seguinte forma:\n",
    " - o construtor recebe o número de `k_arms` existentes no ambiente e inicializa os seguintes atributos:\n",
    "    - `n_arms`: vetor que guardará quantas vezes o agente realizou cada ação. Inicializado com um vetor de zeros com tamanho igual ao número de ações (alavancas).\n",
    "    - `Q_values`: vetor que armazena o $Q$ valor de cada ação. Inicializado com um vetor de zeros com tamanho igual ao número de ações (alavancas).\n",
    "    -  `last_action`: última ação do agente. Inicializada com uma ação aleatória.\n",
    "    \n",
    "- A função de `step` deve receber a recompensa do episódio e estar definida da seguinte maneira:\n",
    "   - Atualiza o vetor `n_arms` adicionando mais um ao $n$ da última ação realizada.\n",
    "   - Calcula o $Q$ atual conforme a fórmula definida.\n",
    "   - Atualiza o vetor `Q_values` atualizando o novo valor `Q` da última ação.\n",
    "   - Escolhe a próxima ação passando a lista atualizada de `Q_values` à função argmax.\n",
    "   - Atualizar a última ação do agente com a ação escolhida.\n",
    "   - Retorna a ação escolhida."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercício 2, implementando o agente guloso\n",
    "Complete o código abaixo conforme as definições:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class GreedyAgent():\n",
    "    def __init__(self, k_arms):\n",
    "        self.n_arms = np.zeros(k_arms)\n",
    "        self.Q_values = np.zeros(k_arms)\n",
    "        self.last_action = np.random.randint(0, k_arms)\n",
    "\n",
    "    def agent_step(self, reward):\n",
    "        \"\"\" (float) -> acao(int)\n",
    "        Dá um step para o Agente atualizando os valores Q.\n",
    "        Pega a recompensas do estado e retorna a ação escolhida.\n",
    "        \"\"\" "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Treinando o Agente\n",
    "Com o agente e o ambiente definidos, podemos finalmente treiná-lo!\n",
    "\n",
    "O código de treinamento deve ser definido como:\n",
    " - Inicializamos nosso agente `agent`, com `k_arms = 10`\n",
    " - Inicializamos nosso ambiente `env`, com `k_arms = 10`\n",
    " - Para cada `step` no número total de steps  `num_steps`\n",
    "    - Receber a recompensa do ambiente puxando a alavanca (`env.gamble`) representada pela última ação do agente (`agent.last_action`).\n",
    "    - Atualizar a estimativa de valor do agente (`agent.agent_step`)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercício 3, implementando o treinamento do agente\n",
    "Complete o código a baixo conforme as definições:\n",
    " "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "n_steps = 1_000\n",
    "\n",
    "# inicialize o agente e o ambiente\n",
    "agent = ...\n",
    "env = ...\n",
    "\n",
    "score = [0]\n",
    "means = []\n",
    "max_expectation = np.max(env.bandits_expectations)\n",
    "\n",
    "for step in range(n_steps):\n",
    "    reward = ... # Tome ação no ambiente\n",
    "\n",
    "    ... # Atualize a estimativa de valor do agente\n",
    "\n",
    "    score.append(score[-1] + reward)\n",
    "    means.append(score[-1]/(step+1))\n",
    "\n",
    "plt.figure(figsize=(11,5))\n",
    "plt.title(\"Recompensa de uma simulação de um agente guloso\")\n",
    "plt.axline((0, max_expectation), slope=0, ls=\"--\", c=\"red\", label=\"Melhor possível\")\n",
    "plt.plot(means, label=\"Guloso\")\n",
    "plt.xlabel(\"Steps\")\n",
    "plt.ylabel(\"Recompensa\")\n",
    "plt.legend(loc=\"best\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Se tudo deu certo você verá o gráfico de uma simulação, com a recompensa comparada com a melhor possível. Você verá que, provavelmente, os resultados não são os melhores, mas existe uma chance de que, por conta de sorte, ele consiga a melhor pontuação. Para eliminar esse fator de sorte, podemos executar a simulação várias vezes e pegar a média:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "n_steps = 1_000\n",
    "n_simulations = 200\n",
    "total_means = []\n",
    "\n",
    "max_means = 0\n",
    "for simulation in range(n_simulations):\n",
    "\n",
    "    agent = ...\n",
    "    env = ...\n",
    "\n",
    "    score = [0]\n",
    "    means = []\n",
    "\n",
    "    max_means += np.max(env.bandits_expectations)\n",
    "\n",
    "    for step in range(n_steps):\n",
    "        reward = ... # Tome ação no ambiente\n",
    "\n",
    "        ... # Atualize a estimativa de valor do agente\n",
    "\n",
    "        score.append(score[-1] + reward)\n",
    "        means.append(score[-1]/(step+1))\n",
    "\n",
    "    total_means.append(means)\n",
    "\n",
    "plt.figure(figsize=(11,5))\n",
    "plt.title(\"Recompensa média de um agente guloso\")\n",
    "plt.axline((0, max_means/n_simulations), slope=0, ls=\"--\", c=\"red\", label=\"Melhor possível\")\n",
    "plt.plot(np.mean(total_means, axis=0), label=\"Guloso\")\n",
    "plt.xlabel(\"Steps\")\n",
    "plt.ylabel(\"Recompensa Média\")\n",
    "plt.legend(loc=\"best\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Por mais que o Algoritmo Guloso consiga chegar rapidamente a uma recompensa média relativamente grande, ele ficará preso a ela para sempre. Por sempre escolher a ação que parece a melhor no momento, esse agente deixa de explorar novas ações rapidamente e possui grandes chances de ficar estagnado em uma \"armadilha\", já que acabará não conhecendo outras ações que podem ser melhores e, na média, ficará preso a uma solução não otimizada.\n",
    "\n",
    "Imagine, por exemplo, que, devido à aleatoriedade que as alavancas apresentam, uma das alavancas ruins produziu, nas primeiras interações, valores relativamente altos, enquuanto a melhor alavanca produziu valores relativamente baixos. Como o nosso agente se prende sempre ao que parece ótimo no momento, ele provavelmente não será capaz de superar esse problema e acabará decidindo por uma ação que não é a melhor.\n",
    "\n",
    "A solução para isso é balancear o quanto o agente persiste na aparente melhor ação no momento e o quanto ele arrisca em novas possibilidades. Para isso, vamos introduzir o conceito do **Algoritmo ε-Guloso** que possui uma chance aleatória de fazer uma ação de **exploração**!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 🧭 Criando um Algoritmo ε-Guloso\n",
    "A ideia de um algoritmo é adicionar um parâmetro $\\varepsilon$, que controla a probabilidade do agente realizar uma ação aleatória de exploração. A seguir, discutimos um pouco mais sobre esses dois conceitos.\n",
    "\n",
    "## Exploração e Explotação\n",
    "\n",
    "Como no agente guloso nós sempre pegamos a ação de maior valor estimado até aquele momento, é fácil dele cair em soluções subótimas. Para resolver isso, introduzimos a ideia de **exploração** no algoritmo.\n",
    "\n",
    "A exploração é uma maneira do agente identificar cenários ainda não vistos, conhecendo melhor o valor de cada ação. A explotação, por sua vez, é utilizar esse conhecimento para tomar a melhor decisão. Uma analogia com o mundo real seria o menu de um restaurante: imagine que você pediu um prato lá e acabou gostando deste prato, você poderia sempre pedi-lo quando fosse nesse restaurante e acabaria feliz, porém, se não se arriscar a pedir nenhum outro prato nunca saberá se pode haver um prato do qual você acabe gostando mais!\n",
    "\n",
    "## Definindo o Agente\n",
    "No geral, o agente $\\varepsilon$-guloso é bem parecido com o agente guloso, a maior diferença sendo a presença desse novo parâmetro $\\varepsilon$ e a chance $\\varepsilon$ dele executar uma ação aleatória ao invés da de maior valor estimado.\n",
    "\n",
    "Com isso o código ficaria definido como:\n",
    " - No construtor, além do parâmetro `k_arms`, agora ele deve receber o parâmetro `epsilon`.\n",
    "    - Além dos atributos já definidos no agente guloso, agora ele também deve inicializar um atributo `self.epsilon` que armazena o valor de `epsilon`\n",
    " - Na função de `step` todos os passos de atualização dos vetores continuam os mesmos, o que muda é agora colocar a chance de executar uma ação aleatória\n",
    "    - Ao invés de só escolher a próxima ação com base no argmax você deve gerar um número real aleatório entre 0 e 1.\n",
    "    - Se esse número for menor que o epsilon, a próxima ação deve ser aleatória (um número inteiro aleatório entre 0 e número de braços-1)\n",
    "    - Se não, a próxima ação é a com maior $Q$ valor (passando a lista de valores $Q$ na argmax)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercício 4, implementado o agente ε-Guloso"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class EpsilonGreedy():\n",
    "    def __init__(self, k_arms, epsilon=0.1):\n",
    "        self.epsilon = epsilon\n",
    "        self.n_arms = np.zeros(k_arms)\n",
    "        self.Q_values = np.zeros(k_arms)\n",
    "        self.last_action = np.random.randint(0, k_arms)\n",
    "\n",
    "    def agent_step(self, reward):\n",
    "        \"\"\" (float) -> acao(int)\n",
    "        Dá um step para o Agente atualizando os valores Q.\n",
    "        Pega a recompensas do estado e retorna a ação escolhida.\n",
    "        \"\"\" "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Treinando o Agente\n",
    "O processo de treinamento é o mesmo, o único diferencial é que agora podemos testar diferentes resultados para diferentes valores de $\\varepsilon$.\n",
    " - Lembre-se de inicializar o agente e o ambiente. Para o agente, lembre de passar o parâmetro de `epsilon=eps`.\n",
    " - Dentro da lista `epsilons` escreva alguns valores para o parâmetro. Recomendamos três em específico: 0.1, 0.5 e 0 (se `epsilon = 0` então é só o algoritmo guloso), mas sinta-se livre para experimentar mais parâmetros.\n",
    " - Como foram os resultados obtidos? Qual é a relação de mudar o valor de $\\varepsilon$ e a média das recompensas médias?\n",
    " - Sinta-se livre para também testar valores de $\\varepsilon$ bem pequenos (0.01 por exemplo) e também aumentar o número de steps."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "n_steps = 3_000\n",
    "n_simulations = 20\n",
    "total_means = []\n",
    "max_means = []\n",
    "\n",
    "# coloque outros parâmetros para epsilon!\n",
    "epsilons = [0, 0.5, 0.1, ..., ...]\n",
    "\n",
    "plt.figure(figsize=(11,5))\n",
    "\n",
    "# Fazer 20 simulações, com 3.000 steps para cada valor de epsilon\n",
    "for eps in epsilons: \n",
    "    max_mean = 0\n",
    "    for runs in range(n_simulations):\n",
    "\n",
    "        agent = ... # inicialize o agente com um epsilon diferente\n",
    "\n",
    "        env = ... \n",
    "\n",
    "        score = [0]\n",
    "        means = []\n",
    "\n",
    "        max_mean += np.max(env.bandits_expectations)\n",
    "\n",
    "        for step in range(n_steps):\n",
    "            reward = ... # Tome ação no ambiente\n",
    "\n",
    "            ... # Atualize a estimativa de valor do agente\n",
    "\n",
    "            score.append(score[-1] + reward)\n",
    "            means.append(score[-1]/(step+1))\n",
    "        total_means.append(means)\n",
    "\n",
    "    max_means.append(max_mean/n_simulations)\n",
    "    \n",
    "    plt.plot(np.mean(total_means, axis=0), label=f\"{eps}\")\n",
    "\n",
    "y = np.mean(max_means, 0)\n",
    "plt.axline((0, y), slope=0, ls=\"--\", c=\"red\", label=\"Melhor possível\")\n",
    "plt.legend(loc=\"best\")\n",
    "plt.title(\"Recompensa Média de um Agente Epsilon-Guloso\")\n",
    "plt.xlabel(\"Steps\")\n",
    "plt.ylabel(\"Recompensa Média\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Parabéns piloto! Se tudo deu certo você conseguirá ver os resultados do seu modelo, que mostram como essa simples mudança consegue, após um certo número de iterações, melhores resultados que um mero agente guloso!\n",
    "\n",
    "Como comentário final, aqui vai uma sugestão: uma pequena mudança que você pode implementar no seu próprio notebook é tentar variar os chutes iniciais dos Q-valores (definidos no construtor do agente). Tente trocar esses valores por outros que você ache interessantes e re-execute o código; você pôde notar alguma diferença? Para te ajudar, uma escolha promissora que você pode fazer é colocar números altos em todos os chutes iniciais (essa técnica é conhecida como _valores iniciais otimistas_). Tente essa configuração e comente: qual poderia ser a vantagem dessa alteração?\n",
    "\n",
    "Agora, com seu modelo criado, você está pronto para faturar milhões no cassino de Monte Carlo, para depois gastar todo esse dinheiro em ***🍦 sorvetinhos 🍦 ***, obviamente.\n",
    "\n",
    "> Caso esteja interessado, você pode olhar também mais duas implementações que obtém resultados ainda melhores!\n",
    " - Bandits com [função softmax](https://github.com/turing-usp/Aprendizado-por-Reforco/tree/main/Aprendizado%20por%20Refor%C3%A7o%20Cl%C3%A1ssico/Bandits/SoftMax) que calculam um valor de *preferência* de uma ação.\n",
    " - Bandits com [limite de confiança superior](https://github.com/turing-usp/Aprendizado-por-Reforco/tree/main/Aprendizado%20por%20Refor%C3%A7o%20Cl%C3%A1ssico/Bandits/Limite%20de%20Confian%C3%A7a%20Superior) que utiliza um parâmetro de confiança para explorar e explotar.\n",
    " - Para um formalismo maior, você também pode ler o capítulo de Bandits no fantástico livro do [Sutton & Barton](https://web.archive.org/web/20210608124316/https://incompleteideas.net/book/RLbook2020.pdf) referência principal em Aprendizado por Reforço."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.4"
  },
  "orig_nbformat": 2
 },
 "nbformat": 4,
 "nbformat_minor": 2
}