2024-05-31 15:06:41 +02:00
|
|
|
# Copyright (c) Microsoft. All rights reserved.
|
|
|
|
|
|
2025-06-19 16:24:16 +09:00
|
|
|
import pytest
|
|
|
|
|
|
Python: major features for the Kernel Arguments, Function Result and new Prompt Templating (#5077)
### Motivation and Context
<!-- Thank you for your contribution to the semantic-kernel repo! Please
help reviewers and future users, providing the following information:
1. Why is this change required?
2. What problem does it solve?
3. What scenario does it contribute to?
4. If it fixes an open issue, please link to the issue here. -->
Major work to replace the context with Kernel Arguments on the front-end
and Function Results on the back.
Updated the function decorator to a new approach, in line with dotnet.
Revamps the way function are called, allowing native functions to be
completely ignorant of SK, other then the decorator.
This also moves things into the new folder structure in sync with
dotnet.
### Description
<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->
Adds:
- KernelArguments, a dict-like class that replaces the variables in
KernelContext. Closes #4565
- FunctionResult, a class to hold the results of function executions,
includes the function, the value and metadata, as well as two convenient
function to get the value out of it (str and get_inner_content) the
first is generic, the second specifically for KernelContent responses
(from AI services).
- AI Service Selector class, has a default, which is based on the order
in the arguments followed by the order in the functions, can be
overridden to implement your own strategy. Closes #4631
- Introduces ChatHistory and refactors the PromptTemplateConfig. Closes
#4856, #4630
- Improves parsing of templates, will now all validate during creation
and throw an error then, instead of some that do not check for validaty
until used.
- Introduces named_args block and thereby the ability to have multiple
arguments for a function call in a template. Closes #5003
Updates:
- kernel_function decorators, the parameter decorator was removed and
instead we now use Annotated to add a description of a field and we get
the type and required from the function definition.
- core plugins, use the new approach to kernel_function decorators.
- planners, template engines have all been updated to use the kernel and
kernelarguments instead of Context.
- Events have been updated, now use kernelarguments and function_result
- Tokenizers support for named_args and improvements on parsing and
checking.
- Kernel examples and notebooks to use the latest code.
- All unit and integration tests. There is more code coverage now than
before.
Removed:
- kernelContext
- kernel_function_parameter_decorator
- delegate handling code for native functions
- file_io_plugin and tests
- SemanticFunctionConfig
- ChatPromptTemplate
### 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
- [ ] I didn't break anyone :smile:
---------
Co-authored-by: Evan Mattson <evmattso@microsoft.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>
2024-02-24 21:05:40 +01:00
|
|
|
from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
|
|
|
|
|
from semantic_kernel.functions.kernel_arguments import KernelArguments
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def test_kernel_arguments():
|
|
|
|
|
kargs = KernelArguments()
|
|
|
|
|
assert kargs is not None
|
2024-04-16 16:21:29 +02:00
|
|
|
assert kargs.execution_settings is None
|
Python: major features for the Kernel Arguments, Function Result and new Prompt Templating (#5077)
### Motivation and Context
<!-- Thank you for your contribution to the semantic-kernel repo! Please
help reviewers and future users, providing the following information:
1. Why is this change required?
2. What problem does it solve?
3. What scenario does it contribute to?
4. If it fixes an open issue, please link to the issue here. -->
Major work to replace the context with Kernel Arguments on the front-end
and Function Results on the back.
Updated the function decorator to a new approach, in line with dotnet.
Revamps the way function are called, allowing native functions to be
completely ignorant of SK, other then the decorator.
This also moves things into the new folder structure in sync with
dotnet.
### Description
<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->
Adds:
- KernelArguments, a dict-like class that replaces the variables in
KernelContext. Closes #4565
- FunctionResult, a class to hold the results of function executions,
includes the function, the value and metadata, as well as two convenient
function to get the value out of it (str and get_inner_content) the
first is generic, the second specifically for KernelContent responses
(from AI services).
- AI Service Selector class, has a default, which is based on the order
in the arguments followed by the order in the functions, can be
overridden to implement your own strategy. Closes #4631
- Introduces ChatHistory and refactors the PromptTemplateConfig. Closes
#4856, #4630
- Improves parsing of templates, will now all validate during creation
and throw an error then, instead of some that do not check for validaty
until used.
- Introduces named_args block and thereby the ability to have multiple
arguments for a function call in a template. Closes #5003
Updates:
- kernel_function decorators, the parameter decorator was removed and
instead we now use Annotated to add a description of a field and we get
the type and required from the function definition.
- core plugins, use the new approach to kernel_function decorators.
- planners, template engines have all been updated to use the kernel and
kernelarguments instead of Context.
- Events have been updated, now use kernelarguments and function_result
- Tokenizers support for named_args and improvements on parsing and
checking.
- Kernel examples and notebooks to use the latest code.
- All unit and integration tests. There is more code coverage now than
before.
Removed:
- kernelContext
- kernel_function_parameter_decorator
- delegate handling code for native functions
- file_io_plugin and tests
- SemanticFunctionConfig
- ChatPromptTemplate
### 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
- [ ] I didn't break anyone :smile:
---------
Co-authored-by: Evan Mattson <evmattso@microsoft.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>
2024-02-24 21:05:40 +01:00
|
|
|
assert not kargs.keys()
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def test_kernel_arguments_with_input():
|
|
|
|
|
kargs = KernelArguments(input=10)
|
|
|
|
|
assert kargs is not None
|
|
|
|
|
assert kargs["input"] == 10
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def test_kernel_arguments_with_input_get():
|
|
|
|
|
kargs = KernelArguments(input=10)
|
|
|
|
|
assert kargs is not None
|
|
|
|
|
assert kargs.get("input", None) == 10
|
|
|
|
|
assert not kargs.get("input2", None)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def test_kernel_arguments_keys():
|
|
|
|
|
kargs = KernelArguments(input=10)
|
|
|
|
|
assert kargs is not None
|
|
|
|
|
assert list(kargs.keys()) == ["input"]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def test_kernel_arguments_with_execution_settings():
|
|
|
|
|
test_pes = PromptExecutionSettings(service_id="test")
|
|
|
|
|
kargs = KernelArguments(settings=[test_pes])
|
|
|
|
|
assert kargs is not None
|
|
|
|
|
assert kargs.execution_settings == {"test": test_pes}
|
Python: Fix KernelArgument bug in invoke_prompt functions (#8414)
### Motivation and Context
<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
1. Why is this change required?
2. What problem does it solve?
3. What scenario does it contribute to?
4. If it fixes an open issue, please link to the issue here.
-->
In `invoke_prompt(...)` and `invoke_prompt_async(...)`, the `arguments`
parameter is tested to see if it's empty before proceeding. The type of
the `arguments` parameter is `KernelArgument`, which derives from a
`dict` type, with an additional field for execution settings. When
`arguments` contains only the execution settings, it will be considered
as an empty dictionary. This will result in the `arguments` parameter
being overridden completely, invalidating all execution settings passed
to the APIs.
To reproduce (assuming we have a plugin/function that will return the
weather):
```
result = await kernel.invoke_prompt(
"What is the weather like in my location?",
arguments=KernelArguments(
settings={
service_id: PromptExecutionSettings(
service_id=service_id,
function_choice_behavior=FunctionChoiceBehavior.Auto(),
),
}
),
)
```
In the example above, the settings will be overridden to None.
### Description
<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->
1. Fix the bug.
2. Fix mypy in the pre-commit hook in order to commit.
### 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 :smile:
2024-08-29 08:40:53 -07:00
|
|
|
|
|
|
|
|
|
|
|
|
|
def test_kernel_arguments_bool():
|
|
|
|
|
# An empty KernelArguments object should return False
|
|
|
|
|
assert not KernelArguments()
|
|
|
|
|
# An KernelArguments object with keyword arguments should return True
|
|
|
|
|
assert KernelArguments(input=10)
|
|
|
|
|
# An KernelArguments object with execution_settings should return True
|
|
|
|
|
assert KernelArguments(settings=PromptExecutionSettings(service_id="test"))
|
|
|
|
|
# An KernelArguments object with both keyword arguments and execution_settings should return True
|
|
|
|
|
assert KernelArguments(input=10, settings=PromptExecutionSettings(service_id="test"))
|
2025-06-19 16:24:16 +09:00
|
|
|
|
|
|
|
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
|
|
|
"lhs, rhs, expected_dict, expected_settings_keys",
|
|
|
|
|
[
|
|
|
|
|
# Merging different keys
|
|
|
|
|
(KernelArguments(a=1), KernelArguments(b=2), {"a": 1, "b": 2}, None),
|
|
|
|
|
# RHS overwrites when keys duplicate
|
|
|
|
|
(KernelArguments(a=1), KernelArguments(a=99), {"a": 99}, None),
|
|
|
|
|
# Merging with a plain dict
|
|
|
|
|
(KernelArguments(a=1), {"b": 2}, {"a": 1, "b": 2}, None),
|
|
|
|
|
# Merging execution_settings together
|
|
|
|
|
(
|
|
|
|
|
KernelArguments(settings=PromptExecutionSettings(service_id="s1")),
|
|
|
|
|
KernelArguments(settings=PromptExecutionSettings(service_id="s2")),
|
|
|
|
|
{},
|
|
|
|
|
["s1", "s2"],
|
|
|
|
|
),
|
|
|
|
|
# Same service_id is overwritten by RHS
|
|
|
|
|
(
|
|
|
|
|
KernelArguments(settings=PromptExecutionSettings(service_id="shared")),
|
|
|
|
|
KernelArguments(settings=PromptExecutionSettings(service_id="shared")),
|
|
|
|
|
{},
|
|
|
|
|
["shared"],
|
|
|
|
|
),
|
|
|
|
|
],
|
|
|
|
|
)
|
|
|
|
|
def test_kernel_arguments_or_operator(lhs, rhs, expected_dict, expected_settings_keys):
|
|
|
|
|
"""Test the __or__ operator (lhs | rhs) with various argument combinations."""
|
|
|
|
|
result = lhs | rhs
|
|
|
|
|
assert isinstance(result, KernelArguments)
|
|
|
|
|
assert dict(result) == expected_dict
|
|
|
|
|
if expected_settings_keys is None:
|
|
|
|
|
assert result.execution_settings is None
|
|
|
|
|
else:
|
|
|
|
|
assert sorted(result.execution_settings.keys()) == sorted(expected_settings_keys)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@pytest.mark.parametrize("rhs", [42, "foo", None])
|
|
|
|
|
def test_kernel_arguments_or_operator_with_invalid_type(rhs):
|
|
|
|
|
"""Test the __or__ operator with an invalid type raises TypeError."""
|
|
|
|
|
with pytest.raises(TypeError):
|
|
|
|
|
KernelArguments() | rhs
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
|
|
|
"lhs, rhs, expected_dict, expected_settings_keys",
|
|
|
|
|
[
|
|
|
|
|
# Dict merge (in-place)
|
|
|
|
|
(KernelArguments(a=1), {"b": 2}, {"a": 1, "b": 2}, None),
|
|
|
|
|
# Merging between KernelArguments
|
|
|
|
|
(KernelArguments(a=1), KernelArguments(b=2), {"a": 1, "b": 2}, None),
|
|
|
|
|
# Retain existing execution_settings after dict merge
|
|
|
|
|
(KernelArguments(a=1, settings=PromptExecutionSettings(service_id="s1")), {"b": 2}, {"a": 1, "b": 2}, ["s1"]),
|
|
|
|
|
# In-place merge of execution_settings
|
|
|
|
|
(
|
|
|
|
|
KernelArguments(settings=PromptExecutionSettings(service_id="s1")),
|
|
|
|
|
KernelArguments(settings=PromptExecutionSettings(service_id="s2")),
|
|
|
|
|
{},
|
|
|
|
|
["s1", "s2"],
|
|
|
|
|
),
|
|
|
|
|
],
|
|
|
|
|
)
|
|
|
|
|
def test_kernel_arguments_inplace_merge(lhs, rhs, expected_dict, expected_settings_keys):
|
|
|
|
|
"""Test the |= operator with various argument combinations without execution_settings."""
|
|
|
|
|
original_id = id(lhs)
|
|
|
|
|
lhs |= rhs
|
|
|
|
|
# Verify this is the same object (in-place)
|
|
|
|
|
assert id(lhs) == original_id
|
|
|
|
|
assert dict(lhs) == expected_dict
|
|
|
|
|
if expected_settings_keys is None:
|
|
|
|
|
assert lhs.execution_settings is None
|
|
|
|
|
else:
|
|
|
|
|
assert sorted(lhs.execution_settings.keys()) == sorted(expected_settings_keys)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
|
|
|
"rhs, lhs, expected_dict, expected_settings_keys",
|
|
|
|
|
[
|
|
|
|
|
# Merging different keys
|
|
|
|
|
({"b": 2}, KernelArguments(a=1), {"b": 2, "a": 1}, None),
|
|
|
|
|
# RHS overwrites when keys duplicate
|
|
|
|
|
({"a": 1}, KernelArguments(a=99), {"a": 99}, None),
|
|
|
|
|
# Merging with a KernelArguments
|
|
|
|
|
({"b": 2}, KernelArguments(a=1), {"b": 2, "a": 1}, None),
|
|
|
|
|
# Merging execution_settings together
|
|
|
|
|
(
|
|
|
|
|
{"test": "value"},
|
|
|
|
|
KernelArguments(settings=PromptExecutionSettings(service_id="s2")),
|
|
|
|
|
{"test": "value"},
|
|
|
|
|
["s2"],
|
|
|
|
|
),
|
|
|
|
|
# Plain dict on the left with KernelArguments+settings on the right
|
|
|
|
|
(
|
|
|
|
|
{"a": 1},
|
|
|
|
|
KernelArguments(b=2, settings=PromptExecutionSettings(service_id="shared")),
|
|
|
|
|
{"a": 1, "b": 2},
|
|
|
|
|
["shared"],
|
|
|
|
|
),
|
|
|
|
|
# KernelArguments on both sides with execution_settings
|
|
|
|
|
(
|
|
|
|
|
KernelArguments(a=1, settings=PromptExecutionSettings(service_id="s1")),
|
|
|
|
|
KernelArguments(b=2, settings=PromptExecutionSettings(service_id="s2")),
|
|
|
|
|
{"a": 1, "b": 2},
|
|
|
|
|
["s1", "s2"],
|
|
|
|
|
),
|
|
|
|
|
# Same service_id is overwritten by RHS (KernelArguments)
|
|
|
|
|
(
|
|
|
|
|
KernelArguments(a=1, settings=PromptExecutionSettings(service_id="shared")),
|
|
|
|
|
KernelArguments(b=2, settings=PromptExecutionSettings(service_id="shared")),
|
|
|
|
|
{"a": 1, "b": 2},
|
|
|
|
|
["shared"],
|
|
|
|
|
),
|
|
|
|
|
],
|
|
|
|
|
)
|
|
|
|
|
def test_kernel_arguments_ror_operator(rhs, lhs, expected_dict, expected_settings_keys):
|
|
|
|
|
"""Test the __ror__ operator (lhs | rhs) with various argument combinations."""
|
|
|
|
|
result = rhs | lhs
|
|
|
|
|
assert isinstance(result, KernelArguments)
|
|
|
|
|
assert dict(result) == expected_dict
|
|
|
|
|
if expected_settings_keys is None:
|
|
|
|
|
assert result.execution_settings is None
|
|
|
|
|
else:
|
|
|
|
|
assert sorted(result.execution_settings.keys()) == sorted(expected_settings_keys)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@pytest.mark.parametrize("lhs", [42, "foo", None])
|
|
|
|
|
def test_kernel_arguments_ror_operator_with_invalid_type(lhs):
|
|
|
|
|
"""Test the __ror__ operator with an invalid type raises TypeError."""
|
|
|
|
|
with pytest.raises(TypeError):
|
|
|
|
|
lhs | KernelArguments()
|
