diff --git a/examples/Chained_function_calling_with_OpenAPI_spec.ipynb b/examples/Chained_function_calling_with_OpenAPI_spec.ipynb deleted file mode 100644 index 5d01a4f7e5..0000000000 --- a/examples/Chained_function_calling_with_OpenAPI_spec.ipynb +++ /dev/null @@ -1 +0,0 @@ -{"cells":[{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"8317718bcd8b475e9b336514241d679e","deepnote_cell_type":"text-cell-h1","formattedRanges":[]},"source":["# Chained function-calling using an OpenAPI specification"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"6f810c4e582c41a1bd3bdfc4263dee89","deepnote_cell_type":"text-cell-p","formattedRanges":[]},"source":["The majority of the tools we use over the internet are powered by RESTful APIs. Giving GPT the power to call them opens up a world of possibilities. This notebook demonstrates how GPTs can be used to intelligently call APIs. It leverages OpenAPI specifications and chained function calls. \n","\n","The [OpenAPI Specification (OAS)](https://swagger.io/specification/) is a universally accepted standard for describing the details of RESTful APIs in a format that machines can read and interpret. It enables both humans and computers to understand the capabilities of a service without direct access to the source code.\n","\n","This notebook is divided into two main sections: \n","\n","1. The first section involves converting a sample OpenAPI spec into a list of function definitions along with their expected arguments. This is done by parsing the OpenAPI spec and extracting the necessary information. \n","2. The second section involves taking the list of functions generated in the first step, along with a user instruction, and executing the functions sequentially. This is done by feeding the function definitions and the user instruction to the Chat completion API, which generates the JSON objects for function calls."]},{"cell_type":"code","execution_count":null,"metadata":{"cell_id":"bf983b3e199d4ea6a2718e58a141bd88","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":10617,"execution_start":1697419508239,"source_hash":"d6b9a6d3"},"outputs":[],"source":["!pip install -q jsonref\n","!pip install -q openai"]},{"cell_type":"code","execution_count":2,"metadata":{"cell_id":"12fb12583cc74b7c842a1b4656b94f47","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":10,"execution_start":1697419706563,"source_hash":"750280cb"},"outputs":[],"source":["import os\n","import json\n","import jsonref\n","import openai\n","import requests\n","from pprint import pp\n","\n","openai.api_key = os.environ[\"OPENAI_API_KEY\"]"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"76ae868e66b14cc48c9c447302ea268e","deepnote_cell_type":"text-cell-h2","formattedRanges":[]},"source":["## Converting OpenAPI Specifications into OpenAI Functions"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"9cf167d2d5fe4d7eadb69ba18db4a696","deepnote_cell_type":"text-cell-p","formattedRanges":[]},"source":["The example OpenAPI spec we use here was created using `gpt-4`. Here we will transform the spec into a set of function definitions that can be supplied to the chat completion API. The model, based on the provided user instructions, generates a JSON object containing the necessary arguments to call these functions.\n","\n","Here's a brief overview of the dialogue that led to its creation:\n","\n","```\n","User: Let's generate a fake Swagger openai.json for a \"froge\" character database.\n","Assistant: Provides a draft Swagger specification.\n","User: Use OpenAPI spec and also add endpoints for getting and updating the name for a froge and getting froge by name.\n","Assistant: Updates the specification to OpenAPI 3.0.0, adds endpoints for updating a Froge's name, and getting a Froge by name.\n","User: Could you also add a function name as operationId to it?\n","Assistant: Adds operationId for function names to each endpoint.\n","```\n","\n","Before we proceed, let's inspect this generated spec. OpenAPI specs include details about the API's endpoints, the operations they support, the parameters they accept, the requests they can handle, and the responses they return. The spec is defined in JSON format.\n","\n","The endpoints in the spec include operations for:\n","\n","- listing all \"froge\" characters\n","- creating a new \"froge\" character\n","- retrieving a \"froge\" character by ID\n","- deleting a \"froge\" character by ID\n","- updating a \"froge\" character's name by ID\n","- retrieving a \"froge\" character by name.\n","\n","Each operation in the spec has an operationId, a unique string used to identify an operation, which we will use as the function name when we parse the spec into function specifications. The spec also includes schemas that define the data types and structures of the parameters for each operation. These schemas will be used to validate the input parameters when we call the functions.\n","\n","You can see the schema here:\n"]},{"cell_type":"code","execution_count":3,"metadata":{"cell_id":"176efbfea4b546d28d9d9966342f286a","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":231,"execution_start":1697419710160,"source_hash":"1ce3848"},"outputs":[{"data":{"text/plain":["{'openapi': '3.0.0',\n"," 'info': {'version': '1.0.0',\n"," 'title': 'Froge Character API',\n"," 'description': 'An API for managing froge character data'},\n"," 'paths': {'/froge': {'get': {'summary': 'List all froge characters',\n"," 'operationId': 'listFroges',\n"," 'responses': {'200': {'description': 'A list of froge characters',\n"," 'content': {'application/json': {'schema': {'type': 'array',\n"," 'items': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'age': {'type': 'integer'}},\n"," 'required': ['name', 'age']}}}}}}},\n"," 'post': {'summary': 'Create a new froge character',\n"," 'operationId': 'createFroge',\n"," 'requestBody': {'required': True,\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'age': {'type': 'integer'}},\n"," 'required': ['name', 'age']}}}},\n"," 'responses': {'201': {'description': 'The froge character was created',\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'age': {'type': 'integer'}},\n"," 'required': ['name', 'age']}}}}}}},\n"," '/froge/{id}': {'get': {'summary': 'Retrieve a froge character by ID',\n"," 'operationId': 'getFrogeById',\n"," 'parameters': [{'name': 'id',\n"," 'in': 'path',\n"," 'required': True,\n"," 'schema': {'type': 'string'}}],\n"," 'responses': {'200': {'description': 'The froge character',\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'age': {'type': 'integer'}},\n"," 'required': ['name', 'age']}}}}}},\n"," 'delete': {'summary': 'Delete a froge character by ID',\n"," 'operationId': 'deleteFroge',\n"," 'parameters': [{'name': 'id',\n"," 'in': 'path',\n"," 'required': True,\n"," 'schema': {'type': 'string'}}],\n"," 'responses': {'204': {'description': 'The froge character was deleted'}}},\n"," 'patch': {'summary': \"Update a froge character's name by ID\",\n"," 'operationId': 'updateFrogeName',\n"," 'parameters': [{'name': 'id',\n"," 'in': 'path',\n"," 'required': True,\n"," 'schema': {'type': 'string'}}],\n"," 'requestBody': {'required': True,\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'name': {'type': 'string'}},\n"," 'required': ['name']}}}},\n"," 'responses': {'200': {'description': \"The froge character's name was updated\",\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'age': {'type': 'integer'}},\n"," 'required': ['name', 'age']}}}}}}},\n"," '/froge/name/{name}': {'get': {'summary': 'Retrieve a froge character by name',\n"," 'operationId': 'getFrogeByName',\n"," 'parameters': [{'name': 'name',\n"," 'in': 'path',\n"," 'required': True,\n"," 'schema': {'type': 'string'}}],\n"," 'responses': {'200': {'description': 'The froge character',\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'age': {'type': 'integer'}},\n"," 'required': ['name', 'age']}}}}}}}},\n"," 'components': {'schemas': {'Froge': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'age': {'type': 'integer'}},\n"," 'required': ['name', 'age']}}}}"]},"metadata":{},"output_type":"display_data"}],"source":["url = \"https://gist.githubusercontent.com/shyamal-anadkat/d44674a87778796222bdb8fa9158ad47/raw/030d173d53c55d806a93976705cf1c5f9e9c5240/frogeapi.json\"\n","openapi_spec = jsonref.loads(requests.get(url).content)\n","\n","display(openapi_spec)"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"e3e39ad4ac854299bf62b5f7bb1bef45","deepnote_cell_type":"text-cell-p","formattedRanges":[]},"source":["Now that we have a good understanding of the OpenAPI spec, we can proceed to parse it into function specifications.\n","\n","The main objective of `parse_functions` is to generate a list of functions, where each function is represented as a dictionary containing the following keys:\n","- 'name': This corresponds to the operation identifier of the API endpoint as defined in the OpenAPI specification.\n","- 'description': This is a brief description or summary of the function, providing an overview of what the function does.\n","- 'parameters': This is a schema that defines the expected input parameters for the function. It provides information about the type of each parameter, whether it is required or optional, and other related details.\n","\n","The output of this function is a list of such dictionaries, each representing a function defined in the OpenAPI specification."]},{"cell_type":"code","execution_count":4,"metadata":{"cell_id":"adbb17ca8a2a4fa2aa3f0213a0e211b6","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":333,"execution_start":1697419853135,"source_hash":"ad112cb1"},"outputs":[{"name":"stdout","output_type":"stream","text":["{'name': 'listFroges',\n"," 'description': 'List all froge characters',\n"," 'parameters': {'type': 'object', 'properties': {}}}\n","\n","{'name': 'createFroge',\n"," 'description': 'Create a new froge character',\n"," 'parameters': {'type': 'object',\n"," 'properties': {'requestBody': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'age': {'type': 'integer'}},\n"," 'required': ['name', 'age']}}}}\n","\n","{'name': 'getFrogeById',\n"," 'description': 'Retrieve a froge character by ID',\n"," 'parameters': {'type': 'object',\n"," 'properties': {'parameters': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'}}}}}}\n","\n","{'name': 'deleteFroge',\n"," 'description': 'Delete a froge character by ID',\n"," 'parameters': {'type': 'object',\n"," 'properties': {'parameters': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'}}}}}}\n","\n","{'name': 'updateFrogeName',\n"," 'description': \"Update a froge character's name by ID\",\n"," 'parameters': {'type': 'object',\n"," 'properties': {'requestBody': {'type': 'object',\n"," 'properties': {'name': {'type': 'string'}},\n"," 'required': ['name']},\n"," 'parameters': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'}}}}}}\n","\n","{'name': 'getFrogeByName',\n"," 'description': 'Retrieve a froge character by name',\n"," 'parameters': {'type': 'object',\n"," 'properties': {'parameters': {'type': 'object',\n"," 'properties': {'name': {'type': 'string'}}}}}}\n","\n"]}],"source":["def parse_functions(openapi_spec): \n","\n"," # Initialize an empty list to store the function specifications\n"," functions = []\n","\n"," # Iterate through the paths and methods specified in the OpenAPI spec\n"," for path, methods in openapi_spec[\"paths\"].items():\n"," for method, spec_with_ref in methods.items():\n"," # Replace any JSON references in the spec\n"," spec = jsonref.replace_refs(spec_with_ref)\n","\n"," # Extract the operationId which will be used as the function name\n"," function_name = spec.get(\"operationId\")\n"," \n"," # Gather the description, request body and parameters from the spec\n"," desc = spec.get(\"description\") or spec.get(\"summary\", \"\")\n"," req_body = spec.get(\"requestBody\", {}).get(\"content\", {}).get(\"application/json\", {}).get(\"schema\")\n"," params = spec.get(\"parameters\", [])\n"," \n"," # Initialize an empty schema\n"," schema = {\"type\": \"object\", \"properties\": {}}\n"," \n"," # If a request body is defined, add it to the schema\n"," if req_body:\n"," schema[\"properties\"][\"requestBody\"] = req_body\n"," \n"," # If parameters are defined, add them to the schema\n"," if params:\n"," param_properties = {param[\"name\"]: param[\"schema\"] for param in params if \"schema\" in param}\n"," schema[\"properties\"][\"parameters\"] = {\"type\": \"object\", \"properties\": param_properties}\n"," \n"," # Append the function specification to the list of functions\n"," functions.append({\"name\": function_name, \"description\": desc, \"parameters\": schema})\n","\n"," # Return the list of function specifications\n"," return functions\n","\n","# Parse the OpenAPI spec to get the function specifications\n","functions = parse_functions(openapi_spec)\n","\n","\n","for function in functions:\n"," pp(function)\n"," print()\n"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"f03f1aacdade4ed9a422797d3cf79fbb","deepnote_cell_type":"text-cell-h2","formattedRanges":[]},"source":["## Orchestrating Sequential Function Calls\n"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"08712696b5fd4cafac7b4b496ee67c5a","deepnote_cell_type":"text-cell-p","formattedRanges":[]},"source":["Now that we have these function definitions that we have derived from the OpenAPI spec, we can leverage them to orchestrate a series of calls to the `gpt-3.5-turbo-16k-0613` model. \n","\n","The model will determine the sequence of functions to call based on the user's input and the available function specifications. \n","\n","It's important to note that the chat completions API does not execute the function; instead, it generates the JSON that you can use to call the function in your own code."]},{"cell_type":"code","execution_count":5,"metadata":{"cell_id":"b8f7d0f157264694b958008f93aabf3f","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":6442,"execution_start":1697419907347,"source_hash":"ac9ad493"},"outputs":[{"name":"stdout","output_type":"stream","text":["\n","Function call #: 1\n","{'name': 'listFroges',\n"," 'arguments': '{}'}\n","\n","Function call #: 2\n","{'name': 'createFroge',\n"," 'arguments': '{\\n'\n"," ' \"requestBody\": {\\n'\n"," ' \"id\": \"1234\",\\n'\n"," ' \"name\": \"dalle3\",\\n'\n"," ' \"age\": 2\\n'\n"," ' }\\n'\n"," '}'}\n","\n","Function call #: 3\n","{'name': 'deleteFroge',\n"," 'arguments': '{\\n \"parameters\": {\\n \"id\": \"2456\"\\n }\\n}'}\n","\n","Message:\n","Actions:\n","1. Retrieved all the froges.\n","2. Created a new froge named \"dalle3\" with an age of 2 and a random numerical id.\n","3. Deleted the froge with id 2456.\n"]}],"source":["SYSTEM_PROMPT = \"\"\"\n","You are a helpful assistant. \n","Respond to the following prompt by using function_call and then summarize actions. \n","Ask for clarification if a user request is ambiguous.\n","\"\"\"\n","\n","USER_PROMPT = \"\"\"\n","Instruction: Get all the froges. \n","Then create a new 2-year old froge named dalle3, with a random numerical id. \n","Then delete froge with id 2456.\n","\"\"\"\n","\n","messages = [\n"," {\"role\": \"system\", \"content\": SYSTEM_PROMPT},\n"," {\"role\": \"user\", \"content\": USER_PROMPT}\n","]\n","\n","# Maximum number of chained calls allowed to prevent infinite or lengthy loops\n","MAX_CHAINED_CALLS = 5\n","\n","def get_openai_response(functions, messages):\n"," return openai.ChatCompletion.create(\n"," model='gpt-3.5-turbo-16k-0613',\n"," functions=functions,\n"," function_call=\"auto\", # \"auto\" means the model can pick between generating a message or calling a function.\n"," temperature=0,\n"," messages=messages\n"," )\n","\n","def process_chained_calls(functions, messages):\n"," stack = 0\n"," while stack < MAX_CHAINED_CALLS:\n"," response = get_openai_response(functions, messages)\n"," message = response[\"choices\"][0][\"message\"]\n"," \n"," if message.get(\"function_call\"):\n"," print(f\"\\nFunction call #: {stack + 1}\")\n"," pp(message[\"function_call\"])\n"," messages.append(message)\n"," stack += 1\n"," else:\n"," print(\"\\nMessage:\")\n"," print(message[\"content\"])\n"," break\n"," \n"," if stack >= MAX_CHAINED_CALLS:\n"," print(f\"Reached max chained function calls: {MAX_CHAINED_CALLS}\")\n","\n","process_chained_calls(functions, messages)"]},{"attachments":{},"cell_type":"markdown","metadata":{},"source":["\n","### Conclusion\n","\n","We have demonstrated how to convert OpenAPI specs into function specifications that can be given to GPT for it to intelligently call them, and shown how these can be chained together to perform complex operations.\n","\n","Possible extensions of this system could include handling more complex user instructions that require conditional logic or looping, integrating with real APIs to perform actual operations, and improving error handling and validation to ensure the instructions are feasible and the function calls are successful."]}],"metadata":{"deepnote":{},"deepnote_execution_queue":[],"deepnote_notebook_id":"84d101406ec34e36a9cf96d0c0c25a7d","kernelspec":{"display_name":"Python 3","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.9.13"},"orig_nbformat":2},"nbformat":4,"nbformat_minor":0} diff --git a/examples/Function_calling_with_an_OpenAPI_spec.ipynb b/examples/Function_calling_with_an_OpenAPI_spec.ipynb new file mode 100644 index 0000000000..2fc4662f57 --- /dev/null +++ b/examples/Function_calling_with_an_OpenAPI_spec.ipynb @@ -0,0 +1 @@ +{"cells":[{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"8317718bcd8b475e9b336514241d679e","deepnote_cell_type":"text-cell-h1","formattedRanges":[]},"source":["# Function-calling with an OpenAPI specification\n"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"6f810c4e582c41a1bd3bdfc4263dee89","deepnote_cell_type":"text-cell-p","formattedRanges":[]},"source":["Much of the internet is powered by RESTful APIs. Giving GPT the ability to call them opens up a world of possibilities. This notebook demonstrates how GPTs can be used to intelligently call APIs. It leverages OpenAPI specifications and chained function calls.\n","\n","The [OpenAPI Specification (OAS)](https://swagger.io/specification/) is a universally accepted standard for describing the details of RESTful APIs in a format that machines can read and interpret. It enables both humans and computers to understand the capabilities of a service, and it can be leveraged to show GPT how to call APIs.\n","\n","This notebook is divided into two main sections:\n","\n","1. How to convert a sample OpenAPI specification into a list of function definitions for the chat completions API.\n","2. How to use the chat completions API to intelligently invoke these functions based on user instructions.\n","\n","We recommend familiariazing yourself with [function-calling](./How_to_call_functions_with_chat_models.ipynb) before proceding.\n"]},{"cell_type":"code","execution_count":null,"metadata":{"cell_id":"bf983b3e199d4ea6a2718e58a141bd88","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":10617,"execution_start":1697419508239,"source_hash":"d6b9a6d3"},"outputs":[],"source":["!pip install -q jsonref # for resolving $ref's in the OpenAPI spec\n","!pip install -q openai"]},{"cell_type":"code","execution_count":2,"metadata":{"cell_id":"12fb12583cc74b7c842a1b4656b94f47","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":10,"execution_start":1697419706563,"source_hash":"750280cb"},"outputs":[],"source":["import os\n","import json\n","import jsonref\n","import openai\n","import requests\n","from pprint import pp\n","\n","openai.api_key = os.environ[\"OPENAI_API_KEY\"]"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"76ae868e66b14cc48c9c447302ea268e","deepnote_cell_type":"text-cell-h2","formattedRanges":[]},"source":["## How to convert an OpenAPI specification into function definitions\n"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"9cf167d2d5fe4d7eadb69ba18db4a696","deepnote_cell_type":"text-cell-p","formattedRanges":[]},"source":["The example OpenAPI spec we use here was created using `gpt-4`. We will transform this sample spec into a set of function definitions that can be supplied to the chat completion API. The model, based on the provided user instructions, generates a JSON object containing the necessary arguments to call these functions.\n","\n","Before we proceed, let's inspect this generated spec. OpenAPI specs include details about the API's endpoints, the operations they support, the parameters they accept, the requests they can handle, and the responses they return. The spec is defined in JSON format.\n","\n","The endpoints in the spec include operations for:\n","\n","- Listing all events\n","- Creating a new event\n","- Retrieving an event by ID\n","- Deleting an event by ID\n","- Updating an event name by ID\n","\n","Each operation in the spec has an `operationId`, which we will use as the function name when we parse the spec into function specifications. The spec also includes schemas that define the data types and structures of the parameters for each operation.\n","\n","You can see the schema here:\n"]},{"cell_type":"code","execution_count":3,"metadata":{"cell_id":"176efbfea4b546d28d9d9966342f286a","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":231,"execution_start":1697419710160,"source_hash":"1ce3848"},"outputs":[{"data":{"text/plain":["{'openapi': '3.0.0',\n"," 'info': {'version': '1.0.0',\n"," 'title': 'Event Management API',\n"," 'description': 'An API for managing event data'},\n"," 'paths': {'/events': {'get': {'summary': 'List all events',\n"," 'operationId': 'listEvents',\n"," 'responses': {'200': {'description': 'A list of events',\n"," 'content': {'application/json': {'schema': {'type': 'array',\n"," 'items': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'date': {'type': 'string', 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name', 'date', 'location']}}}}}}},\n"," 'post': {'summary': 'Create a new event',\n"," 'operationId': 'createEvent',\n"," 'requestBody': {'required': True,\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'date': {'type': 'string', 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name', 'date', 'location']}}}},\n"," 'responses': {'201': {'description': 'The event was created',\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'date': {'type': 'string', 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name', 'date', 'location']}}}}}}},\n"," '/events/{id}': {'get': {'summary': 'Retrieve an event by ID',\n"," 'operationId': 'getEventById',\n"," 'parameters': [{'name': 'id',\n"," 'in': 'path',\n"," 'required': True,\n"," 'schema': {'type': 'string'}}],\n"," 'responses': {'200': {'description': 'The event',\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'date': {'type': 'string', 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name', 'date', 'location']}}}}}},\n"," 'delete': {'summary': 'Delete an event by ID',\n"," 'operationId': 'deleteEvent',\n"," 'parameters': [{'name': 'id',\n"," 'in': 'path',\n"," 'required': True,\n"," 'schema': {'type': 'string'}}],\n"," 'responses': {'204': {'description': 'The event was deleted'}}},\n"," 'patch': {'summary': \"Update an event's details by ID\",\n"," 'operationId': 'updateEventDetails',\n"," 'parameters': [{'name': 'id',\n"," 'in': 'path',\n"," 'required': True,\n"," 'schema': {'type': 'string'}}],\n"," 'requestBody': {'required': True,\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'name': {'type': 'string'},\n"," 'date': {'type': 'string', 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name', 'date', 'location']}}}},\n"," 'responses': {'200': {'description': \"The event's details were updated\",\n"," 'content': {'application/json': {'schema': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'date': {'type': 'string', 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name', 'date', 'location']}}}}}}}},\n"," 'components': {'schemas': {'Event': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'date': {'type': 'string', 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name', 'date', 'location']}}}}"]},"metadata":{},"output_type":"display_data"}],"source":["with open('./data/example_events_openapi.json', 'r') as f:\n"," openapi_spec = jsonref.loads(f.read()) # it's important to load with jsonref, as explained below\n","\n","display(openapi_spec)"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"e3e39ad4ac854299bf62b5f7bb1bef45","deepnote_cell_type":"text-cell-p","formattedRanges":[]},"source":["Now that we have a good understanding of the OpenAPI spec, we can proceed to parse it into function specifications.\n","\n","We can write a simple `openapi_to_functions` function to generate a list of definitions, where each function is represented as a dictionary containing the following keys:\n","\n","- `name`: This corresponds to the operation identifier of the API endpoint as defined in the OpenAPI specification.\n","- `description`: This is a brief description or summary of the function, providing an overview of what the function does.\n","- `parameters`: This is a schema that defines the expected input parameters for the function. It provides information about the type of each parameter, whether it is required or optional, and other related details.\n","\n","For each of the endpoints defined in the schema, we need to do the following:\n","\n","1. **Resolve JSON references**: In an OpenAPI specification, it's common to use JSON references (also known as $ref) to avoid duplication. These references point to definitions that are used in multiple places. For example, if multiple API endpoints return the same object structure, that structure can be defined once and then referenced wherever it's needed. We need to resolve and replace these references with the content they point to.\n","\n","2. **Extract a name for the functions:** We will simply use the operationId as the function name. Alternatively, we could use the endpoint path and operation as the function name.\n","\n","3. **Extract a description and parameters:** We will iterate through the `description`, `summary`, `requestBody` and `parameters` fields to populate the function's description and parameters.\n","\n","Here's the implementation:\n"]},{"cell_type":"code","execution_count":4,"metadata":{"cell_id":"adbb17ca8a2a4fa2aa3f0213a0e211b6","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":333,"execution_start":1697419853135,"source_hash":"ad112cb1"},"outputs":[{"name":"stdout","output_type":"stream","text":["{'name': 'listEvents',\n"," 'description': 'List all events',\n"," 'parameters': {'type': 'object', 'properties': {}}}\n","\n","{'name': 'createEvent',\n"," 'description': 'Create a new event',\n"," 'parameters': {'type': 'object',\n"," 'properties': {'requestBody': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'},\n"," 'name': {'type': 'string'},\n"," 'date': {'type': 'string',\n"," 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name',\n"," 'date',\n"," 'location']}}}}\n","\n","{'name': 'getEventById',\n"," 'description': 'Retrieve an event by ID',\n"," 'parameters': {'type': 'object',\n"," 'properties': {'parameters': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'}}}}}}\n","\n","{'name': 'deleteEvent',\n"," 'description': 'Delete an event by ID',\n"," 'parameters': {'type': 'object',\n"," 'properties': {'parameters': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'}}}}}}\n","\n","{'name': 'updateEventDetails',\n"," 'description': \"Update an event's details by ID\",\n"," 'parameters': {'type': 'object',\n"," 'properties': {'requestBody': {'type': 'object',\n"," 'properties': {'name': {'type': 'string'},\n"," 'date': {'type': 'string',\n"," 'format': 'date-time'},\n"," 'location': {'type': 'string'}},\n"," 'required': ['name',\n"," 'date',\n"," 'location']},\n"," 'parameters': {'type': 'object',\n"," 'properties': {'id': {'type': 'string'}}}}}}\n","\n"]}],"source":["def openapi_to_functions(openapi_spec):\n"," functions = []\n","\n"," for path, methods in openapi_spec[\"paths\"].items():\n"," for method, spec_with_ref in methods.items():\n"," # 1. Resolve JSON references.\n"," spec = jsonref.replace_refs(spec_with_ref)\n","\n"," # 2. Extract a name for the functions.\n"," function_name = spec.get(\"operationId\")\n","\n"," # 3. Extract a description and parameters.\n"," desc = spec.get(\"description\") or spec.get(\"summary\", \"\")\n","\n"," schema = {\"type\": \"object\", \"properties\": {}}\n","\n"," req_body = (\n"," spec.get(\"requestBody\", {})\n"," .get(\"content\", {})\n"," .get(\"application/json\", {})\n"," .get(\"schema\")\n"," )\n"," if req_body:\n"," schema[\"properties\"][\"requestBody\"] = req_body\n","\n"," params = spec.get(\"parameters\", [])\n"," if params:\n"," param_properties = {\n"," param[\"name\"]: param[\"schema\"]\n"," for param in params\n"," if \"schema\" in param\n"," }\n"," schema[\"properties\"][\"parameters\"] = {\n"," \"type\": \"object\",\n"," \"properties\": param_properties,\n"," }\n","\n"," functions.append(\n"," {\"name\": function_name, \"description\": desc, \"parameters\": schema}\n"," )\n","\n"," return functions\n","\n","\n","functions = openapi_to_functions(openapi_spec)\n","\n","for function in functions:\n"," pp(function)\n"," print()"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"f03f1aacdade4ed9a422797d3cf79fbb","deepnote_cell_type":"text-cell-h2","formattedRanges":[]},"source":["## How to call these functions with GPT\n"]},{"attachments":{},"cell_type":"markdown","metadata":{"cell_id":"08712696b5fd4cafac7b4b496ee67c5a","deepnote_cell_type":"text-cell-p","formattedRanges":[]},"source":["Now that we have these function definitions, we can leverage GPT to call them intelligently based on user inputs.\n","\n","It's important to note that the chat completions API does not execute the function; instead, it generates the JSON that you can use to call the function in your own code.\n","\n","For more information on function-calling, refer to our dedicated [function-calling guide](./How_to_call_functions_with_chat_models.ipynb).\n"]},{"cell_type":"code","execution_count":14,"metadata":{"cell_id":"b8f7d0f157264694b958008f93aabf3f","deepnote_cell_type":"code","deepnote_to_be_reexecuted":false,"execution_millis":6442,"execution_start":1697419907347,"source_hash":"ac9ad493"},"outputs":[{"name":"stdout","output_type":"stream","text":["\n"," >> Function call #: 1\n","\n","{'name': 'listEvents',\n"," 'arguments': '{}'}\n","\n"," >> Function call #: 2\n","\n","{'name': 'createEvent',\n"," 'arguments': '{\\n'\n"," ' \"requestBody\": {\\n'\n"," ' \"id\": \"1234\",\\n'\n"," ' \"name\": \"AGI Party\",\\n'\n"," ' \"date\": \"2022-12-31\",\\n'\n"," ' \"location\": \"New York\"\\n'\n"," ' }\\n'\n"," '}'}\n","\n"," >> Function call #: 3\n","\n","{'name': 'deleteEvent',\n"," 'arguments': '{\\n \"parameters\": {\\n \"id\": \"2456\"\\n }\\n}'}\n","\n",">> Message:\n","\n","Actions summary:\n","1. Retrieved all the events successfully.\n","2. Created a new event named \"AGI Party\" with ID 1234, scheduled for December 31, 2022, in New York.\n","3. Deleted the event with ID 2456.\n"]}],"source":["SYSTEM_MESSAGE = \"\"\"\n","You are a helpful assistant. \n","Respond to the following prompt by using function_call and then summarize actions. \n","Ask for clarification if a user request is ambiguous.\n","\"\"\"\n","\n","# Maximum number of function calls allowed to prevent infinite or lengthy loops\n","MAX_CALLS = 5\n","\n","\n","def get_openai_response(functions, messages):\n"," return openai.ChatCompletion.create(\n"," model=\"gpt-3.5-turbo-16k-0613\",\n"," functions=functions,\n"," function_call=\"auto\", # \"auto\" means the model can pick between generating a message or calling a function.\n"," temperature=0,\n"," messages=messages,\n"," )\n","\n","\n","def process_user_instruction(functions, instruction):\n"," num_calls = 0\n"," messages = [\n"," {\"content\": SYSTEM_MESSAGE, \"role\": \"system\"},\n"," {\"content\": instruction, \"role\": \"user\"},\n"," ]\n","\n"," while num_calls < MAX_CALLS:\n"," response = get_openai_response(functions, messages)\n"," message = response[\"choices\"][0][\"message\"]\n","\n"," if message.get(\"function_call\"):\n"," print(f\"\\n>> Function call #: {num_calls + 1}\\n\")\n"," pp(message[\"function_call\"])\n"," messages.append(message)\n","\n"," # For the sake of this example, we'll simply add a message to simulate success.\n"," # Normally, you'd want to call the function here, and append the results to messages.\n"," messages.append(\n"," {\n"," \"role\": \"function\",\n"," \"content\": \"success\",\n"," \"name\": message[\"function_call\"][\"name\"],\n"," }\n"," )\n","\n"," num_calls += 1\n"," else:\n"," print(\"\\n>> Message:\\n\")\n"," print(message[\"content\"])\n"," break\n","\n"," if num_calls >= MAX_CALLS:\n"," print(f\"Reached max chained function calls: {MAX_CALLS}\")\n","\n","\n","USER_INSTRUCTION = \"\"\"\n","Instruction: Get all the events. \n","Then create a new event named AGI Party.\n","Then delete event with id 2456.\n","\"\"\"\n","\n","process_user_instruction(functions, USER_INSTRUCTION)"]},{"attachments":{},"cell_type":"markdown","metadata":{},"source":["### Conclusion\n","\n","We have demonstrated how to convert OpenAPI specs into function specifications that can be given to GPT for it to intelligently call them, and shown how these can be chained together to perform complex operations.\n","\n","Possible extensions of this system could include handling more complex user instructions that require conditional logic or looping, integrating with real APIs to perform actual operations, and improving error handling and validation to ensure the instructions are feasible and the function calls are successful.\n"]}],"metadata":{"deepnote":{},"deepnote_execution_queue":[],"deepnote_notebook_id":"84d101406ec34e36a9cf96d0c0c25a7d","kernelspec":{"display_name":"Python 3","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.9.13"},"orig_nbformat":2},"nbformat":4,"nbformat_minor":0} diff --git a/examples/data/example_events_openapi.json b/examples/data/example_events_openapi.json new file mode 100644 index 0000000000..49c10e8cde --- /dev/null +++ b/examples/data/example_events_openapi.json @@ -0,0 +1,184 @@ +{ + "openapi": "3.0.0", + "info": { + "version": "1.0.0", + "title": "Event Management API", + "description": "An API for managing event data" + }, + "paths": { + "/events": { + "get": { + "summary": "List all events", + "operationId": "listEvents", + "responses": { + "200": { + "description": "A list of events", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Event" + } + } + } + } + } + } + }, + "post": { + "summary": "Create a new event", + "operationId": "createEvent", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Event" + } + } + } + }, + "responses": { + "201": { + "description": "The event was created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Event" + } + } + } + } + } + } + }, + "/events/{id}": { + "get": { + "summary": "Retrieve an event by ID", + "operationId": "getEventById", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The event", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Event" + } + } + } + } + } + }, + "delete": { + "summary": "Delete an event by ID", + "operationId": "deleteEvent", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "The event was deleted" + } + } + }, + "patch": { + "summary": "Update an event's details by ID", + "operationId": "updateEventDetails", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "date": { + "type": "string", + "format": "date-time" + }, + "location": { + "type": "string" + } + }, + "required": [ + "name", + "date", + "location" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The event's details were updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Event" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Event": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "date": { + "type": "string", + "format": "date-time" + }, + "location": { + "type": "string" + } + }, + "required": [ + "name", + "date", + "location" + ] + } + } + } +} \ No newline at end of file diff --git a/registry.yaml b/registry.yaml index 805dde0b4f..8b3be30e64 100644 --- a/registry.yaml +++ b/registry.yaml @@ -1053,10 +1053,11 @@ tags: [] - title: Chained Function Calling with OpenAPI Spec - path: examples/Chained_function_calling_with_OpenAPI_spec.ipynb + path: examples/Function_calling_with_an_OpenAPI_spec.ipynb date: 2023-10-15 authors: - shyamal-anadkat + - simonpfish tags: - completions - functions