04_openai_functions_langchain_pydantic.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### OpenAI Functions w/ LangChain and Pydantic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OpenAI's `gpt-3.5-turbo-0613` and `gpt-4-0613` models have been fine-tuned to interact with functions. These advancements enable the models to determine when and how a user-defined function should be invoked based on the context provided in the prompt. It is important to understand that the [Chat Completions API](https://platform.openai.com/docs/guides/gpt/chat-completions-api) does not actually execute the `function` itself. Instead, it generates a structured `JSON` response that developers can use to call the `function` within their codebase.\n",
    "\n",
    "To effectively use `function-calling`, it is required to first define the functions using a `JSON` schema, and then incorporate the `functions` and `function_call` properties in a [Chat Completions](https://platform.openai.com/docs/guides/gpt/chat-completions-api) request.\n",
    "\n",
    "This notebook illustrates how to combine [LangChain](https://www.langchain.com/) and [Pydantic](https://docs.pydantic.dev/) as an abstraction layer to facilitate the process of creating `OpenAI` `functions` and handling `JSON` formatting.\n",
    "\n",
    "For comprehensive information, refer to the [OpenAI Function Calling](https://platform.openai.com/docs/guides/gpt/function-calling) and [LangChain Expression Language (LCEL)](https://python.langchain.com/docs/expression_language/) guides."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1. Load OpenAI API Key"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "%pip install --upgrade openai langchain python-dotenv --quiet"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import openai\n",
    "\n",
    "from dotenv import load_dotenv, find_dotenv\n",
    "\n",
    "_ = load_dotenv(find_dotenv()) # read local .env file\n",
    "openai.api_key = os.environ['OPENAI_API_KEY']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### 2. Creating OpenAI Functions w/ LangChain and Pydantic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An `OpenAI` `function` is defined by three main parameters: `name`, `description`, and `parameters`. The `description` serves a pivotal role, guiding the model in deciding when and how to execute the function, making it crucial to provide a clear and concise explanation of the function's purpose.\n",
    "\n",
    "The `parameters` represent a `JSON` schema detailing the expected inputs that the function can accept.\n",
    "\n",
    "In this section, we will explore how to leverage `Pydantic` and `LangChain` to easily construct `OpenAI` function definitions that include these parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pydantic import BaseModel, Field\n",
    "from langchain.chat_models import ChatOpenAI\n",
    "from langchain.utils.openai_functions import convert_pydantic_to_openai_function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### 2.1 Define Pydantic Models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, we aim to enhance `OpenAI` with the functionality of a travel assistant. To achieve this, we need to invoke two key functions: `FlightSearch` and `EventSearch`. Our first step involves crafting the corresponding `Pydantic` models to define the structure of the data we need to extract from the prompt. In practice. the extracted data will be the arguments of those functions.\n",
    "\n",
    "[Pydantic Models](https://docs.pydantic.dev/latest/concepts/models/) are essentially classes that derive from `pydantic.BaseModel`, defining fields as type-annotated attributes. They bear a strong resemblance to `Python` dataclasses. However, they have been designed with subtle but significant differences that optimize various operations such as validation, serialization, and `JSON` schema generation. We will delve into these capabilities in the forthcoming step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "class FlightSearch(BaseModel):\n",
    "    \"\"\"To retrieve flight results, call this function with: the origin and destination airport codes, and the date of travel.\"\"\"\n",
    "    \n",
    "    origin: str = Field(..., description=\"origin airport code\", examples=[\"SFO\"])\n",
    "    destination: str = Field(..., description=\"destination airport code\", examples=[\"LAX\"])\n",
    "    date: str = Field(..., description=\"date to search flights\", examples=[\"2024-08-01\"])\n",
    "\n",
    "    async def run(self):\n",
    "        print(f\"Searching for flights from {self.origin} to {self.destination} on {self.date}\")\n",
    "        pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "class EventSearch(BaseModel):\n",
    "    \"\"\"Retrieve the top events in a city for a given date.\"\"\"\n",
    "    \n",
    "    location: str = Field(..., description=\"city name\", examples=[\"San Francisco\"])\n",
    "    date: str = Field(..., description=\"date to search events\", examples=[\"2024-08-01\"])\n",
    "    n: int = Field(..., description=\"number of events to return\", examples=[5])\n",
    "\n",
    "    async def run(self):\n",
    "        print(f\"Searching for {self.n} events in {self.location} on {self.date}\")\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### 2.2 Convert Pydantic Functions to OpenAI"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "travel_functions = [\n",
    "    convert_pydantic_to_openai_function(FlightSearch),\n",
    "    convert_pydantic_to_openai_function(EventSearch),\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's take a look at how our `Pydantic` models have been translated into `OpenAI` function definitions. It's worth noting that the `docstring` for each class is repurposed as the function's description. This underscores the significance of a well-written `docstring`. Additionally, the fields of the model serve as the foundation for defining the function's parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'name': 'FlightSearch',\n",
      " 'description': 'To retrieve flight results, call this function with: the '\n",
      "                'origin and destination airport codes, and the date of travel.',\n",
      " 'parameters': {'description': 'To retrieve flight results, call this function '\n",
      "                               'with: the origin and destination airport '\n",
      "                               'codes, and the date of travel.',\n",
      "                'properties': {'origin': {'description': 'origin airport code',\n",
      "                                          'examples': ['SFO'],\n",
      "                                          'title': 'Origin',\n",
      "                                          'type': 'string'},\n",
      "                               'destination': {'description': 'destination '\n",
      "                                                              'airport code',\n",
      "                                               'examples': ['LAX'],\n",
      "                                               'title': 'Destination',\n",
      "                                               'type': 'string'},\n",
      "                               'date': {'description': 'date to search flights',\n",
      "                                        'examples': ['2024-08-01'],\n",
      "                                        'title': 'Date',\n",
      "                                        'type': 'string'}},\n",
      "                'required': ['origin', 'destination', 'date'],\n",
      "                'title': 'FlightSearch',\n",
      "                'type': 'object'}}\n",
      "\n",
      "{'name': 'EventSearch',\n",
      " 'description': 'Retrieve the top events in a city for a given date.',\n",
      " 'parameters': {'description': 'Retrieve the top events in a city for a given '\n",
      "                               'date.',\n",
      "                'properties': {'location': {'description': 'city name',\n",
      "                                            'examples': ['San Francisco'],\n",
      "                                            'title': 'Location',\n",
      "                                            'type': 'string'},\n",
      "                               'date': {'description': 'date to search events',\n",
      "                                        'examples': ['2024-08-01'],\n",
      "                                        'title': 'Date',\n",
      "                                        'type': 'string'},\n",
      "                               'n': {'description': 'number of events to '\n",
      "                                                    'return',\n",
      "                                     'examples': [5],\n",
      "                                     'title': 'N',\n",
      "                                     'type': 'integer'}},\n",
      "                'required': ['location', 'date', 'n'],\n",
      "                'title': 'EventSearch',\n",
      "                'type': 'object'}}\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from pprint import pp\n",
    "\n",
    "for function in travel_functions:\n",
    "    pp(function)\n",
    "    print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3. Invoking OpenAI Functions w/ Langchain Expression Language"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This section illustrates how to compose the input and output types for our functions using the `langchain expression language (LCEL)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "from langchain.prompts import ChatPromptTemplate\n",
    "from langchain.output_parsers.openai_functions import JsonOutputFunctionsParser\n",
    "\n",
    "oai = ChatOpenAI(temperature=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### 3.1 Create a Chat Prompt Template"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A chat template serves as the foundation for context-aware prompts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "prompt = ChatPromptTemplate.from_messages([\n",
    "    (\"system\", \"You are a helpful travel assistant. Your task is to help users find flights and events.\"),\n",
    "    (\"user\", \"{query}\")\n",
    "])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### 3.2 Bind Functions with the Model"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " This allows `OpenAI` to intelligently select the appropriate function in response to the user's query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "openai_with_travel_functions = oai.bind(functions=travel_functions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### 3.3 Composing Input and Output Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Composition in `langchain expression language (LCEL)` follows the syntax of Linux pipes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "travel_assist_chain = prompt | openai_with_travel_functions "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### 3.4 Invoking Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have reached the stage where we can let `OpenAI` determine which of our functions should be invoked based on the context provided in the prompt."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note the following example where `OpenAI` follows the instructions provided in the `FlightSearch` description to autonomously parse the date from the user's query, and convert city names into airport codes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "AIMessage(content='', additional_kwargs={'function_call': {'arguments': '{\\n  \"origin\": \"SFO\",\\n  \"destination\": \"LAX\",\\n  \"date\": \"2024-01-22\"\\n}', 'name': 'FlightSearch'}})"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "travel_assist_chain.invoke({\"query\": \"search one-way flights from San Francisco to Los Angeles for 22nd January 2024\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, `OpenAI` identifies the city name, date, and event count as defined in the `EventSearch` function description."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "AIMessage(content='', additional_kwargs={'function_call': {'arguments': '{\\n  \"location\": \"Los Angeles\",\\n  \"date\": \"2024-01-25\",\\n  \"n\": 3\\n}', 'name': 'EventSearch'}})"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "travel_assist_chain.invoke({\"query\": \"what are the top three events scheduled in Los Angeles for 25th January 2024?\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### 3.5 Parsing Output as `JSON`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You might want to enhance this worflow to easily parse outputs into `JSON` format by composing also the `JsonOutputFunctionsParser()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "travel_assist_chain = prompt | openai_with_travel_functions | JsonOutputFunctionsParser()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This facilitates the retrieval of structured `JSON` responses in our examples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'origin': 'SFO', 'destination': 'LAX', 'date': '2024-01-22'}"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "travel_assist_chain.invoke({\"query\": \"search one-way flights from San Francisco to Los Angeles for 22nd January 2024\"})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'location': 'Los Angeles', 'date': '2024-01-25', 'n': 3}"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "travel_assist_chain.invoke({\"query\": \"what are the top three events scheduled in Los Angeles for 25th January 2024?\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}