### Motivation and Context
The dynamic payload creation was requested by a few internal teams. It
allows SK RestAPI functionality consumer code to only supply arguments
for parameters specified in the OpenAPI payload metadata for PUT and
POST operations, while the rest – payload constriction, data type
conversion, parameter namespacing, etc. – is handled by SK RestAPI
functionality.
### Description
#### Context
Today, the only way to pass a payload for a PUT or POST RestAPI
operation is by adding the `payload` argument to the context variables
collection before executing the operation. The `payload` argument, for
operations requiring an 'application/json' payload, is expected to be a
valid JSON with all the necessary properties initialized. This approach
is not convenient for SK consumers who only want to provide the required
payload parameters, similar to how they handle query string and header
parameters, without having to construct the payload themselves.
#### Dynamic creation of payload
By default, dynamic payload creation is disabled to ensure backward
compatibility. To enable it, the `BuildOperationPayloadDynamically`
property of the `OpenApiSkillExecutionParameters` execution parameters
should be set to `true` when importing the AI plugin:
```csharp
var plugin = await kernel.ImportAIPluginAsync("<skill name>", new Uri("<chatGPT-plugin>"), new OpenApiSkillExecutionParameters(httpClient) { BuildOperationPayloadDynamically = true });
```
So, if a RestAPI operation payload schema requires payload like the
following:
```json
{
"value": "secret-value",
"attributes": {
"enabled": true
}
}
```
To dynamically build it, the consumer code needs to register the
following arguments in the context variables collection:
```csharp
var contextVariables = new ContextVariables();
contextVariables.Set("value", "secret-value");
contextVariables.Set("enabled", true);
```
#### Payload parameter namespacing
When building payload dynamically, and a RestAPI operation requires the
'application/json' content type, it's possible that the content may have
properties with the identical names, see example below, at different
levels. In such cases, SK can't resolve their values unambiguously from
a flat list of arguments unless there's a namespacing mechanism that
allows the distinction of those properties from one another.
The namespacing mechanism relies on prefixing parameter names with their
parent parameter name, separated by dots. So, the 'namespaced' parameter
names should be used when adding arguments to the context variables
collection. For example, consider this JSON:
```json
{
"upn": "<sender upn>",
"receiver": {
"upn": "<receiver upn>"
},
"cc": {
"upn": "<cc upn>"
}
}
```
It contains `upn` properties at different levels. The argument
registration for the parameters (property values) will look like:
```csharp
var contextVariables = new ContextVariables();
contextVariables.Set("upn", "<sender-upn-value>");
contextVariables.Set("receiver.upn", "<receiver-upn-value>");
contextVariables.Set("cc.upn", "<cc-upn-value>");
```
The namespacing mechanism is disabled by default for backward
compatibility and can be easily enabled by setting the value `true` to
the `NamespacePayloadParameters` property of the
`OpenApiSkillExecutionParameters` execution parameters when importing
the AI plugin:
```csharp
var plugin = await kernel.ImportAIPluginAsync("<skill name>", new Uri("<chatGPT-plugin>"), new OpenApiSkillExecutionParameters(httpClient) { NamespacePayloadParameters = true });
```
#### Parameter arguments data type conversion
Currently, the SK context variables collection only supports string
variables.This means that in order to set or add a primitive or complex
type variable, it must first be converted or serialized into a string.
However, this behavior causes issues when the RestAPI functionality
sends HTTP requests with an 'application/json' payload. For instance, a
property like enabled might have the string value `"true"` instead of
the intended Boolean value `true`.
To mitigate this problem, the RestAPIOperationRunner class iterates over
the operation payload metadata. During this process, it converts all
string arguments to their corresponding types as specified in the
metadata. This ensures accurate type representation within the operation
payload.
### Contribution Checklist
<!-- Before submitting this PR, please make sure: -->
- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone 😄
---------
Co-authored-by: Dmytro Struk <[email protected]>
### Motivation
The purpose of this ADR is to describe the existing challenges with SK
error handling mechanism, propose solutions for improvement, and share
points to consider along with questions to think about.
---------
Co-authored-by: Dmytro Struk <[email protected]>
Co-authored-by: Shawn Callegari <[email protected]>
### Motivation and Context
Please help reviewers and future users, providing the following
information:
1. Why is this change required? The folder structure used in the Java
port has diverged from that used in .Net. Some of the changes make sense
i.e., are idiomatic Java and others we should review.
### Description
ADR to define the folder structure to be used for the Java port. This
includes a comparison of the current .Net and Java folder structures and
proposal for the Java folder structure we should move towards.
### Contribution Checklist
- [x] The code builds clean without any errors or warnings
- [x] The PR follows SK Contribution Guidelines
(https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
- [x] The code follows the .NET coding conventions
(https://learn.microsoft.com/dotnet/csharp/fundamentals/coding-style/coding-conventions)
verified with `dotnet format`
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone 😄
### Motivation and Context
Please help reviewers and future users, providing the following
information:
1. Why is this change required? Proposal for how architectural decisions
get documented and reviewed.
2. What problem does it solve? Provides transparency in the
architectural decision making and review process.
3. What scenario does it contribute to? Will help to keep the language
ports on the SK in synch.
4. If it fixes an open issue, please link to the issue here.
### Description
This PR includes:
- README explaining how we will use MADR
- Two templates which are the starting point for new decision records
- One sample decision record which documents the proposal to use MADR
Co-authored-by: Lee Miller <[email protected]>
