docs/07_AssistantsAPI/01_SimpleRun.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 07 Assistants API | 01 Assistant Run Thread\n",
    "\n",
    "## Azure Environment\n",
    "\n",
    "To execute the sample code Azure service specific information like endpoint, api key etc. is needed ([Details and instructions can be found here](../01_DemoEnvironment/01_Environment.ipynb))\n",
    "\n",
    "## Step 1: Create Assistants Client\n",
    "\n",
    "The AssistantsClient from the NuGet package Azure.AI.OpenAI.Assistants serves as an interface for developers to interact with OpenAI's Assistants API, facilitating the integration of AI-powered conversational agents into applications. Through this client, developers can send queries to AI assistants, receive responses, and manage conversation sessions, enabling seamless deployment of virtual assistants for various tasks such as customer support, information retrieval, and task automation.\n",
    "\n",
    "The AssistantsClient from Azure.AI.OpenAI.Assistants is a .NET client library that acts as the centralized point for all .NET functionality that want to interact with a deployed Azure OpenAI Large Language Model using the Assistants API. It provides all methods to access the OpenAI Assistants REST API for various tasks such as Assistant creation, Thread creation, Run creation etc.. \n",
    "\n",
    "The OpenAIClient can connect to LLMs supporting the Assistants API. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "#r \"nuget: Azure.AI.OpenAI.Assistants, 1.0.0-beta.3\"\n",
    "#r \"nuget: DotNetEnv, 2.5.0\"\n",
    "\n",
    "using Azure;\n",
    "using Azure.AI.OpenAI.Assistants;\n",
    "using DotNetEnv;\n",
    "\n",
    "//configuration file is created during environment creation\n",
    "//if you skipped the deployment just remove the code and provide values from your deployment\n",
    "static string _configurationFile = @\"../01_DemoEnvironment/conf/application.env\";\n",
    "Env.Load(_configurationFile);\n",
    "\n",
    "string oAiApiKey = Environment.GetEnvironmentVariable(\"SKIT_AOAI1106_APIKEY\") ?? \"SKIT_AOAI1106_APIKEY not found\";\n",
    "string oAiEndpoint = Environment.GetEnvironmentVariable(\"SKIT_AOAI1106_ENDPOINT\") ?? \"SKIT_AOAI1106_ENDPOINT not found\";\n",
    "string chatCompletionDeploymentName = Environment.GetEnvironmentVariable(\"SKIT_AOAI1106_DEPLOYMENTNAME\") ?? \"SKIT_AOAI1106_DEPLOYMENTNAME not found\";\n",
    "\n",
    "AzureKeyCredential azureKeyCredential = new AzureKeyCredential(oAiApiKey);\n",
    "AssistantsClient assistantsClient = new AssistantsClient(new Uri(oAiEndpoint), azureKeyCredential);\n",
    "\n",
    "Console.WriteLine($\"AssistantClient created...\");\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected output:\n",
    "\n",
    "```\n",
    "Installed Packages\n",
    "- Azure.AI.OpenAI.Assistants, 1.0.0-beta.3\n",
    "- DotNetEnv, 2.5.0\n",
    "\n",
    "AssistantClient created...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Create Assistant\n",
    "\n",
    "The following cell, demonstrate the creation of a basic Assistant. To create the Assistant the following information is provided: \n",
    "\n",
    "- Assistant name: A user friendly name for the to be created Assistant\n",
    "- Assistant instructions: The system message or system prompt which defines the Assistant.\n",
    "- Assistant description: A user friendly description of the to be created Assistant\n",
    "\n",
    "The `CreateAssistantAsync()` function call returns a unique id of the created Assistant which is used for all further interaction with the Assistant."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "string assistantName = \"SimpleAssistant\";\n",
    "string assistantInstruction = @\"\n",
    "    You help people find information and answer questions.\n",
    "\";\n",
    "string assistantDescription = \"Assistant to help answer questions based on LLM training data\";\n",
    "\n",
    "AssistantCreationOptions assistantCreationOptions; \n",
    "assistantCreationOptions = new AssistantCreationOptions(chatCompletionDeploymentName){\n",
    "    Name = assistantName,\n",
    "    Description = assistantDescription,\n",
    "    Instructions = assistantInstruction,\n",
    "}; \n",
    "\n",
    "Response<Assistant> responseAssistant = await assistantsClient.CreateAssistantAsync(assistantCreationOptions);\n",
    "\n",
    "Console.WriteLine($\"Assistant created: {responseAssistant.Value.Id}\");\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected outcome:\n",
    "\n",
    "```\n",
    "Assistant created: asst_xxxxxxxxxxxxxx\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Create Thread\n",
    "\n",
    "A Thread is used as container for user messages as well as LLM creates assistant messages. It stores the whole chat history within the server side LLM. The function call `CreateThreadAsync()` returns a unique Thread id which is used for all further interactions with the Thread."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "Response<AssistantThread> responseThread = await assistantsClient.CreateThreadAsync();\n",
    "\n",
    "Console.WriteLine($\"Thread created: {responseThread.Value.Id}\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected outcome:\n",
    "\n",
    "```\n",
    "Thread created: thread_xxxxxxxxxxxxxxxxxxxx\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Add Message to Thread\n",
    "\n",
    "As mentioned in step 3 LLM chat history is stored within a Thread. This means to provide a \"question\" to the LLM it needs to be stored within the created Thread. This is done calling the function `CreateMessageAsync()` where the user message, the Thread id as well as `MessageRole.User`is provided."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "string messageContent = \"What are the 3 biggest cloud provider based on regional presence?\";\n",
    "        \n",
    "Response<ThreadMessage> responseThreadMessage = await assistantsClient.CreateMessageAsync(\n",
    "    responseThread.Value.Id, \n",
    "    MessageRole.User, \n",
    "    messageContent\n",
    ");\n",
    "\n",
    "Console.WriteLine($\"Message created: {responseThreadMessage.Value.Id}\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected outcome:\n",
    "\n",
    "```\n",
    "Message created: msg_xxxxxxxxxxxxxxxxxx\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 5: Create Run\n",
    "\n",
    "After an Assistant and a Thread with user messages has been created both abstractions can be brought together in a so called RunThread to perform with the help of an LLM instance the completion. Which can be somehow described as \"answering the user question\". The Azure OpenAI instance to be used has been provided while creating the `AssistantsClient` object while the specific LLM deployment has been provided while creating the Assistants object. \n",
    "\n",
    "The function call `CreateRunAsync()` can be used to create the asynchronous Run. It provides a unique Run id which can be used to retrieve the state of the asynchronous execution. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "CreateRunOptions createRunOptions = new CreateRunOptions(responseAssistant.Value.Id); \n",
    "\n",
    "Response<ThreadRun> responseThreadRun = await assistantsClient.CreateRunAsync(\n",
    "    responseThread.Value.Id, \n",
    "    createRunOptions\n",
    "); \n",
    "\n",
    "Console.WriteLine($\"Run created: {responseThreadRun.Value.Id}\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected outcome:\n",
    "\n",
    "```\n",
    "Run created: run_xxxxxxxxxxxxxxxxxxxxxxxx\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 6: Check Status & Retrieve Message\n",
    "\n",
    "The sample cell waits for 5 seconds to allow some time for completion. It uses: \n",
    "\n",
    "- `GetRunAsync()`: to retrieve the current state of the Run\n",
    "- `GetMessagesAsync()`: to retrieve **all** messages from the Thread\n",
    "\n",
    "and shows the latest message from Thread which is the LLM completion\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "//Give some time to finalize Run\n",
    "System.Threading.Thread.Sleep(TimeSpan.FromSeconds(5));\n",
    "\n",
    "//Get Run status\n",
    "responseThreadRun = await assistantsClient.GetRunAsync(\n",
    "    responseThread.Value.Id,\n",
    "    responseThreadRun.Value.Id\n",
    "); \n",
    "\n",
    "Console.WriteLine($\"Run status: {responseThreadRun.Value.Status}\");\n",
    "\n",
    "//Wait for Run completion\n",
    "while(responseThreadRun.Value.Status != RunStatus.Completed) {\n",
    "    Console.WriteLine($\"Waiting for run completion...\");\n",
    "    System.Threading.Thread.Sleep(TimeSpan.FromSeconds(5));\n",
    "    responseThreadRun = await assistantsClient.GetRunAsync(\n",
    "        responseThread.Value.Id,\n",
    "        responseThreadRun.Value.Id\n",
    "    ); \n",
    "}\n",
    "\n",
    "//Get Run results\n",
    "Response<PageableList<ThreadMessage>> responseThreadMessages = await assistantsClient.GetMessagesAsync(\n",
    "    responseThread.Value.Id\n",
    ");\n",
    "\n",
    "//Get last assistnat created message\n",
    "ThreadMessage threadMessage = responseThreadMessages.Value.First<ThreadMessage>();\n",
    "\n",
    "Console.WriteLine($\"Message created by/at: {threadMessage.Role} - {threadMessage.CreatedAt}\");\n",
    "foreach(MessageContent messageContent in threadMessage.ContentItems)\n",
    "{\n",
    "    if (messageContent is MessageTextContent textItem)\n",
    "        Console.WriteLine($\"\\t Content: {textItem.Text}\");\n",
    "}\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected output:\n",
    "\n",
    "```\n",
    "Run status: completed\n",
    "Message created by/at: assistant - <some date>\n",
    "\t Content: As of my last knowledge update in April 2023, the three biggest cloud providers based on global regional presence are:\n",
    "     ...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 7: Clean up resources\n",
    "\n",
    "Assistant as well as Thread will be deleted. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "await assistantsClient.DeleteAssistantAsync(responseAssistant.Value.Id);\n",
    "await assistantsClient.DeleteThreadAsync(responseThread.Value.Id);\n",
    "\n",
    "Console.WriteLine($\"Assistant and Thread deleted...\");\n",
    "\n",
    "        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected output:\n",
    "\n",
    "```\n",
    "Assistant and Thread deleted ...\n",
    "```\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".NET (C#)",
   "language": "C#",
   "name": ".net-csharp"
  },
  "language_info": {
   "name": "polyglot-notebook"
  },
  "polyglot_notebook": {
   "kernelInfo": {
    "defaultKernelName": "csharp",
    "items": [
     {
      "aliases": [],
      "languageName": "csharp",
      "name": "csharp"
     }
    ]
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}