Python/.Net: Agent Resources for Learn-Site Update (#9104)

### 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.
-->

Learn Site Resources for Agent Framework docs 

### Description
<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

Resources and code associated with examples

### 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: Evan Mattson <[email protected]>

.github/_typos.toml

@@ -17,7 +17,10 @@ extend-exclude = [
     "*response.json",
     "test_content.txt",
     "serializedChatHistoryV1_15_1.json",
-    "MultipleFunctionsVsParameters.cs"
+    "MultipleFunctionsVsParameters.cs",
+    "PopulationByCountry.csv",
+    "PopulationByAdmin1.csv",
+    "WomensSuffrage.txt",
 ]
 
 [default.extend-words]

dotnet/samples/LearnResources/Plugins/GitHub/GitHubModels.cs

@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace Plugins;
+
+/// <summary>
+/// Models for GitHub REST API GET responses:
+/// https://docs.github.com/en/rest
+/// </summary>
+internal static class GitHubModels
+{
+    public sealed class Repo
+    {
+        [JsonPropertyName("id")]
+        public long Id { get; set; }
+
+        [JsonPropertyName("full_name")]
+        public string Name { get; set; }
+
+        [JsonPropertyName("description")]
+        public string Description { get; set; }
+
+        [JsonPropertyName("html_url")]
+        public string Url { get; set; }
+    }
+
+    public sealed class User
+    {
+        [JsonPropertyName("id")]
+        public long Id { get; set; }
+
+        [JsonPropertyName("login")]
+        public string Login { get; set; }
+
+        [JsonPropertyName("name")]
+        public string Name { get; set; }
+
+        [JsonPropertyName("company")]
+        public string Company { get; set; }
+
+        [JsonPropertyName("html_url")]
+        public string Url { get; set; }
+    }
+
+    public class Issue
+    {
+        [JsonPropertyName("id")]
+        public long Id { get; set; }
+
+        [JsonPropertyName("number")]
+        public int Number { get; set; }
+
+        [JsonPropertyName("html_url")]
+        public string Url { get; set; }
+
+        [JsonPropertyName("title")]
+        public string Title { get; set; }
+
+        [JsonPropertyName("state")]
+        public string State { get; set; }
+
+        [JsonPropertyName("labels")]
+        public Label[] Labels { get; set; }
+
+        [JsonPropertyName("created_at")]
+        public string WhenCreated { get; set; }
+
+        [JsonPropertyName("closed_at")]
+        public string WhenClosed { get; set; }
+    }
+
+    public sealed class IssueDetail : Issue
+    {
+        [JsonPropertyName("body")]
+        public string Body { get; set; }
+    }
+
+    public sealed class Label
+    {
+        [JsonPropertyName("id")]
+        public long Id { get; set; }
+
+        [JsonPropertyName("name")]
+        public string Name { get; set; }
+
+        [JsonPropertyName("description")]
+        public string Description { get; set; }
+    }
+}

dotnet/samples/LearnResources/Plugins/GitHub/GitHubPlugin.cs

@@ -0,0 +1,107 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json;
+using Microsoft.SemanticKernel;
+
+namespace Plugins;
+
+internal sealed class GitHubSettings
+{
+    public string BaseUrl { get; set; } = "https://api.github.com";
+
+    public string Token { get; set; } = string.Empty;
+}
+
+internal sealed class GitHubPlugin(GitHubSettings settings)
+{
+    [KernelFunction]
+    public async Task<GitHubModels.User> GetUserProfileAsync()
+    {
+        using HttpClient client = this.CreateClient();
+        JsonDocument response = await MakeRequestAsync(client, "/user");
+        return response.Deserialize<GitHubModels.User>() ?? throw new InvalidDataException($"Request failed: {nameof(GetUserProfileAsync)}");
+    }
+
+    [KernelFunction]
+    public async Task<GitHubModels.Repo> GetRepositoryAsync(string organization, string repo)
+    {
+        using HttpClient client = this.CreateClient();
+        JsonDocument response = await MakeRequestAsync(client, $"/repos/{organization}/{repo}");
+
+        return response.Deserialize<GitHubModels.Repo>() ?? throw new InvalidDataException($"Request failed: {nameof(GetRepositoryAsync)}");
+    }
+
+    [KernelFunction]
+    public async Task<GitHubModels.Issue[]> GetIssuesAsync(
+        string organization,
+        string repo,
+        [Description("default count is 30")]
+        int? maxResults = null,
+        [Description("open, closed, or all")]
+        string state = "",
+        string label = "",
+        string assignee = "")
+    {
+        using HttpClient client = this.CreateClient();
+
+        string path = $"/repos/{organization}/{repo}/issues?";
+        path = BuildQuery(path, "state", state);
+        path = BuildQuery(path, "assignee", assignee);
+        path = BuildQuery(path, "labels", label);
+        path = BuildQuery(path, "per_page", maxResults?.ToString() ?? string.Empty);
+
+        JsonDocument response = await MakeRequestAsync(client, path);
+
+        return response.Deserialize<GitHubModels.Issue[]>() ?? throw new InvalidDataException($"Request failed: {nameof(GetIssuesAsync)}");
+    }
+
+    [KernelFunction]
+    public async Task<GitHubModels.IssueDetail> GetIssueDetailAsync(string organization, string repo, int issueId)
+    {
+        using HttpClient client = this.CreateClient();
+
+        string path = $"/repos/{organization}/{repo}/issues/{issueId}";
+
+        JsonDocument response = await MakeRequestAsync(client, path);
+
+        return response.Deserialize<GitHubModels.IssueDetail>() ?? throw new InvalidDataException($"Request failed: {nameof(GetIssueDetailAsync)}");
+    }
+
+    private HttpClient CreateClient()
+    {
+        HttpClient client = new()
+        {
+            BaseAddress = new Uri(settings.BaseUrl)
+        };
+
+        client.DefaultRequestHeaders.Clear();
+        client.DefaultRequestHeaders.Add("User-Agent", "request");
+        client.DefaultRequestHeaders.Add("Accept", "application/vnd.github+json");
+        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {settings.Token}");
+        client.DefaultRequestHeaders.Add("X-GitHub-Api-Version", "2022-11-28");
+
+        return client;
+    }
+
+    private static string BuildQuery(string path, string key, string value)
+    {
+        if (!string.IsNullOrWhiteSpace(value))
+        {
+            return $"{path}{key}={value}&";
+        }
+
+        return path;
+    }
+
+    private static async Task<JsonDocument> MakeRequestAsync(HttpClient client, string path)
+    {
+        Console.WriteLine($"REQUEST: {path}");
+        Console.WriteLine();
+
+        HttpResponseMessage response = await client.GetAsync(new Uri(path));
+        response.EnsureSuccessStatusCode();
+        string content = await response.Content.ReadAsStringAsync();
+        return JsonDocument.Parse(content);
+    }
+}

dotnet/samples/LearnResources/Resources/Grimms-The-King-of-the-Golden-Mountain.txt

@@ -0,0 +1,36 @@
+The King of the Golden Mountain
+By the Grimm Brothers
+
+There was once a merchant who had only one child, a son, that was very young, and barely able to run alone. He had two richly laden ships then making a voyage upon the seas, in which he had embarked all his wealth, in the hope of making great gains, when the news came that both were lost. Thus from being a rich man he became all at once so very poor that nothing was left to him but one small plot of land; and there he often went in an evening to take his walk, and ease his mind of a little of his trouble.
+
+One day, as he was roaming along in a brown study, thinking with no great comfort on what he had been and what he now was, and was like to be, all on a sudden there stood before him a little, rough-looking, black dwarf. ’Prithee, friend, why so sorrowful?’ said he to the merchant; ’what is it you take so deeply to heart?’ ’If you would do me any good I would willingly tell you,’ said the merchant. ’Who knows but I may?’ said the little man: ’tell me what ails you, and perhaps you will find I may be of some use.’ Then the merchant told him how all his wealth was gone to the bottom of the sea, and how he had nothing left but that little plot of land. ’Oh, trouble not yourself about that,’ said the dwarf; ’only undertake to bring me here, twelve years hence, whatever meets you first on your going home, and I will give you as much as you please.’ The merchant thought this was no great thing to ask; that it would most likely be his dog or his cat, or something of that sort, but forgot his little boy Heinel; so he agreed to the bargain, and signed and sealed the bond to do what was asked of him.
+
+But as he drew near home, his little boy was so glad to see him that he crept behind him, and laid fast hold of his legs, and looked up in his face and laughed. Then the father started, trembling with fear and horror, and saw what it was that he had bound himself to do; but as no gold was come, he made himself easy by thinking that it was only a joke that the dwarf was playing him, and that, at any rate, when the money came, he should see the bearer, and would not take it in.
+
+About a month afterwards he went upstairs into a lumber-room to look for some old iron, that he might sell it and raise a little money; and there, instead of his iron, he saw a large pile of gold lying on the floor. At the sight of this he was overjoyed, and forgetting all about his son, went into trade again, and became a richer merchant than before.
+
+Meantime little Heinel grew up, and as the end of the twelve years drew near the merchant began to call to mind his bond, and became very sad and thoughtful; so that care and sorrow were written upon his face. The boy one day asked what was the matter, but his father would not tell for some time; at last, however, he said that he had, without knowing it, sold him for gold to a little, ugly-looking, black dwarf, and that the twelve years were coming round when he must keep his word. Then Heinel said, ’Father, give yourself very little trouble about that; I shall be too much for the little man.’
+
+When the time came, the father and son went out together to the place agreed upon: and the son drew a circle on the ground, and set himself and his father in the middle of it. The little black dwarf soon came, and walked round and round about the circle, but could not find any way to get into it, and he either could not, or dared not, jump over it. At last the boy said to him. ’Have you anything to say to us, my friend, or what do you want?’ Now Heinel had found a friend in a good fairy, that was fond of him, and had told him what to do; for this fairy knew what good luck was in store for him. ’Have you brought me what you said you would?’ said the dwarf to the merchant. The old man held his tongue, but Heinel said again, ’What do you want here?’ The dwarf said, ’I come to talk with your father, not with you.’ ’You have cheated and taken in my father,’ said the son; ’pray give him up his bond at once.’ ’Fair and softly,’ said the little old man; ’right is right; I have paid my money, and your father has had it, and spent it; so be so good as to let me have what I paid it for.’ ’You must have my consent to that first,’ said Heinel, ’so please to step in here, and let us talk it over.’ The old man grinned, and showed his teeth, as if he should have been very glad to get into the circle if he could. Then at last, after a long talk, they came to terms. Heinel agreed that his father must give him up, and that so far the dwarf should have his way: but, on the other hand, the fairy had told Heinel what fortune was in store for him, if he followed his own course; and he did not choose to be given up to his hump-backed friend, who seemed so anxious for his company.
+
+So, to make a sort of drawn battle of the matter, it was settled that Heinel should be put into an open boat, that lay on the sea-shore hard by; that the father should push him off with his own hand, and that he should thus be set adrift, and left to the bad or good luck of wind and weather. Then he took leave of his father, and set himself in the boat, but before it got far off a wave struck it, and it fell with one side low in the water, so the merchant thought that poor Heinel was lost, and went home very sorrowful, while the dwarf went his way, thinking that at any rate he had had his revenge.
+
+The boat, however, did not sink, for the good fairy took care of her friend, and soon raised the boat up again, and it went safely on. The young man sat safe within, till at length it ran ashore upon an unknown land. As he jumped upon the shore he saw before him a beautiful castle but empty and dreary within, for it was enchanted. ’Here,’ said he to himself, ’must I find the prize the good fairy told me of.’ So he once more searched the whole palace through, till at last he found a white snake, lying coiled up on a cushion in one of the chambers.
+
+Now the white snake was an enchanted princess; and she was very glad to see him, and said, ’Are you at last come to set me free? Twelve long years have I waited here for the fairy to bring you hither as she promised, for you alone can save me. This night twelve men will come: their faces will be black, and they will be dressed in chain armour. They will ask what you do here, but give no answer; and let them do what they will–beat, whip, pinch, prick, or torment you–bear all; only speak not a word, and at twelve o’clock they must go away. The second night twelve others will come: and the third night twenty-four, who will even cut off your head; but at the twelfth hour of that night their power is gone, and I shall be free, and will come and bring you the Water of Life, and will wash you with it, and bring you back to life and health.’ And all came to pass as she had said; Heinel bore all, and spoke not a word; and the third night the princess came, and fell on his neck and kissed him. Joy and gladness burst forth throughout the castle, the wedding was celebrated, and he was crowned king of the Golden Mountain.
+
+They lived together very happily, and the queen had a son. And thus eight years had passed over their heads, when the king thought of his father; and he began to long to see him once again. But the queen was against his going, and said, ’I know well that misfortunes will come upon us if you go.’ However, he gave her no rest till she agreed. At his going away she gave him a wishing-ring, and said, ’Take this ring, and put it on your finger; whatever you wish it will bring you; only promise never to make use of it to bring me hence to your father’s house.’ Then he said he would do what she asked, and put the ring on his finger, and wished himself near the town where his father lived.
+
+Heinel found himself at the gates in a moment; but the guards would not let him go in, because he was so strangely clad. So he went up to a neighbouring hill, where a shepherd dwelt, and borrowed his old frock, and thus passed unknown into the town. When he came to his father’s house, he said he was his son; but the merchant would not believe him, and said he had had but one son, his poor Heinel, who he knew was long since dead: and as he was only dressed like a poor shepherd, he would not even give him anything to eat. The king, however, still vowed that he was his son, and said, ’Is there no mark by which you would know me if I am really your son?’ ’Yes,’ said his mother, ’our Heinel had a mark like a raspberry on his right arm.’ Then he showed them the mark, and they knew that what he had said was true.
+
+He next told them how he was king of the Golden Mountain, and was married to a princess, and had a son seven years old. But the merchant said, ’that can never be true; he must be a fine king truly who travels about in a shepherd’s frock!’ At this the son was vexed; and forgetting his word, turned his ring, and wished for his queen and son. In an instant they stood before him; but the queen wept, and said he had broken his word, and bad luck would follow. He did all he could to soothe her, and she at last seemed to be appeased; but she was not so in truth, and was only thinking how she should punish him.
+
+One day he took her to walk with him out of the town, and showed her the spot where the boat was set adrift upon the wide waters. Then he sat himself down, and said, ’I am very much tired; sit by me, I will rest my head in your lap, and sleep a while.’ As soon as he had fallen asleep, however, she drew the ring from his finger, and crept softly away, and wished herself and her son at home in their kingdom. And when he awoke he found himself alone, and saw that the ring was gone from his finger. ’I can never go back to my father’s house,’ said he; ’they would say I am a sorcerer: I will journey forth into the world, till I come again to my kingdom.’
+
+So saying he set out and travelled till he came to a hill, where three giants were sharing their father’s goods; and as they saw him pass they cried out and said, ’Little men have sharp wits; he shall part the goods between us.’ Now there was a sword that cut off an enemy’s head whenever the wearer gave the words, ’Heads off!’; a cloak that made the owner invisible, or gave him any form he pleased; and a pair of boots that carried the wearer wherever he wished. Heinel said they must first let him try these wonderful things, then he might know how to set a value upon them. Then they gave him the cloak, and he wished himself a fly, and in a moment he was a fly. ’The cloak is very well,’ said he: ’now give me the sword.’ ’No,’ said they; ’not unless you undertake not to say, “Heads off!” for if you do we are all dead men.’ So they gave it him, charging him to try it on a tree. He next asked for the boots also; and the moment he had all three in his power, he wished himself at the Golden Mountain; and there he was at once. So the giants were left behind with no goods to share or quarrel about.
+
+As Heinel came near his castle he heard the sound of merry music; and the people around told him that his queen was about to marry another husband. Then he threw his cloak around him, and passed through the castle hall, and placed himself by the side of the queen, where no one saw him. But when anything to eat was put upon her plate, he took it away and ate it himself; and when a glass of wine was handed to her, he took it and drank it; and thus, though they kept on giving her meat and drink, her plate and cup were always empty.
+
+Upon this, fear and remorse came over her, and she went into her chamber alone, and sat there weeping; and he followed her there. ’Alas!’ said she to herself, ’was I not once set free? Why then does this enchantment still seem to bind me?’
+
+’False and fickle one!’ said he. ’One indeed came who set thee free, and he is now near thee again; but how have you used him? Ought he to have had such treatment from thee?’ Then he went out and sent away the company, and said the wedding was at an end, for that he was come back to the kingdom. But the princes, peers, and great men mocked at him. However, he would enter into no parley with them, but only asked them if they would go in peace or not. Then they turned upon him and tried to seize him; but he drew his sword. ’Heads Off!’ cried he; and with the word the traitors’ heads fell before him, and Heinel was once more king of the Golden Mountain.