docs/06_SemanticKernel/01_PlugIn_SemanticFunction_Inline.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 06 SemanticKernel | 01 Plugin - Semantic Function - Inline Definition\n",
    "\n",
    "## Semantic function \n",
    "\n",
    "This notebook focuses on the definition and usage of ***semantic functions*** which are defined inline (in code). A semantic function can be seen as encapsulation of LLM calls.\n",
    "\n",
    "Additional information: \n",
    "- [Overview Semantic Function](./README.md)\n",
    "- [Creating semantic functions inline (MS Learn)](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/plugins/semantic-functions/inline-semantic-functions?tabs=Csharp)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 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 Semantic Kernel instance\n",
    "\n",
    "An instance of Semantic Kernel can be created using the KernelBuilder object provided by the Semantic Kernel SDK. It acts as the centralized point for all .NET functionality that want to interact with Semantic Kernel functionality or concepts.\n",
    "\n",
    "It abstracts e.g., models from the OpenAI GPT family and can communicate with Azure OpenAI LLM instances as well as LLMs deployed on OpenAI. In the sample we use models deployed on Azure."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "#r \"nuget: Microsoft.SemanticKernel, 1.0.0-beta1\"\n",
    "#r \"nuget: DotNetEnv, 2.5.0\"\n",
    "\n",
    "using Azure; \n",
    "using DotNetEnv;\n",
    "using Microsoft.SemanticKernel;\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_AOAI_APIKEY\") ?? \"SKIT_AOAI_APIKEY not found\";\n",
    "string oAiEndpoint = Environment.GetEnvironmentVariable(\"SKIT_AOAI_ENDPOINT\") ?? \"SKIT_AOAI_ENDPOINT not found\";\n",
    "string chatCompletionDeploymentName = Environment.GetEnvironmentVariable(\"SKIT_CHATCOMPLETION_DEPLOYMENTNAME\") ?? \"SKIT_CHATCOMPLETION_DEPLOYMENTNAME not found\";\n",
    "\n",
    "IKernel kernel = new KernelBuilder()\n",
    "    .WithAzureChatCompletionService(\n",
    "        endpoint: oAiEndpoint, \n",
    "        apiKey: oAiApiKey,\n",
    "        deploymentName: chatCompletionDeploymentName)\n",
    "    .Build();\n",
    "\n",
    "Console.WriteLine($\"Semantic Kernel initialized...\");\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Expected output:\n",
    "\n",
    "```\n",
    "Installed Packages\n",
    "DotNetEnv, 2.5.0\n",
    "Microsoft.SemanticKernel, 1.0.0-beta1\n",
    "\n",
    "Semantic Kernel initialized...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Define and register Semantic inline function\n",
    "\n",
    "The kernel function `CreateSemanticFunction` can be used, beside other ways, to create and register a Semantic Function inline in c# code. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "using Microsoft.SemanticKernel.SemanticFunctions;\n",
    "using Microsoft.SemanticKernel.Connectors.AI.OpenAI;\n",
    "\n",
    "\n",
    "//Define semantic function inline\n",
    "string skPrompt = @\"Summarize the provided unstructured text in 3 easy to understand sentences. \n",
    "                    The sentences need to be short and provide the most important content of the provided text.\n",
    "                    Text to summarize: {{$input}}\";\n",
    "\n",
    "OpenAIRequestSettings openAIRequestSettings = new OpenAIRequestSettings\n",
    "{\n",
    "    MaxTokens = 100,\n",
    "    Temperature = 0.7,\n",
    "    TopP = 1,\n",
    "    FrequencyPenalty = 0,\n",
    "    PresencePenalty = 0,\n",
    "    StopSequences = new List<string> { \"\\n\" }\n",
    "};\n",
    "\n",
    "string plugInName = \"SemanticFunctions\";\n",
    "string functionName = \"SummarizeText\";\n",
    "\n",
    "kernel.CreateSemanticFunction(\n",
    "    promptTemplate: skPrompt, \n",
    "    functionName: functionName,\n",
    "    pluginName: plugInName, \n",
    "    requestSettings: openAIRequestSettings\n",
    ");\n",
    "\n",
    "Console.WriteLine($\"Semantic inline function 'SummarizeFunction' in plug-in 'SemanticFunctions' registered...\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Expected output:\n",
    "\n",
    "```\n",
    "Semantic inline function 'SummarizeFunction' in plug-in 'SemanticFunctions' registered...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Execute function as part of a skill\n",
    "\n",
    "The kernel function `RunAsync()` takes an `ISKFunction` object and input parameters to execute the function. `RunAsync()` provides multiple overloads to execute semantic functions, native functions, plans ([check here for details](05_Planner.ipynb)) etc. Using the kernel function `GetFunction()` allows retrieving an ISKFunction object just by by providing plugin name and function name.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    }
   },
   "outputs": [],
   "source": [
    "using System.IO;\n",
    "\n",
    "//Read text which should be summarized from file\n",
    "string assetsFolder = @\"../../assets\";\n",
    "string input = await File.ReadAllTextAsync(Path.Combine(assetsFolder,\"docs\",\"07_SemanticKernel\", \"aci_documentation.txt\"));\n",
    "\n",
    "ISKFunction sKFunction = kernel.Functions.GetFunction(plugInName, functionName);\n",
    "var kernelResult = await kernel.RunAsync(input, sKFunction);\n",
    "\n",
    "Console.WriteLine($\"Summary: {kernelResult.GetValue<string>().Substring(0,50)}...\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Expected output:\n",
    "\n",
    "```\n",
    "Summary: GitHub Actions is a fea...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next steps\n",
    "\n",
    "Now that a semantic function was was defined inline, registered as part of a Skill and executed using Semantic Kernel the next steps can be performed: \n",
    "\n",
    "- [Define, register and execute a semantic function from a file](./02_PlugIn_SemanticFunction_File.ipynb)\n",
    "- [Define, register and execute a native function (c#)](./03_PlugIn_NativeFunction.ipynb)\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
}