instructor/tutorials/2.tips.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8bb7d0d0-2b7f-4e9e-8565-467dc5c6fd22",
   "metadata": {},
   "source": [
    "# General Tips on Prompting\n",
    "\n",
    "Before we get into some big applications of schema engineering I want to equip you with the tools for success. \n",
    "\n",
    "This notebook is to share some general advice when using prompts to get the most of your models. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a785c25-b08d-4ab4-bbd7-22e3b090c2ed",
   "metadata": {},
   "source": [
    "## Classification\n",
    "\n",
    "For classification we've found theres generally two methods of modeling.\n",
    "\n",
    "1. using Enums\n",
    "2. using Literals\n",
    "\n",
    "\n",
    "Use an enum in Python when you need a set of named constants that are related and you want to ensure type safety, readability, and prevent invalid values. Enums are helpful for grouping and iterating over these constants.\n",
    "\n",
    "Use literals when you have a small, unchanging set of values that you don't need to group or iterate over, and when type safety and preventing invalid values is less of a concern. Literals are simpler and more direct for basic, one-off values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "fdf5e1d9-31ad-4e8a-a55e-e2e70fff598d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'age': 17, 'name': 'Harry Potter', 'house': <House.Gryffindor: 'gryffindor'>}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from enum import Enum\n",
    "from pydantic import BaseModel, Field\n",
    "from typing_extensions import Literal\n",
    "\n",
    "import instructor\n",
    "from openai import OpenAI\n",
    "\n",
    "client = instructor.patch(OpenAI())\n",
    "\n",
    "# Tip: Do not use auto() as they cast to 1,2,3,4 \n",
    "class House(Enum):\n",
    "    Gryffindor = \"gryffindor\"\n",
    "    Hufflepuff = \"hufflepuff\"\n",
    "    Ravenclaw = \"ravenclaw\"\n",
    "    Slytherin = \"slytherin\"\n",
    "\n",
    "class Character(BaseModel):\n",
    "    age: int\n",
    "    name: str\n",
    "    house: House\n",
    "    \n",
    "resp = client.chat.completions.create(\n",
    "    model=\"gpt-4-1106-preview\",\n",
    "    messages=[\n",
    "        {\n",
    "            \"role\": \"user\", \n",
    "            \"content\": \"Harry Potter\"\n",
    "        }\n",
    "    ],\n",
    "    response_model=Character\n",
    ")\n",
    "resp.model_dump()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "03db160c-81e9-4373-bfec-7a107224b6dd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'age': 17, 'name': 'Harry Potter', 'house': 'Gryffindor'}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "class Character(BaseModel):\n",
    "    age: int\n",
    "    name: str\n",
    "    house: Literal[\"Gryffindor\", \"Hufflepuff\", \"Ravenclaw\", \"Slytherin\"]\n",
    "    \n",
    "resp = client.chat.completions.create(\n",
    "    model=\"gpt-4-1106-preview\",\n",
    "    messages=[\n",
    "        {\n",
    "            \"role\": \"user\", \n",
    "            \"content\": \"Harry Potter\"\n",
    "        }\n",
    "    ],\n",
    "    response_model=Character\n",
    ")\n",
    "resp.model_dump()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "803e0ce6-6e7e-4d86-a7a8-49ebaad0a40b",
   "metadata": {},
   "source": [
    "## Arbitrary long properties\n",
    "\n",
    "Often times there are long properties that you might want to extract from data that we can not specify in advanced. We can get around this by defining an arbitrary key value store like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "0e7938b8-4666-4df4-bd80-f53e8baf7550",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'age': 38,\n",
       " 'name': 'Severus Snape',\n",
       " 'house': 'Slytherin',\n",
       " 'properties': [{'key': 'position', 'value': 'Professor of Potions'},\n",
       "  {'key': 'loyalty', 'value': 'Dumbledore, Hogwarts'},\n",
       "  {'key': 'patronus', 'value': 'Doe'},\n",
       "  {'key': 'skill', 'value': 'Occlumency'}]}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from typing import List\n",
    "\n",
    "class Property(BaseModel):\n",
    "    key: str = Field(description=\"Must be snake case\")\n",
    "    value: str\n",
    "\n",
    "class Character(BaseModel):\n",
    "    age: int\n",
    "    name: str\n",
    "    house: Literal[\"Gryffindor\", \"Hufflepuff\", \"Ravenclaw\", \"Slytherin\"]\n",
    "    properties: List[Property]\n",
    "\n",
    "resp = client.chat.completions.create(\n",
    "    model=\"gpt-4-1106-preview\",\n",
    "    messages=[\n",
    "        {\n",
    "            \"role\": \"user\", \n",
    "            \"content\": \"Snape from Harry Potter\"\n",
    "        }\n",
    "    ],\n",
    "    response_model=Character\n",
    ")\n",
    "resp.model_dump()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3e62f68-a79f-4f65-9c1f-726e4e2d340a",
   "metadata": {},
   "source": [
    "## Limiting the length of lists \n",
    "\n",
    "In later chapters we'll talk about how to use validators to assert the length of lists but we can also use prompting tricks to enumerate values. Here we'll define a index to count the properties.\n",
    "\n",
    "In this following example instead of extraction we're going to work on generation instead."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "69a58d01-ab6f-41b6-bc0c-b0e55fdb6fe4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'age': 38,\n",
       " 'name': 'Severus Snape',\n",
       " 'house': 'Slytherin',\n",
       " 'properties': [{'index': '1',\n",
       "   'key': 'Occupation',\n",
       "   'value': 'Professor of Potions and later Defence Against the Dark Arts'},\n",
       "  {'index': '2',\n",
       "   'key': 'Allegiance',\n",
       "   'value': 'Order of the Phoenix, Hogwarts'},\n",
       "  {'index': '3', 'key': 'Patronus', 'value': 'Doe'},\n",
       "  {'index': '4',\n",
       "   'key': 'Skills',\n",
       "   'value': 'Potions master, Occlumens, Legilimens'},\n",
       "  {'index': '5', 'key': 'Portrayed by', 'value': 'Alan Rickman'}]}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "class Property(BaseModel):\n",
    "    index: str = Field(..., description=\"Monotonically increasing ID\")\n",
    "    key: str\n",
    "    value: str\n",
    "\n",
    "class Character(BaseModel):\n",
    "    age: int\n",
    "    name: str\n",
    "    house: Literal[\"Gryffindor\", \"Hufflepuff\", \"Ravenclaw\", \"Slytherin\"]\n",
    "    properties: List[Property] = Field(..., description=\"Numbered list of arbitrary extracted properties, should be exactly 5\")\n",
    "\n",
    "resp = client.chat.completions.create(\n",
    "    model=\"gpt-4-1106-preview\",\n",
    "    messages=[\n",
    "        {\n",
    "            \"role\": \"user\", \n",
    "            \"content\": \"Snape from Harry Potter\"\n",
    "        }\n",
    "    ],\n",
    "    response_model=Character\n",
    ")\n",
    "resp.model_dump()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bbc1d900-617a-4e4d-a401-6d10a5153cda",
   "metadata": {},
   "source": [
    "## Defining Multiple Entities\n",
    "\n",
    "Now that we see a single entity with many properties we can continue to nest them into many users"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "1f2a2b14-a956-4f96-90c9-e11ca04ab7d1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'users': [{'age': 38,\n",
       "   'name': 'Severus Snape',\n",
       "   'house': 'Slytherin',\n",
       "   'properties': [{'index': '1',\n",
       "     'key': 'Role',\n",
       "     'value': 'Professor of Potions, later Defence Against the Dark Arts, and head of Slytherin House'},\n",
       "    {'index': '2', 'key': 'Patronus', 'value': 'Doe'},\n",
       "    {'index': '3', 'key': 'Loyalty', 'value': 'Dumbledore, Harry, Hogwarts'},\n",
       "    {'index': '4',\n",
       "     'key': 'Special Skill',\n",
       "     'value': 'Occlumens, Potions Master'},\n",
       "    {'index': '5', 'key': 'Played by', 'value': 'Alan Rickman'}]},\n",
       "  {'age': 115,\n",
       "   'name': 'Albus Dumbledore',\n",
       "   'house': 'Gryffindor',\n",
       "   'properties': [{'index': '1',\n",
       "     'key': 'Role',\n",
       "     'value': 'Headmaster of Hogwarts'},\n",
       "    {'index': '2', 'key': 'Patronus', 'value': 'Phoenix'},\n",
       "    {'index': '3',\n",
       "     'key': 'Loyalty',\n",
       "     'value': 'Order of the Phoenix, Hogwarts'},\n",
       "    {'index': '4',\n",
       "     'key': 'Special Skill',\n",
       "     'value': 'Considered to be the most powerful wizard of his time'},\n",
       "    {'index': '5',\n",
       "     'key': 'Played by',\n",
       "     'value': 'Richard Harris (films 1-2), Michael Gambon (films 3-6)'}]}]}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "class Characters(BaseModel):\n",
    "    users: List[Character]\n",
    "\n",
    "resp = client.chat.completions.create(\n",
    "    model=\"gpt-4-1106-preview\",\n",
    "    messages=[\n",
    "        {\n",
    "            \"role\": \"user\", \n",
    "            \"content\": \"Snape and Dumbledore from Harry Potter\"\n",
    "        }\n",
    "    ],\n",
    "    response_model=Characters\n",
    ")\n",
    "resp.model_dump()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6ed3144-bde1-4033-9c94-a6926fa079d2",
   "metadata": {},
   "source": [
    "## Defining Relationships \n",
    "\n",
    "Now only can we define lists of users, with list of properties one of the more interesting things I've learned about prompting is that we can also easily define lists of references."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "6de8768e-b36a-4a51-9cf9-940d178552f6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'users': [{'id': 1, 'name': 'Harry Potter', 'friends': [2, 3, 4, 5]},\n",
       "  {'id': 2, 'name': 'Hermione Granger', 'friends': [1, 3, 4, 5]},\n",
       "  {'id': 3, 'name': 'Ron Weasley', 'friends': [1, 2, 4, 5]},\n",
       "  {'id': 4, 'name': 'Ginny Weasley', 'friends': [1, 2, 3, 5]},\n",
       "  {'id': 5, 'name': 'Neville Longbottom', 'friends': [1, 2, 3, 4]}]}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "class Character(BaseModel):\n",
    "    id: int\n",
    "    name: str\n",
    "    friends: List[int]\n",
    "\n",
    "class Characters(BaseModel):\n",
    "    users: List[Character]\n",
    "\n",
    "resp = client.chat.completions.create(\n",
    "    model=\"gpt-4-1106-preview\",\n",
    "    messages=[\n",
    "        {\n",
    "            \"role\": \"user\", \n",
    "            \"content\": \"The 5 kids from Harry Potter\"\n",
    "        }\n",
    "    ],\n",
    "    response_model=Characters\n",
    ")\n",
    "resp.model_dump()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "b31e10d7-ebd2-49b4-b2c4-20dd67ca135d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n",
       "<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n",
       " \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n",
       "<!-- Generated by graphviz version 9.0.0 (20230911.1827)\n",
       " -->\n",
       "<!-- Pages: 1 -->\n",
       "<svg width=\"335pt\" height=\"332pt\"\n",
       " viewBox=\"0.00 0.00 334.59 332.00\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n",
       "<g id=\"graph0\" class=\"graph\" transform=\"scale(1 1) rotate(0) translate(4 328)\">\n",
       "<polygon fill=\"white\" stroke=\"none\" points=\"-4,4 -4,-328 330.59,-328 330.59,4 -4,4\"/>\n",
       "<!-- 1 -->\n",
       "<g id=\"node1\" class=\"node\">\n",
       "<title>1</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"100.86\" cy=\"-306\" rx=\"56.98\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"100.86\" y=\"-300.95\" font-family=\"Times,serif\" font-size=\"14.00\">Harry Potter</text>\n",
       "</g>\n",
       "<!-- 2 -->\n",
       "<g id=\"node2\" class=\"node\">\n",
       "<title>2</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"155.86\" cy=\"-234\" rx=\"81.04\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"155.86\" y=\"-228.95\" font-family=\"Times,serif\" font-size=\"14.00\">Hermione Granger</text>\n",
       "</g>\n",
       "<!-- 1&#45;&gt;2 -->\n",
       "<g id=\"edge1\" class=\"edge\">\n",
       "<title>1&#45;&gt;2</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M114.17,-288.05C120.59,-279.89 128.43,-269.91 135.57,-260.82\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"138.3,-263 141.73,-252.98 132.8,-258.68 138.3,-263\"/>\n",
       "</g>\n",
       "<!-- 3 -->\n",
       "<g id=\"node3\" class=\"node\">\n",
       "<title>3</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"74.86\" cy=\"-162\" rx=\"60.05\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"74.86\" y=\"-156.95\" font-family=\"Times,serif\" font-size=\"14.00\">Ron Weasley</text>\n",
       "</g>\n",
       "<!-- 1&#45;&gt;3 -->\n",
       "<g id=\"edge2\" class=\"edge\">\n",
       "<title>1&#45;&gt;3</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M86.04,-288.17C78.39,-278.35 69.85,-265.31 65.86,-252 59.91,-232.21 62.58,-208.94 66.51,-191.16\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"69.88,-192.12 68.91,-181.57 63.09,-190.43 69.88,-192.12\"/>\n",
       "</g>\n",
       "<!-- 4 -->\n",
       "<g id=\"node4\" class=\"node\">\n",
       "<title>4</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"258.86\" cy=\"-90\" rx=\"67.73\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"258.86\" y=\"-84.95\" font-family=\"Times,serif\" font-size=\"14.00\">Ginny Weasley</text>\n",
       "</g>\n",
       "<!-- 1&#45;&gt;4 -->\n",
       "<g id=\"edge3\" class=\"edge\">\n",
       "<title>1&#45;&gt;4</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M154.52,-299.63C186.26,-293.47 224.35,-280.26 245.86,-252 274.95,-213.77 270.93,-154.61 265.08,-119.65\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"268.53,-119.05 263.27,-109.86 261.65,-120.33 268.53,-119.05\"/>\n",
       "</g>\n",
       "<!-- 5 -->\n",
       "<g id=\"node5\" class=\"node\">\n",
       "<title>5</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"140.86\" cy=\"-18\" rx=\"86.67\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"140.86\" y=\"-12.95\" font-family=\"Times,serif\" font-size=\"14.00\">Neville Longbottom</text>\n",
       "</g>\n",
       "<!-- 1&#45;&gt;5 -->\n",
       "<g id=\"edge4\" class=\"edge\">\n",
       "<title>1&#45;&gt;5</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M79.42,-289.02C44.45,-260.85 -18.64,-200.06 5.86,-144 25.53,-98.98 70.3,-62.93 102.9,-41.33\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"104.39,-44.54 110.9,-36.18 100.59,-38.65 104.39,-44.54\"/>\n",
       "</g>\n",
       "<!-- 2&#45;&gt;3 -->\n",
       "<g id=\"edge5\" class=\"edge\">\n",
       "<title>2&#45;&gt;3</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M136.25,-216.05C126.13,-207.31 113.61,-196.49 102.52,-186.9\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"105,-184.43 95.15,-180.54 100.43,-189.72 105,-184.43\"/>\n",
       "</g>\n",
       "<!-- 2&#45;&gt;4 -->\n",
       "<g id=\"edge6\" class=\"edge\">\n",
       "<title>2&#45;&gt;4</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M168.28,-215.87C186.16,-191.22 219.29,-145.54 240.15,-116.79\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"242.78,-119.12 245.82,-108.97 237.11,-115.01 242.78,-119.12\"/>\n",
       "</g>\n",
       "<!-- 2&#45;&gt;5 -->\n",
       "<g id=\"edge7\" class=\"edge\">\n",
       "<title>2&#45;&gt;5</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M154.65,-215.85C152.08,-179.14 146.02,-92.66 142.86,-47.53\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"146.36,-47.47 142.17,-37.74 139.38,-47.96 146.36,-47.47\"/>\n",
       "</g>\n",
       "<!-- 3&#45;&gt;4 -->\n",
       "<g id=\"edge8\" class=\"edge\">\n",
       "<title>3&#45;&gt;4</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M110.77,-147.34C139.21,-136.52 179.22,-121.3 210.48,-109.41\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"211.62,-112.72 219.72,-105.89 209.13,-106.17 211.62,-112.72\"/>\n",
       "</g>\n",
       "<!-- 3&#45;&gt;5 -->\n",
       "<g id=\"edge9\" class=\"edge\">\n",
       "<title>3&#45;&gt;5</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M82.82,-143.87C94.07,-119.67 114.73,-75.21 128.12,-46.39\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"131.19,-48.11 132.23,-37.56 124.84,-45.15 131.19,-48.11\"/>\n",
       "</g>\n",
       "<!-- 4&#45;&gt;5 -->\n",
       "<g id=\"edge10\" class=\"edge\">\n",
       "<title>4&#45;&gt;5</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M232.08,-73.12C216.16,-63.67 195.74,-51.56 178.25,-41.18\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"180.03,-38.17 169.65,-36.08 176.46,-44.19 180.03,-38.17\"/>\n",
       "</g>\n",
       "</g>\n",
       "</svg>\n"
      ],
      "text/plain": [
       "<graphviz.graphs.Digraph at 0x10f1ed610>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from graphviz import Digraph\n",
    "from IPython.display import display\n",
    "from typing import List\n",
    "\n",
    "dot = Digraph()\n",
    "\n",
    "# Create nodes for each user\n",
    "for user in resp.users:\n",
    "    dot.node(str(user.id), user.name)\n",
    "\n",
    "# Create edges for friends\n",
    "for user in resp.users:\n",
    "    for friend_id in user.friends:\n",
    "        # To avoid duplicating edges, only add an edge if the friend ID is greater than the user ID\n",
    "        if friend_id > user.id:\n",
    "            dot.edge(str(user.id), str(friend_id))\n",
    "            \n",
    "\n",
    "# Render the graph to a file\n",
    "display(dot)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "523b5797-71a5-4a96-a4b7-21280fb73015",
   "metadata": {},
   "source": [
    "With the tools we've discussed, we can find numerous real-world applications in production settings. These include extracting action items from transcripts, generating fake data, filling out forms, and creating objects that correspond to generative UI. These simple tricks will be highly useful."
   ]
  }
 ],
 "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.11.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}