diff --git a/FEATURE_MATRIX.md b/FEATURE_MATRIX.md index a4459402fb38..ce8dedf35079 100644 --- a/FEATURE_MATRIX.md +++ b/FEATURE_MATRIX.md @@ -1,5 +1,5 @@ -# Semantic Kernel Feature Matrix by Language +# Semantic Kernel feature matrix by language -This document can be found on the Semantic Kernel Documentation site on [Supported Languages.](https://learn.microsoft.com/en-us/semantic-kernel/get-started/supported-languages) +This document has been moved to the Semantic Kernel Documentation site. You can find it by navigating to the [Supported Languages](https://learn.microsoft.com/en-us/semantic-kernel/get-started/supported-languages) page. -To make an update on the page, file a PR on the [docs repo.](https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/semantic-kernel/get-started/supported-languages.md) \ No newline at end of file +To make an update on the page, file a PR on the [docs repo.](https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/semantic-kernel/get-started/supported-languages.md) diff --git a/README.md b/README.md index 327f5cedb9cf..fdabd29538c9 100644 --- a/README.md +++ b/README.md @@ -22,17 +22,17 @@ code **native functions**, and **embeddings-based memory** unlocking new potenti and adding value to applications with AI. SK supports -[prompt templating](docs/PROMPT_TEMPLATE_LANGUAGE.md), function +[prompt templating](https://learn.microsoft.com/en-us/semantic-kernel/prompt-engineering/prompt-template-syntax), function chaining, -[vectorized memory](docs/EMBEDDINGS.md), and -[intelligent planning](docs/PLANNERS.md) +[vectorized memory](https://learn.microsoft.com/en-us/semantic-kernel/memories/embeddings), and +[intelligent planning](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/planner) capabilities out of the box. Semantic Kernel supports and encapsulates several design patterns from the latest -in AI research, such that developers can infuse their applications with [plugins](https://learn.microsoft.com/semantic-kernel/howto/) like [prompt](docs/PROMPT_TEMPLATE_LANGUAGE.md) -chaining, recursive reasoning, summarization, zero/few-shot learning, contextual -memory, long-term memory, [embeddings](docs/EMBEDDINGS.md), semantic indexing, -[planning](docs/PLANNERS.md), retrieval-augmented generation and accessing external +in AI research, such that developers can infuse their applications with [plugins](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/plugins) like [prompt +chaining](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/chaining-functions), recursive reasoning, summarization, zero/few-shot learning, contextual +memory, long-term memory, [embeddings](https://learn.microsoft.com/en-us/semantic-kernel/memories/embeddings), semantic indexing, +[planning](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/planner), retrieval-augmented generation and accessing external knowledge stores as well as your own data. By joining the SK community, you can build AI-first apps faster and have a front-row @@ -85,7 +85,6 @@ and to run one of the C# or Python console applications/scripts: 4. Copy the code from [here](python/README.md) into the `hello-world.py` script. 5. Run the python script. - ## Sample apps ⚡ The repository includes some sample applications, with a React frontend and @@ -95,7 +94,7 @@ Follow the links for more information and instructions about running these apps. | | | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| [Simple chat summary](samples/apps/chat-summary-webapp-react/README.md) | Use ready-to-use plugins and get plugins into your app easily. | +| [Simple chat summary](samples/apps/chat-summary-webapp-react/README.md) | Use ready-to-use plugins and get plugins into your app easily. | | [Book creator](samples/apps/book-creator-webapp-react/README.md) | Use planner to deconstruct a complex goal and envision using the planner in your app. | | [Authentication and APIs](samples/apps/auth-api-webapp-react/README.md) | Use a basic connector pattern to authenticate and connect to an API and imagine integrating external data into your app's LLM AI. | | [GitHub repository Q&A](samples/apps/github-qna-webapp-react/README.md) | Use embeddings and memory to store recent data and allow you to query against it. | @@ -120,8 +119,9 @@ Getting Semantic Kernel deployed to Azure as web app service is easy with one-cl For a more hands-on overview, you can also check out the C# and Python Jupyter notebooks, starting from here: -* [Getting Started with C# notebook](samples/notebooks/dotnet/00-getting-started.ipynb) -* [Getting Started with Python notebook](samples/notebooks/python/00-getting-started.ipynb) + +- [Getting Started with C# notebook](samples/notebooks/dotnet/00-getting-started.ipynb) +- [Getting Started with Python notebook](samples/notebooks/python/00-getting-started.ipynb) **Requirements:** C# notebooks require [.NET 7](https://dotnet.microsoft.com/download) and the VS Code [Polyglot extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode). diff --git a/docs/PLANNERS.md b/docs/PLANNERS.md index b5a8689f6baf..9ff63664adca 100644 --- a/docs/PLANNERS.md +++ b/docs/PLANNERS.md @@ -1,41 +1,5 @@ -# SK Planner +# Semantic Kernel planner -![image](https://user-images.githubusercontent.com/371009/221739773-cf43522f-c1e4-42f2-b73d-5ba84e21febb.png) +This document has been moved to the Semantic Kernel Documentation site. You can find it by navigating to the [Automatically orchestrate AI with planner](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/planner) page. -Planners work backwards from a goal that’s provided from a user's ASK. - -![image](https://user-images.githubusercontent.com/371009/221742094-2920c697-7494-4a7b-a894-4f24fb90965f.png) - -We call this approach "goal-oriented AI" — harking back to the early days of AI -when researchers aspired for computers to beat the world's reigning chess champion. -That grand goal was achieved eventually, but with the unusual competence of new -LLM AI models to provide step-by-step directions for practically any goal can be -attainable when the right -[skills](SKILLS.md) -are available. - -Because planners have access to either a pre-defined library of pre-made skills -and/or a dynamically defined set of skills, they are able to fulfill an -[ASK](GLOSSARY.md) -with confidence. In addition, planners call upon memories to best situate the -ASK's context and connectors to call APIs and to leverage other external -capabilities. - -# What is the value of "goal-oriented" AI? - -The *[Jobs To Be Done (JTBD)](https://hbr.org/2016/09/know-your-customers-jobs-to-be-done)* -movement has popularized a shift in moving from work outputs to work outcomes. Instead -of focusing on the features or the functions of a product or a service, the JTBD -approach emphasizes the goals and desires of the customer or the user, and the value -or the benefit that they seek or expect from using the product or service. By -understanding and articulating the JTBD of the customer or the user, a product or -service can be designed and delivered more effectively. You just need to make the -right ASK that isn't just "turn on the lights" and instead a more challenging goal -like "I want a job promotion." - -# What if Planners need a Skill that's unavailable? - -Planners will operate within the skills they have available. In the event that a -desired skill does not exist, some planners can suggest you to create the skill. -Or, depending upon the level of complexity, the kernel can help you write the -missing skill. \ No newline at end of file +To make an update on the page, file a PR on the [docs repo.](https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/semantic-kernel/ai-orchestration/planner.md) diff --git a/docs/PROMPT_TEMPLATE_LANGUAGE.md b/docs/PROMPT_TEMPLATE_LANGUAGE.md index 4b829f14cf20..4a5c00784cdc 100644 --- a/docs/PROMPT_TEMPLATE_LANGUAGE.md +++ b/docs/PROMPT_TEMPLATE_LANGUAGE.md @@ -1,252 +1,5 @@ -Prompts are the inputs or queries that a user or a program gives to a Large Learning Model ([LLM](https://en.wikipedia.org/wiki/Wikipedia:Large_language_models)) AI, -in order to elicit a specific response from the model. - -Prompts can be natural -language sentences or questions, or code snippets or commands, or any combination -of text or code, depending on the domain and the task. - -Prompts can also be nested -or chained, meaning that the output of one prompt can be used as the input of another -prompt, creating more complex and dynamic interactions with the model. - # SK Prompt Template Syntax -The Semantic Kernel prompt template language is a simple and powerful way to -define and compose AI -[functions](GLOSSARY.md) -**using plain text**. -You can use it to create natural language prompts, generate responses, extract -information, **invoke other prompts** or perform any other task that can be -expressed with text. - -The language supports three basic features that allow you to (**#1**) include -variables, (**#2**) call external functions, and (**#3**) pass parameters to functions. - -It is not required to write any code or import any external libraries, just use the -curly braces `{{...}}` to embed expressions in your prompts. -Semantic Kernel will parse your template and execute the logic behind it. -This way, you can easily integrate AI into your apps with minimal effort and -maximum flexibility. - -## Variables - -To include a variable value in your text, use the `{{$variableName}}` syntax. -For example, if you have a variable called `name` that holds the user's name, -you can write: - - Hello {{$name}}, welcome to Semantic Kernel! - -This will produce a greeting with the user's name. - -Spaces are ignored, so if you find it more readable, you can also write: - - Hello {{ $name }}, welcome to Semantic Kernel! - -## Function calls - -To call an external function and embed the result in your text, use the -`{{namespace.functionName}}` syntax. -For example, if you have a function called `weather.getForecast` that returns -the weather forecast for a given location, you can write: - - The weather today is {{weather.getForecast}}. - -This will produce a sentence with the weather forecast for the default location -stored in the `input` variable. -The `input` variable is set automatically by the kernel when invoking a function. -For instance, the code above is equivalent to: - - The weather today is {{weather.getForecast $input}}. - -## Function parameters - -To call an external function and pass a parameter to it, use the -`{{namespace.functionName $varName}}` and -`{{namespace.functionName "value"}}` syntax. -For example, if you want to pass a different input to the weather forecast -function, you can write: - - The weather today in {{$city}} is {{weather.getForecast $city}}. - The weather today in Schio is {{weather.getForecast "Schio"}}. - -This will produce two sentences with the weather forecast for two different -locations, using the city stored in the _`city`_ **variable** and the _"Schio"_ -location **value** hardcoded in the prompt template. - -## Design Principles - -The template language is designed to be simple and fast to render, allowing -to create functions with a simple text editor, using natural language, reducing -special syntax to a minimum, and minimizing edge cases. - -The template language uses the **«`$`»** symbol on purpose, to clearly distinguish -between function calls that retrieve content executing some code, from variables, -which are replaced with data from the local temporary memory. - -Branching features such as _"if"_, _"for"_, and code blocks are not part of SK's -template language. This reflects SK's design principle of using natural language -as much as possible, with a clear separation from traditional programming code. - -By using a simple language, the kernel can also avoid complex parsing and -external dependencies, resulting in a fast and memory efficient processing. - -## Semantic function example - -A Semantic Function is a function written in a natural language in a text file (i.e., "skprompt.txt") using SK's Prompt Template language. The following is a simple example of a semantic function defined with a prompt template, using the syntax described. - -`== File: skprompt.txt ==` - -``` -My name: {{msgraph.GetMyName}} -My email: {{msgraph.GetMyEmailAddress}} -My hobbies: {{memory.recall "my hobbies"}} -Recipient: {{$recipient}} -Email to reply to: -========= -{{$sourceEmail}} -========= -Generate a response to the email, to say: {{$input}} - -Include the original email quoted after the response. -``` - -If we were to write that function in C#, it would look something like: - -```csharp -async Task GenResponseToEmailAsync( - string whatToSay, - string recipient, - string sourceEmail) -{ - try { - string name = await this._msgraph.GetMyName(); - } catch { - ... - } - - try { - string email = await this._msgraph.GetMyEmailAddress(); - } catch { - ... - } - - try { - // Use AI to generate an email using the 5 given variables - // Take care of retry logic, tracking AI costs, etc. - string response = await ... - - return response; - } catch { - ... - } -} -``` - -# Notes about special chars - -Semantic function templates are text files, so there is no need to escape special chars -like new lines and tabs. However, there are two cases that require a special syntax: - -1. Including double curly braces in the prompt templates -2. Passing to functions hardcoded values that include quotes - -## Prompts needing double curly braces - -Double curly braces have a special use case, they are used to inject variables, -values, and functions into templates. - -If you need to include the **`{{`** and **`}}`** sequences in your prompts, which -could trigger special rendering logic, the best solution is to use string values -enclosed in quotes, like `{{ "{{" }}` and `{{ "}}" }}` - -For example: - - {{ "{{" }} and {{ "}}" }} are special SK sequences. - -will render to: - - {{ and }} are special SK sequences. - -## Values that include quotes, and escaping - -Values can be enclosed using **single quotes** and **double quotes**. - -To avoid the need for special syntax, when working with a value that contains -_single quotes_, we recommend wrapping the value with _double quotes_. Similarly, -when using a value that contains _double quotes_, wrap the value with _single quotes_. - -For example: - - ...text... {{ functionName "one 'quoted' word" }} ...text... - ...text... {{ functionName 'one "quoted" word' }} ...text... - -For those cases where the value contains both single and double quotes, you will -need _escaping_, using the special **«`\`»** symbol. - -When using double quotes around a value, use **«`\"`»** to include a double quote -symbol inside the value: - - ... {{ "quotes' \"escaping\" example" }} ... - -and similarly, when using single quotes, use **«`\'`»** to include a single quote -inside the value: - - ... {{ 'quotes\' "escaping" example' }} ... - -Both are rendered to: - - ... quotes' "escaping" example ... - -Note that for consistency, the sequences **«`\'`»** and **«`\"`»** do always render -to **«`'`»** and **«`"`»**, even when escaping might not be required. - -For instance: - - ... {{ 'no need to \"escape" ' }} ... - -is equivalent to: - - ... {{ 'no need to "escape" ' }} ... - -and both render to: - - ... no need to "escape" ... - -In case you may need to render a backslash in front of a quote, since **«`\`»** -is a special char, you will need to escape it too, and use the special sequences -**«`\\\'`»** and **«`\\\"`»**. - -For example: - - {{ 'two special chars \\\' here' }} - -is rendered to: - - two special chars \' here - -Similarly to single and double quotes, the symbol **«`\`»** doesn't always need -to be escaped. However, for consistency, it can be escaped even when not required. - -For instance: - - ... {{ 'c:\\documents\\ai' }} ... - -is equivalent to: - - ... {{ 'c:\documents\ai' }} ... - -and both are rendered to: - - ... c:\documents\ai ... - -Lastly, backslashes have a special meaning only when used in front of -**«`'`»**, **«`"`»** and **«`\`»**. - -In all other cases, the backslash character has no impact and is rendered as is. -For example: - - {{ "nothing special about these sequences: \0 \n \t \r \foo" }} - -is rendered to: +This document has been moved to the Semantic Kernel Documentation site. You can find it by navigating to the [Prompt template syntax](https://learn.microsoft.com/en-us/semantic-kernel/prompt-engineering/prompt-template-syntax) page. - nothing special about these sequences: \0 \n \t \r \foo +To make an update on the page, file a PR on the [docs repo.](https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/semantic-kernel/prompt-engineering/prompt-template-syntax.md) diff --git a/docs/SKILLS.md b/docs/SKILLS.md index cc0a75643278..2407b01ce3e4 100644 --- a/docs/SKILLS.md +++ b/docs/SKILLS.md @@ -1,79 +1,5 @@ -# What are Skills? +# What are plugins? -![image](https://user-images.githubusercontent.com/371009/221739773-cf43522f-c1e4-42f2-b73d-5ba84e21febb.png) +This document has been moved to the Semantic Kernel Documentation site. You can find it by navigating to the [Using AI plugins in Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/ai-orchestration/plugins) page. -A skill refers to a domain of expertise made available to the kernel as a single -function, or as a group of functions related to the skill. The design of SK skills -has prioritized maximum flexibility for the developer to be both lightweight and -extensible. - -# What is a Function? - -![image](https://user-images.githubusercontent.com/371009/221742673-3ee8abb8-fe10-4669-93e5-5096d3d09580.png) - -A function is the basic building block for a skill. A function can be expressed -as either: - -1. an LLM AI prompt — also called a "semantic" function -2. native computer code -- also called a "native" function - -When using native computer code, it's also possible to invoke an LLM AI prompt — -which means that there can be functions that are hybrid LLM AI × native code as well. - -Functions can be connected end-to-end, or "chained together," to create more powerful -capabilities. When they are represented as pure LLM AI prompts in semantic functions, -the word "function" and "prompt" can be used interchangeably. - -# What is the relationship between semantic functions and skills? - -A skill is the container in which functions live. You can think of a semantic skill -as a directory of folders that contain multiple directories of semantic functions -or a single directory as well. - -``` -SkillName (directory name) -│ -└─── Function1Name (directory name) -│ -└─── Function2Name (directory name) -``` - -Each function directory will have an skprompt.txt file and a config.json file. There's -much more to learn about semantic functions in Building Semantic Functions if you -wish to go deeper. - -# What is the relationship between native functions and skills? - -Native functions are loosely inspired by Azure Functions and exist as individual -native skill files as in MyNativeSkill.cs below: - -``` -MyAppSource -│ -└───MySkillsDirectory - │ - └─── MySemanticSkill (a directory) - | │ - | └─── MyFirstSemanticFunction (a directory) - | └─── MyOtherSemanticFunction (a directory) - │ - └─── MyNativeSkill.cs (a file) - └─── MyOtherNativeSkill.cs (a file) -``` - -Each file will contain multiple native functions that are associated with a skill. - -# Where to find skills in the GitHub repo - -Skills are stored in one of three places: - -1. Core Skills: these are skills available at any time to the kernel that embody - a few standard capabilities like working with time, text, files, and http requests. - The core skills can be found [here](../dotnet/src/Skills/Skills.Core). - -2. Semantic Skills: these skills are managed by you in a directory of your choice. - -3. Native Skills: these skills are also managed by you in a directory of your choice. - -For more examples of skills, and the ones that we use in our sample apps, look inside -the [/samples/skills](../samples/skills) folder. +To make an update on the page, file a PR on the [docs repo.](https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/semantic-kernel/ai-orchestration/plugins.md)