Python: Introduce feature decorator to allow for experimental and release candidate decorator usage

[moonbox3]

Motivation and Context

This change is required to improve the flexibility and maintainability of our feature annotation system. Previously, separate decorators (e.g., experimental_function and experimental_class) were used to mark experimental features, resulting in code duplication and limiting our ability to handle additional feature stages. As our SDK evolves, we need a unified approach that can support multiple stages—such as experimental, release candidate, and future states—while also allowing version information for release candidate features to be centrally managed.

Description

This PR refactors our feature decorators by introducing a unified stage decorator that updates the docstring and attaches metadata for both functions and classes. Two convenience decorators, experimental and release_candidate, are built on top of stage:

• The experimental decorator marks features as experimental and sets an is_experimental attribute.
• The release_candidate decorator supports multiple usage patterns (with or without parentheses and with an optional version parameter) to mark features as release candidate and sets an is_release_candidate attribute.

This unified approach reduces duplication, simplifies the codebase, and lays the groundwork for easily extending feature stages in the future.

This decorator supports the following usage patterns:

• @experimental (for both classes and functions)
• @release_candidate (no parentheses)
• @release_candidate() (empty parentheses)
• @release_candidate("1.21.3-rc1") (positional version)
• @release_candidate(version="1.21.3-rc1") (keyword version)

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 😄

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
semantic_kernel/agents/azure_ai
agent_content_generation.py	145	20	86%	68–71, 89, 91, 286, 338–370
agent_thread_actions.py	341	129	62%	140, 142, 177–180, 365, 367, 406–407, 433, 436–440, 443–455, 458–489, 495–502, 505–518, 534–565, 609, 612, 641–675, 738, 743–748, 768–775, 806–815, 858–868
azure_ai_agent.py	93	14	85%	95, 97, 103, 112–117, 119, 121, 142–145, 193, 253
azure_ai_agent_utils.py	34	1	97%	44
azure_ai_channel.py	41	3	93%	93, 120–121
semantic_kernel/agents/bedrock
bedrock_agent.py	184	33	82%	106, 120, 124, 126, 173–186, 252, 276, 293, 325, 360–363, 366, 369, 371, 403, 420–421, 423–424, 466, 477–478, 490, 526–537, 548, 565–578
bedrock_agent_base.py	165	8	95%	90, 160–175
semantic_kernel/agents/channels
bedrock_agent_channel.py	80	44	45%	50–71, 90–111, 156–157, 168–185, 189–190, 199–211
chat_history_channel.py	79	2	97%	168, 171
semantic_kernel/agents/chat_completion
chat_completion_agent.py	110	7	94%	82, 85, 94–99, 124, 192
semantic_kernel/agents/group_chat
agent_chat.py	127	3	98%	80, 103, 176
agent_group_chat.py	115	13	89%	73, 163, 213, 217–228
broadcast_queue.py	74	1	99%	37
semantic_kernel/agents/open_ai
assistant_content_generation.py	179	28	84%	67, 94–97, 101–119, 258–260, 314, 411–419, 469
assistant_thread_actions.py	316	38	88%	104, 107, 110, 187, 189, 226–232, 402, 460, 477, 562–571, 607–621, 633–634, 705, 710, 742
azure_assistant_agent.py	35	2	94%	79, 83
open_ai_assistant_agent.py	174	5	97%	221, 234, 270, 439, 526
semantic_kernel/agents/strategies/selection
kernel_function_selection_strategy.py	57	4	93%	62–65
selection_strategy.py	20	2	90%	41, 57
semantic_kernel/agents/strategies/termination
kernel_function_termination_strategy.py	47	4	91%	54–57
semantic_kernel/connectors/ai/anthropic/services
anthropic_chat_completion.py	162	8	95%	159, 165, 178, 184, 188, 245–247, 380
semantic_kernel/connectors/ai/azure_ai_inference/services
azure_ai_inference_base.py	44	1	98%	99
azure_ai_inference_chat_completion.py	110	6	95%	120–123, 132, 156, 182
semantic_kernel/connectors/ai/embeddings
embedding_generator_base.py	8	1	88%	50
semantic_kernel/connectors/ai/hugging_face/services
hf_text_embedding.py	32	5	84%	80–84
semantic_kernel/connectors/ai/mistral_ai/services
mistral_ai_chat_completion.py	120	38	68%	121–124, 134, 149–152, 167, 183–187, 202–210, 227–235, 248–261, 267, 276–280, 325–328
mistral_ai_text_embedding.py	39	1	97%	108
semantic_kernel/connectors/ai/onnx/services
onnx_gen_ai_chat_completion.py	72	6	92%	69–70, 100, 126, 174, 180
onnx_gen_ai_text_completion.py	46	5	89%	54–55, 87, 117, 133
semantic_kernel/connectors/memory/azure_ai_search
azure_ai_search_collection.py	137	36	74%	174, 176, 249–290, 300–310, 314, 318, 323–326
azure_ai_search_store.py	42	2	95%	130–131
utils.py	73	7	90%	125, 127, 129, 150–151, 154–155
semantic_kernel/connectors/memory/azure_cosmos_db
azure_cosmos_db_mongodb_collection.py	95	63	34%	81–114, 142–143, 146–189, 198–222, 233–253
azure_cosmos_db_mongodb_store.py	36	16	56%	56–85, 107–116
azure_cosmos_db_no_sql_base.py	50	9	82%	93, 96–97, 105, 115–119
azure_cosmos_db_no_sql_collection.py	171	67	61%	98–99, 140–147, 158–172, 178–186, 192–196, 219–243, 247, 251, 275, 303–304, 308–313
azure_cosmos_db_no_sql_store.py	33	6	82%	91–96
semantic_kernel/connectors/memory/mongodb_atlas
mongodb_atlas_collection.py	135	42	69%	148, 155, 188–190, 196–198, 205, 209, 221–222, 230–237, 247, 258–260, 268–293, 300–306, 310, 314, 324–325
mongodb_atlas_store.py	52	7	87%	89–90, 92, 139–140, 144–145
semantic_kernel/connectors/memory/redis
redis_collection.py	241	47	80%	174, 179–180, 191–201, 209–229, 232–239, 254–259, 263, 339, 376–383, 461, 483–490
redis_store.py	42	2	95%	108–109
semantic_kernel/connectors/memory/weaviate
weaviate_collection.py	177	59	67%	173–176, 180–186, 190–191, 202–219, 226–233, 242–262, 271–287, 291, 294–298, 342, 346–353, 368, 387, 403, 412–413, 419, 424
weaviate_store.py	59	17	71%	110–118, 122–127, 132–137, 142–143
semantic_kernel/connectors/openapi_plugin
openapi_manager.py	80	8	90%	54, 71, 93–96, 141–142
openapi_runner.py	105	2	98%	177–178
semantic_kernel/connectors/openapi_plugin/models
rest_api_operation.py	235	24	90%	101–102, 111–112, 121–122, 132, 141–142, 161–162, 171–172, 191–192, 228–229, 263–271, 393
rest_api_parameter.py	95	20	79%	55, 64–65, 74–75, 84–85, 94–95, 114–115, 124–125, 134–135, 144–145, 150, 154–155
rest_api_payload.py	46	6	87%	46–47, 66–67, 76–77
rest_api_payload_property.py	70	17	76%	41–42, 51–52, 61–62, 71–72, 81–82, 91–92, 97, 101–102, 111–112
semantic_kernel/connectors/search/bing
bing_search.py	115	115	0%	3–212
bing_search_response.py	17	17	0%	3–29
bing_web_page.py	16	16	0%	4–23
semantic_kernel/connectors/search/google
google_search.py	103	103	0%	3–194
google_search_response.py	21	21	0%	3–33
google_search_result.py	21	21	0%	3–29
semantic_kernel/contents
audio_content.py	21	1	95%	88
binary_content.py	111	11	90%	99, 120, 127, 140, 145–146, 187–191
semantic_kernel/contents/history_reducer
chat_history_reducer.py	29	9	69%	55–63
chat_history_reducer_utils.py	98	12	88%	103–105, 165–166, 181–186, 199, 204–205
chat_history_summarization_reducer.py	71	7	90%	96–97, 122–123, 130, 138, 171
chat_history_truncation_reducer.py	30	3	90%	50–53, 69
semantic_kernel/core_plugins/crew_ai
crew_ai_enterprise.py	87	14	84%	70–71, 105–106, 122–123, 160–161, 171, 201–202, 211–218
semantic_kernel/data/text_search
text_search.py	75	2	97%	269–271
semantic_kernel/data/vector_search
vector_search.py	33	2	94%	124–125
vector_text_search.py	20	3	85%	56–59
vectorizable_text_search.py	19	3	84%	61–64
vectorized_search.py	19	3	84%	56–59
semantic_kernel/processes
process_builder.py	77	44	43%	60–73, 77–79, 85–95, 99–108, 112–118, 122–126, 131, 135–140
process_end_step.py	19	2	89%	37, 41
process_function_target_builder.py	27	3	89%	43–46
process_step_builder.py	110	24	78%	45, 94, 108, 115–128, 140–147, 156, 165–175, 180, 220
process_step_edge_builder.py	35	3	91%	43, 60, 70
semantic_kernel/processes/dapr_runtime
dapr_kernel_process.py	22	2	91%	26, 38
dapr_kernel_process_context.py	34	2	94%	25, 27
dapr_process_info.py	32	4	88%	26, 31, 41, 48
dapr_step_info.py	31	2	94%	30, 39
semantic_kernel/processes/dapr_runtime/actors
event_buffer_actor.py	52	17	67%	40–43, 65–68, 81–85, 89–92
external_event_buffer_actor.py	55	12	78%	52–55, 77–80, 103–106
message_buffer_actor.py	49	12	76%	39–42, 57–60, 74–77
process_actor.py	244	113	54%	72–76, 81, 84, 90, 93, 97, 103, 106, 122–125, 130, 143, 161–165, 170, 180, 185, 194–202, 206–208, 216–224, 235, 251–312, 317, 328, 342–350, 353–360, 364–392, 423–436
step_actor.py	261	131	50%	81–85, 90, 93, 97–98, 110–112, 156–159, 173–175, 183, 187–188, 214, 222–223, 239–246, 253–254, 262–360, 364, 368–371, 375–391, 395–416, 420–438, 442–445, 449, 453–456
semantic_kernel/processes/kernel_process
kernel_process.py	24	1	96%	58
kernel_process_step_context.py	18	1	94%	38
semantic_kernel/processes/local_runtime
local_kernel_process.py	22	2	91%	24, 35
local_kernel_process_context.py	32	2	94%	67–68
local_process.py	138	53	62%	66, 103, 113, 131–142, 176–203, 207–212, 216, 220–226, 230–241, 245–246
local_step.py	174	108	38%	64, 74, 83–173, 177, 181, 185–186, 191–261, 265–268, 272–275, 279–288, 294–297, 301–303
semantic_kernel/utils
feature_stage_decorator.py	42	1	98%	138
semantic_kernel/utils/telemetry/model_diagnostics
decorators.py	189	11	94%	60–63, 380–382, 426–429
TOTAL	18867	2367	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3170	5 💤	0 ❌	0 🔥	1m 26s ⏱️