docs/01_AgentAI_Intro.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "3e67f200",
   "metadata": {},
   "source": [
    "# Magic Tools Introduction\n",
    "\n",
    "This library provides a simple, familiar and flexible way to combine Python functions with OpenAI functions. Magic Tools wraps the OpenAI API - making it easier to manage conversations and add AI to your Python applications.\n",
    "\n",
    "## Introduction\n",
    "\n",
    "The `magic_tools` library enables you to maintain the state of a conversation, invoke the model for generating responses, and parse the model's responses to generate function arguments that adhere to a given function specification. It also allows you to manage function specifications and execute functions whose inputs are model-generated. In this guide, we'll walk you through the library's various functionalities and demonstrate how to utilize them effectively.\n",
    "\n",
    "## What to expect\n",
    "\n",
    "We'll start by introducing the basic concepts: \n",
    "1. Tool\n",
    "1. Conversation\n",
    "2. An Function Specification\n",
    "\n",
    "Then, we will create a real-world application where we integrate model-generated arguments into function executions, demonstrating the interaction between the model and a SQLite database.\n",
    "\n",
    "## What is a Tool Decorator? <a name=\"tool-decorator\"></a>\n",
    "\n",
    "A tool decorator from the `magic_tools` library is a Python decorator. OpenAI Functions are specified with the following fields:\n",
    "\n",
    "- **Name:** The name of the function.\n",
    "- **Description:** A description of what the function does. The model will use this to decide when to call the function.\n",
    "- **Parameters:** The parameters object contains all of the input fields the function requires. These inputs can be of the following types: String, Number, Boolean, Object, Null, AnyOf. Refer to the [API reference docs](https://platform.openai.com/docs/api-reference/chat) for details.\n",
    "- **Required:** Which of the parameters are required to make a query. The rest will be treated as optional.\n",
    "\n",
    "These are auto-generated from a Python function when annotated with a `@tool`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "31425d9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# !pip install agentai"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "dab872c5",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The autoreload extension is already loaded. To reload it, use:\n",
      "  %reload_ext autoreload\n"
     ]
    }
   ],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "\n",
    "GPT_MODEL = \"gpt-3.5-turbo-0613\"\n",
    "EMBEDDING_MODEL = \"text-embedding-ada-002\"\n",
    "\n",
    "from agentai.api import chat_complete, chat_complete_execute_fn\n",
    "from agentai.annotations import tool, ToolRegistry\n",
    "from agentai.conversation import Conversation\n",
    "from agentai.sqlite_utils import DBUtils\n",
    "import json\n",
    "from typing import Any\n",
    "from enum import Enum\n",
    "import sqlite3\n",
    "\n",
    "\n",
    "weather_registry = ToolRegistry()  # Namespace for functions"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "29d4e02b",
   "metadata": {},
   "source": [
    "## Basic concepts\n",
    "\n",
    "Next we'll create a specification for a function called ```get_current_weather```. Later we'll pass this function specification to the API in order to generate function arguments that adhere to the specification.\n",
    "\n",
    "### Tool\n",
    "\n",
    "`@tool` is a magic decorator that wraps a Python function and generates a function specification using the function's docstring and type hints. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "d2e25069",
   "metadata": {},
   "outputs": [],
   "source": [
    "class TemperatureUnit(Enum):\n",
    "    celsius = \"celsius\"\n",
    "    fahrenheit = \"fahrenheit\"\n",
    "\n",
    "\n",
    "@tool(weather_registry)\n",
    "def get_current_weather(location: str, format: TemperatureUnit) -> str:\n",
    "    \"\"\"\n",
    "    Get the current weather\n",
    "\n",
    "    Args:\n",
    "        location (str): The city and state, e.g. San Francisco, CA\n",
    "        format (str): The temperature unit to use. Infer this from the users location.\n",
    "\n",
    "    Returns:\n",
    "        str: The current weather\n",
    "    \"\"\"\n",
    "    # Your function implementation goes here.\n",
    "    return f\"The weather in {location} is 72 degrees {format}\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "3acf660f",
   "metadata": {},
   "source": [
    "### Conversation\n",
    "\n",
    "Conversation is a class that maintains the state of a conversation. It is used to keep track of the conversation history. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "131d9a33",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<OpenAIObject at 0x121a42180> JSON: {\n",
       "  \"role\": \"assistant\",\n",
       "  \"content\": \"Sure, I can help you with that. Could you please provide me with your location?\"\n",
       "}"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "conversation = Conversation()\n",
    "conversation.add_message(\n",
    "    role=\"system\",\n",
    "    content=\"\"\"You are an AI assistant.\n",
    "- Follow the user's requirements carefully & to the letter.\n",
    "- First think step-by-step - describe your plan for what to do, written out in great detail.\n",
    "- Ask the user for any missing information.\n",
    "- Then decide about functions to use.\n",
    "- Minimize any other statements.\n",
    "- Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous\"\"\",\n",
    ")\n",
    "\n",
    "conversation.add_message(\"user\", \"what is the weather like today?\")\n",
    "\n",
    "completion = chat_complete(\n",
    "    conversation=conversation,\n",
    "    tool_registry=weather_registry,\n",
    "    model=GPT_MODEL,\n",
    "    function_call=\"auto\",\n",
    ")\n",
    "message = completion[\"choices\"][0][\"message\"]  # Get the first message\n",
    "conversation.add_message(role=message[\"role\"], content=message[\"content\"])\n",
    "message"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "854b6e61",
   "metadata": {},
   "outputs": [
    {
     "ename": "AttributeError",
     "evalue": "'function' object has no attribute 'execute_from_conversation'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m                            Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[20], line 11\u001b[0m\n\u001b[1;32m      3\u001b[0m completion \u001b[39m=\u001b[39m chat_complete(\n\u001b[1;32m      4\u001b[0m     conversation\u001b[39m=\u001b[39mconversation,\n\u001b[1;32m      5\u001b[0m     tool_registry\u001b[39m=\u001b[39mweather_registry,\n\u001b[1;32m      6\u001b[0m     model\u001b[39m=\u001b[39mGPT_MODEL,\n\u001b[1;32m      7\u001b[0m     function_call\u001b[39m=\u001b[39m{\u001b[39m\"\u001b[39m\u001b[39mname\u001b[39m\u001b[39m\"\u001b[39m: \u001b[39m\"\u001b[39m\u001b[39mget_current_weather\u001b[39m\u001b[39m\"\u001b[39m},\n\u001b[1;32m      8\u001b[0m )\n\u001b[1;32m     10\u001b[0m \u001b[39m# get_current_weather.execute_from_completion(completion)\u001b[39;00m\n\u001b[0;32m---> 11\u001b[0m get_current_weather\u001b[39m.\u001b[39;49mexecute_from_conversation(conversation)\n\u001b[1;32m     12\u001b[0m \u001b[39m# message = completion[\"choices\"][0][\"message\"]  # Get the first message\u001b[39;00m\n\u001b[1;32m     13\u001b[0m \u001b[39m# function_arguments = json.loads(message[\"function_call\"][\"arguments\"])\u001b[39;00m\n\u001b[1;32m     14\u001b[0m \u001b[39m# function_name = message[\"function_call\"][\"name\"]\u001b[39;00m\n\u001b[0;32m   (...)\u001b[0m\n\u001b[1;32m     19\u001b[0m \u001b[39m# )\u001b[39;00m\n\u001b[1;32m     20\u001b[0m \u001b[39m# conversation.display_conversation()\u001b[39;00m\n",
      "\u001b[0;31mAttributeError\u001b[0m: 'function' object has no attribute 'execute_from_conversation'"
     ]
    }
   ],
   "source": [
    "# Once the user provides the required information, the model can generate the function arguments\n",
    "conversation.add_message(\"user\", \"I'm in Bengaluru, India\")\n",
    "completion = chat_complete(\n",
    "    conversation=conversation,\n",
    "    tool_registry=weather_registry,\n",
    "    model=GPT_MODEL,\n",
    "    function_call={\"name\": \"get_current_weather\"},\n",
    ")\n",
    "\n",
    "# get_current_weather.execute_from_completion(completion)\n",
    "get_current_weather.execute_from_conversation(conversation)\n",
    "# message = completion[\"choices\"][0][\"message\"]  # Get the first message\n",
    "# function_arguments = json.loads(message[\"function_call\"][\"arguments\"])\n",
    "# function_name = message[\"function_call\"][\"name\"]\n",
    "# conversation.add_message(\n",
    "#     role=message[\"role\"],\n",
    "#     content=message[\"function_call\"][\"arguments\"],\n",
    "#     name=function_name,\n",
    "# )\n",
    "# conversation.display_conversation()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "b4482aee",
   "metadata": {},
   "source": [
    "## Integrating API calls with function execution\n",
    "\n",
    "In our next example, we'll demonstrate how to execute functions whose inputs are model-generated, and use this to implement an agent that can answer questions for us about a database. For simplicity we'll use the [Chinook sample database](https://www.sqlitetutorial.net/sqlite-sample-database/).\n",
    "\n",
    "*Note:* SQL generation use cases are high-risk in a production environment - models can be unreliable when generating consistent SQL syntax. A more reliable way to solve this problem may be to build a query generation API that takes the desired columns as input from the model."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "f7654fef",
   "metadata": {},
   "source": [
    "### Pull SQL Database Info\n",
    "\n",
    "First let's define some helpful utility functions to extract data from a SQLite database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "30f6b60e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Opened database successfully\n"
     ]
    }
   ],
   "source": [
    "conn = sqlite3.connect(\"../data/Chinook.db\")\n",
    "print(\"Opened database successfully\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "77e6e5ea",
   "metadata": {},
   "source": [
    "Now can use these utility functions to extract a representation of the database schema."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0c0104cd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Table: Album\n",
      "Columns: AlbumId, Title, ArtistId\n",
      "Table: Artist\n",
      "Columns: ArtistId, Name\n",
      "Table: Customer\n",
      "Columns: CustomerId, FirstName, LastName, Company, Address, City, State, Country, PostalCode, Phone, Fax, Email, SupportRepId\n",
      "Table: Employee\n",
      "Columns: EmployeeId, LastName, FirstName, Title, ReportsTo, BirthDate, HireDate, Address, City, State, Country, PostalCode, Phone, Fax, Email\n",
      "Table: Genre\n",
      "Columns: GenreId, Name\n",
      "Table: Invoice\n",
      "Columns: InvoiceId, CustomerId, InvoiceDate, BillingAddress, BillingCity, BillingState, BillingCountry, BillingPostalCode, Total\n",
      "Table: InvoiceLine\n",
      "Columns: InvoiceLineId, InvoiceId, TrackId, UnitPrice, Quantity\n",
      "Table: MediaType\n",
      "Columns: MediaTypeId, Name\n",
      "Table: Playlist\n",
      "Columns: PlaylistId, Name\n",
      "Table: PlaylistTrack\n",
      "Columns: PlaylistId, TrackId\n",
      "Table: Track\n",
      "Columns: TrackId, Name, AlbumId, MediaTypeId, GenreId, Composer, Milliseconds, Bytes, UnitPrice\n"
     ]
    }
   ],
   "source": [
    "db_registry = ToolRegistry()  # Namespace for functions\n",
    "database_string = DBUtils(conn).get_database_string()\n",
    "print(database_string)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "ae73c9ee",
   "metadata": {},
   "source": [
    "As before, we'll define a function specification for the function we'd like the API to generate arguments for. Notice that we are inserting the database schema into the function specification. This will be important for the model to know about."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0258813a",
   "metadata": {},
   "outputs": [],
   "source": [
    "@tool(registry=db_registry)\n",
    "def ask_database(query: str) -> Any:\n",
    "    \"\"\"\n",
    "    Use this function to answer user questions about music. Input should be a fully formed SQL query.\n",
    "\n",
    "    Args:\n",
    "        query (str):SQL query extracting info to answer the user's question.\n",
    "                    SQL should be written using this database schema:\n",
    "                    Table: Album\n",
    "                    Columns: AlbumId, Title, ArtistId\n",
    "                    Table: Artist\n",
    "                    Columns: ArtistId, Name\n",
    "                    Table: Customer\n",
    "                    Columns: CustomerId, FirstName, LastName, Company, Address, City, State, Country, PostalCode, Phone, Fax, Email, SupportRepId\n",
    "                    Table: Employee\n",
    "                    Columns: EmployeeId, LastName, FirstName, Title, ReportsTo, BirthDate, HireDate, Address, City, State, Country, PostalCode, Phone, Fax, Email\n",
    "                    Table: Genre\n",
    "                    Columns: GenreId, Name\n",
    "                    Table: Invoice\n",
    "                    Columns: InvoiceId, CustomerId, InvoiceDate, BillingAddress, BillingCity, BillingState, BillingCountry, BillingPostalCode, Total\n",
    "                    Table: InvoiceLine\n",
    "                    Columns: InvoiceLineId, InvoiceId, TrackId, UnitPrice, Quantity\n",
    "                    Table: MediaType\n",
    "                    Columns: MediaTypeId, Name\n",
    "                    Table: Playlist\n",
    "                    Columns: PlaylistId, Name\n",
    "                    Table: PlaylistTrack\n",
    "                    Columns: PlaylistId, TrackId\n",
    "                    Table: Track\n",
    "                    Columns: TrackId, Name, AlbumId, MediaTypeId, GenreId, Composer, Milliseconds, Bytes, UnitPrice\n",
    "\n",
    "                    IMPORTANT: Please return a fixed SQL in PLAIN TEXT.\n",
    "                    Your response should consist of ONLY the SQL query.\n",
    "    \"\"\"\n",
    "    results = conn.execute(query).fetchall()\n",
    "    return results"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "da08c121",
   "metadata": {},
   "source": [
    "### SQL Execution\n",
    "\n",
    "Now let's implement the function that the agent will use to query the database. We also need to implement utilities to integrate the calls to the Chat Completions API with the function it is calling."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "38c55083",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[('Iron Maiden', 213), ('U2', 135), ('Led Zeppelin', 114), ('Metallica', 112), ('Lost', 92)]\n"
     ]
    }
   ],
   "source": [
    "agent_system_message = \"\"\"You are ChinookGPT, a helpful assistant who gets answers to user questions from the Chinook Music Database.\n",
    "If you need more information, ask for it. When writing SQL, use explicit table_name.column_name notation.\n",
    "Provide as many details (columns!) as possible to your users.\n",
    "Begin!\"\"\"\n",
    "\n",
    "sql_conversation = Conversation()\n",
    "sql_conversation.add_message(role=\"system\", content=agent_system_message)\n",
    "sql_conversation.add_message(role=\"user\", content=\"Hi, who are the top 5 artists by number of tracks\")\n",
    "results, function_arguments, executed_function = chat_complete_execute_fn(\n",
    "    conversation=sql_conversation,\n",
    "    tool_registry=db_registry,\n",
    "    model=GPT_MODEL,\n",
    ")\n",
    "print(results)\n",
    "\n",
    "sql_conversation.add_message(role=\"assistant\", content=str(results), name=executed_function.__name__)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28471ddc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[31msystem: You are ChinookGPT, a helpful assistant who gets answers to user questions from the Chinook Music Database.\n",
      "If you need more information, ask for it. When writing SQL, use explicit table_name.column_name notation.\n",
      "Provide as many details (columns!) as possible to your users.\n",
      "Begin!\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[32muser: Hi, who are the top 5 artists by number of tracks\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[34massistant: [('Iron Maiden', 213), ('U2', 135), ('Led Zeppelin', 114), ('Metallica', 112), ('Lost', 92)]\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[34massistant: The top 5 artists by the number of tracks are:\n",
      "1. Iron Maiden - 213 tracks\n",
      "2. U2 - 135 tracks\n",
      "3. Led Zeppelin - 114 tracks\n",
      "4. Metallica - 112 tracks\n",
      "5. Lost - 92 tracks\n",
      "\n",
      "\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "# Preparing the User message\n",
    "completion = chat_complete(\n",
    "    conversation=sql_conversation,\n",
    "    tool_registry=db_registry,\n",
    "    model=GPT_MODEL,\n",
    "    function_call=False,\n",
    ")\n",
    "message = completion[\"choices\"][0][\"message\"]  # Get the first message\n",
    "sql_conversation.add_message(message[\"role\"], message[\"content\"])\n",
    "sql_conversation.display_conversation()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "710481dc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'query': 'SELECT AlbumId, Title, COUNT(TrackId) AS TrackCount FROM Album JOIN Track USING(AlbumId) GROUP BY AlbumId ORDER BY TrackCount DESC LIMIT 1'}\n",
      "\u001b[31msystem: You are ChinookGPT, a helpful assistant who gets answers to user questions from the Chinook Music Database.\n",
      "If you need more information, ask for it. When writing SQL, use explicit table_name.column_name notation.\n",
      "Provide as many details (columns!) as possible to your users.\n",
      "Begin!\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[32muser: Hi, who are the top 5 artists by number of tracks\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[34massistant: [('Iron Maiden', 213), ('U2', 135), ('Led Zeppelin', 114), ('Metallica', 112), ('Lost', 92)]\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[34massistant: The top 5 artists by the number of tracks are:\n",
      "1. Iron Maiden - 213 tracks\n",
      "2. U2 - 135 tracks\n",
      "3. Led Zeppelin - 114 tracks\n",
      "4. Metallica - 112 tracks\n",
      "5. Lost - 92 tracks\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[32muser: What is the name of the album with the most tracks\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[34massistant: [(141, 'Greatest Hits', 57)]\n",
      "\n",
      "\u001b[0m\n",
      "\u001b[34massistant: The album with the most tracks is \"Greatest Hits\" with 57 tracks.\n",
      "\n",
      "\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "sql_conversation.add_message(\"user\", \"What is the name of the album with the most tracks\")\n",
    "results, function_arguments, executed_function = chat_complete_execute_fn(\n",
    "    conversation=sql_conversation,\n",
    "    tool_registry=db_registry,\n",
    "    model=GPT_MODEL,\n",
    ")\n",
    "print(function_arguments)\n",
    "sql_conversation.add_message(role=\"assistant\", content=str(results), name=executed_function.__name__)\n",
    "\n",
    "# Preparing the User message\n",
    "completion = chat_complete(\n",
    "    conversation=sql_conversation,\n",
    "    tool_registry=db_registry,\n",
    "    model=GPT_MODEL,\n",
    "    function_call=False,\n",
    ")\n",
    "message = completion[\"choices\"][0][\"message\"]  # Get the first message\n",
    "sql_conversation.add_message(message[\"role\"], message[\"content\"])\n",
    "sql_conversation.display_conversation()"
   ]
  }
 ],
 "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.8.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}