chore: import upstream snapshot with attribution

dotnet/samples/GettingStartedWithProcesses/Step03/Steps/CutFoodStep.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Process;
+
+namespace Step03.Steps;
+
+/// <summary>
+/// Step used in the Processes Samples:
+/// - Step_03_FoodPreparation.cs
+/// </summary>
+[KernelProcessStepMetadata("CutFoodStep.V1")]
+public class CutFoodStep : KernelProcessStep
+{
+    public static class ProcessStepFunctions
+    {
+        public const string ChopFood = nameof(ChopFood);
+        public const string SliceFood = nameof(SliceFood);
+    }
+
+    public static class OutputEvents
+    {
+        public const string ChoppingReady = nameof(ChoppingReady);
+        public const string SlicingReady = nameof(SlicingReady);
+    }
+
+    [KernelFunction(ProcessStepFunctions.ChopFood)]
+    public async Task ChopFoodAsync(KernelProcessStepContext context, List<string> foodActions)
+    {
+        var foodToBeCut = foodActions.First();
+        foodActions.Add(this.getActionString(foodToBeCut, "chopped"));
+        Console.WriteLine($"CUTTING_STEP: Ingredient {foodToBeCut} has been chopped!");
+        await context.EmitEventAsync(new() { Id = OutputEvents.ChoppingReady, Data = foodActions });
+    }
+
+    [KernelFunction(ProcessStepFunctions.SliceFood)]
+    public async Task SliceFoodAsync(KernelProcessStepContext context, List<string> foodActions)
+    {
+        var foodToBeCut = foodActions.First();
+        foodActions.Add(this.getActionString(foodToBeCut, "sliced"));
+        Console.WriteLine($"CUTTING_STEP: Ingredient {foodToBeCut} has been sliced!");
+        await context.EmitEventAsync(new() { Id = OutputEvents.SlicingReady, Data = foodActions });
+    }
+
+    private string getActionString(string food, string action)
+    {
+        return $"{food}_{action}";
+    }
+}

dotnet/samples/GettingStartedWithProcesses/Step03/Steps/CutFoodWithSharpeningStep.cs

@@ -0,0 +1,101 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Process;
+
+namespace Step03.Steps;
+
+/// <summary>
+/// Step used in the Processes Samples:
+/// - Step_03_FoodPreparation.cs
+/// </summary>
+[KernelProcessStepMetadata("CutFoodStep.V2")]
+public class CutFoodWithSharpeningStep : KernelProcessStep<CutFoodWithSharpeningState>
+{
+    public static class ProcessStepFunctions
+    {
+        public const string ChopFood = nameof(ChopFood);
+        public const string SliceFood = nameof(SliceFood);
+        public const string SharpenKnife = nameof(SharpenKnife);
+    }
+
+    public static class OutputEvents
+    {
+        public const string ChoppingReady = nameof(ChoppingReady);
+        public const string SlicingReady = nameof(SlicingReady);
+        public const string KnifeNeedsSharpening = nameof(KnifeNeedsSharpening);
+        public const string KnifeSharpened = nameof(KnifeSharpened);
+    }
+
+    internal CutFoodWithSharpeningState? _state;
+
+    public override ValueTask ActivateAsync(KernelProcessStepState<CutFoodWithSharpeningState> state)
+    {
+        _state = state.State;
+        return ValueTask.CompletedTask;
+    }
+
+    [KernelFunction(ProcessStepFunctions.ChopFood)]
+    public async Task ChopFoodAsync(KernelProcessStepContext context, List<string> foodActions)
+    {
+        var foodToBeCut = foodActions.First();
+        if (this.KnifeNeedsSharpening())
+        {
+            Console.WriteLine($"CUTTING_STEP: Dull knife, cannot chop {foodToBeCut} - needs sharpening.");
+            await context.EmitEventAsync(new() { Id = OutputEvents.KnifeNeedsSharpening, Data = foodActions });
+            return;
+        }
+        // Update knife sharpness
+        this._state!.KnifeSharpness--;
+
+        // Chop food
+        foodActions.Add(this.getActionString(foodToBeCut, "chopped"));
+        Console.WriteLine($"CUTTING_STEP: Ingredient {foodToBeCut} has been chopped! - knife sharpness: {this._state.KnifeSharpness}");
+        await context.EmitEventAsync(new() { Id = OutputEvents.ChoppingReady, Data = foodActions });
+    }
+
+    [KernelFunction(ProcessStepFunctions.SliceFood)]
+    public async Task SliceFoodAsync(KernelProcessStepContext context, List<string> foodActions)
+    {
+        var foodToBeCut = foodActions.First();
+        if (this.KnifeNeedsSharpening())
+        {
+            Console.WriteLine($"CUTTING_STEP: Dull knife, cannot slice {foodToBeCut} - needs sharpening.");
+            await context.EmitEventAsync(new() { Id = OutputEvents.KnifeNeedsSharpening, Data = foodActions });
+            return;
+        }
+        // Update knife sharpness
+        this._state!.KnifeSharpness--;
+
+        // Slice food
+        foodActions.Add(this.getActionString(foodToBeCut, "sliced"));
+        Console.WriteLine($"CUTTING_STEP: Ingredient {foodToBeCut} has been sliced! - knife sharpness: {this._state.KnifeSharpness}");
+        await context.EmitEventAsync(new() { Id = OutputEvents.SlicingReady, Data = foodActions });
+    }
+
+    [KernelFunction(ProcessStepFunctions.SharpenKnife)]
+    public async Task SharpenKnifeAsync(KernelProcessStepContext context, List<string> foodActions)
+    {
+        this._state!.KnifeSharpness += this._state._sharpeningBoost;
+        Console.WriteLine($"KNIFE SHARPENED: Knife sharpness is now {this._state.KnifeSharpness}!");
+        await context.EmitEventAsync(new() { Id = OutputEvents.KnifeSharpened, Data = foodActions });
+    }
+
+    private bool KnifeNeedsSharpening() => this._state?.KnifeSharpness == this._state?._needsSharpeningLimit;
+
+    private string getActionString(string food, string action)
+    {
+        return $"{food}_{action}";
+    }
+}
+
+/// <summary>
+/// The state object for the <see cref="CutFoodWithSharpeningStep"/>.
+/// </summary>
+public sealed class CutFoodWithSharpeningState
+{
+    public int KnifeSharpness { get; set; } = 5;
+
+    internal int _needsSharpeningLimit = 3;
+    internal int _sharpeningBoost = 5;
+}

dotnet/samples/GettingStartedWithProcesses/Step03/Steps/ExternalStep.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+
+namespace Step03.Steps;
+
+/// <summary>
+/// Step used in the Processes Samples:
+/// - Step_03_FoodPreparation.cs
+/// </summary>
+public class ExternalStep(string externalEventName) : KernelProcessStep
+{
+    private readonly string _externalEventName = externalEventName;
+
+    [KernelFunction]
+    public async Task EmitExternalEventAsync(KernelProcessStepContext context, object data)
+    {
+        await context.EmitEventAsync(new() { Id = this._externalEventName, Data = data, Visibility = KernelProcessEventVisibility.Public });
+    }
+}

dotnet/samples/GettingStartedWithProcesses/Step03/Steps/FryFoodStep.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Process;
+
+namespace Step03.Steps;
+
+/// <summary>
+/// Step used in the Processes Samples:
+/// - Step_03_FoodPreparation.cs
+/// </summary>
+[KernelProcessStepMetadata("FryFoodStep.V1")]
+public class FryFoodStep : KernelProcessStep
+{
+    public static class ProcessStepFunctions
+    {
+        public const string FryFood = nameof(FryFood);
+    }
+
+    public static class OutputEvents
+    {
+        public const string FoodRuined = nameof(FoodRuined);
+        public const string FriedFoodReady = nameof(FriedFoodReady);
+    }
+
+    private readonly Random _randomSeed = new();
+
+    [KernelFunction(ProcessStepFunctions.FryFood)]
+    public async Task FryFoodAsync(KernelProcessStepContext context, List<string> foodActions)
+    {
+        var foodToFry = foodActions.First();
+        // This step may fail sometimes
+        int fryerMalfunction = _randomSeed.Next(0, 10);
+
+        // foodToFry could potentially be used to set the frying temperature and cooking duration
+        if (fryerMalfunction < 5)
+        {
+            // Oh no! Food got burnt :(
+            foodActions.Add($"{foodToFry}_frying_failed");
+            Console.WriteLine($"FRYING_STEP: Ingredient {foodToFry} got burnt while frying :(");
+            await context.EmitEventAsync(new() { Id = OutputEvents.FoodRuined, Data = foodActions });
+            return;
+        }
+
+        foodActions.Add($"{foodToFry}_frying_succeeded");
+        Console.WriteLine($"FRYING_STEP: Ingredient {foodToFry} is ready!");
+        await context.EmitEventAsync(new() { Id = OutputEvents.FriedFoodReady, Data = foodActions, Visibility = KernelProcessEventVisibility.Public });
+    }
+}

dotnet/samples/GettingStartedWithProcesses/Step03/Steps/GatherIngredientsStep.cs

@@ -0,0 +1,124 @@
+// Copyright (c) Microsoft. All rights reserved.
+using Microsoft.SemanticKernel;
+using Step03.Models;
+namespace Step03.Steps;
+
+/// <summary>
+/// Step used as base by many other cooking processes
+/// When used in other processes a new step is based on this one with custom GatherIngredientsAsync functionality
+/// </summary>
+public class GatherIngredientsStep : KernelProcessStep
+{
+    public static class ProcessStepFunctions
+    {
+        public const string GatherIngredients = nameof(GatherIngredients);
+    }
+
+    public static class OutputEvents
+    {
+        public const string IngredientsGathered = nameof(IngredientsGathered);
+    }
+
+    private readonly FoodIngredients _ingredient;
+
+    public GatherIngredientsStep(FoodIngredients ingredient)
+    {
+        this._ingredient = ingredient;
+    }
+
+    /// <summary>
+    /// Method to be overridden by the user set custom ingredients to be gathered and events to be triggered
+    /// </summary>
+    /// <param name="context">The context for the current step and process. <see cref="KernelProcessStepContext"/></param>
+    /// <param name="foodActions">list of actions taken to the food</param>
+    /// <returns></returns>
+    [KernelFunction(ProcessStepFunctions.GatherIngredients)]
+    public virtual async Task GatherIngredientsAsync(KernelProcessStepContext context, List<string> foodActions)
+    {
+        var ingredient = this._ingredient.ToFriendlyString();
+        var updatedFoodActions = new List<string>();
+        updatedFoodActions.AddRange(foodActions);
+        if (updatedFoodActions.Count == 0)
+        {
+            updatedFoodActions.Add(ingredient);
+        }
+        updatedFoodActions.Add($"{ingredient}_gathered");
+
+        Console.WriteLine($"GATHER_INGREDIENT: Gathered ingredient {ingredient}");
+        await context.EmitEventAsync(new() { Id = OutputEvents.IngredientsGathered, Data = updatedFoodActions });
+    }
+}
+
+/// <summary>
+/// Stateful Step used as base by many other cooking processes
+/// When used in other processes a new step is based on this one with custom GatherIngredientsAsync functionality
+/// </summary>
+public class GatherIngredientsWithStockStep : KernelProcessStep<GatherIngredientsState>
+{
+    public static class ProcessStepFunctions
+    {
+        public const string GatherIngredients = nameof(GatherIngredients);
+    }
+
+    public static class OutputEvents
+    {
+        public const string IngredientsGathered = nameof(IngredientsGathered);
+        public const string IngredientsOutOfStock = nameof(IngredientsOutOfStock);
+    }
+
+    private readonly FoodIngredients _ingredient;
+
+    public GatherIngredientsWithStockStep(FoodIngredients ingredient)
+    {
+        this._ingredient = ingredient;
+    }
+
+    internal GatherIngredientsState? _state;
+
+    public override ValueTask ActivateAsync(KernelProcessStepState<GatherIngredientsState> state)
+    {
+        _state = state.State;
+        return ValueTask.CompletedTask;
+    }
+
+    /// <summary>
+    /// Method to be overridden by the user set custom ingredients to be gathered and events to be triggered
+    /// </summary>
+    /// <param name="context">The context for the current step and process. <see cref="KernelProcessStepContext"/></param>
+    /// <param name="foodActions">list of actions taken to the food</param>
+    /// <returns></returns>
+    [KernelFunction(ProcessStepFunctions.GatherIngredients)]
+    public virtual async Task GatherIngredientsAsync(KernelProcessStepContext context, List<string> foodActions)
+    {
+        var ingredient = this._ingredient.ToFriendlyString(); ;
+        var updatedFoodActions = new List<string>();
+        updatedFoodActions.AddRange(foodActions);
+
+        if (this._state!.IngredientsStock == 0)
+        {
+            Console.WriteLine($"GATHER_INGREDIENT: Could not gather {ingredient} - OUT OF STOCK!");
+            await context.EmitEventAsync(new() { Id = OutputEvents.IngredientsOutOfStock, Data = updatedFoodActions });
+            return;
+        }
+
+        if (updatedFoodActions.Count == 0)
+        {
+            updatedFoodActions.Add(ingredient);
+        }
+        updatedFoodActions.Add($"{ingredient}_gathered");
+
+        // Updating stock of ingredients
+        this._state.IngredientsStock--;
+
+        Console.WriteLine($"GATHER_INGREDIENT: Gathered ingredient {ingredient} - remaining: {this._state.IngredientsStock}");
+        await context.EmitEventAsync(new() { Id = OutputEvents.IngredientsGathered, Data = updatedFoodActions });
+    }
+}
+
+/// <summary>
+/// The state object for the <see cref="GatherIngredientsWithStockStep"/>.
+/// </summary>
+public sealed class GatherIngredientsState
+{
+    public int IngredientsStock { get; set; } = 5;
+}