.Net: API Manifest Plugins

[zengin]

Motivation and Context

This PR contains main implementation part of #4662 and adds it into Functions.OpenApi.Extensions project. There were also couple of bug fixes in the mentioned PR, those will be handled in subsequent PRs.

API Manifest can describe capabilities of an AI plugin for a chat-based system among other things. For a full description of API Manifest, see the API Manifest Specification.

API Manifest refers to one or more OpenAPI documents as API dependencies and it selects a subset of operations from those documents to describe the capabilities of an AI plugin.

Description

Semantic Kernel has a way of creating plugins from OpenAPI operations, but it has a couple of limitations that can be addressed with API Manifest:

1. It can only create functions from OpenAPI operations that are described in a single OpenAPI document.
2. It cannot reference multiple OpenAPI documents in a single plugin.

Not being able to slice OpenAPI operations is a major limitation, especially for large APIs such as Microsoft Graph, which has over 1000 operations.

Today, we can create a Semantic Kernel plugin from an OpenAPI file and one OpenAPI file corresponds to one plugin. We don't have a way of selecting a subset of operations.

graph TB

subgraph OpenAPI1
operation11
operation12
operation13
end

subgraph OpenAPI2
operation21
operation22
operation23
end

subgraph OpenAPIPlugin1
function11
function12
function13
end

subgraph OpenAPIPlugin2
function21
function22
function23
end

operation11 -.- function11
operation12 -.- function12
operation13 -.- function13

operation21 -.- function21
operation22 -.- function22
operation23 -.- function23

style OpenAPIPlugin1 fill:blue,color:white
style OpenAPIPlugin2 fill:blue,color:white

Proposed Solution

After Semantic Kernel APIManifest support, we will have an APIManifest file, which will be used as a filter on OpenAPI files and it can reference more than one OpenAPI file. The filter can be used as a guide to select only certain operations to be converted into functions.

Assume that we want to create a single plugin with function11 from OpenAPI1 and function21 and function22 from OpenAPI2. We want to preserve the one-to-one mapping between the APIManifest and the plugin, e.g. between ApiManifestX and PluginX:

graph TB

subgraph OpenAPI1
operation11
operation12
operation13
end

subgraph OpenAPI2
operation21
operation22
operation23
end

subgraph APIManifestX
reference11
reference21
reference22
end

subgraph PluginX
function11
function21
function22
end

reference11 -.- operation11
reference21 -.- operation21
reference22 -.- operation22

function11 -.- reference11
function21 -.- reference21
function22 -.- reference22

style APIManifestX fill:green,color:white
style PluginX fill:blue,color:white

If we use existing OpenAPI to Plugin public methods after on-the-fly slicing, we can only achieve the following because there is an assumption that a single OpenAPI is converted into a single plugin, which breaks APIManifest to Plugin one-to-one mapping. A single APIManifestX file corresponds to two plugins, namely, PluginX1 and PluginX2:

graph TB

subgraph OpenAPI1
operation11
operation12
operation13
end

subgraph OpenAPI2
operation21
operation22
operation23
end

subgraph APIManifestX
reference11
reference21
reference22
end

subgraph OpenAPI1_Sliced
operation11_sliced[operation11]
end

subgraph OpenAPI2_Sliced
operation21_sliced[operation21]
operation22_sliced[operation22]
end

subgraph PluginX1
function11
end

subgraph PluginX2
function21
function22
end

reference11 -.- operation11
reference21 -.- operation21
reference22 -.- operation22

operation11 -.- operation11_sliced -.- function11
operation21 -.- operation21_sliced -.- function21
operation22 -.- operation22_sliced -.- function22

style APIManifestX fill:green,color:white
style PluginX1 fill:blue,color:white
style PluginX2 fill:blue,color:white

To avoid this, the implementation of regular OpenAPI plugin generation and API Manifest plugin generation meets at the function generation level, so reuse starts at CreateRestApiFunction.

The PR also adds a KernelSyntaxExample for /me/messages endpoint of Microsoft Graph.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the SK Contribution Guidelines and the pre-submission formatting script raises no violations
• All unit tests pass, and I have added new tests where possible
• I didn't break anyone 😄

[zengin]

@dmytrostruk @markwallace-microsoft can I get one more review, please? Thanks!