diff --git a/.github/issue-routing-owners.yaml b/.github/issue-routing-owners.yaml index dfa1e9c1b97..225e8f83d8b 100644 --- a/.github/issue-routing-owners.yaml +++ b/.github/issue-routing-owners.yaml @@ -82,6 +82,7 @@ routes: - { path: dotnet/src/Microsoft.Agents.AI.OpenAI/, owner: rogerbarreto, labels: [agents] } - { path: dotnet/src/Microsoft.Agents.AI.Purview/, owner: westey-m, labels: [security] } - { path: dotnet/src/Microsoft.Agents.AI.Tools.Shell/, owner: westey-m, labels: [agents] } + - { path: dotnet/src/Microsoft.Agents.AI.TypeSafe/, owner: rogerbarreto, labels: [agents] } - { path: dotnet/src/Microsoft.Agents.AI.Valkey/, owner: westey-m, labels: [] } - { path: dotnet/src/Microsoft.Agents.AI.Workflows/, owner: baywet, labels: [] } - { path: dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/, owner: baywet, labels: [] } diff --git a/.github/workflows/dotnet-verify-samples.yml b/.github/workflows/dotnet-verify-samples.yml index 1f1b40e9f4a..1f3ffc703c2 100644 --- a/.github/workflows/dotnet-verify-samples.yml +++ b/.github/workflows/dotnet-verify-samples.yml @@ -109,6 +109,8 @@ jobs: FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }} FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }} AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }} + # TypeSafe (Jev) + TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }} - name: Write Job Summary if: always() diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx index e2a8083dc9e..84d443c28da 100644 --- a/dotnet/agent-framework-dotnet.slnx +++ b/dotnet/agent-framework-dotnet.slnx @@ -37,6 +37,9 @@ + + + @@ -70,6 +73,7 @@ + @@ -640,6 +644,7 @@ + @@ -697,6 +702,7 @@ + diff --git a/dotnet/agent-framework-src-and-tests.slnf b/dotnet/agent-framework-src-and-tests.slnf index 0f74c86ec68..8a6c9451fcc 100644 --- a/dotnet/agent-framework-src-and-tests.slnf +++ b/dotnet/agent-framework-src-and-tests.slnf @@ -30,6 +30,7 @@ "src\\Microsoft.Agents.AI.OpenAI\\Microsoft.Agents.AI.OpenAI.csproj", "src\\Microsoft.Agents.AI.Purview\\Microsoft.Agents.AI.Purview.csproj", "src\\Microsoft.Agents.AI.Tools.Shell\\Microsoft.Agents.AI.Tools.Shell.csproj", + "src\\Microsoft.Agents.AI.TypeSafe\\Microsoft.Agents.AI.TypeSafe.csproj", "src\\Microsoft.Agents.AI.Valkey\\Microsoft.Agents.AI.Valkey.csproj", "src\\Microsoft.Agents.AI.Workflows.Declarative.Foundry\\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj", "src\\Microsoft.Agents.AI.Workflows.Declarative.Mcp\\Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj", @@ -65,6 +66,7 @@ "tests\\Microsoft.Agents.AI.OpenAI.UnitTests\\Microsoft.Agents.AI.OpenAI.UnitTests.csproj", "tests\\Microsoft.Agents.AI.Purview.UnitTests\\Microsoft.Agents.AI.Purview.UnitTests.csproj", "tests\\Microsoft.Agents.AI.Tools.Shell.UnitTests\\Microsoft.Agents.AI.Tools.Shell.UnitTests.csproj", + "tests\\Microsoft.Agents.AI.TypeSafe.UnitTests\\Microsoft.Agents.AI.TypeSafe.UnitTests.csproj", "tests\\Microsoft.Agents.AI.UnitTests\\Microsoft.Agents.AI.UnitTests.csproj", "tests\\Microsoft.Agents.AI.Valkey.UnitTests\\Microsoft.Agents.AI.Valkey.UnitTests.csproj", "tests\\Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests\\Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests.csproj", diff --git a/dotnet/eng/verify-samples/AgentsSamples.cs b/dotnet/eng/verify-samples/AgentsSamples.cs index a4c32d13d50..3f8504d5980 100644 --- a/dotnet/eng/verify-samples/AgentsSamples.cs +++ b/dotnet/eng/verify-samples/AgentsSamples.cs @@ -90,6 +90,55 @@ internal static class AgentsSamples ], }, + new SampleDefinition + { + Name = "Agent_TypeSafe_Step01_LoopJudge", + ProjectPath = "samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge", + RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT", "TYPESAFE_API_KEY"], + OptionalEnvironmentVariables = ["FOUNDRY_MODEL"], + MustContain = ["Answer 1:", "Judge:", "red_sunsets:", "Final answer:"], + ExpectedOutputDescription = + [ + "The first answer should explain only why the sky is blue, and the judge should mark red_sunsets as missing with a low probability.", + "A later answer should also explain why sunsets are red, and the judge should mark red_sunsets as met for it.", + "Every numbered answer (Answer 1, Answer 2, and so on) should be followed by a Judge block with probabilities. The Final answer section repeats the last judged answer and has no Judge block of its own.", + "The final answer should explain both why the sky is blue and why sunsets are red.", + "The output should not contain error messages or stack traces.", + ], + }, + + new SampleDefinition + { + Name = "Agent_TypeSafe_Step02_DecisionTool", + ProjectPath = "samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool", + RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT", "TYPESAFE_API_KEY"], + OptionalEnvironmentVariables = ["FOUNDRY_MODEL"], + MustContain = ["Ticket:", "Tool result:", "department", "The same tool, answered by a local keyword decision client:"], + ExpectedOutputDescription = + [ + "Each ticket should show a tool result with department, urgentProbability, and frustration values, followed by a one-line agent reply.", + "The failing Stripe integration ticket should be routed to Technical with a high urgent probability, and the invoice request should be routed to Billing with a low urgent probability.", + "The last part should show a tool result from the local keyword decision client for the invoice ticket, routed to Billing, followed by an agent reply.", + "The output should not contain error messages or stack traces.", + ], + }, + + new SampleDefinition + { + Name = "Agent_TypeSafe_Step03_DecisionRouting", + ProjectPath = "samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting", + RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT", "TYPESAFE_API_KEY"], + OptionalEnvironmentVariables = ["FOUNDRY_MODEL", "FOUNDRY_REASONING_MODEL"], + MustContain = ["User:", "Route: Fast", "Route: Reasoning", "Agent:"], + ExpectedOutputDescription = + [ + "The question about the capital of France should be routed to Fast and answered with Paris.", + "The demand forecasting request should be routed to Reasoning and answered with a comparison of three methods and a recommendation.", + "Each route line should show the probabilities of both routes and the model that answered.", + "The output should not contain error messages or stack traces.", + ], + }, + // ── Agents ────────────────────────────────────────────────────────── new SampleDefinition @@ -416,6 +465,29 @@ internal static class AgentsSamples ], }, + new SampleDefinition + { + Name = "Agent_Step25_ClassificationWithJev", + ProjectPath = "samples/02-agents/Agents/Agent_Step25_ClassificationWithJev", + RequiredEnvironmentVariables = ["FOUNDRY_PROJECT_ENDPOINT", "TYPESAFE_API_KEY"], + OptionalEnvironmentVariables = ["FOUNDRY_MODEL"], + MustContain = + [ + "Ticket:", + "Tool result:", + "The same tool, answered by a local keyword classifier:", + "local-keyword-classifier", + ], + ExpectedOutputDescription = + [ + "Each of the three tickets should show a tool result with department, urgent, and frustration answers from a jev model, followed by a one-line agent reply.", + "The failing Stripe integration ticket should be routed to technical and marked urgent, and the invoice request should be routed to billing and not urgent.", + "The vague account ticket may be sent to human review when the department confidence is low.", + "The last part should show a tool result from the local-keyword-classifier model for the invoice ticket, followed by an agent reply.", + "The output should not contain error messages or stack traces.", + ], + }, + // ── AgentSkills ───────────────────────────────────────────────────── new SampleDefinition diff --git a/dotnet/samples/02-agents/AgentProviders/README.md b/dotnet/samples/02-agents/AgentProviders/README.md index 32c0afb1025..ebd09d35646 100644 --- a/dotnet/samples/02-agents/AgentProviders/README.md +++ b/dotnet/samples/02-agents/AgentProviders/README.md @@ -94,6 +94,14 @@ covering basics, function tools, structured output, middleware, MCP, code interp | [Conversation](./openai/Agent_OpenAI_Step05_Conversation/) | Multi-turn conversations with OpenAI | | [Code Interpreter](./openai/Agent_OpenAI_Step06_CodeInterpreterFileDownload/) | Code interpreter with file downloads | +### [TypeSafe](./typesafe/) + +| Sample | Description | +| --- | --- | +| [Loop judge](./typesafe/Agent_TypeSafe_Step01_LoopJudge/) | Use Jev as the judge of a LoopAgent, through an IDecisionClient and a typed decision definition | +| [Decision tool](./typesafe/Agent_TypeSafe_Step02_DecisionTool/) | Give an agent a decision as a tool with `DecisionDefinition.AsAIFunction`, and answer it with Jev or a local decision client | +| [Decision routing](./typesafe/Agent_TypeSafe_Step03_DecisionRouting/) | Route each request of an agent to a fast or a reasoning model, with Jev choosing the route through `RoutingChatClient` | + ## Running the samples Navigate to a sample directory and run: diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/Agent_TypeSafe_Step01_LoopJudge.csproj b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/Agent_TypeSafe_Step01_LoopJudge.csproj new file mode 100644 index 00000000000..48a53996f27 --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/Agent_TypeSafe_Step01_LoopJudge.csproj @@ -0,0 +1,20 @@ + + + + Exe + net10.0 + + enable + enable + + + + + + + + + + + + diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/Program.cs b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/Program.cs new file mode 100644 index 00000000000..fd303db594e --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/Program.cs @@ -0,0 +1,120 @@ +// Copyright (c) Microsoft. All rights reserved. + +// This sample uses Jev, the TypeSafe System One model, as the judge of a LoopAgent. A Foundry agent writes the +// answer. After each answer, Jev checks every criterion with its own yes or no question, and the loop sends the agent +// the criteria that are still missing, until the answer meets all of them. The judge uses the decision API proposed +// for Microsoft.Extensions.AI: an IDecisionClient and a typed DecisionDefinition. + +#pragma warning disable MAAI001 // LoopAgent and DelegateLoopEvaluator are experimental. +#pragma warning disable MEAI001 // The decision API is experimental. + +using System.ClientModel; +using Azure.AI.Projects; +using Azure.Identity; +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.TypeSafe; +using Microsoft.Extensions.AI; + +var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."); +var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini"; +var typeSafeApiKey = Environment.GetEnvironmentVariable("TYPESAFE_API_KEY") ?? throw new InvalidOperationException("TYPESAFE_API_KEY is not set."); + +// 1. The criteria, as a typed verdict. Each property is a Binary question, whose answer is the probability that the +// answer meets the criterion, so the judge reports exactly which criteria are missing instead of a single verdict. The +// questions describe what a good answer contains; wording that steers the judge, such as "only say yes if", tends to +// push every answer one way. +DecisionDefinition criteria = DecisionDefinition.Create(builder => +{ + builder.BinaryProbability(verdict => verdict.BlueSky, "Does `answer` explain why the daytime sky appears blue?"); + builder.BinaryProbability(verdict => verdict.RedSunsets, "Does `answer` explain why sunsets appear red or orange?"); + builder.BinaryProbability(verdict => verdict.PlainLanguage, "Does `answer` use clear language suitable for a general audience?"); +}); + +// A criterion is met when its probability is above this threshold. 0.5 is not calibrated for any task: a higher value +// accepts fewer answers that still miss a criterion, at the cost of more loop runs. Choose it on labeled examples of +// your own answers. +const double CriterionThreshold = 0.5; + +// 2. The agent that writes the answers. Its instructions hold back part of the first answer, so the judge has a gap +// to find and the loop runs more than once. +// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production. +// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid +// latency issues, unintended credential probing, and potential security risks from fallback mechanisms. +AIAgent answerer = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential()).AsAIAgent( + model: deploymentName, + name: "Answerer", + instructions: """ + You answer science questions for a general audience in one short paragraph. + Your first answer is a single sentence about why the daytime sky is blue. It does not mention sunsets, even + if the user asks about them. + When feedback lists missing points, rewrite the whole answer so that it covers them too. + """); + +// 3. The judge. AIJudgeLoopEvaluator asks a chat client for JSON structured output, which a decision model does not +// write, so a DelegateLoopEvaluator asks the decision client the criteria questions instead. The state is the request +// and the latest answer. +using IDecisionClient judge = new JevDecisionClient(new ApiKeyCredential(typeSafeApiKey)); +bool accepted = false; +var evaluator = new DelegateLoopEvaluator(async (context, cancellationToken) => +{ + Console.WriteLine($"\nAnswer {context.Iteration}:\n{context.LastResponse.Text}"); + string request = string.Join("\n", context.InitialMessages.Select(message => message.Text)); + List missing = await JudgeAsync(request, context.LastResponse.Text, cancellationToken); + accepted = missing.Count == 0; + + // The feedback names the missing criteria, which is the gap analysis that a generative judge would write. + return accepted + ? LoopEvaluation.Stop() + : LoopEvaluation.Continue($"Your answer does not yet: {string.Join("; ", missing)}. Rewrite the whole answer so that it does."); +}); + +// 4. The loop re-runs the agent until the judge stops it. MaxIterations bounds the cost if the answer never passes. +const int MaxIterations = 3; +const string Request = "Explain why the sky is blue and why sunsets are red."; +AIAgent loop = new LoopAgent(answerer, evaluator, new LoopAgentOptions { MaxIterations = MaxIterations, NonStreamingReturnsLastResponseOnly = true }); +AgentResponse response = await loop.RunAsync(Request); + +// LoopAgent stops at MaxIterations before it calls the evaluator, so an answer from the last allowed run has not been +// judged yet. Judging it here keeps the final answer from being presented as accepted when it may miss a criterion. +if (!accepted) +{ + Console.WriteLine($"\nAnswer {MaxIterations} (the last run the loop allows):\n{response.Text}"); + accepted = (await JudgeAsync(Request, response.Text, CancellationToken.None)).Count == 0; +} + +Console.WriteLine(accepted ? "\nFinal answer:" : "\nFinal answer (some criteria are still missing):"); +Console.WriteLine(response.Text); + +// Asks the judge whether the answer meets each criterion, prints the probabilities, and returns the missing criteria. +async Task> JudgeAsync(string request, string answer, CancellationToken cancellationToken) +{ + DecisionResponse decision = await judge.GetResponseAsync(new JudgedAnswer(request, answer), criteria, cancellationToken: cancellationToken); + Verdict verdict = decision.Result; + + Console.WriteLine("Judge:"); + List missing = []; + foreach ((string name, string description, double probability) in new[] + { + ("blue_sky", "explain why the daytime sky appears blue", verdict.BlueSky), + ("red_sunsets", "explain why sunsets appear red or orange", verdict.RedSunsets), + ("plain_language", "use clear language suitable for a general audience", verdict.PlainLanguage), + }) + { + bool met = probability > CriterionThreshold; + Console.WriteLine($" {name}: {(met ? "met" : "missing")} (probability {probability:F2})"); + if (!met) + { + missing.Add(description); + } + } + + return missing; +} + +/// The state the judge reads: the user's request and the answer to judge. +internal sealed record JudgedAnswer(string Request, string Answer); + +/// The probability that the answer meets each criterion. +#pragma warning disable CA1812 // Instantiated by the decision definition, which creates the result from the answers. +internal sealed record Verdict(double BlueSky, double RedSunsets, double PlainLanguage); +#pragma warning restore CA1812 diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/README.md b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/README.md new file mode 100644 index 00000000000..897b4d105f1 --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step01_LoopJudge/README.md @@ -0,0 +1,109 @@ +# Jev as the judge of a loop + +This sample uses Jev, the TypeSafe System One model, as the judge of a `LoopAgent`. A Foundry agent writes the +answer, and Jev decides whether the answer is complete. The judge uses the decision API proposed for +Microsoft.Extensions.AI ([dotnet/extensions#7795](https://github.com/dotnet/extensions/pull/7795)), which +`Microsoft.Agents.AI.Abstractions` carries until it ships: `JevDecisionClient` is an `IDecisionClient`, and the criteria +are a typed `DecisionDefinition`. Any other `IDecisionClient` can be the judge without changing the loop. + +A generative judge writes a verdict and a gap analysis. A decision model writes no text, so the sample asks one Binary +question per criterion instead. Each answer is the probability, from 0 to 1, that the answer meets that criterion, so +the judge reports exactly which criteria are missing: + +```text +Judge: + blue_sky: met (probability 0.99) + red_sunsets: missing (probability 0.02) + plain_language: met (probability 0.92) +``` + +The loop turns the missing criteria into the feedback for the next run, and stops when every criterion is met or after +three runs. The agent's instructions hold back part of the first answer on purpose, so the loop visibly runs twice. + +`LoopAgent` checks `MaxIterations` before it calls the evaluator, so when the loop reaches its limit, the answer of the +last run has not been judged. The sample judges that answer after the loop and labels the final answer when some +criteria are still missing, instead of presenting it as accepted. + +## The criteria as a typed definition + +Each criterion is a `double` property of `Verdict`, declared as a Binary probability with its question: + +```csharp +DecisionDefinition criteria = DecisionDefinition.Create(builder => +{ + builder.BinaryProbability(verdict => verdict.BlueSky, "Does `answer` explain why the daytime sky appears blue?"); + builder.BinaryProbability(verdict => verdict.RedSunsets, "Does `answer` explain why sunsets appear red or orange?"); + builder.BinaryProbability(verdict => verdict.PlainLanguage, "Does `answer` use clear language suitable for a general audience?"); +}); +``` + +The state is a `JudgedAnswer(Request, Answer)` record, so the questions can refer to its fields in backticks. One call +answers every criterion and returns a `Verdict` with the probabilities, plus the complete decision response as +`Evidence`: + +```csharp +DecisionResponse decision = await judge.GetResponseAsync(new JudgedAnswer(request, answer), criteria); +``` + +The same pattern works with `builder.Score` for a graded rubric, or `builder.Choice` with an enum to classify what kind +of revision is needed. + +## Why a delegate evaluator + +`AIJudgeLoopEvaluator` asks a chat client for a `JudgeVerdict` as JSON structured output, which a decision model does +not write. The sample wraps the decision client in a `DelegateLoopEvaluator` instead: + +```csharp +var evaluator = new DelegateLoopEvaluator(async (context, cancellationToken) => +{ + string request = string.Join("\n", context.InitialMessages.Select(message => message.Text)); + List missing = await JudgeAsync(request, context.LastResponse.Text, cancellationToken); + accepted = missing.Count == 0; + return accepted + ? LoopEvaluation.Stop() + : LoopEvaluation.Continue($"Your answer does not yet: {string.Join("; ", missing)}. ..."); +}); +``` + +`JudgeAsync` returns the criteria whose probability is at or below `CriterionThreshold`. + +## Writing criteria for a judge + +- **Choose the threshold on your own data.** The sample treats a criterion as met when its probability is above + `CriterionThreshold`, which is 0.5. That value is not calibrated for any task. The threshold trades two errors + against each other: a higher value accepts fewer answers that still miss a criterion, and costs more loop runs, while + a lower value stops sooner and lets more incomplete answers through. Pick it from labeled examples of the answers your + agent writes, based on which error costs you more. +- **Describe the criterion, do not steer the judge.** Ask what a good answer contains, as the sample does ("Does + `answer` explain why sunsets appear red or orange?"). Directional wording such as "only say yes if" or + "lean towards yes" tends to push every answer the same way instead of making the judge more accurate. When a + criterion is hard to judge, a neutral description of what is being judged helps more than stronger wording. +- **Ask about the response, not the topic.** When the conversation contains harmful or sensitive content, a question + such as "Is this safe?" can be read as a question about that content rather than about the answer. A correct + refusal could then look like a missing criterion, and the loop would keep revising an answer that was already right. + Ask how the response handles the request, for example "Does `answer` decline to give dangerous instructions?", and + check such criteria on labeled examples, including refusals, before relying on them. + +## Prerequisites + +- .NET 10 SDK or later +- A Microsoft Foundry project with a deployed chat model +- Azure CLI installed and authenticated (`az login`) +- A TypeSafe API key + +Set the environment variables: + +```powershell +$env:FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" +$env:FOUNDRY_MODEL="gpt-5.4-mini" # Optional, defaults to gpt-5.4-mini +$env:TYPESAFE_API_KEY="your-typesafe-api-key" +``` + +## Running the sample + +```powershell +dotnet run +``` + +The sample prints each answer with the judge's probabilities, then the final answer, labeled when some criteria are +still missing. The wording of the answers and the exact probabilities vary between runs. diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/Agent_TypeSafe_Step02_DecisionTool.csproj b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/Agent_TypeSafe_Step02_DecisionTool.csproj new file mode 100644 index 00000000000..48a53996f27 --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/Agent_TypeSafe_Step02_DecisionTool.csproj @@ -0,0 +1,20 @@ + + + + Exe + net10.0 + + enable + enable + + + + + + + + + + + + diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/KeywordDecisionClient.cs b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/KeywordDecisionClient.cs new file mode 100644 index 00000000000..9242e06e73c --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/KeywordDecisionClient.cs @@ -0,0 +1,78 @@ +// Copyright (c) Microsoft. All rights reserved. + +#pragma warning disable MEAI001 // The decision API is experimental. + +using System.Text.RegularExpressions; +using Microsoft.Extensions.AI; + +/// +/// A local that answers by matching words, as a stand-in for another decision model. +/// +/// +/// It knows only this sample's questions: a Choice picks the candidate whose description shares the most words with the +/// ticket, a Binary question looks for urgent words, and a Score counts frustrated words. Like any decision client, it +/// answers every question with a complete distribution. +/// +internal sealed partial class KeywordDecisionClient : IDecisionClient +{ + private static readonly string[] s_urgentWords = ["asap", "urgent", "immediately", "losing", "down", "blocked"]; + private static readonly string[] s_frustratedWords = ["still", "keeps", "again", "losing", "days", "failing"]; + + public Task GetResponseAsync(DecisionRequest request, DecisionOptions? options = null, CancellationToken cancellationToken = default) + { + HashSet words = Stems(request.State.GetRawText()); + List answers = [.. request.Questions.Select(question => Answer(question, words))]; + return Task.FromResult(new DecisionResponse(request, answers, new DecisionProvenance(providerName: "local", modelId: "local-keyword-matcher"))); + } + + public object? GetService(Type serviceType, object? serviceKey = null) => + serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + + public void Dispose() + { + } + + private static DecisionAnswer Answer(DecisionQuestion question, HashSet words) => + question switch + { + ChoiceDecisionQuestion choice => Choose(choice, words), + BinaryDecisionQuestion binary => new BinaryDecisionAnswer(binary.Id, s_urgentWords.Any(word => words.Contains(Stem(word))) ? 0.9 : 0.1), + ScoreDecisionQuestion score => Rate(score, words), + _ => throw new NotSupportedException($"The keyword client does not answer {question.Kind} questions."), + }; + + // Each candidate scores one plus the number of its description words in the ticket, and the scores become the + // probabilities. + private static ChoiceDecisionAnswer Choose(ChoiceDecisionQuestion choice, HashSet words) + { + double[] scores = [.. choice.Candidates.Select(candidate => 1.0 + Stems(candidate.Description).Count(words.Contains))]; + double total = scores.Sum(); + int selected = Array.IndexOf(scores, scores.Max()); + return new ChoiceDecisionAnswer( + choice.Id, + choice.Candidates[selected].Id, + [.. choice.Candidates.Select((candidate, index) => new DecisionProbability(candidate.Id, scores[index] / total))]); + } + + // The level is the number of frustrated words, at most the top level, with most of the probability on it. + private static ScoreDecisionAnswer Rate(ScoreDecisionQuestion score, HashSet words) + { + int top = score.Levels.Count - 1; + int level = Math.Min(top, s_frustratedWords.Count(word => words.Contains(Stem(word))) / 2); + double[] probabilities = [.. score.Levels.Select((_, index) => index == level ? 0.8 : 0.2 / top)]; + double expected = Math.Round(probabilities.Select((probability, index) => probability * index).Sum(), 10); + return new ScoreDecisionAnswer( + score.Id, + expected, + [.. score.Levels.Select((level, index) => new DecisionProbability(level.Id, probabilities[index]))]); + } + + // Words are compared by their first five letters, ignoring case, so "Invoice" matches "invoices". + private static HashSet Stems(string text) => + new(WordPattern().Matches(text).Select(match => Stem(match.Value)), StringComparer.OrdinalIgnoreCase); + + private static string Stem(string word) => word.Length > 5 ? word[..5] : word; + + [GeneratedRegex("[a-z]+", RegexOptions.IgnoreCase)] + private static partial Regex WordPattern(); +} diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/Program.cs b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/Program.cs new file mode 100644 index 00000000000..18ab00d6c7e --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/Program.cs @@ -0,0 +1,122 @@ +// Copyright (c) Microsoft. All rights reserved. + +// This sample gives a Foundry agent a decision as a tool, with the decision API proposed for Microsoft.Extensions.AI. +// The application fixes the questions in a typed DecisionDefinition, and the agent only passes the ticket: Jev, the +// TypeSafe System One model, answers the questions, and the agent replies from the typed result. The same tool is then +// answered by a local IDecisionClient, without changing the agent. + +#pragma warning disable MEAI001 // The decision API is experimental. + +using System.ClientModel; +using System.ComponentModel; +using Azure.AI.Projects; +using Azure.Identity; +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.TypeSafe; +using Microsoft.Extensions.AI; + +var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."); +var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini"; +var typeSafeApiKey = Environment.GetEnvironmentVariable("TYPESAFE_API_KEY") ?? throw new InvalidOperationException("TYPESAFE_API_KEY is not set."); + +// +// 1. The questions, as a typed result. The enum property is a Choice among its values, the probability is a Binary +// question, and the frustration is a Score on an ordered rubric. The [Description] attributes on TicketAnalysis and +// Department, at the end of this file, are the question instructions and the choice descriptions. +DecisionDefinition analysis = DecisionDefinition.Create(builder => +{ + builder.Choice(result => result.Department); + builder.BinaryProbability(result => result.UrgentProbability); + builder.Score(result => result.Frustration, [new("calm", "The customer is calm."), new("annoyed", "The customer is annoyed."), new("angry", "The customer is angry.")]); +}); +// + +// +// 2. The tool. Its only argument is the ticket. The questions and the decision client belong to the application, so +// the model cannot change what is asked, and the result is the typed TicketAnalysis. +var toolOptions = new AIFunctionFactoryOptions +{ + Name = "analyze_ticket", + Description = "Classifies a support ticket: the department that should handle it, the probability that it is urgent, and how frustrated the customer is.", +}; + +using IDecisionClient jev = new JevDecisionClient(new ApiKeyCredential(typeSafeApiKey)); +AIFunction analyzeTicket = analysis.AsAIFunction(jev, toolOptions); +// + +const string Instructions = """ + You triage customer support tickets. For each ticket, call analyze_ticket with the ticket text, then reply in one + line with the department, whether the ticket is urgent (when the urgent probability is above 0.5), and the + frustration level (0 is calm, 1 annoyed, 2 angry). + """; + +// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production. +// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid +// latency issues, unintended credential probing, and potential security risks from fallback mechanisms. +var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential()); +AIAgent agent = projectClient.AsAIAgent(model: deploymentName, instructions: Instructions, name: "TicketTriage", tools: [analyzeTicket]); + +string[] tickets = +[ + "I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.", + "Hi, could you send me a copy of last month's invoice when you get a chance? Thanks!", +]; + +foreach (string ticket in tickets) +{ + await TriageAsync(agent, ticket); +} + +// +// 3. The same definition and agent instructions, answered by another decision client. Any IDecisionClient works, +// such as another decision model or, here, a local keyword matcher. +using IDecisionClient keywords = new KeywordDecisionClient(); +AIAgent localAgent = projectClient.AsAIAgent( + model: deploymentName, + instructions: Instructions, + name: "LocalTicketTriage", + tools: [analysis.AsAIFunction(keywords, toolOptions)]); +// + +Console.WriteLine("The same tool, answered by a local keyword decision client:"); +Console.WriteLine(); +await TriageAsync(localAgent, tickets[1]); + +static async Task TriageAsync(AIAgent agent, string ticket) +{ + AgentResponse response = await agent.RunAsync(ticket); + + Console.WriteLine($"Ticket: {ticket}"); + foreach (FunctionResultContent result in response.Messages.SelectMany(static m => m.Contents).OfType()) + { + Console.WriteLine($"Tool result: {result.Result}"); + } + + Console.WriteLine($"Agent: {response.Text}"); + Console.WriteLine(); +} + +#pragma warning disable CA1812 // SupportTicket is the tool argument, and TicketAnalysis is created from the answers. + +/// The tool's input: the ticket that the agent passes. +internal sealed record SupportTicket([Description("The ticket text, as the customer wrote it.")] string Text); + +/// The teams that handle tickets. Each description tells the decision model what belongs to the team. +internal enum Department +{ + [Description("Payments, invoices, refunds, and charges.")] + Billing, + + [Description("Bugs, outages, errors, and integrations.")] + Technical, + + [Description("Plans, pricing, upgrades, and new purchases.")] + Sales, +} + +/// The tool's result. Each description is the instruction of the question that fills the property. +internal sealed record TicketAnalysis( + [Description("Which team should handle the ticket?")] Department Department, + [Description("Does the ticket need urgent attention?")] double UrgentProbability, + [Description("How frustrated is the customer who wrote the ticket?")] double Frustration); +#pragma warning restore CA1812 diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/README.md b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/README.md new file mode 100644 index 00000000000..58de761fc9e --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/README.md @@ -0,0 +1,65 @@ +# A decision as an agent tool + +This sample gives a Foundry agent a decision as a tool, with the decision API proposed for Microsoft.Extensions.AI +([dotnet/extensions#7795](https://github.com/dotnet/extensions/pull/7795) and +[#7796](https://github.com/dotnet/extensions/pull/7796)), which `Microsoft.Agents.AI.Abstractions` carries until it ships. +The agent triages support tickets: it calls the tool with the ticket, and replies from the typed result. + +## How it works + +The application declares the questions once, as a typed result: + +```csharp +DecisionDefinition analysis = DecisionDefinition.Create(builder => +{ + builder.Choice(result => result.Department); + builder.BinaryProbability(result => result.UrgentProbability); + builder.Score(result => result.Frustration, [new("calm", "..."), new("annoyed", "..."), new("angry", "...")]); +}); +``` + +`Department` is an enum, so its question is a Choice among its values, and the `[Description]` of each value tells the +decision model what belongs to it. The `[Description]` of each `TicketAnalysis` parameter is the instruction of its +question. + +`AsAIFunction` turns the definition into the agent's tool: + +```csharp +using IDecisionClient jev = new JevDecisionClient(new ApiKeyCredential(typeSafeApiKey)); +AIFunction analyzeTicket = analysis.AsAIFunction(jev, new AIFunctionFactoryOptions { Name = "analyze_ticket", ... }); +``` + +The tool's only argument is the `SupportTicket`. The questions and the decision client belong to the application, so +the model cannot change what is asked or which labels exist, and the result is a `TicketAnalysis` rather than raw +answers. Jev, the TypeSafe System One model, answers all three questions in one call. + +The last part answers the same tool with `KeywordDecisionClient`, a local `IDecisionClient` that matches words. The +agent and the definition do not change, which is how another decision model, such as Azure OpenAI Decisions, would be +used. + +Compare with [Agent_Step25_ClassificationWithJev](../../../Agents/Agent_Step25_ClassificationWithJev/), where the +agent's model writes the questions on every call through `JevAIToolBuilder`. + +## Prerequisites + +- .NET 10 SDK or later +- A Microsoft Foundry project with a deployed chat model +- Azure CLI installed and authenticated (`az login`) +- A TypeSafe API key + +Set the environment variables: + +```powershell +$env:FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" +$env:FOUNDRY_MODEL="gpt-5.4-mini" # Optional, defaults to gpt-5.4-mini +$env:TYPESAFE_API_KEY="your-typesafe-api-key" +``` + +## Running the sample + +```powershell +dotnet run +``` + +For each ticket, the sample prints the tool result and the agent's one-line reply. The exact probabilities vary between +runs. diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/Agent_TypeSafe_Step03_DecisionRouting.csproj b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/Agent_TypeSafe_Step03_DecisionRouting.csproj new file mode 100644 index 00000000000..48a53996f27 --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/Agent_TypeSafe_Step03_DecisionRouting.csproj @@ -0,0 +1,20 @@ + + + + Exe + net10.0 + + enable + enable + + + + + + + + + + + + diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/Program.cs b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/Program.cs new file mode 100644 index 00000000000..6657b491a47 --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/Program.cs @@ -0,0 +1,92 @@ +// Copyright (c) Microsoft. All rights reserved. + +// This sample routes each request of an agent to a fast model or a reasoning model, and a decision model chooses the +// route. RoutingChatClient from Microsoft.Extensions.AI asks a selector which chat client handles each call, and the +// selector asks Jev, the TypeSafe System One model, a Choice question through the decision API proposed for +// Microsoft.Extensions.AI. The agent itself is an ordinary agent over the router. + +#pragma warning disable MEAI001 // RoutingChatClient and the decision API are experimental. + +using System.ClientModel; +using System.ComponentModel; +using Azure.AI.Extensions.OpenAI; +using Azure.AI.Projects; +using Azure.Identity; +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.TypeSafe; +using Microsoft.Extensions.AI; + +var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."); +var fastModel = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini"; +var reasoningModel = Environment.GetEnvironmentVariable("FOUNDRY_REASONING_MODEL") ?? fastModel; +var typeSafeApiKey = Environment.GetEnvironmentVariable("TYPESAFE_API_KEY") ?? throw new InvalidOperationException("TYPESAFE_API_KEY is not set."); + +// 1. The route question: a Choice among the values of Route, whose descriptions tell the decision model when to pick +// each one. +DecisionDefinition routing = DecisionDefinition.Create(builder => builder.Choice(decision => decision.Route)); + +// 2. One chat client per route. Each one is bound to its own deployment. +// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production. +// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid +// latency issues, unintended credential probing, and potential security risks from fallback mechanisms. +var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential()); +using IChatClient fast = projectClient.GetProjectOpenAIClient().GetProjectResponsesClientForModel(fastModel).AsIChatClientWithStoredOutputDisabled(fastModel); +using IChatClient reasoning = projectClient.GetProjectOpenAIClient().GetProjectResponsesClientForModel(reasoningModel).AsIChatClientWithStoredOutputDisabled(reasoningModel); +Dictionary clients = new() { [Route.Fast] = fast, [Route.Reasoning] = reasoning }; + +// +// 3. The router. Before each call, the selector sends the conversation to the decision client and forwards the call to +// the chat client of the chosen route. The decision returns the whole distribution, so the route's certainty is +// visible, and the application could, for example, prefer the reasoning model when the choice is close. +using IDecisionClient jev = new JevDecisionClient(new ApiKeyCredential(typeSafeApiKey)); +using RoutingChatClient router = RoutingChatClient.Create(async (context, cancellationToken) => +{ + var state = new RoutingState([.. context.Messages.Select(message => new RoutingMessage(message.Role.Value, message.Text))]); + DecisionResponse decision = await jev.GetResponseAsync(state, routing, cancellationToken: cancellationToken); + IReadOnlyDictionary distribution = decision.GetDistribution(result => result.Route); + + Route route = decision.Result.Route; + Console.WriteLine($"Route: {route} (fast {distribution[Route.Fast]:F2}, reasoning {distribution[Route.Reasoning]:F2}), model {(route == Route.Fast ? fastModel : reasoningModel)}"); + return clients[route]; +}); +// + +// 4. The agent. It knows nothing about the routing; every model call goes through the router. +AIAgent agent = router.AsAIAgent(name: "Assistant", instructions: "You are a helpful assistant. Answer in at most three sentences."); + +string[] requests = +[ + "What is the capital of France?", + "We are launching a product with no sales history. Compare three ways to forecast its first-year demand, and recommend one with its main risk.", +]; + +foreach (string request in requests) +{ + Console.WriteLine($"User: {request}"); + AgentResponse response = await agent.RunAsync(request); + Console.WriteLine($"Agent: {response.Text}"); + Console.WriteLine(); +} + +/// The routes. Each description tells the decision model when to pick the route. +internal enum Route +{ + [Description("Short, routine requests where a quick answer is enough.")] + Fast, + + [Description("Requests that need multi-step analysis, comparisons, or careful planning.")] + Reasoning, +} + +#pragma warning disable CA1812 // RouteDecision is created from the answers. + +/// The decision: the route of the latest request. +internal sealed record RouteDecision([Description("Which model should answer the latest user request?")] Route Route); + +#pragma warning restore CA1812 + +/// The state the decision model reads: the conversation, as role and text. +internal sealed record RoutingState(IReadOnlyList Messages); + +/// One message of the conversation. +internal sealed record RoutingMessage(string Role, string Text); diff --git a/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/README.md b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/README.md new file mode 100644 index 00000000000..e06eeeda0ae --- /dev/null +++ b/dotnet/samples/02-agents/AgentProviders/typesafe/Agent_TypeSafe_Step03_DecisionRouting/README.md @@ -0,0 +1,69 @@ +# Routing an agent's requests with a decision model + +This sample routes each request of an agent to a fast model or a reasoning model, and a decision model chooses the +route. It combines `RoutingChatClient` from Microsoft.Extensions.AI with the decision API proposed for +Microsoft.Extensions.AI ([dotnet/extensions#7795](https://github.com/dotnet/extensions/pull/7795) and +[#7796](https://github.com/dotnet/extensions/pull/7796)), which `Microsoft.Agents.AI.Abstractions` carries until it ships. + +## How it works + +The route is a Choice among the values of an enum, whose descriptions say when to pick each one: + +```csharp +internal enum Route +{ + [Description("Short, routine requests where a quick answer is enough.")] + Fast, + + [Description("Requests that need multi-step analysis, comparisons, or careful planning.")] + Reasoning, +} + +DecisionDefinition routing = DecisionDefinition.Create(builder => builder.Choice(decision => decision.Route)); +``` + +`RoutingChatClient.Create` calls a selector before every model call. The selector sends the conversation to the +decision client, and returns the chat client of the chosen route: + +```csharp +RoutingChatClient router = RoutingChatClient.Create(async (context, cancellationToken) => +{ + var state = new RoutingState([.. context.Messages.Select(message => new RoutingMessage(message.Role.Value, message.Text))]); + DecisionResponse decision = await jev.GetResponseAsync(state, routing, cancellationToken: cancellationToken); + return clients[decision.Result.Route]; +}); + +AIAgent agent = router.AsAIAgent(name: "Assistant", instructions: "..."); +``` + +The agent knows nothing about the routing. The decision also returns the whole distribution (`GetDistribution`), so +the application can see how certain the route is, and could, for example, prefer the reasoning model when the choice +is close. + +Each chat client is bound to its own deployment. `RoutingChatClient` forwards the caller's `ChatOptions`, so if your +agent sets `ChatOptions.ModelId`, make each routed client ignore or reject a model that is not its own. + +## Prerequisites + +- .NET 10 SDK or later +- A Microsoft Foundry project with two deployed chat models: a fast one and a reasoning one +- Azure CLI installed and authenticated (`az login`) +- A TypeSafe API key + +Set the environment variables: + +```powershell +$env:FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" +$env:FOUNDRY_MODEL="gpt-5.4-mini" # Optional fast model, defaults to gpt-5.4-mini +$env:FOUNDRY_REASONING_MODEL="your-reasoning-model" # Optional, defaults to FOUNDRY_MODEL +$env:TYPESAFE_API_KEY="your-typesafe-api-key" +``` + +## Running the sample + +```powershell +dotnet run +``` + +For each request, the sample prints the route with both probabilities and the model that answered, followed by the +agent's answer. A short factual question goes to the fast model, and a planning question to the reasoning model. diff --git a/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/Agent_Step25_ClassificationWithJev.csproj b/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/Agent_Step25_ClassificationWithJev.csproj new file mode 100644 index 00000000000..1c976a48330 --- /dev/null +++ b/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/Agent_Step25_ClassificationWithJev.csproj @@ -0,0 +1,21 @@ + + + + Exe + net10.0 + + enable + enable + + + + + + + + + + + + + diff --git a/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/KeywordClassifier.cs b/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/KeywordClassifier.cs new file mode 100644 index 00000000000..338dd1e7dc6 --- /dev/null +++ b/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/KeywordClassifier.cs @@ -0,0 +1,60 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Diagnostics.CodeAnalysis; + +/// +/// A local classifier that stands in for another classification client. It has its own request and response types, +/// knows nothing about Jev, and needs no network: it scores each option by the words it shares with the text. +/// +[SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by the service provider")] +internal sealed class KeywordClassifier +{ + private static readonly char[] s_separators = [' ', ',', '.', '!', '?', ';', ':', '\'', '"', '(', ')', '-', '\n', '\r', '\t']; + + public Task ClassifyAsync(ClassificationRequest request, CancellationToken cancellationToken) + { + HashSet words = Words(request.Text); + var results = new Dictionary(); + foreach (ClassificationTask task in request.Tasks) + { + // One point per shared word, plus one so that every option keeps some probability. + double[] points = [.. task.Options.Select(option => Words(option.Description).Count(words.Contains) + 1.0)]; + double total = points.Sum(); + results[task.Id] = new ClassificationResult( + task.Kind, + [.. task.Options.Select((option, index) => new ScoredOption(option.Key, option.Description, points[index] / total))]); + } + + return Task.FromResult(new ClassificationResponse(results)); + } + + // Words are compared in upper case and without a plural "S", so "invoice" matches "invoices". + private static HashSet Words(string text) => + [.. text.ToUpperInvariant().Split(s_separators, StringSplitOptions.RemoveEmptyEntries).Where(word => word.Length > 3).Select(word => word.TrimEnd('S'))]; +} + +/// What the classifier decides for one task. +internal enum ClassificationKind +{ + PickOne, + Rate, + YesNo, +} + +/// The classifier's request: the text and the tasks to decide about it. +internal sealed record ClassificationRequest(string Text, IReadOnlyList Tasks); + +/// One task: pick one option, rate on ordered options, or decide yes or no. +internal sealed record ClassificationTask(string Id, ClassificationKind Kind, IReadOnlyList Options); + +/// An option of a task and the words that describe it. +internal sealed record ClassificationOption(string Key, string Description); + +/// The classifier's response: one result per task, by task ID. +internal sealed record ClassificationResponse(IReadOnlyDictionary Results); + +/// The result of one task: every option with its probability. +internal sealed record ClassificationResult(ClassificationKind Kind, IReadOnlyList Options); + +/// An option with the probability that the classifier gives it. +internal sealed record ScoredOption(string Key, string Description, double Probability); diff --git a/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/Program.cs b/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/Program.cs new file mode 100644 index 00000000000..a228d7573d2 --- /dev/null +++ b/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/Program.cs @@ -0,0 +1,147 @@ +// Copyright (c) Microsoft. All rights reserved. + +// Classification with Jev — Give an agent a fast, calibrated classifier as a tool +// +// Jev, the TypeSafe System One model, does not write text: it answers typed questions +// (choice, score, noul) about a state and returns calibrated probabilities. This sample gives +// a support agent a Jev tool built with JevAIToolBuilder. The agent's model decides which +// questions to ask, Jev answers them, and the model writes the routing decision, sending +// uncertain tickets to a human. The second part answers the same tool with another client. + +using System.ClientModel; +using System.Globalization; +using Azure.AI.Projects; +using Azure.Identity; +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.TypeSafe; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.DependencyInjection; + +var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."); +var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini"; +var typeSafeApiKey = Environment.GetEnvironmentVariable("TYPESAFE_API_KEY") ?? throw new InvalidOperationException("TYPESAFE_API_KEY is not set."); + +// +// The tool's arguments are a Jev request (the state plus typed questions) and its result is the Jev response. +AIFunction jev = new JevAIToolBuilder(new ApiKeyCredential(typeSafeApiKey)).Build(); +// + +const string Instructions = """ + You triage customer support tickets. For every ticket, call ask_system_one once with the ticket text as the + state and these questions: + - "department": a choice between billing (payments, invoices, refunds), technical (bugs, outages, integrations), + and sales (pricing, upgrades, new accounts). + - "urgent": a noul asking whether the customer needs help urgently. + - "frustration": a score with the rubric calm, annoyed, and angry. + Then reply in one line with the department, whether it is urgent, and the frustration level. When the department + confidence is below 0.6, say the ticket needs human review instead of naming a department. + """; + +// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production. +// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid +// latency issues, unintended credential probing, and potential security risks from fallback mechanisms. +var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential()); +AIAgent agent = projectClient.AsAIAgent(model: deploymentName, instructions: Instructions, name: "TicketTriage", tools: [jev]); + +string[] tickets = +[ + "I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.", + "Hi, could you send me a copy of last month's invoice when you get a chance? Thanks!", + "I'd like to talk to someone about my account.", +]; + +foreach (string ticket in tickets) +{ + await TriageAsync(agent, ticket); +} + +// +// The same tool can be answered by another client. UseClient takes the client's operation and two mappers: one from +// the JevRequest that the model writes to the client's request, and one from the client's response to a JevResult. +// The tool resolves the client from the agent's services, in a new scope on every call, and checks the mapped result +// against the request before the model sees it. +AIFunction localJev = new JevAIToolBuilder() + .UseClient( + (classifier, request, cancellationToken) => classifier.ClassifyAsync(request, cancellationToken), + inputMapper: ToClassificationRequest, + outputMapper: ToJevResult) + .Build(); + +using ServiceProvider services = new ServiceCollection() + .AddSingleton() + .BuildServiceProvider(); +AIAgent localAgent = projectClient.AsAIAgent( + model: deploymentName, + instructions: Instructions, + name: "LocalTicketTriage", + tools: [localJev], + services: services); +// + +Console.WriteLine("The same tool, answered by a local keyword classifier:"); +Console.WriteLine(); +await TriageAsync(localAgent, tickets[1]); + +static async Task TriageAsync(AIAgent agent, string ticket) +{ + AgentResponse response = await agent.RunAsync(ticket); + + Console.WriteLine($"Ticket: {ticket}"); + foreach (FunctionResultContent result in response.Messages.SelectMany(static m => m.Contents).OfType()) + { + Console.WriteLine($"Tool result: {result.Result}"); + } + + Console.WriteLine($"Agent: {response.Text}"); + Console.WriteLine(); +} + +// +// Converts each Jev question into a classifier task. The options carry the words the classifier matches. +static ClassificationRequest ToClassificationRequest(JevRequest request) => + new( + request.State.ToString(), + [.. request.Questions.Select(question => question.Value switch + { + JevChoiceQuestion choice => new ClassificationTask( + question.Key, + ClassificationKind.PickOne, + [.. choice.Criteria.Select(criterion => new ClassificationOption(criterion.Key, $"{criterion.Key} {criterion.Value}"))]), + JevScoreQuestion score => new ClassificationTask( + question.Key, + ClassificationKind.Rate, + [.. score.Criteria.Select((level, index) => new ClassificationOption(index.ToString(CultureInfo.InvariantCulture), level.ToString()))]), + JevNoulQuestion noul => new ClassificationTask( + question.Key, + ClassificationKind.YesNo, + [new ClassificationOption("yes", $"{noul.Instructions} {noul.Criteria?.True}"), new ClassificationOption("no", $"{noul.Criteria?.False}")]), + _ => throw new NotSupportedException($"Question '{question.Key}' has an unknown type."), + })]); + +// Converts each classifier result back into the Jev answer of the same kind. +static JevResult ToJevResult(ClassificationResponse response) => new() +{ + Model = "local-keyword-classifier", + Answers = response.Results.ToDictionary(result => result.Key, result => ToJevResponse(result.Value)), + Usage = new JevUsage { InputTokens = 0, OutputTokens = 0 }, +}; + +static JevResponse ToJevResponse(ClassificationResult result) +{ + ScoredOption best = result.Options.MaxBy(option => option.Probability)!; + Dictionary probabilities = result.Options.ToDictionary(option => option.Key, option => option.Probability); + return result.Kind switch + { + ClassificationKind.PickOne => new JevChoiceResponse { Choice = best.Key, Confidence = best.Probability, Probabilities = probabilities }, + ClassificationKind.Rate => new JevScoreResponse + { + // Like Jev, the score is the expected value over the rubric, so it can fall between levels. + Score = result.Options.Sum(option => int.Parse(option.Key, CultureInfo.InvariantCulture) * option.Probability), + Confidence = best.Probability, + Legend = result.Options.ToDictionary(option => option.Key, option => (JevEntry)option.Description), + Probabilities = probabilities, + }, + _ => new JevNoulResponse { Noul = probabilities["yes"] }, + }; +} +// diff --git a/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/README.md b/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/README.md new file mode 100644 index 00000000000..f088f05d5df --- /dev/null +++ b/dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev/README.md @@ -0,0 +1,129 @@ +# Classification with Jev + +This sample gives an agent a classifier tool built with `JevAIToolBuilder` from `Microsoft.Agents.AI.TypeSafe`. + +Jev, the TypeSafe System One model, does not write text. It answers typed questions about a state and returns +calibrated probabilities. An agent's model writes the replies; Jev makes the fast, structured decisions: + +1. The agent's model calls `ask_system_one` with a Jev request: the `state` and the `questions` to + answer about it. +2. Jev answers each question: + + | Question type | What it answers | Answer | + | --- | --- | --- | + | `choice` | Which of these named alternatives? | The selected label, the probability of each label, and a confidence | + | `score` | Which score on an ordered rubric (2 to 10 entries)? | An expected score that can fall between rubric entries, the probability of each score, and a confidence | + | `noul` | Yes or no? | The probability, from 0 to 1, of yes | + + The state, the instructions, and every criterion can be text or JSON, like `EntryType` in the official TypeSafe SDK + ([`@typesafe-ai/sdk`](https://github.com/typesafe-ai/typesafe-sdk-js)). The Jev contract types mirror the SDK's type + names: `JevRequest`, `JevChoiceQuestion`, `JevResult`, `JevChoiceResponse`, and so on. + +3. The model reads the answers and writes the reply. Here it routes each support ticket and sends uncertain tickets to + human review. +4. The same tool is answered by a local keyword classifier instead of the TypeSafe API, through `UseClient` and the + agent's services (see [Using another client](#using-another-client)). + +When the application, rather than the model, decides the questions, give the agent a +`DecisionDefinition.AsAIFunction` tool over `JevDecisionClient` instead, as in +[Decision tool](../../AgentProviders/typesafe/Agent_TypeSafe_Step02_DecisionTool/). + +## Configuring the client + +`JevAIToolBuilder` hides the HTTP client. The API key is an `ApiKeyCredential`, and `JevAIToolOptions` follows the +`ClientPipelineOptions` pattern of the OpenAI and Azure AI client libraries: + +```csharp +var options = new JevAIToolOptions +{ + ModelId = "jev-latest", // default + Transport = new HttpClientPipelineTransport(httpClient), // for example from IHttpClientFactory + NetworkTimeout = TimeSpan.FromSeconds(30), +}; +options.AddPolicy(myPolicy, PipelinePosition.PerCall); // custom pipeline policies + +AIFunction jev = new JevAIToolBuilder(new ApiKeyCredential(apiKey), options).Build(); +``` + +Unset pipeline settings get the defaults of the official SDK: two retries on 408, 429, and 5xx responses (529 means +overloaded), honoring `retry-after-ms` or `Retry-After` up to one minute and otherwise backing off from half a second +to five seconds, and a 10-second timeout per attempt. `Name` and `Description` set what the agent's model sees. + +## Using another client + +Any other client can answer the requests instead of the TypeSafe API. The second part of the sample shows it with +`KeywordClassifier`, a local classifier in [KeywordClassifier.cs](./KeywordClassifier.cs) that has its own request and +response types, knows nothing about Jev, and needs no network. `UseClient` takes the client's operation and two +mappers between the Jev types and the client's types: + +```csharp +AIFunction localJev = new JevAIToolBuilder() + .UseClient( + (classifier, request, cancellationToken) => classifier.ClassifyAsync(request, cancellationToken), + inputMapper: ToClassificationRequest, + outputMapper: ToJevResult) + .Build(); +``` + +`ToClassificationRequest` turns each Jev question into a classifier task, and `ToJevResult` turns each classifier +result back into the Jev answer of the same kind (see the `mappers` region of [Program.cs](./Program.cs)). The tool +checks the mapped result before the model sees it: every question needs an answer of the same type, and a `choice` +answer and its probabilities may only use the labels the question offered. The output mapper receives only the +client's response, so the client's result says which kind of answer it is. + +The keyword classifier is far less certain than Jev, so for the same invoice ticket the agent's confidence rule +usually sends it to human review. Use `UseMapping` instead of `UseClient` for a mapping that is a single delegate from +a `JevRequest` to a `JevResult`. + +## Dependency injection + +Every mapping receives the `IServiceProvider` of the agent that calls the tool. `FunctionInvokingChatClient` passes +it in `AIFunctionArguments.Services`, from the services the agent was created with. `UseClient` resolves +the client from a new scope on every call and disposes the scope afterwards, so scoped and disposable clients work +even though hosted agents are singletons that receive the root provider. The sample registers the classifier in a +`ServiceCollection` and passes the provider to the agent: + +```csharp +using ServiceProvider services = new ServiceCollection() + .AddSingleton() + .BuildServiceProvider(); +AIAgent localAgent = projectClient.AsAIAgent(model: deploymentName, instructions: Instructions, tools: [localJev], services: services); +``` + +In a host, register the client and build the tool in the agent's tool factory: + +```csharp +builder.Services.AddScoped(); +builder.Services.AddAIAgent("triage", Instructions) + .WithAITool(sp => new JevAIToolBuilder() + .UseClient( + (classifier, request, cancellationToken) => classifier.ClassifyAsync(request, cancellationToken), + inputMapper: ToClassificationRequest, + outputMapper: ToJevResult) + .Build()); +``` + +With the TypeSafe API, build the tool in the same `WithAITool` factory and take the credential and the transport from +the container or configuration. + +## Prerequisites + +- .NET 10 SDK or later +- A Microsoft Foundry project with a model deployment +- Azure CLI installed and authenticated (for Azure credential authentication) +- A TypeSafe API key (see the [TypeSafe quickstart](https://docs.typesafe.ai/introduction/quickstart)) + +Set the following environment variables: + +```powershell +$env:FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Foundry project endpoint +$env:FOUNDRY_MODEL="gpt-5.4-mini" # Optional, defaults to gpt-5.4-mini +$env:TYPESAFE_API_KEY="" +``` + +## Run the sample + +```powershell +cd dotnet/samples/02-agents/Agents/Agent_Step25_ClassificationWithJev +dotnet run +``` diff --git a/dotnet/samples/02-agents/Agents/README.md b/dotnet/samples/02-agents/Agents/README.md index 487e7f269a2..356cf1116bf 100644 --- a/dotnet/samples/02-agents/Agents/README.md +++ b/dotnet/samples/02-agents/Agents/README.md @@ -51,6 +51,7 @@ Before you begin, ensure you have the following prerequisites: |[Switching agent operating mode](./Agent_Step22_AgentMode/)|This sample demonstrates how to use the AgentModeProvider to track and switch an agent's operating mode at runtime, including the built-in plan/execute modes and custom modes, with a simple input loop that switches mode using a slash command.| |[Tracking work with a todo list](./Agent_Step23_TodoList/)|This sample demonstrates how to use the TodoProvider to let an agent plan and track multi-step work using a todo list that persists across turns, printing the evolving todo list after each turn.| |[Routing turns across multiple models](./Agent_Step24_MultiModelRouting/)|This sample demonstrates how to use the RoutePersistingRoutingChatClient to route each agent turn to one of several named chat clients, switching the active model mid-conversation while preserving the conversation history.| +|[Classification with Jev](./Agent_Step25_ClassificationWithJev/)|This sample demonstrates how to give an agent a Jev tool built with JevAIToolBuilder, so the agent's model asks Jev typed choice, score, and noul questions and uses the calibrated answers to route support tickets.| ## Running the samples from the console diff --git a/dotnet/samples/AGENTS.md b/dotnet/samples/AGENTS.md index 7c56735e4c7..7b395cd6f2b 100644 --- a/dotnet/samples/AGENTS.md +++ b/dotnet/samples/AGENTS.md @@ -26,7 +26,8 @@ dotnet/samples/ │ │ ├── google-gemini/ # Google Gemini provider sample │ │ ├── ollama/ # Ollama provider sample │ │ ├── onnx/ # ONNX Runtime provider sample -│ │ └── openai/ # OpenAI provider samples +│ │ ├── openai/ # OpenAI provider samples +│ │ └── typesafe/ # TypeSafe (Jev) decision API samples │ ├── AgentOpenTelemetry/ # OpenTelemetry integration │ ├── AgentSkills/ # Agent skills patterns │ ├── AgentWithMemory/ # Memory providers (chat history, Mem0, Valkey, Foundry, AgentMemory) diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/.editorconfig b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/.editorconfig new file mode 100644 index 00000000000..3fde50f62c5 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/.editorconfig @@ -0,0 +1,22 @@ +# These files are a verbatim copy of the decision API proposed for Microsoft.Extensions.AI. The rules below keep them +# compiling unchanged, so the copy can be diffed against the upstream source and deleted when Microsoft.Extensions.AI +# ships the API. See README.md. + +[*.cs] +# The upstream code uses the upstream style and file header. +dotnet_style_qualification_for_field = false:none +dotnet_style_qualification_for_property = false:none +dotnet_style_qualification_for_method = false:none +dotnet_style_qualification_for_event = false:none +dotnet_diagnostic.IDE0001.severity = none +dotnet_diagnostic.IDE0009.severity = none +dotnet_diagnostic.IDE0073.severity = none +dotnet_diagnostic.RCS1146.severity = none +dotnet_diagnostic.RCS1173.severity = none + +# Upstream marks every public type experimental, and the internal helper types that use them do not repeat the attribute. +dotnet_diagnostic.MEAI001.severity = none + +# The overload shapes are the upstream API, which the MEAI API review owns. +dotnet_diagnostic.RS0026.severity = none +dotnet_diagnostic.RS0027.severity = none diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionAnswers.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionAnswers.cs new file mode 100644 index 00000000000..f4227f9b199 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionAnswers.cs @@ -0,0 +1,404 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +#pragma warning disable SA1402 // File may only contain a single type — decision answer types are co-located as one immutable model. +#pragma warning disable SA1649 // File name should match first type name — decision answer types are co-located as one immutable model. +#pragma warning disable CA1032 // Implement standard exception constructors — protocol exceptions expose the protocol-specific constructors. + +using System; +using System.Collections.Generic; +using System.Collections.ObjectModel; +using System.Diagnostics.CodeAnalysis; +using System.Linq; +using System.Text.Json.Serialization; +using Microsoft.Shared.DiagnosticIds; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.AI; + +/// Identifies the precision represented by provider-reported probabilities. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public enum DecisionPrecision +{ + /// The provider reports values without a declared decimal rounding. + HighPrecision, + + /// The provider reports values rounded to four decimal places. + FourDecimalPlaces, + + /// The provider reports values rounded to two decimal places. + TwoDecimalPlaces, +} + +/// Represents one named probability observation. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionProbability +{ + /// Initializes a new instance of the class. + /// The exact opaque candidate or level ID. + /// The probability value. + [JsonConstructor] + public DecisionProbability(string id, double value) + { + Id = Throw.IfNullOrWhitespace(id); + Value = value; + } + + /// Gets the exact opaque candidate or level ID. + public string Id { get; } + + /// Gets the native double probability value. + public double Value { get; } +} + +/// Represents a provider result for one decision question. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")] +[JsonDerivedType(typeof(BinaryDecisionAnswer), "binary")] +[JsonDerivedType(typeof(ChoiceDecisionAnswer), "choice")] +[JsonDerivedType(typeof(ScoreDecisionAnswer), "score")] +public abstract class DecisionAnswer +{ + internal const double DistributionTolerance = 1e-6; + + private protected DecisionAnswer( + string questionId, + DecisionKind kind, + DecisionPrecision precision, + object? rawRepresentation, + IReadOnlyDictionary? additionalProperties) + { + QuestionId = Throw.IfNullOrWhitespace(questionId); + if (!Enum.IsDefined(typeof(DecisionPrecision), precision)) + { + Throw.ArgumentOutOfRangeException(nameof(precision)); + } + + Kind = kind; + Precision = precision; + RawRepresentation = rawRepresentation; + AdditionalProperties = DecisionSnapshots.Properties(additionalProperties); + } + + /// Gets the exact opaque question ID this answer belongs to. + public string QuestionId { get; } + + /// Gets the semantic kind of this answer. + public DecisionKind Kind { get; } + + /// Gets the precision declared for the numeric observations. + public DecisionPrecision Precision { get; } + + /// + /// Gets the provider-owned raw representation, if available. + /// This value is not cloned or used for semantic data and must be treated as diagnostic-only. + /// + [JsonIgnore] + public object? RawRepresentation { get; } + + /// + /// Gets an owned read-only snapshot of provider extension data. + /// Values are shallow-copied references and must be independently safe to share. + /// + public IReadOnlyDictionary? AdditionalProperties { get; } + + internal static void ValidateProbability(double value) + { + if (double.IsNaN(value) || double.IsInfinity(value) || value < 0 || value > 1) + { + throw new DecisionProtocolException("Probability must be finite and in the range [0, 1]."); + } + } + + internal static void ValidateDistribution( + IReadOnlyList probabilities, + DecisionPrecision precision) + { + double sum = 0; + HashSet ids = new(StringComparer.Ordinal); + + foreach (DecisionProbability probability in probabilities) + { + if (probability is null) + { + throw new DecisionProtocolException("A probability distribution cannot contain null entries."); + } + + if (!ids.Add(probability.Id)) + { + throw new DecisionProtocolException("A probability distribution contains a duplicate ID."); + } + + ValidateProbability(probability.Value); + sum += probability.Value; + } + + double tolerance = GetDistributionTolerance(precision, probabilities.Count); + if (Math.Abs(sum - 1) > tolerance) + { + throw new DecisionProtocolException( + "A probability distribution must sum to 1 within the bound allowed by its declared rounding."); + } + + double roundingHalfUnit = GetRoundingHalfUnit(precision); + double lowerBound = 0; + double upperBound = 0; + foreach (DecisionProbability probability in probabilities) + { + lowerBound += Math.Max(0, probability.Value - roundingHalfUnit); + upperBound += Math.Min(1, probability.Value + roundingHalfUnit); + } + + if (lowerBound > 1 + DistributionTolerance || upperBound < 1 - DistributionTolerance) + { + throw new DecisionProtocolException( + "A probability distribution has no normalized latent values consistent with its declared rounding."); + } + } + + internal static double GetDistributionTolerance(DecisionPrecision precision, int count) + { + return precision switch + { + DecisionPrecision.HighPrecision => DistributionTolerance, + DecisionPrecision.FourDecimalPlaces => (count * 0.00005) + DistributionTolerance, + DecisionPrecision.TwoDecimalPlaces => (count * 0.005) + DistributionTolerance, + _ => throw new ArgumentOutOfRangeException(nameof(precision)), + }; + } + + internal static (double Minimum, double Maximum) GetFeasibleExpectedScoreBounds( + IReadOnlyList probabilities, + DecisionPrecision precision) + { + double roundingHalfUnit = GetRoundingHalfUnit(precision); + double lowerMass = 0; + double upperMass = 0; + for (int i = 0; i < probabilities.Count; i++) + { + double probability = probabilities[i].Value; + lowerMass += Math.Max(0, probability - roundingHalfUnit); + upperMass += Math.Min(1, probability + roundingHalfUnit); + } + + if (lowerMass > 1 + DistributionTolerance || upperMass < 1 - DistributionTolerance) + { + throw new DecisionProtocolException( + "A probability distribution has no normalized latent values consistent with its declared rounding."); + } + + double remaining = Math.Max(0, 1 - lowerMass); + double minimum = 0; + for (int i = 0; i < probabilities.Count; i++) + { + double lower = Math.Max(0, probabilities[i].Value - roundingHalfUnit); + double capacity = Math.Min(1, probabilities[i].Value + roundingHalfUnit) - lower; + double allocated = Math.Min(remaining, capacity); + minimum += (lower + allocated) * i; + remaining -= allocated; + } + + remaining = Math.Max(0, 1 - lowerMass); + double maximum = 0; + double[] lowerValues = new double[probabilities.Count]; + for (int i = 0; i < probabilities.Count; i++) + { + lowerValues[i] = Math.Max(0, probabilities[i].Value - roundingHalfUnit); + maximum += lowerValues[i] * i; + } + + for (int i = probabilities.Count - 1; i >= 0; i--) + { + double capacity = Math.Min(1, probabilities[i].Value + roundingHalfUnit) - lowerValues[i]; + double allocated = Math.Min(remaining, capacity); + maximum += allocated * i; + remaining -= allocated; + } + + if (remaining > DistributionTolerance) + { + throw new DecisionProtocolException( + "A probability distribution has no normalized latent values consistent with its declared rounding."); + } + + return (minimum, maximum); + } + + internal static double GetRoundingHalfUnit(DecisionPrecision precision) => + precision switch + { + DecisionPrecision.HighPrecision => 0, + DecisionPrecision.FourDecimalPlaces => 0.00005, + DecisionPrecision.TwoDecimalPlaces => 0.005, + _ => throw new ArgumentOutOfRangeException(nameof(precision)), + }; +} + +/// Represents the probability that a binary proposition is true. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class BinaryDecisionAnswer : DecisionAnswer +{ + /// Initializes a new instance of the class. + [JsonConstructor] + public BinaryDecisionAnswer( + string questionId, + double trueProbability, + DecisionPrecision precision = DecisionPrecision.HighPrecision, + object? rawRepresentation = null, + IReadOnlyDictionary? additionalProperties = null) + : base(questionId, DecisionKind.Binary, precision, rawRepresentation, additionalProperties) + { + ValidateProbability(trueProbability); + TrueProbability = trueProbability; + } + + /// Gets the probability that the proposition is true. + public double TrueProbability { get; } +} + +/// Represents a selected candidate and its complete probability distribution. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class ChoiceDecisionAnswer : DecisionAnswer +{ + /// Initializes a new instance of the class. + [JsonConstructor] + public ChoiceDecisionAnswer( + string questionId, + string selectedCandidateId, + IReadOnlyList probabilities, + DecisionPrecision precision = DecisionPrecision.HighPrecision, + object? rawRepresentation = null, + IReadOnlyDictionary? additionalProperties = null) + : base(questionId, DecisionKind.Choice, precision, rawRepresentation, additionalProperties) + { + SelectedCandidateId = Throw.IfNullOrWhitespace(selectedCandidateId); + _ = Throw.IfNull(probabilities); + + DecisionProbability[] copy = probabilities.ToArray(); + if (copy.Length == 0) + { + throw new DecisionProtocolException("A choice answer requires a complete distribution."); + } + + ValidateDistribution(copy, precision); + if (!Array.Exists(copy, probability => string.Equals(probability.Id, SelectedCandidateId, StringComparison.Ordinal))) + { + throw new DecisionProtocolException("The selected candidate is not present in the distribution."); + } + + Probabilities = Array.AsReadOnly(copy); + } + + /// Gets the exact selected candidate ID. + public string SelectedCandidateId { get; } + + /// Gets the complete ordered candidate distribution. + public IReadOnlyList Probabilities { get; } +} + +/// +/// Represents an ordinal score and its complete level distribution. +/// A reported score is checked against normalized latent values within the declared clipped rounding intervals; observed probabilities and the derived expectation are never repaired. +/// +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class ScoreDecisionAnswer : DecisionAnswer +{ + /// Initializes a new instance of the class. + [JsonConstructor] + public ScoreDecisionAnswer( + string questionId, + double? score, + IReadOnlyList probabilities, + DecisionPrecision precision = DecisionPrecision.HighPrecision, + object? rawRepresentation = null, + IReadOnlyDictionary? additionalProperties = null) + : base(questionId, DecisionKind.Score, precision, rawRepresentation, additionalProperties) + { + _ = Throw.IfNull(probabilities); + + DecisionProbability[] copy = probabilities.ToArray(); + if (copy.Length < 2) + { + throw new DecisionProtocolException("A score answer requires at least two levels."); + } + + ValidateDistribution(copy, precision); + if (score is double reportedScore && + (double.IsNaN(reportedScore) || double.IsInfinity(reportedScore) || reportedScore < 0 || reportedScore > copy.Length - 1)) + { + throw new DecisionProtocolException("A score must be finite and within the ordinal level range."); + } + + double expectedScore = copy.Select((probability, index) => probability.Value * index).Sum(); + if (score is double nativeScore) + { + (double minimum, double maximum) = GetFeasibleExpectedScoreBounds(copy, precision); + double scalarHalfUnit = GetRoundingHalfUnit(precision); + if (nativeScore + scalarHalfUnit + DistributionTolerance < minimum || + nativeScore - scalarHalfUnit - DistributionTolerance > maximum) + { + throw new DecisionProtocolException("The score does not agree with its probability distribution."); + } + } + + Score = score; + ExpectedScore = expectedScore; + Probabilities = Array.AsReadOnly(copy); + } + + /// Gets the provider-reported score, retaining any declared rounding, or when it was not reported. + public double? Score { get; } + + /// Gets the score derived from the observed distribution without repairing it, which may fall outside the ordinal level bounds after rounding. + public double ExpectedScore { get; } + + /// Gets the complete ordered level distribution. + public IReadOnlyList Probabilities { get; } +} + +/// Represents a protocol-invalid provider result. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionProtocolException : Exception +{ + /// Initializes a new instance of the class. + public DecisionProtocolException() + { + } + + /// Initializes a new instance of the class with a message. + public DecisionProtocolException(string message) + : base(message) + { + } + + /// Initializes a new instance of the class with a message and inner exception. + public DecisionProtocolException(string message, Exception innerException) + : base(message, innerException) + { + } +} + +internal static class DecisionSnapshots +{ + internal static IReadOnlyDictionary? Properties( + IReadOnlyDictionary? entries) + { + if (entries is null) + { + return null; + } + + Dictionary copy = new(StringComparer.Ordinal); + foreach (KeyValuePair property in entries) + { + if (copy.ContainsKey(property.Key)) + { + Throw.ArgumentException(nameof(entries), "Extension property names must be unique."); + } + + copy.Add(property.Key, property.Value); + } + + return new ReadOnlyDictionary(copy); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionBinding.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionBinding.cs new file mode 100644 index 00000000000..8c40cd2244d --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionBinding.cs @@ -0,0 +1,191 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +#pragma warning disable SA1402 // File may only contain a single type — binding proof types are co-located as one API surface. +#pragma warning disable SA1649 // File name should match first type name — binding proof types are co-located as one API surface. +#pragma warning disable SA1204 // Static extension type is intentionally grouped with the binding types. + +using System; +using System.Collections.Generic; +using System.Collections.ObjectModel; +using System.Diagnostics.CodeAnalysis; +using System.Linq; +using System.Text.Json.Serialization.Metadata; +using Microsoft.Shared.DiagnosticIds; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.AI; + +/// Provides an explicit mapping from a choice candidate ID to an enum value. +/// The application-owned enum type. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionEnumDefinition + where TEnum : struct, Enum +{ + private readonly ReadOnlyDictionary _values; + + /// Initializes a new instance of the class. + public DecisionEnumDefinition(IEnumerable> values) + { + _ = Throw.IfNull(values); + + DecisionEnumValue[] copy = values.ToArray(); + if (copy.Length == 0) + { + Throw.ArgumentException(nameof(values), "An enum definition requires at least one value."); + } + + Dictionary byId = new(StringComparer.Ordinal); + HashSet enumValues = new(); + DecisionCandidate[] candidates = new DecisionCandidate[copy.Length]; + + for (int i = 0; i < copy.Length; i++) + { + DecisionEnumValue value = copy[i]; + if (!enumValues.Add(value.Value)) + { + Throw.ArgumentException(nameof(values), "Enum aliases or duplicate enum values are not allowed."); + } + + if (byId.ContainsKey(value.Id)) + { + Throw.ArgumentException( + nameof(values), + "Enum candidate IDs must be unique using ordinal comparison."); + } + + byId.Add(value.Id, value.Value); + candidates[i] = new DecisionCandidate(value.Id, value.Description); + } + + _values = new ReadOnlyDictionary(byId); + Candidates = Array.AsReadOnly(candidates); + } + + /// Gets the ordered candidate snapshot for a choice question. + public IReadOnlyList Candidates { get; } + + /// Creates a choice question using this exact enum mapping. + /// The choice question with the exact mapped candidate IDs. + public ChoiceDecisionQuestion CreateQuestion(string id, string? instructions) => + new(id, instructions, Candidates); + + /// Maps an exact selected candidate ID to its enum value. + /// The mapped enum value. + public TEnum Parse(string candidateId) + { + _ = Throw.IfNullOrWhitespace(candidateId); + if (_values.TryGetValue(candidateId, out TEnum value)) + { + return value; + } + + throw new DecisionProtocolException($"Unknown candidate ID '{candidateId}'."); + } +} + +/// Describes one enum mapping entry. +/// The application-owned enum type. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionEnumValue + where TEnum : struct, Enum +{ + /// Initializes a new instance of the class. + public DecisionEnumValue(TEnum value, string id, string description) + { + Value = value; + Id = Throw.IfNullOrWhitespace(id); + Description = Throw.IfNullOrWhitespace(description); + } + + /// Gets the application enum value. + public TEnum Value { get; } + + /// Gets the exact candidate ID. + public string Id { get; } + + /// Gets the candidate description. + public string Description { get; } +} + +/// Provides typed access to a complete decision response. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionAnswerSet +{ + internal DecisionAnswerSet(DecisionResponse response) + { + Response = response; + } + + /// Gets the complete unmodified response, including probability evidence. + public DecisionResponse Response { get; } + + /// Gets a binary answer by exact question ID. + /// The complete binary answer. + public BinaryDecisionAnswer GetBinary(string questionId) => + Response.GetAnswer(questionId) as BinaryDecisionAnswer ?? + throw new DecisionProtocolException($"Question '{questionId}' is not binary."); + + /// Gets a choice answer by exact question ID. + /// The complete choice answer. + public ChoiceDecisionAnswer GetChoice(string questionId) => + Response.GetAnswer(questionId) as ChoiceDecisionAnswer ?? + throw new DecisionProtocolException($"Question '{questionId}' is not a choice."); + + /// Gets a choice answer and maps its exact selected ID to an enum. + /// The application-owned enum type. + /// The mapped enum value. + public TEnum GetChoice(string questionId, DecisionEnumDefinition definition) + where TEnum : struct, Enum + { + _ = Throw.IfNull(definition); + return definition.Parse(GetChoice(questionId).SelectedCandidateId); + } + + /// Gets a score answer by exact question ID. + /// The complete score answer. + public ScoreDecisionAnswer GetScore(string questionId) => + Response.GetAnswer(questionId) as ScoreDecisionAnswer ?? + throw new DecisionProtocolException($"Question '{questionId}' is not a score."); +} + +/// Maps one complete response to an application-owned result without inference or reflection. +/// The application-owned result type. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionResultBinding +{ + private readonly Func _map; + + /// Initializes a new instance of the class. + /// The source-generated JSON contract for the application result. + /// The application-owned mapping delegate. + public DecisionResultBinding( + JsonTypeInfo resultTypeInfo, + Func map) + { + ResultTypeInfo = Throw.IfNull(resultTypeInfo); + _map = Throw.IfNull(map); + } + + /// Gets the explicit source-generated result contract. + public JsonTypeInfo ResultTypeInfo { get; } + + internal TResult Map(DecisionResponse response) => _map(new DecisionAnswerSet(response)); +} + +/// Provides response binding extensions. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public static class DecisionBindingExtensions +{ + /// Maps a complete response locally using the supplied explicit binding. + /// The application-owned result type. + /// The application-owned result. + public static TResult Bind( + this DecisionResponse response, + DecisionResultBinding binding) + { + _ = Throw.IfNull(response); + _ = Throw.IfNull(binding); + return binding.Map(response); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionClient.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionClient.cs new file mode 100644 index 00000000000..7777cb682f7 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionClient.cs @@ -0,0 +1,546 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +#pragma warning disable SA1402 // File may only contain a single type — decision client contracts are co-located as one API surface. +#pragma warning disable SA1649 // File name should match first type name — decision client contracts are co-located as one API surface. +#pragma warning disable SA1204 // Static extension types are intentionally grouped with the client contracts. +#pragma warning disable S1128 // Unused "using" should be removed — ExperimentalAttribute is supplied by the shared API contract. +#pragma warning disable S2302 // Protocol diagnostics intentionally mention the opaque question concept. +#pragma warning disable CA1032 // Implement standard exception constructors — client exceptions expose the client-specific constructors. + +using System; +using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; +using System.Linq; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Text.Json.Serialization.Metadata; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Shared.DiagnosticIds; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.AI; + +/// Provides provider-neutral decision inference over a heterogeneous question batch. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public interface IDecisionClient : IDisposable +{ + /// Evaluates all questions against the same request state. + /// The owned decision request. + /// Optional per-request options. + /// The cancellation token to monitor. + /// A complete, correlated decision response or an exception. + Task GetResponseAsync( + DecisionRequest request, + DecisionOptions? options = null, + CancellationToken cancellationToken = default); + + /// Retrieves a provider service for the exact requested type and key. + /// The requested provider service, or when unavailable. + object? GetService(Type serviceType, object? serviceKey = null); +} + +/// Provides per-request decision options. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public class DecisionOptions +{ + /// Initializes a new instance of the class. + public DecisionOptions() + { + } + + /// Initializes a new instance of the class by copying another instance. + protected DecisionOptions(DecisionOptions? other) + { + if (other is null) + { + return; + } + + ModelId = other.ModelId; + AdditionalProperties = other.AdditionalProperties?.Clone(); + RawRepresentationFactory = other.RawRepresentationFactory; + } + + /// Gets or sets the requested model ID. + public string? ModelId { get; set; } + + /// Gets or sets provider-specific extension properties. + public AdditionalPropertiesDictionary? AdditionalProperties { get; set; } + + /// + /// Gets or sets a callback that creates provider-specific raw options. + /// The callback should return a new instance for each invocation; the provider may mutate it. + /// + [JsonIgnore] + public Func? RawRepresentationFactory { get; set; } + + /// Creates a deliberate shallow clone of these options. + /// A cloned options instance. + public virtual DecisionOptions Clone() => new(this); +} + +/// Provides metadata about an . +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionClientMetadata +{ + /// Initializes a new instance of the class. + public DecisionClientMetadata( + string? providerName = null, + Uri? providerUri = null, + string? defaultModelId = null, + IReadOnlyList? supportedKinds = null) + { + ProviderName = providerName; + ProviderUri = providerUri; + DefaultModelId = defaultModelId; + + if (supportedKinds is not null) + { + DecisionKind[] copy = supportedKinds.Distinct().ToArray(); + foreach (DecisionKind kind in copy) + { + if (!Enum.IsDefined(typeof(DecisionKind), kind)) + { + Throw.ArgumentException(nameof(supportedKinds), "Supported kinds must be defined decision kinds."); + } + } + + SupportedKinds = Array.AsReadOnly(copy); + } + } + + /// Gets the provider name, when known. + public string? ProviderName { get; } + + /// Gets the provider URI, when known. + public Uri? ProviderUri { get; } + + /// Gets the default model ID, when known. + public string? DefaultModelId { get; } + + /// Gets the owned supported-kind snapshot, or when unknown. + public IReadOnlyList? SupportedKinds { get; } +} + +/// Classifies a provider failure without prescribing retry behavior. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionClientException : Exception +{ + /// Initializes a new instance of the class. + public DecisionClientException() + : this(string.Empty, isTransient: false) + { + } + + /// Initializes a new instance of the class with a message. + public DecisionClientException(string message) + : this(message, isTransient: false) + { + } + + /// Initializes a new instance of the class with provider classification. + public DecisionClientException(string message, bool isTransient, Exception? innerException = null) + : base(message, innerException) + { + IsTransient = isTransient; + } + + /// Initializes a new instance of the class with a message and inner exception. + public DecisionClientException(string message, Exception innerException) + : this(message, isTransient: false, innerException) + { + } + + /// Gets a value indicating whether the provider classified the failure as transient. + public bool IsTransient { get; } +} + +/// Provides extensions for decision clients. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public static class DecisionClientExtensions +{ + /// Gets a typed provider service, or when it is unavailable. + /// The provider service type. + /// The requested provider service, or when unavailable. + public static TService? GetService(this IDecisionClient client, object? serviceKey = null) + { + _ = Throw.IfNull(client); + return client.GetService(typeof(TService), serviceKey) is TService service ? service : default; + } + + /// Evaluates typed state using an explicit source-generated JSON contract. + /// The application state type. + /// A complete, correlated decision response. + public static async Task GetResponseAsync( + this IDecisionClient client, + TState state, + JsonTypeInfo stateTypeInfo, + IEnumerable questions, + DecisionOptions? options = null, + CancellationToken cancellationToken = default) + { + _ = Throw.IfNull(client); + _ = Throw.IfNull(stateTypeInfo); + + DecisionRequest request = DecisionRequest.Create(state, stateTypeInfo, questions); + DecisionResponse response = await client.GetResponseAsync(request, options, cancellationToken).ConfigureAwait(false); + response.ValidateAgainst(request); + return response; + } + + /// Evaluates a JSON state using a reusable typed decision definition. + /// The application-owned result type. + /// The decision client. + /// The explicit JSON state evaluated by every declared question. + /// The immutable typed decision definition. + /// Optional per-request options. + /// The cancellation token to monitor. + /// The typed result and complete neutral evidence. + public static async Task> GetResponseAsync( + this IDecisionClient client, + JsonElement state, + DecisionDefinition definition, + DecisionOptions? options = null, + CancellationToken cancellationToken = default) + { + _ = Throw.IfNull(client); + _ = Throw.IfNull(definition); + + DecisionRequest request = new(state, definition.Questions); + DecisionResponse response = await client.GetResponseAsync( + request, + options, + cancellationToken).ConfigureAwait(false); + return definition.Bind(response, request); + } + + /// Evaluates typed application state using a reusable typed decision definition. + /// The application state type. + /// The application-owned result type. + /// The decision client. + /// The application-owned state. + /// The immutable typed decision definition. + /// Optional per-request options. + /// The cancellation token to monitor. + /// The typed result and complete neutral evidence. + public static Task> GetResponseAsync( + this IDecisionClient client, + TState state, + DecisionDefinition definition, + DecisionOptions? options = null, + CancellationToken cancellationToken = default) + { + _ = Throw.IfNull(definition); + return GetResponseAsync( + client, + state, + definition, + definition.SerializerOptions, + options, + cancellationToken); + } + + /// Evaluates typed application state using explicit source-generated state metadata. + /// The application state type. + /// The application-owned result type. + /// The decision client. + /// The application-owned state. + /// The JSON contract for . + /// The immutable typed decision definition. + /// Optional per-request options. + /// The cancellation token to monitor. + /// The typed result and complete neutral evidence. + public static Task> GetResponseAsync( + this IDecisionClient client, + TState state, + JsonTypeInfo stateTypeInfo, + DecisionDefinition definition, + DecisionOptions? options = null, + CancellationToken cancellationToken = default) + { + _ = Throw.IfNull(stateTypeInfo); + return GetResponseAsync( + client, + state, + definition, + stateTypeInfo, + options, + cancellationToken); + } + + private static async Task> GetResponseAsync( + IDecisionClient client, + TState state, + DecisionDefinition definition, + JsonSerializerOptions serializerOptions, + DecisionOptions? options, + CancellationToken cancellationToken) + { + _ = Throw.IfNull(client); + _ = Throw.IfNull(definition); + + JsonTypeInfo stateTypeInfo = serializerOptions.GetTypeInfo(typeof(TState)); + JsonElement stateJson = JsonSerializer.SerializeToElement(state, stateTypeInfo); + return await GetResponseAsync(client, stateJson, definition, options, cancellationToken).ConfigureAwait(false); + } + + private static async Task> GetResponseAsync( + IDecisionClient client, + TState state, + DecisionDefinition definition, + JsonTypeInfo stateTypeInfo, + DecisionOptions? options, + CancellationToken cancellationToken) + { + _ = Throw.IfNull(client); + _ = Throw.IfNull(definition); + + JsonElement stateJson = JsonSerializer.SerializeToElement(state, stateTypeInfo); + return await GetResponseAsync(client, stateJson, definition, options, cancellationToken).ConfigureAwait(false); + } +} + +/// Identifies provider/model provenance without inventing missing identity. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionProvenance +{ + /// Initializes a new instance of the class. + public DecisionProvenance( + string? providerName = null, + Uri? providerUri = null, + string? modelId = null, + string? responseId = null, + DecisionPrecision? precision = null) + { + ProviderName = providerName; + ProviderUri = providerUri; + ModelId = modelId; + ResponseId = responseId; + Precision = precision; + } + + /// Gets the provider name, when reported. + public string? ProviderName { get; } + + /// Gets the provider URI, when reported. + public Uri? ProviderUri { get; } + + /// Gets the model ID, when reported. + public string? ModelId { get; } + + /// Gets the provider response ID, when reported. + public string? ResponseId { get; } + + /// Gets the reported probability precision, when available. + public DecisionPrecision? Precision { get; } +} + +/// Represents a complete response correlated to one request. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionResponse +{ + /// Initializes a new instance of the class and validates it. + [JsonConstructor] + public DecisionResponse( + DecisionRequest request, + IReadOnlyList answers, + DecisionProvenance? provenance = null, + UsageDetails? usage = null, + object? rawRepresentation = null, + IReadOnlyDictionary? additionalProperties = null) + { + Request = Throw.IfNull(request); + _ = Throw.IfNull(answers); + + DecisionAnswer[] copy = answers.ToArray(); + if (copy.Length != request.Questions.Count) + { + throw new DecisionProtocolException("A response must contain one answer for every question."); + } + + for (int i = 0; i < copy.Length; i++) + { + ValidateAnswer(request.Questions[i], copy[i]); + } + + Answers = Array.AsReadOnly(copy); + Provenance = provenance; + Usage = usage; + RawRepresentation = rawRepresentation; + AdditionalProperties = DecisionSnapshots.Properties(additionalProperties); + } + + /// Gets the request snapshot evaluated by the provider. + public DecisionRequest Request { get; } + + /// Gets complete answers in the exact request order. + public IReadOnlyList Answers { get; } + + /// Gets provider/model provenance, when reported. + public DecisionProvenance? Provenance { get; } + + /// Gets usage details reported by the provider. + public UsageDetails? Usage { get; } + + /// + /// Gets the provider-owned raw response, if available. + /// This value is not cloned or used for semantic data and must be treated as diagnostic-only. + /// + [JsonIgnore] + public object? RawRepresentation { get; } + + /// + /// Gets an owned read-only snapshot of provider extension data. + /// Values are shallow-copied references and must be independently safe to share. + /// + public IReadOnlyDictionary? AdditionalProperties { get; } + + /// Gets an answer by exact ordinal question ID. + /// The answer associated with the exact question ID. + public DecisionAnswer GetAnswer(string questionId) + { + _ = Throw.IfNullOrWhitespace(questionId); + foreach (DecisionAnswer answer in Answers) + { + if (string.Equals(answer.QuestionId, questionId, StringComparison.Ordinal)) + { + return answer; + } + } + + throw new KeyNotFoundException($"No answer exists for question ID '{questionId}'."); + } + + internal void ValidateAgainst(DecisionRequest expectedRequest) + { + _ = Throw.IfNull(expectedRequest); + + if (!JsonElement.DeepEquals(Request.State, expectedRequest.State) || + Request.Questions.Count != expectedRequest.Questions.Count) + { + throw new DecisionProtocolException("The response does not correspond to the request sent by the client."); + } + + for (int i = 0; i < Request.Questions.Count; i++) + { + if (!QuestionsAreEquivalent(Request.Questions[i], expectedRequest.Questions[i])) + { + throw new DecisionProtocolException("The response does not correspond to the request sent by the client."); + } + } + } + + private static bool QuestionsAreEquivalent(DecisionQuestion actual, DecisionQuestion expected) + { + if (actual.Kind != expected.Kind || + !string.Equals(actual.Id, expected.Id, StringComparison.Ordinal) || + !string.Equals(actual.Instructions, expected.Instructions, StringComparison.Ordinal)) + { + return false; + } + + return (actual, expected) switch + { + (BinaryDecisionQuestion actualBinary, BinaryDecisionQuestion expectedBinary) => + string.Equals(actualBinary.TrueDescription, expectedBinary.TrueDescription, StringComparison.Ordinal) && + string.Equals(actualBinary.FalseDescription, expectedBinary.FalseDescription, StringComparison.Ordinal), + + (ChoiceDecisionQuestion actualChoice, ChoiceDecisionQuestion expectedChoice) => + CandidatesAreEquivalent(actualChoice.Candidates, expectedChoice.Candidates), + + (ScoreDecisionQuestion actualScore, ScoreDecisionQuestion expectedScore) => + LevelsAreEquivalent(actualScore.Levels, expectedScore.Levels), + + _ => false, + }; + } + + private static bool CandidatesAreEquivalent( + IReadOnlyList actual, + IReadOnlyList expected) + { + if (actual.Count != expected.Count) + { + return false; + } + + for (int i = 0; i < actual.Count; i++) + { + if (!string.Equals(actual[i].Id, expected[i].Id, StringComparison.Ordinal) || + !string.Equals(actual[i].Description, expected[i].Description, StringComparison.Ordinal)) + { + return false; + } + } + + return true; + } + + private static bool LevelsAreEquivalent( + IReadOnlyList actual, + IReadOnlyList expected) + { + if (actual.Count != expected.Count) + { + return false; + } + + for (int i = 0; i < actual.Count; i++) + { + if (!string.Equals(actual[i].Id, expected[i].Id, StringComparison.Ordinal) || + !string.Equals(actual[i].Description, expected[i].Description, StringComparison.Ordinal)) + { + return false; + } + } + + return true; + } + + private static void ValidateAnswer(DecisionQuestion question, DecisionAnswer answer) + { + if (answer is null || + !string.Equals(question.Id, answer.QuestionId, StringComparison.Ordinal) || + question.Kind != answer.Kind) + { + throw new DecisionProtocolException("An answer does not exactly match its question."); + } + + switch (question) + { + case BinaryDecisionQuestion when answer is BinaryDecisionAnswer: + return; + + case ChoiceDecisionQuestion choice when answer is ChoiceDecisionAnswer choiceAnswer: + if (choiceAnswer.Probabilities.Count != choice.Candidates.Count || + !choice.Candidates.Select(static candidate => candidate.Id) + .SequenceEqual( + choiceAnswer.Probabilities.Select(static probability => probability.Id), + StringComparer.Ordinal)) + { + throw new DecisionProtocolException( + "Choice probabilities must contain exactly the requested candidate IDs in order."); + } + + return; + + case ScoreDecisionQuestion score when answer is ScoreDecisionAnswer scoreAnswer: + if (scoreAnswer.Probabilities.Count != score.Levels.Count || + !score.Levels.Select(static level => level.Id) + .SequenceEqual( + scoreAnswer.Probabilities.Select(static probability => probability.Id), + StringComparer.Ordinal)) + { + throw new DecisionProtocolException( + "Score probabilities must contain exactly the requested level IDs in order."); + } + + return; + + default: + throw new DecisionProtocolException("An answer kind does not match its question."); + } + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionDefinitions.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionDefinitions.cs new file mode 100644 index 00000000000..887426af88b --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionDefinitions.cs @@ -0,0 +1,739 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +#pragma warning disable SA1402 // Definition and nested builder are one immutable API surface. +#pragma warning disable SA1649 // File name identifies the primary definition type. +#pragma warning disable CA1000 // The generic type is the natural home for the typed factory methods. +#pragma warning disable CA1032 // Decision materialization exposes protocol-specific failures. +#pragma warning disable S2302 // Protocol exception messages intentionally describe the response and configured options. + +using System; +using System.Collections.Generic; +using System.Collections.ObjectModel; +using System.ComponentModel; +using System.Diagnostics.CodeAnalysis; +using System.IO; +using System.Linq; +using System.Linq.Expressions; +using System.Reflection; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Text.Json.Serialization.Metadata; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Shared.DiagnosticIds; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.AI; + +/// +/// Declares the decision questions and application-owned result properties for a typed decision flow. +/// +/// The application-owned result type. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionDefinition +{ + private readonly ReadOnlyCollection> _questions; + + private DecisionDefinition( + JsonTypeInfo resultTypeInfo, + JsonSerializerOptions serializerOptions, + IReadOnlyList> questions) + { + ResultTypeInfo = resultTypeInfo; + SerializerOptions = serializerOptions; + _questions = new ReadOnlyCollection>(questions.ToArray()); + Questions = new ReadOnlyCollection(_questions.Select(static question => question.Question).ToArray()); + } + + /// Gets the explicit JSON contract used to materialize the application result. + public JsonTypeInfo ResultTypeInfo { get; } + + /// Gets the serializer options associated with this definition. + [JsonIgnore] + public JsonSerializerOptions SerializerOptions { get; } + + /// Gets the immutable ordered questions declared by this definition. + public IReadOnlyList Questions { get; } + + /// + /// Creates a typed definition using the configured default JSON contract for . + /// + /// The explicit question declaration callback. + /// + /// Optional JSON options used for property and enum metadata. A missing resolver is supplied from the MEAI defaults; + /// explicit caller resolvers and converters are preserved without mutating the caller's options. + /// + /// An immutable decision definition. + public static DecisionDefinition Create( + Action configure, + JsonSerializerOptions? serializerOptions = null) + { + _ = Throw.IfNull(configure); + serializerOptions = new JsonSerializerOptions(serializerOptions ?? AIJsonUtilities.DefaultOptions); + serializerOptions.TypeInfoResolver ??= AIJsonUtilities.DefaultOptions.TypeInfoResolver; + serializerOptions.MakeReadOnly(); + + JsonTypeInfo resultTypeInfo = GetResultTypeInfo(serializerOptions); + return Create(resultTypeInfo, configure); + } + + /// Creates a typed definition using an application-supplied JSON contract. + /// The JSON contract for . + /// The explicit question declaration callback. + /// An immutable decision definition. + public static DecisionDefinition Create( + JsonTypeInfo resultTypeInfo, + Action configure) + { + _ = Throw.IfNull(resultTypeInfo); + _ = Throw.IfNull(configure); + + Builder builder = new(resultTypeInfo); + configure(builder); + return builder.Build(); + } + + private static AIFunctionFactoryOptions GetFunctionOptions( + AIFunctionFactoryOptions? functionOptions, + JsonSerializerOptions serializerOptions) + { + if (functionOptions is null) + { + return new AIFunctionFactoryOptions { SerializerOptions = serializerOptions }; + } + + if (functionOptions.SerializerOptions is not null) + { + return functionOptions; + } + + return new AIFunctionFactoryOptions + { + SerializerOptions = serializerOptions, + JsonSchemaCreateOptions = functionOptions.JsonSchemaCreateOptions, + Name = functionOptions.Name, + Description = functionOptions.Description, + AdditionalProperties = functionOptions.AdditionalProperties, + ConfigureParameterBinding = functionOptions.ConfigureParameterBinding, + MarshalResult = functionOptions.MarshalResult, + ExcludeResultSchema = functionOptions.ExcludeResultSchema, + }; + } + + /// Creates an that evaluates this definition for a caller-owned state type. + /// The application-owned state type exposed as the function's input. + /// The caller-owned decision client. + /// Optional standard function factory options. + /// + /// Optional decision options shallow-copied during construction and cloned for each invocation. Nested values and + /// the raw-options factory remain caller/provider-owned. + /// + /// + /// Optional explicit JSON contract for . When omitted, the definition's serializer + /// options must contain the state contract. + /// + /// A function whose only model-facing input is and whose result is . + public AIFunction AsAIFunction( + IDecisionClient client, + AIFunctionFactoryOptions? functionOptions = null, + DecisionOptions? decisionOptions = null, + JsonTypeInfo? stateTypeInfo = null) + { + _ = Throw.IfNull(client); + + stateTypeInfo ??= GetStateTypeInfo(); + DecisionOptions? decisionOptionsSnapshot = decisionOptions?.Clone(); + DecisionFunctionInvoker invoker = new(client, this, stateTypeInfo, decisionOptionsSnapshot); + + return AIFunctionFactory.Create( + invoker.InvokeAsync, + GetFunctionOptions(functionOptions, stateTypeInfo.Options)); + } + + internal DecisionResponse Bind(DecisionResponse response, DecisionRequest expectedRequest) + { + _ = Throw.IfNull(response); + response.ValidateAgainst(expectedRequest); + + using MemoryStream stream = new(); + using (Utf8JsonWriter writer = new(stream)) + { + writer.WriteStartObject(); + + foreach (DecisionDefinitionQuestion question in _questions) + { + DecisionAnswer answer = response.GetAnswer(question.Question.Id); + switch (question.Kind) + { + case DecisionKind.Binary: + writer.WriteNumber(question.PropertyName, ((BinaryDecisionAnswer)answer).TrueProbability); + break; + + case DecisionKind.Choice: + ChoiceDecisionAnswer choice = (ChoiceDecisionAnswer)answer; + writer.WriteString(question.PropertyName, choice.SelectedCandidateId); + break; + + case DecisionKind.Score: + ScoreDecisionAnswer score = (ScoreDecisionAnswer)answer; + if (question.UsesExpectedScore) + { + writer.WriteNumber(question.PropertyName, score.ExpectedScore); + } + else if (score.Score is double reportedScore) + { + writer.WriteNumber(question.PropertyName, reportedScore); + } + else + { + throw new DecisionProtocolException( + $"Question '{question.Question.Id}' does not contain a provider-reported score."); + } + break; + + default: + throw new DecisionProtocolException($"Unsupported decision kind '{question.Kind}'."); + } + } + + writer.WriteEndObject(); + } + + byte[] resultJson = stream.ToArray(); + TResult result; + try + { + result = JsonSerializer.Deserialize(resultJson, ResultTypeInfo)!; + } + catch (Exception exception) when (exception is JsonException or NotSupportedException) + { + throw new DecisionProtocolException( + "The decision response could not be materialized as the declared result type.", + exception); + } + + if (result is null) + { + throw new DecisionProtocolException("The decision response produced a null result."); + } + + foreach (DecisionDefinitionQuestion question in _questions) + { + DecisionAnswer answer = response.GetAnswer(question.Question.Id); + object? actualValue = question.ValueAccessor(result); + bool preserved = question.Kind switch + { + DecisionKind.Binary => actualValue is double actualBinary && + actualBinary.Equals(((BinaryDecisionAnswer)answer).TrueProbability), + DecisionKind.Choice => question.ChoiceValueMatches is not null && + question.ChoiceValueMatches(actualValue, ((ChoiceDecisionAnswer)answer).SelectedCandidateId), + DecisionKind.Score => actualValue is double actualScore && + actualScore.Equals(question.UsesExpectedScore + ? ((ScoreDecisionAnswer)answer).ExpectedScore + : ((ScoreDecisionAnswer)answer).Score ?? double.NaN), + _ => false, + }; + + if (!preserved) + { + throw new DecisionProtocolException( + $"The decision response value for result property '{question.Property.Name}' was not preserved by the configured JSON contract."); + } + } + + return new DecisionResponse(result, response, this); + } + + private JsonTypeInfo GetStateTypeInfo() + { + return SerializerOptions.GetTypeInfo(typeof(TState)) is JsonTypeInfo stateTypeInfo + ? stateTypeInfo + : throw new NotSupportedException( + $"The configured JSON options do not contain a contract for state type '{typeof(TState)}'."); + } + + private sealed class DecisionFunctionInvoker( + IDecisionClient client, + DecisionDefinition definition, + JsonTypeInfo stateTypeInfo, + DecisionOptions? decisionOptionsSnapshot) + { + private readonly IDecisionClient _client = client; + private readonly DecisionDefinition _definition = definition; + private readonly JsonTypeInfo _stateTypeInfo = stateTypeInfo; + private readonly DecisionOptions? _decisionOptionsSnapshot = decisionOptionsSnapshot; + + [DisplayName("evaluate_decision")] + [Description("Evaluate the declared decision for one application state.")] + public async Task InvokeAsync( + [Description("The application state for the declared decision.")] TState state, + CancellationToken cancellationToken) + { + DecisionResponse response = await _client.GetResponseAsync( + state, + _stateTypeInfo, + _definition, + _decisionOptionsSnapshot?.Clone(), + cancellationToken).ConfigureAwait(false); + return response.Result; + } + } + + internal IReadOnlyDictionary GetDistribution( + DecisionResponse response, + Expression> selector) + where TEnum : struct, Enum + { + DecisionDefinitionQuestion question = FindQuestion(selector); + if (question.Kind != DecisionKind.Choice || + question.EnumDefinition is not DecisionEnumDefinition definition) + { + throw new DecisionProtocolException("The selected result property is not a choice enum in this definition."); + } + + ChoiceDecisionAnswer answer = (ChoiceDecisionAnswer)response.Evidence.GetAnswer(question.Question.Id); + Dictionary values = new(); + foreach (DecisionProbability probability in answer.Probabilities) + { + values.Add(definition.Parse(probability.Id), probability.Value); + } + + return new ReadOnlyDictionary(values); + } + + private static JsonTypeInfo GetResultTypeInfo(JsonSerializerOptions options) + { + if (options.GetTypeInfo(typeof(TResult)) is not JsonTypeInfo resultTypeInfo) + { + throw new NotSupportedException( + $"The configured JSON options do not contain a contract for result type '{typeof(TResult)}'."); + } + + return resultTypeInfo; + } + + private static PropertyInfo GetDirectProperty(Expression> selector) + { + _ = Throw.IfNull(selector); + + Expression body = selector.Body; + if (body is UnaryExpression { NodeType: ExpressionType.Convert } conversion) + { + body = conversion.Operand; + } + + if (body is not MemberExpression { Member: PropertyInfo property, Expression: ParameterExpression parameter } || + selector.Parameters.Count != 1 || + selector.Parameters[0] != parameter) + { + Throw.ArgumentException( + nameof(selector), + "The selector must access one direct instance property of the result type."); + return null!; + } + + return property; + } + + private DecisionDefinitionQuestion FindQuestion(Expression> selector) + { + PropertyInfo property = GetDirectProperty(selector); + return _questions.FirstOrDefault(question => question.Property == property) ?? + throw new DecisionProtocolException($"The result property '{property.Name}' is not declared in this definition."); + } + + /// Builds a through explicit property declarations. + [Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] + public sealed class Builder + { + private readonly JsonTypeInfo _resultTypeInfo; + private readonly List> _questions = []; + + private static DecisionEnumDefinition CreateEnumDefinition<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicFields)] TEnum>( + PropertyInfo property, + JsonTypeInfo resultTypeInfo, + JsonPropertyInfo jsonProperty) + where TEnum : struct, Enum + { + if (property.PropertyType.IsDefined(typeof(FlagsAttribute), inherit: false)) + { + Throw.ArgumentException("selector", "Flags enums are not supported as closed decision choices."); + } + + if (jsonProperty.CustomConverter is not null) + { + throw new NotSupportedException( + $"Property-specific JSON converters are not supported for decision enum property '{property.Name}'. " + + "Configure the enum converter at the JSON type/options level so candidate IDs and result materialization share one contract."); + } + + JsonTypeInfo enumTypeInfo; + try + { + enumTypeInfo = resultTypeInfo.Options.GetTypeInfo(typeof(TEnum)); + } + catch (Exception exception) when (exception is NotSupportedException or InvalidOperationException) + { + throw new NotSupportedException( + $"The configured JSON options do not contain a contract for enum type '{typeof(TEnum)}'.", + exception); + } + +#if NET5_0_OR_GREATER + TEnum[] enumValues = Enum.GetValues(); +#else + TEnum[] enumValues = Enum.GetValues(typeof(TEnum)).Cast().ToArray(); +#endif + List> values = new(enumValues.Length); + foreach (TEnum value in enumValues) + { + JsonElement serialized = JsonSerializer.SerializeToElement(value, enumTypeInfo); + if (serialized.ValueKind != JsonValueKind.String || serialized.GetString() is not string id) + { + throw new NotSupportedException( + $"Enum type '{typeof(TEnum)}' must use string JSON serialization for decision choices."); + } + + string enumName = Enum.GetName(typeof(TEnum), value)!; + string description = typeof(TEnum).GetField(enumName)?.GetCustomAttribute()?.Description ?? + enumName; + + values.Add(new DecisionEnumValue(value, id, description)); + } + + return new DecisionEnumDefinition(values); + } + + private static JsonPropertyInfo GetJsonProperty(JsonTypeInfo resultTypeInfo, PropertyInfo property) + { + JsonPropertyInfo? jsonProperty = resultTypeInfo.Properties.FirstOrDefault( + candidate => candidate.AttributeProvider is PropertyInfo propertyInfo && propertyInfo == property); + + if (jsonProperty is null) + { + string expectedName = property.GetCustomAttribute()?.Name ?? + resultTypeInfo.Options.PropertyNamingPolicy?.ConvertName(property.Name) ?? + property.Name; + jsonProperty = resultTypeInfo.Properties.FirstOrDefault( + candidate => string.Equals(candidate.Name, expectedName, StringComparison.Ordinal)); + } + + if (jsonProperty is null) + { + Throw.ArgumentException( + nameof(property), + $"The selected property '{property.Name}' is not present in the configured JSON contract."); + } + + return jsonProperty; + } + + private static string GetInstructions(JsonPropertyInfo jsonProperty, PropertyInfo property, string? explicitInstructions) + { + if (explicitInstructions is not null) + { + return Throw.IfNullOrWhitespace(explicitInstructions); + } + + string? description = (jsonProperty.AttributeProvider as PropertyInfo)?.GetCustomAttribute(inherit: true)?.Description; + if (description is not null) + { + return description; + } + +#if NET9_0_OR_GREATER + description = jsonProperty.AssociatedParameter?.AttributeProvider?.GetCustomAttributes(typeof(DescriptionAttribute), inherit: true) + .OfType() + .FirstOrDefault() + ?.Description; +#else + description = GetConstructorDescription(property); +#endif + if (description is not null) + { + return description; + } + + return property.PropertyType.GetCustomAttribute(inherit: true)?.Description ?? + property.Name; + } + + private static void EnsurePropertyCanBeDeclared(PropertyInfo property, Type expectedType) + { + if (property.GetMethod is null || + property.GetMethod.IsStatic || + property.PropertyType != expectedType) + { + Throw.ArgumentException("selector", $"The selected property must be a readable instance property of type '{expectedType}'."); + } + } + +#if !NET9_0_OR_GREATER + [UnconditionalSuppressMessage("Trimming", "IL2075", Justification = "The reflection convenience path checks preserved constructor binding metadata; source-generated metadata is used on newer TFMs.")] +#endif + private static void EnsurePropertyCanBeMaterialized( + PropertyInfo property, + JsonPropertyInfo jsonProperty) + { + if (jsonProperty.Set is not null) + { + return; + } + +#if NET9_0_OR_GREATER + if (jsonProperty.AssociatedParameter is not null) + { + return; + } +#else + ConstructorInfo[] constructors = property.DeclaringType?.GetConstructors() ?? []; + if (Array.Exists( + constructors, + candidate => Array.Exists( + candidate.GetParameters(), + parameter => string.Equals(parameter.Name, property.Name, StringComparison.OrdinalIgnoreCase)))) + { + return; + } +#endif + + Throw.ArgumentException( + "selector", + $"The selected property '{property.Name}' is not writable or bound to a JSON constructor parameter."); + } + +#if !NET9_0_OR_GREATER + [UnconditionalSuppressMessage("Trimming", "IL2075", Justification = "The reflection convenience path intentionally reads preserved constructor parameter metadata; source-generated metadata is used on newer TFMs.")] + private static string? GetConstructorDescription(PropertyInfo property) + { + ConstructorInfo[] constructors = property.DeclaringType?.GetConstructors() ?? []; + ConstructorInfo? constructor = Array.Find( + constructors, + candidate => Array.Exists(candidate.GetParameters(), parameter => + string.Equals(parameter.Name, property.Name, StringComparison.OrdinalIgnoreCase))); + return Array.Find( + constructor?.GetParameters() ?? [], + parameter => string.Equals(parameter.Name, property.Name, StringComparison.OrdinalIgnoreCase)) + ?.GetCustomAttribute(inherit: true) + ?.Description; + } +#endif + + private static Func CreateValueAccessor(Expression> selector) + { +#if NETFRAMEWORK + Func accessor = selector.Compile(); +#else + Func accessor = selector.Compile(true); +#endif + return result => accessor(result); + } + + private static Func CreateChoiceValueMatcher( + DecisionEnumDefinition enumDefinition) + where TEnum : struct, Enum => + (actualValue, candidateId) => + actualValue is TEnum actual && + EqualityComparer.Default.Equals(actual, enumDefinition.Parse(candidateId)); + + internal Builder(JsonTypeInfo resultTypeInfo) + { + _resultTypeInfo = resultTypeInfo; + } + + /// Declares an enum-backed choice question. + /// The result property enum type. + /// A direct result property selector. + /// Optional explicit question instructions. + public void Choice<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicFields)] TEnum>( + Expression> selector, + string? instructions = null) + where TEnum : struct, Enum + { + PropertyInfo property = GetDirectProperty(selector); + EnsurePropertyCanBeDeclared(property, typeof(TEnum)); + + JsonPropertyInfo jsonProperty = GetJsonProperty(_resultTypeInfo, property); + EnsurePropertyCanBeMaterialized(property, jsonProperty); + DecisionEnumDefinition enumDefinition = CreateEnumDefinition(property, _resultTypeInfo, jsonProperty); + AddQuestion( + property, + jsonProperty.Name, + new ChoiceDecisionQuestion(jsonProperty.Name, GetInstructions(jsonProperty, property, instructions), enumDefinition.Candidates), + enumDefinition, + DecisionKind.Choice, + valueAccessor: CreateValueAccessor(selector), + choiceValueMatches: CreateChoiceValueMatcher(enumDefinition)); + } + + /// Declares a binary probability question backed by a result property. + /// A direct result property selector. + /// Optional explicit question instructions. + public void BinaryProbability( + Expression> selector, + string? instructions = null) + { + PropertyInfo property = GetDirectProperty(selector); + EnsurePropertyCanBeDeclared(property, typeof(double)); + + JsonPropertyInfo jsonProperty = GetJsonProperty(_resultTypeInfo, property); + EnsurePropertyCanBeMaterialized(property, jsonProperty); + AddQuestion( + property, + jsonProperty.Name, + new BinaryDecisionQuestion(jsonProperty.Name, GetInstructions(jsonProperty, property, instructions)), + enumDefinition: null, + DecisionKind.Binary, + valueAccessor: CreateValueAccessor(selector)); + } + + /// Declares an ordinal score question with an explicit ordered rubric. + /// A direct result property selector. + /// The caller-defined ordered score levels. + /// Optional explicit question instructions. + public void Score( + Expression> selector, + IReadOnlyList levels, + string? instructions = null) + { + AddScore(selector, levels, instructions, usesExpectedScore: false); + } + + /// Declares an ordinal score question projected from the complete observed distribution. + /// A direct result property selector. + /// The caller-defined ordered score levels. + /// Optional explicit question instructions. + public void ExpectedScore( + Expression> selector, + IReadOnlyList levels, + string? instructions = null) + { + AddScore(selector, levels, instructions, usesExpectedScore: true); + } + + private void AddScore( + Expression> selector, + IReadOnlyList levels, + string? instructions, + bool usesExpectedScore) + { + PropertyInfo property = GetDirectProperty(selector); + EnsurePropertyCanBeDeclared(property, typeof(double)); + _ = Throw.IfNull(levels); + + JsonPropertyInfo jsonProperty = GetJsonProperty(_resultTypeInfo, property); + EnsurePropertyCanBeMaterialized(property, jsonProperty); + AddQuestion( + property, + jsonProperty.Name, + new ScoreDecisionQuestion(jsonProperty.Name, GetInstructions(jsonProperty, property, instructions), levels), + enumDefinition: null, + DecisionKind.Score, + usesExpectedScore, + valueAccessor: CreateValueAccessor(selector)); + } + + internal DecisionDefinition Build() + { + if (_questions.Count == 0) + { + Throw.ArgumentException("configure", "A decision definition must declare at least one question."); + } + + return new DecisionDefinition( + _resultTypeInfo, + _resultTypeInfo.Options, + _questions); + } + + private void AddQuestion( + PropertyInfo property, + string propertyName, + DecisionQuestion question, + object? enumDefinition, + DecisionKind kind, + bool usesExpectedScore = false, + Func? valueAccessor = null, + Func? choiceValueMatches = null) + { + if (_questions.Exists(existing => existing.Property == property || string.Equals(existing.PropertyName, propertyName, StringComparison.Ordinal))) + { + Throw.ArgumentException("selector", "A result property or JSON property name can only be declared once."); + } + + _questions.Add(new DecisionDefinitionQuestion( + property, + propertyName, + question, + enumDefinition, + kind, + usesExpectedScore, + valueAccessor ?? throw new InvalidOperationException("A direct property accessor is required."), + choiceValueMatches)); + } + } + +} + +/// Contains a typed result and the complete neutral evidence that produced it. +/// The application-owned result type. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionResponse +{ + private readonly DecisionDefinition _definition; + + internal DecisionResponse(TResult result, DecisionResponse evidence, DecisionDefinition definition) + { + Result = result; + Evidence = evidence; + _definition = definition; + } + + /// Gets the application-owned materialized result. + public TResult Result { get; } + + /// Gets the complete original response, including distributions and metadata. + public DecisionResponse Evidence { get; } + + /// Gets the complete probability distribution for an enum-backed choice property. + /// The enum property type. + /// The direct result property selector. + /// An immutable enum-to-probability snapshot. + public IReadOnlyDictionary GetDistribution( + Expression> selector) + where TEnum : struct, Enum => + _definition.GetDistribution(this, selector); +} + +internal sealed class DecisionDefinitionQuestion +{ + internal DecisionDefinitionQuestion( + PropertyInfo property, + string propertyName, + DecisionQuestion question, + object? enumDefinition, + DecisionKind kind, + bool usesExpectedScore, + Func valueAccessor, + Func? choiceValueMatches) + { + Property = property; + PropertyName = propertyName; + Question = question; + EnumDefinition = enumDefinition; + Kind = kind; + UsesExpectedScore = usesExpectedScore; + ValueAccessor = valueAccessor; + ChoiceValueMatches = choiceValueMatches; + } + + internal PropertyInfo Property { get; } + internal string PropertyName { get; } + internal DecisionQuestion Question { get; } + internal object? EnumDefinition { get; } + internal DecisionKind Kind { get; } + internal bool UsesExpectedScore { get; } + internal Func ValueAccessor { get; } + internal Func? ChoiceValueMatches { get; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionFeatures.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionFeatures.cs new file mode 100644 index 00000000000..51a4944233f --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionFeatures.cs @@ -0,0 +1,243 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +#pragma warning disable SA1402 // File may only contain a single type — feature projection types are co-located as one API surface. +#pragma warning disable SA1649 // File name should match first type name — feature projection types are co-located as one API surface. +#pragma warning disable SA1204 // Static projection type is intentionally grouped with the feature model. + +using System; +using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; +using System.Linq; +using Microsoft.Shared.DiagnosticIds; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.AI; + +/// Identifies the semantic value projected by a feature coordinate. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public enum DecisionFeatureValueKind +{ + /// The probability that a binary proposition is true. + BinaryTrueProbability, + + /// The probability that a binary proposition is false. + BinaryFalseProbability, + + /// The probability of one choice candidate. + ChoiceProbability, + + /// The probability of one score level. + ScoreProbability, + + /// The provider-reported ordinal score. + Score, + + /// The ordinal score calculated from the complete observed distribution. + ExpectedScore, +} + +/// Names one stable semantic coordinate in a feature schema. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionFeatureCoordinate +{ + /// Initializes a new instance of the class. + public DecisionFeatureCoordinate( + string name, + string questionId, + DecisionFeatureValueKind valueKind, + string? memberId = null) + { + Name = Throw.IfNullOrWhitespace(name); + QuestionId = Throw.IfNullOrWhitespace(questionId); + if (!Enum.IsDefined(typeof(DecisionFeatureValueKind), valueKind)) + { + Throw.ArgumentOutOfRangeException(nameof(valueKind)); + } + + ValueKind = valueKind; + + bool requiresMemberId = valueKind is DecisionFeatureValueKind.ChoiceProbability or DecisionFeatureValueKind.ScoreProbability; + if (requiresMemberId != (memberId is not null)) + { + Throw.ArgumentException( + nameof(memberId), + requiresMemberId ? "This coordinate kind requires a member ID." : "This coordinate kind does not accept a member ID."); + } + + if (memberId is not null) + { + MemberId = Throw.IfNullOrWhitespace(memberId); + } + } + + /// Gets the stable coordinate name. + public string Name { get; } + + /// Gets the exact question ID supplying this coordinate. + public string QuestionId { get; } + + /// Gets the coordinate semantic kind. + public DecisionFeatureValueKind ValueKind { get; } + + /// Gets the exact candidate or level ID, when applicable. + public string? MemberId { get; } +} + +/// Identifies a named feature schema and its version. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionFeatureSchema +{ + /// Initializes a new instance of the class. + public DecisionFeatureSchema(string id, int version, IEnumerable coordinates) + { + Id = Throw.IfNullOrWhitespace(id); + if (version < 1) + { + Throw.ArgumentOutOfRangeException(nameof(version)); + } + + _ = Throw.IfNull(coordinates); + DecisionFeatureCoordinate[] copy = coordinates.ToArray(); + if (copy.Length == 0 || Array.Exists(copy, static coordinate => coordinate is null)) + { + Throw.ArgumentException(nameof(coordinates), "Coordinates must be nonempty."); + } + + HashSet names = new(StringComparer.Ordinal); + foreach (DecisionFeatureCoordinate coordinate in copy) + { + if (!names.Add(coordinate.Name)) + { + Throw.ArgumentException(nameof(coordinates), "Feature names must be unique using ordinal comparison."); + } + } + + Version = version; + Coordinates = Array.AsReadOnly(copy); + } + + /// Gets the stable schema identity. + public string Id { get; } + + /// Gets the schema version. + public int Version { get; } + + /// Gets the ordered coordinate snapshot. + public IReadOnlyList Coordinates { get; } +} + +/// Represents one named native-double feature value. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionFeatureValue +{ + /// Initializes a new instance of the class. + public DecisionFeatureValue(string name, double value) + { + Name = Throw.IfNullOrWhitespace(name); + if (double.IsNaN(value) || double.IsInfinity(value)) + { + Throw.ArgumentOutOfRangeException(nameof(value)); + } + + Value = value; + } + + /// Gets the stable coordinate name. + public string Name { get; } + + /// Gets the native double value. + public double Value { get; } +} + +/// Represents a named feature projection with schema and provenance. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionFeatureVector +{ + internal DecisionFeatureVector( + DecisionFeatureSchema schema, + IEnumerable values, + DecisionProvenance? provenance) + { + Schema = schema; + Values = Array.AsReadOnly(values.ToArray()); + Provenance = provenance; + } + + /// Gets the explicit feature schema. + public DecisionFeatureSchema Schema { get; } + + /// Gets named values in schema order. + public IReadOnlyList Values { get; } + + /// Gets provider/model provenance, when reported by the response. + public DecisionProvenance? Provenance { get; } +} + +/// Projects complete decision observations into named native-double coordinates. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public static class DecisionFeatureProjection +{ + /// Projects a response without an inference call or probability repair. + /// The named feature vector projected from the complete response. + public static DecisionFeatureVector Project( + DecisionResponse response, + DecisionFeatureSchema schema) + { + _ = Throw.IfNull(response); + _ = Throw.IfNull(schema); + + List values = new(schema.Coordinates.Count); + foreach (DecisionFeatureCoordinate coordinate in schema.Coordinates) + { + DecisionAnswer answer = response.GetAnswer(coordinate.QuestionId); + double value = coordinate.ValueKind switch + { + DecisionFeatureValueKind.BinaryTrueProbability => + GetBinary(answer, coordinate).TrueProbability, + DecisionFeatureValueKind.BinaryFalseProbability => + 1 - GetBinary(answer, coordinate).TrueProbability, + DecisionFeatureValueKind.ChoiceProbability => + GetProbability(GetChoice(answer, coordinate).Probabilities, coordinate.MemberId!), + DecisionFeatureValueKind.ScoreProbability => + GetProbability(GetScore(answer, coordinate).Probabilities, coordinate.MemberId!), + DecisionFeatureValueKind.Score => + GetScore(answer, coordinate).Score ?? + throw new DecisionProtocolException( + $"Question '{coordinate.QuestionId}' does not contain a provider-reported score."), + DecisionFeatureValueKind.ExpectedScore => + GetScore(answer, coordinate).ExpectedScore, + _ => throw new ArgumentOutOfRangeException(nameof(schema)), + }; + + values.Add(new DecisionFeatureValue(coordinate.Name, value)); + } + + return new DecisionFeatureVector(schema, values, response.Provenance); + } + + private static BinaryDecisionAnswer GetBinary(DecisionAnswer answer, DecisionFeatureCoordinate coordinate) => + answer as BinaryDecisionAnswer ?? + throw new ArgumentException($"Question '{coordinate.QuestionId}' is not binary.", nameof(coordinate)); + + private static ChoiceDecisionAnswer GetChoice(DecisionAnswer answer, DecisionFeatureCoordinate coordinate) => + answer as ChoiceDecisionAnswer ?? + throw new ArgumentException($"Question '{coordinate.QuestionId}' is not a choice.", nameof(coordinate)); + + private static ScoreDecisionAnswer GetScore(DecisionAnswer answer, DecisionFeatureCoordinate coordinate) => + answer as ScoreDecisionAnswer ?? + throw new ArgumentException($"Question '{coordinate.QuestionId}' is not a score.", nameof(coordinate)); + + private static double GetProbability(IReadOnlyList probabilities, string memberId) + { + foreach (DecisionProbability probability in probabilities) + { + if (string.Equals(probability.Id, memberId, StringComparison.Ordinal)) + { + return probability.Value; + } + } + + throw new DecisionProtocolException($"Unknown feature member ID '{memberId}'."); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionQuestions.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionQuestions.cs new file mode 100644 index 00000000000..cc37031765c --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/DecisionQuestions.cs @@ -0,0 +1,281 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +#pragma warning disable SA1402 // File may only contain a single type — decision question types are co-located as one immutable model. +#pragma warning disable SA1649 // File name should match first type name — decision question types are co-located as one immutable model. + +using System; +using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; +using System.Linq; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Text.Json.Serialization.Metadata; +using Microsoft.Shared.DiagnosticIds; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.AI; + +/// Identifies the semantic kind of a decision question or answer. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public enum DecisionKind +{ + /// A two-outcome proposition. + Binary, + + /// A choice from a caller-defined unordered set. + Choice, + + /// A position on a caller-defined ordered scale. + Score, +} + +/// Describes a decision question. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")] +[JsonDerivedType(typeof(BinaryDecisionQuestion), "binary")] +[JsonDerivedType(typeof(ChoiceDecisionQuestion), "choice")] +[JsonDerivedType(typeof(ScoreDecisionQuestion), "score")] +public abstract class DecisionQuestion +{ + private protected DecisionQuestion(string id, DecisionKind kind, string? instructions) + { + Id = Throw.IfNullOrWhitespace(id); + Kind = kind; + Instructions = instructions ?? string.Empty; + } + + /// Gets the opaque, caller-owned correlation ID for this question. + public string Id { get; } + + /// Gets the semantic kind of this question. + public DecisionKind Kind { get; } + + /// Gets the explicit instructions that define the question. + public string Instructions { get; } +} + +/// Describes a binary decision question. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class BinaryDecisionQuestion : DecisionQuestion +{ + /// Initializes a new instance of the class. + /// The opaque, caller-owned question ID. + /// The instructions defining the proposition. + /// Optional criteria describing a true result. + /// Optional criteria describing a false result. + [JsonConstructor] + public BinaryDecisionQuestion( + string id, + string? instructions = null, + string? trueDescription = null, + string? falseDescription = null) + : base(id, DecisionKind.Binary, instructions) + { + if (string.IsNullOrWhiteSpace(instructions) && + (string.IsNullOrWhiteSpace(trueDescription) || string.IsNullOrWhiteSpace(falseDescription))) + { + Throw.ArgumentException( + nameof(instructions), + "Binary questions require instructions or both true and false descriptions."); + } + + if (trueDescription is not null) + { + _ = Throw.IfNullOrWhitespace(trueDescription); + } + + if (falseDescription is not null) + { + _ = Throw.IfNullOrWhitespace(falseDescription); + } + + TrueDescription = trueDescription; + FalseDescription = falseDescription; + } + + /// Gets the optional criteria describing a true result. + public string? TrueDescription { get; } + + /// Gets the optional criteria describing a false result. + public string? FalseDescription { get; } +} + +/// Describes one caller-defined choice candidate. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionCandidate +{ + /// Initializes a new instance of the class. + /// The exact opaque candidate ID to round-trip in results. + /// The human-readable candidate criteria. + [JsonConstructor] + public DecisionCandidate(string id, string description) + { + Id = Throw.IfNullOrWhitespace(id); + Description = Throw.IfNullOrWhitespace(description); + } + + /// Gets the exact opaque, caller-owned candidate ID. + public string Id { get; } + + /// Gets the human-readable candidate criteria. + public string Description { get; } +} + +/// Describes a choice decision question. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class ChoiceDecisionQuestion : DecisionQuestion +{ + /// Initializes a new instance of the class. + /// The opaque, caller-owned question ID. + /// The instructions defining the choice. + /// The ordered, caller-defined candidates. + [JsonConstructor] + public ChoiceDecisionQuestion(string id, string? instructions, IReadOnlyList candidates) + : base(id, DecisionKind.Choice, instructions) + { + _ = Throw.IfNull(candidates); + + DecisionCandidate[] copy = candidates.ToArray(); + if (copy.Length == 0 || Array.Exists(copy, static candidate => candidate is null)) + { + Throw.ArgumentException(nameof(candidates), "Candidates must be nonempty."); + } + + HashSet ids = new(StringComparer.Ordinal); + foreach (DecisionCandidate candidate in copy) + { + if (!ids.Add(candidate.Id)) + { + Throw.ArgumentException( + nameof(candidates), + "Candidate IDs must be unique using ordinal comparison."); + } + } + + Candidates = Array.AsReadOnly(copy); + } + + /// Gets the ordered, owned candidate snapshot. + public IReadOnlyList Candidates { get; } +} + +/// Describes one level in an ordered score rubric. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionScoreLevel +{ + /// Initializes a new instance of the class. + /// The exact opaque, caller-owned level ID. + /// The criteria for this level. + [JsonConstructor] + public DecisionScoreLevel(string id, string description) + { + Id = Throw.IfNullOrWhitespace(id); + Description = Throw.IfNullOrWhitespace(description); + } + + /// Gets the exact opaque level ID. + public string Id { get; } + + /// Gets the criteria for this level. + public string Description { get; } +} + +/// Describes a score decision question. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class ScoreDecisionQuestion : DecisionQuestion +{ + /// Initializes a new instance of the class. + /// The opaque, caller-owned question ID. + /// The instructions defining the score. + /// The ordered, caller-defined score levels. + [JsonConstructor] + public ScoreDecisionQuestion(string id, string? instructions, IReadOnlyList levels) + : base(id, DecisionKind.Score, instructions) + { + _ = Throw.IfNull(levels); + + DecisionScoreLevel[] copy = levels.ToArray(); + if (copy.Length < 2 || Array.Exists(copy, static level => level is null)) + { + Throw.ArgumentException(nameof(levels), "A score question requires at least two levels."); + } + + HashSet ids = new(StringComparer.Ordinal); + foreach (DecisionScoreLevel level in copy) + { + if (!ids.Add(level.Id)) + { + Throw.ArgumentException( + nameof(levels), + "Score level IDs must be unique using ordinal comparison."); + } + } + + Levels = Array.AsReadOnly(copy); + } + + /// Gets the ordered, owned score-level snapshot. + public IReadOnlyList Levels { get; } +} + +/// Represents a state and a nonempty, ordered batch of questions. +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class DecisionRequest +{ + /// Initializes a new instance of the class and snapshots its state and questions. + /// The explicit JSON state evaluated by every question. + /// The ordered heterogeneous question batch. + [JsonConstructor] + public DecisionRequest(JsonElement state, IReadOnlyList questions) + { + if (state.ValueKind == JsonValueKind.Undefined) + { + Throw.ArgumentException(nameof(state), "State must be explicit JSON."); + } + + _ = Throw.IfNull(questions); + + DecisionQuestion[] copy = questions.ToArray(); + if (copy.Length == 0 || Array.Exists(copy, static question => question is null)) + { + Throw.ArgumentException(nameof(questions), "Questions must be nonempty."); + } + + HashSet ids = new(StringComparer.Ordinal); + foreach (DecisionQuestion question in copy) + { + if (!ids.Add(question.Id)) + { + Throw.ArgumentException( + nameof(questions), + "Question IDs must be unique using ordinal comparison."); + } + } + + State = state.Clone(); + Questions = Array.AsReadOnly(copy); + } + + /// Gets the owned JSON state snapshot. + public JsonElement State { get; } + + /// Gets the ordered, owned question snapshot. + public IReadOnlyList Questions { get; } + + /// Creates a request from an application-owned state using an explicit source-generated contract. + /// The application state type. + /// The application-owned state. + /// The source-generated JSON contract for . + /// The ordered heterogeneous question batch. + /// An owned decision request. + public static DecisionRequest Create( + TState state, + JsonTypeInfo stateTypeInfo, + IEnumerable questions) + { + _ = Throw.IfNull(stateTypeInfo); + _ = Throw.IfNull(questions); + return new(JsonSerializer.SerializeToElement(state, stateTypeInfo), questions.ToArray()); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/README.md b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/README.md new file mode 100644 index 00000000000..d6c1cedd00f --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/MEAI/README.md @@ -0,0 +1,51 @@ +# MEAI + +A copy of the provider-neutral decision API that is proposed for `Microsoft.Extensions.AI.Abstractions`: +`IDecisionClient`, Binary, Choice, and Score questions and answers, the typed `DecisionDefinition`, and +`DecisionDefinition.AsAIFunction`. Decision models (Jev, Azure OpenAI Decisions, and others) answer typed +questions about a state with probabilities, instead of writing text. + +The types are public, in the `Microsoft.Extensions.AI` namespace, and marked `[Experimental("MEAI001")]`, exactly as +proposed, although they ship in this Agent Framework package. Code written against them today, such as provider +clients and samples, is the code that will compile against the shipped API. This follows how Agent Framework shipped +proposed MEAI types before they were released (#279, #426), and deleted them once MEAI shipped them (#427, #676). + +## Source + +| Proposal | Pull request | Commit | +|---|---|---| +| Layer 1: provider-neutral decision abstractions | [dotnet/extensions#7795](https://github.com/dotnet/extensions/pull/7795) | `02e54f023bdf3c8c2729353b110c22f5f8593957` | +| Layer 2: decision interoperability (`AsAIFunction`) | [dotnet/extensions#7796](https://github.com/dotnet/extensions/pull/7796) | `e87f1126cf22108fb27f6391c7826fb91c25138e` | + +The files are `src/Libraries/Microsoft.Extensions.AI.Abstractions/Decisions/*.cs` at the Layer 2 commit, which contains +Layer 1, without changes. `.editorconfig` keeps the upstream style and API shape from failing the build. The package +injects `src/Shared/DiagnosticIds` and `src/Shared/Throw`, which provide the helpers the upstream code uses, and the +polyfills that the upstream code relies on for .NET Standard 2.0 and .NET Framework. + +Not copied: the upstream tests, the README, and the registration of the decision types in +`AIJsonUtilities.DefaultOptions`. Serializing the decision types therefore uses reflection-based metadata. + +## Placement + +The copy lives where MEAI places the API: everything is in `Microsoft.Extensions.AI.Abstractions` upstream, so it is in +`Microsoft.Agents.AI.Abstractions` here, which every provider package depends on. Only this package may carry the copy, +because a second package with the same public types would make them ambiguous (CS0433) for an application that +references both. + +The API is still in review, and the review on #7795 asks, among other things, to align `DecisionResponse` with +`ChatResponse` and to move the typed layer (`DecisionDefinition`, `DecisionResponse`, and the typed +extensions) to `Microsoft.Extensions.AI`. When upstream changes, copy the new files over these ones and update the +public API files. If the typed layer moves to `Microsoft.Extensions.AI`, move its copy to `Microsoft.Agents.AI`. Each +re-sync can break code that uses the types, which their `MEAI001` diagnostic allows. + +## When Microsoft.Extensions.AI ships the API + +1. Update `Microsoft.Extensions.AI.Abstractions` in `Directory.Packages.props`. From that version on, the copied types + conflict with the shipped ones, so the next steps go in the same change and the same release. +2. Delete this folder and its entries in `PublicAPI/*/PublicAPI.Unshipped.txt` (or `PublicAPI.Shipped.txt`, once a + release has shipped them). +3. Add `[assembly: TypeForwardedTo(typeof(...))]` for each public type, so applications compiled against this package + keep loading the types from `Microsoft.Extensions.AI.Abstractions`. Suppress any package validation difference + between this copy and the shipped shape in `CompatibilitySuppressions.xml`. +4. Fix any difference between this copy and the shipped API in the packages that use it, such as + `Microsoft.Agents.AI.TypeSafe` and the samples. diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net10.0/PublicAPI.Unshipped.txt b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net10.0/PublicAPI.Unshipped.txt index 7dc5c58110b..6dd8fb7d4d5 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net10.0/PublicAPI.Unshipped.txt +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net10.0/PublicAPI.Unshipped.txt @@ -1 +1,174 @@ #nullable enable +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.BinaryDecisionAnswer(string! questionId, double trueProbability, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.TrueProbability.get -> double +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.BinaryDecisionQuestion(string! id, string? instructions = null, string? trueDescription = null, string? falseDescription = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.FalseDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.TrueDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.ChoiceDecisionAnswer(string! questionId, string! selectedCandidateId, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.SelectedCandidateId.get -> string! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.ChoiceDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! candidates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetBinary(string! questionId) -> Microsoft.Extensions.AI.BinaryDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId) -> Microsoft.Extensions.AI.ChoiceDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId, Microsoft.Extensions.AI.DecisionEnumDefinition! definition) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetScore(string! questionId) -> Microsoft.Extensions.AI.ScoreDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.Response.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionBindingExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.DecisionCandidate(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionClientException +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, bool isTransient, System.Exception? innerException = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.IsTransient.get -> bool +[MEAI001]Microsoft.Extensions.AI.DecisionClientExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DecisionClientMetadata(string? providerName = null, System.Uri? providerUri = null, string? defaultModelId = null, System.Collections.Generic.IReadOnlyList? supportedKinds = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DefaultModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.SupportedKinds.get -> System.Collections.Generic.IReadOnlyList? +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.AsAIFunction(Microsoft.Extensions.AI.IDecisionClient! client, Microsoft.Extensions.AI.AIFunctionFactoryOptions? functionOptions = null, Microsoft.Extensions.AI.DecisionOptions? decisionOptions = null, System.Text.Json.Serialization.Metadata.JsonTypeInfo? stateTypeInfo = null) -> Microsoft.Extensions.AI.AIFunction! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.BinaryProbability(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Choice(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.ExpectedScore(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Score(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.SerializerOptions.get -> System.Text.Json.JsonSerializerOptions! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.CreateQuestion(string! id, string? instructions) -> Microsoft.Extensions.AI.ChoiceDecisionQuestion! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.DecisionEnumDefinition(System.Collections.Generic.IEnumerable!>! values) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Parse(string! candidateId) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.DecisionEnumValue(TEnum value, string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Value.get -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.DecisionFeatureCoordinate(string! name, string! questionId, Microsoft.Extensions.AI.DecisionFeatureValueKind valueKind, string? memberId = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.MemberId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.ValueKind.get -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureProjection +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Coordinates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.DecisionFeatureSchema(string! id, int version, System.Collections.Generic.IEnumerable! coordinates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Version.get -> int +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.DecisionFeatureValue(string! name, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryFalseProbability = 1 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryTrueProbability = 0 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ChoiceProbability = 2 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ExpectedScore = 5 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.Score = 4 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ScoreProbability = 3 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Schema.get -> Microsoft.Extensions.AI.DecisionFeatureSchema! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Values.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Binary = 0 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Choice = 1 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Score = 2 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionOptions +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.get -> Microsoft.Extensions.AI.AdditionalPropertiesDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions(Microsoft.Extensions.AI.DecisionOptions? other) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.get -> System.Func? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.FourDecimalPlaces = 1 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.HighPrecision = 0 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.TwoDecimalPlaces = 2 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionProbability +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.DecisionProbability(string! id, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.DecisionProvenance(string? providerName = null, System.Uri? providerUri = null, string? modelId = null, string? responseId = null, Microsoft.Extensions.AI.DecisionPrecision? precision = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ResponseId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Instructions.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionRequest +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.DecisionRequest(System.Text.Json.JsonElement state, System.Collections.Generic.IReadOnlyList! questions) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.State.get -> System.Text.Json.JsonElement +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Answers.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.DecisionResponse(Microsoft.Extensions.AI.DecisionRequest! request, System.Collections.Generic.IReadOnlyList! answers, Microsoft.Extensions.AI.DecisionProvenance? provenance = null, Microsoft.Extensions.AI.UsageDetails? usage = null, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetAnswer(string! questionId) -> Microsoft.Extensions.AI.DecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Request.get -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Usage.get -> Microsoft.Extensions.AI.UsageDetails? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Evidence.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetDistribution(System.Linq.Expressions.Expression!>! selector) -> System.Collections.Generic.IReadOnlyDictionary! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Result.get -> TResult +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.DecisionResultBinding(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Func! map) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.DecisionScoreLevel(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetResponseAsync(Microsoft.Extensions.AI.DecisionRequest! request, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetService(System.Type! serviceType, object? serviceKey = null) -> object? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ExpectedScore.get -> double +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Score.get -> double? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ScoreDecisionAnswer(string! questionId, double? score, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.Levels.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.ScoreDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! levels) -> void +[MEAI001]static Microsoft.Extensions.AI.DecisionBindingExtensions.Bind(this Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionResultBinding! binding) -> TResult +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, System.Text.Json.JsonElement state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetService(this Microsoft.Extensions.AI.IDecisionClient! client, object? serviceKey = null) -> TService? +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Action.Builder!>! configure, System.Text.Json.JsonSerializerOptions? serializerOptions = null) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Action.Builder!>! configure) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionFeatureProjection.Project(Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionFeatureSchema! schema) -> Microsoft.Extensions.AI.DecisionFeatureVector! +[MEAI001]static Microsoft.Extensions.AI.DecisionRequest.Create(TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions) -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]virtual Microsoft.Extensions.AI.DecisionOptions.Clone() -> Microsoft.Extensions.AI.DecisionOptions! diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net472/PublicAPI.Unshipped.txt b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net472/PublicAPI.Unshipped.txt index 7dc5c58110b..6dd8fb7d4d5 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net472/PublicAPI.Unshipped.txt +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net472/PublicAPI.Unshipped.txt @@ -1 +1,174 @@ #nullable enable +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.BinaryDecisionAnswer(string! questionId, double trueProbability, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.TrueProbability.get -> double +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.BinaryDecisionQuestion(string! id, string? instructions = null, string? trueDescription = null, string? falseDescription = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.FalseDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.TrueDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.ChoiceDecisionAnswer(string! questionId, string! selectedCandidateId, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.SelectedCandidateId.get -> string! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.ChoiceDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! candidates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetBinary(string! questionId) -> Microsoft.Extensions.AI.BinaryDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId) -> Microsoft.Extensions.AI.ChoiceDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId, Microsoft.Extensions.AI.DecisionEnumDefinition! definition) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetScore(string! questionId) -> Microsoft.Extensions.AI.ScoreDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.Response.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionBindingExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.DecisionCandidate(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionClientException +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, bool isTransient, System.Exception? innerException = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.IsTransient.get -> bool +[MEAI001]Microsoft.Extensions.AI.DecisionClientExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DecisionClientMetadata(string? providerName = null, System.Uri? providerUri = null, string? defaultModelId = null, System.Collections.Generic.IReadOnlyList? supportedKinds = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DefaultModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.SupportedKinds.get -> System.Collections.Generic.IReadOnlyList? +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.AsAIFunction(Microsoft.Extensions.AI.IDecisionClient! client, Microsoft.Extensions.AI.AIFunctionFactoryOptions? functionOptions = null, Microsoft.Extensions.AI.DecisionOptions? decisionOptions = null, System.Text.Json.Serialization.Metadata.JsonTypeInfo? stateTypeInfo = null) -> Microsoft.Extensions.AI.AIFunction! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.BinaryProbability(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Choice(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.ExpectedScore(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Score(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.SerializerOptions.get -> System.Text.Json.JsonSerializerOptions! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.CreateQuestion(string! id, string? instructions) -> Microsoft.Extensions.AI.ChoiceDecisionQuestion! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.DecisionEnumDefinition(System.Collections.Generic.IEnumerable!>! values) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Parse(string! candidateId) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.DecisionEnumValue(TEnum value, string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Value.get -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.DecisionFeatureCoordinate(string! name, string! questionId, Microsoft.Extensions.AI.DecisionFeatureValueKind valueKind, string? memberId = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.MemberId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.ValueKind.get -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureProjection +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Coordinates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.DecisionFeatureSchema(string! id, int version, System.Collections.Generic.IEnumerable! coordinates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Version.get -> int +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.DecisionFeatureValue(string! name, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryFalseProbability = 1 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryTrueProbability = 0 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ChoiceProbability = 2 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ExpectedScore = 5 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.Score = 4 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ScoreProbability = 3 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Schema.get -> Microsoft.Extensions.AI.DecisionFeatureSchema! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Values.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Binary = 0 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Choice = 1 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Score = 2 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionOptions +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.get -> Microsoft.Extensions.AI.AdditionalPropertiesDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions(Microsoft.Extensions.AI.DecisionOptions? other) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.get -> System.Func? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.FourDecimalPlaces = 1 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.HighPrecision = 0 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.TwoDecimalPlaces = 2 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionProbability +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.DecisionProbability(string! id, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.DecisionProvenance(string? providerName = null, System.Uri? providerUri = null, string? modelId = null, string? responseId = null, Microsoft.Extensions.AI.DecisionPrecision? precision = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ResponseId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Instructions.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionRequest +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.DecisionRequest(System.Text.Json.JsonElement state, System.Collections.Generic.IReadOnlyList! questions) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.State.get -> System.Text.Json.JsonElement +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Answers.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.DecisionResponse(Microsoft.Extensions.AI.DecisionRequest! request, System.Collections.Generic.IReadOnlyList! answers, Microsoft.Extensions.AI.DecisionProvenance? provenance = null, Microsoft.Extensions.AI.UsageDetails? usage = null, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetAnswer(string! questionId) -> Microsoft.Extensions.AI.DecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Request.get -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Usage.get -> Microsoft.Extensions.AI.UsageDetails? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Evidence.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetDistribution(System.Linq.Expressions.Expression!>! selector) -> System.Collections.Generic.IReadOnlyDictionary! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Result.get -> TResult +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.DecisionResultBinding(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Func! map) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.DecisionScoreLevel(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetResponseAsync(Microsoft.Extensions.AI.DecisionRequest! request, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetService(System.Type! serviceType, object? serviceKey = null) -> object? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ExpectedScore.get -> double +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Score.get -> double? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ScoreDecisionAnswer(string! questionId, double? score, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.Levels.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.ScoreDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! levels) -> void +[MEAI001]static Microsoft.Extensions.AI.DecisionBindingExtensions.Bind(this Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionResultBinding! binding) -> TResult +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, System.Text.Json.JsonElement state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetService(this Microsoft.Extensions.AI.IDecisionClient! client, object? serviceKey = null) -> TService? +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Action.Builder!>! configure, System.Text.Json.JsonSerializerOptions? serializerOptions = null) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Action.Builder!>! configure) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionFeatureProjection.Project(Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionFeatureSchema! schema) -> Microsoft.Extensions.AI.DecisionFeatureVector! +[MEAI001]static Microsoft.Extensions.AI.DecisionRequest.Create(TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions) -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]virtual Microsoft.Extensions.AI.DecisionOptions.Clone() -> Microsoft.Extensions.AI.DecisionOptions! diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net8.0/PublicAPI.Unshipped.txt b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net8.0/PublicAPI.Unshipped.txt index 7dc5c58110b..6dd8fb7d4d5 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net8.0/PublicAPI.Unshipped.txt +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net8.0/PublicAPI.Unshipped.txt @@ -1 +1,174 @@ #nullable enable +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.BinaryDecisionAnswer(string! questionId, double trueProbability, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.TrueProbability.get -> double +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.BinaryDecisionQuestion(string! id, string? instructions = null, string? trueDescription = null, string? falseDescription = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.FalseDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.TrueDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.ChoiceDecisionAnswer(string! questionId, string! selectedCandidateId, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.SelectedCandidateId.get -> string! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.ChoiceDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! candidates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetBinary(string! questionId) -> Microsoft.Extensions.AI.BinaryDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId) -> Microsoft.Extensions.AI.ChoiceDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId, Microsoft.Extensions.AI.DecisionEnumDefinition! definition) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetScore(string! questionId) -> Microsoft.Extensions.AI.ScoreDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.Response.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionBindingExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.DecisionCandidate(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionClientException +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, bool isTransient, System.Exception? innerException = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.IsTransient.get -> bool +[MEAI001]Microsoft.Extensions.AI.DecisionClientExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DecisionClientMetadata(string? providerName = null, System.Uri? providerUri = null, string? defaultModelId = null, System.Collections.Generic.IReadOnlyList? supportedKinds = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DefaultModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.SupportedKinds.get -> System.Collections.Generic.IReadOnlyList? +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.AsAIFunction(Microsoft.Extensions.AI.IDecisionClient! client, Microsoft.Extensions.AI.AIFunctionFactoryOptions? functionOptions = null, Microsoft.Extensions.AI.DecisionOptions? decisionOptions = null, System.Text.Json.Serialization.Metadata.JsonTypeInfo? stateTypeInfo = null) -> Microsoft.Extensions.AI.AIFunction! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.BinaryProbability(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Choice(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.ExpectedScore(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Score(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.SerializerOptions.get -> System.Text.Json.JsonSerializerOptions! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.CreateQuestion(string! id, string? instructions) -> Microsoft.Extensions.AI.ChoiceDecisionQuestion! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.DecisionEnumDefinition(System.Collections.Generic.IEnumerable!>! values) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Parse(string! candidateId) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.DecisionEnumValue(TEnum value, string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Value.get -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.DecisionFeatureCoordinate(string! name, string! questionId, Microsoft.Extensions.AI.DecisionFeatureValueKind valueKind, string? memberId = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.MemberId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.ValueKind.get -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureProjection +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Coordinates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.DecisionFeatureSchema(string! id, int version, System.Collections.Generic.IEnumerable! coordinates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Version.get -> int +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.DecisionFeatureValue(string! name, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryFalseProbability = 1 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryTrueProbability = 0 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ChoiceProbability = 2 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ExpectedScore = 5 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.Score = 4 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ScoreProbability = 3 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Schema.get -> Microsoft.Extensions.AI.DecisionFeatureSchema! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Values.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Binary = 0 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Choice = 1 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Score = 2 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionOptions +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.get -> Microsoft.Extensions.AI.AdditionalPropertiesDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions(Microsoft.Extensions.AI.DecisionOptions? other) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.get -> System.Func? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.FourDecimalPlaces = 1 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.HighPrecision = 0 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.TwoDecimalPlaces = 2 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionProbability +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.DecisionProbability(string! id, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.DecisionProvenance(string? providerName = null, System.Uri? providerUri = null, string? modelId = null, string? responseId = null, Microsoft.Extensions.AI.DecisionPrecision? precision = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ResponseId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Instructions.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionRequest +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.DecisionRequest(System.Text.Json.JsonElement state, System.Collections.Generic.IReadOnlyList! questions) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.State.get -> System.Text.Json.JsonElement +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Answers.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.DecisionResponse(Microsoft.Extensions.AI.DecisionRequest! request, System.Collections.Generic.IReadOnlyList! answers, Microsoft.Extensions.AI.DecisionProvenance? provenance = null, Microsoft.Extensions.AI.UsageDetails? usage = null, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetAnswer(string! questionId) -> Microsoft.Extensions.AI.DecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Request.get -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Usage.get -> Microsoft.Extensions.AI.UsageDetails? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Evidence.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetDistribution(System.Linq.Expressions.Expression!>! selector) -> System.Collections.Generic.IReadOnlyDictionary! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Result.get -> TResult +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.DecisionResultBinding(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Func! map) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.DecisionScoreLevel(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetResponseAsync(Microsoft.Extensions.AI.DecisionRequest! request, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetService(System.Type! serviceType, object? serviceKey = null) -> object? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ExpectedScore.get -> double +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Score.get -> double? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ScoreDecisionAnswer(string! questionId, double? score, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.Levels.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.ScoreDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! levels) -> void +[MEAI001]static Microsoft.Extensions.AI.DecisionBindingExtensions.Bind(this Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionResultBinding! binding) -> TResult +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, System.Text.Json.JsonElement state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetService(this Microsoft.Extensions.AI.IDecisionClient! client, object? serviceKey = null) -> TService? +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Action.Builder!>! configure, System.Text.Json.JsonSerializerOptions? serializerOptions = null) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Action.Builder!>! configure) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionFeatureProjection.Project(Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionFeatureSchema! schema) -> Microsoft.Extensions.AI.DecisionFeatureVector! +[MEAI001]static Microsoft.Extensions.AI.DecisionRequest.Create(TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions) -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]virtual Microsoft.Extensions.AI.DecisionOptions.Clone() -> Microsoft.Extensions.AI.DecisionOptions! diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net9.0/PublicAPI.Unshipped.txt b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net9.0/PublicAPI.Unshipped.txt index 7dc5c58110b..6dd8fb7d4d5 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net9.0/PublicAPI.Unshipped.txt +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/net9.0/PublicAPI.Unshipped.txt @@ -1 +1,174 @@ #nullable enable +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.BinaryDecisionAnswer(string! questionId, double trueProbability, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.TrueProbability.get -> double +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.BinaryDecisionQuestion(string! id, string? instructions = null, string? trueDescription = null, string? falseDescription = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.FalseDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.TrueDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.ChoiceDecisionAnswer(string! questionId, string! selectedCandidateId, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.SelectedCandidateId.get -> string! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.ChoiceDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! candidates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetBinary(string! questionId) -> Microsoft.Extensions.AI.BinaryDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId) -> Microsoft.Extensions.AI.ChoiceDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId, Microsoft.Extensions.AI.DecisionEnumDefinition! definition) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetScore(string! questionId) -> Microsoft.Extensions.AI.ScoreDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.Response.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionBindingExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.DecisionCandidate(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionClientException +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, bool isTransient, System.Exception? innerException = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.IsTransient.get -> bool +[MEAI001]Microsoft.Extensions.AI.DecisionClientExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DecisionClientMetadata(string? providerName = null, System.Uri? providerUri = null, string? defaultModelId = null, System.Collections.Generic.IReadOnlyList? supportedKinds = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DefaultModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.SupportedKinds.get -> System.Collections.Generic.IReadOnlyList? +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.AsAIFunction(Microsoft.Extensions.AI.IDecisionClient! client, Microsoft.Extensions.AI.AIFunctionFactoryOptions? functionOptions = null, Microsoft.Extensions.AI.DecisionOptions? decisionOptions = null, System.Text.Json.Serialization.Metadata.JsonTypeInfo? stateTypeInfo = null) -> Microsoft.Extensions.AI.AIFunction! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.BinaryProbability(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Choice(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.ExpectedScore(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Score(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.SerializerOptions.get -> System.Text.Json.JsonSerializerOptions! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.CreateQuestion(string! id, string? instructions) -> Microsoft.Extensions.AI.ChoiceDecisionQuestion! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.DecisionEnumDefinition(System.Collections.Generic.IEnumerable!>! values) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Parse(string! candidateId) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.DecisionEnumValue(TEnum value, string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Value.get -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.DecisionFeatureCoordinate(string! name, string! questionId, Microsoft.Extensions.AI.DecisionFeatureValueKind valueKind, string? memberId = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.MemberId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.ValueKind.get -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureProjection +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Coordinates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.DecisionFeatureSchema(string! id, int version, System.Collections.Generic.IEnumerable! coordinates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Version.get -> int +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.DecisionFeatureValue(string! name, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryFalseProbability = 1 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryTrueProbability = 0 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ChoiceProbability = 2 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ExpectedScore = 5 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.Score = 4 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ScoreProbability = 3 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Schema.get -> Microsoft.Extensions.AI.DecisionFeatureSchema! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Values.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Binary = 0 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Choice = 1 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Score = 2 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionOptions +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.get -> Microsoft.Extensions.AI.AdditionalPropertiesDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions(Microsoft.Extensions.AI.DecisionOptions? other) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.get -> System.Func? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.FourDecimalPlaces = 1 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.HighPrecision = 0 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.TwoDecimalPlaces = 2 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionProbability +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.DecisionProbability(string! id, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.DecisionProvenance(string? providerName = null, System.Uri? providerUri = null, string? modelId = null, string? responseId = null, Microsoft.Extensions.AI.DecisionPrecision? precision = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ResponseId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Instructions.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionRequest +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.DecisionRequest(System.Text.Json.JsonElement state, System.Collections.Generic.IReadOnlyList! questions) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.State.get -> System.Text.Json.JsonElement +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Answers.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.DecisionResponse(Microsoft.Extensions.AI.DecisionRequest! request, System.Collections.Generic.IReadOnlyList! answers, Microsoft.Extensions.AI.DecisionProvenance? provenance = null, Microsoft.Extensions.AI.UsageDetails? usage = null, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetAnswer(string! questionId) -> Microsoft.Extensions.AI.DecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Request.get -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Usage.get -> Microsoft.Extensions.AI.UsageDetails? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Evidence.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetDistribution(System.Linq.Expressions.Expression!>! selector) -> System.Collections.Generic.IReadOnlyDictionary! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Result.get -> TResult +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.DecisionResultBinding(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Func! map) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.DecisionScoreLevel(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetResponseAsync(Microsoft.Extensions.AI.DecisionRequest! request, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetService(System.Type! serviceType, object? serviceKey = null) -> object? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ExpectedScore.get -> double +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Score.get -> double? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ScoreDecisionAnswer(string! questionId, double? score, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.Levels.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.ScoreDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! levels) -> void +[MEAI001]static Microsoft.Extensions.AI.DecisionBindingExtensions.Bind(this Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionResultBinding! binding) -> TResult +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, System.Text.Json.JsonElement state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetService(this Microsoft.Extensions.AI.IDecisionClient! client, object? serviceKey = null) -> TService? +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Action.Builder!>! configure, System.Text.Json.JsonSerializerOptions? serializerOptions = null) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Action.Builder!>! configure) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionFeatureProjection.Project(Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionFeatureSchema! schema) -> Microsoft.Extensions.AI.DecisionFeatureVector! +[MEAI001]static Microsoft.Extensions.AI.DecisionRequest.Create(TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions) -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]virtual Microsoft.Extensions.AI.DecisionOptions.Clone() -> Microsoft.Extensions.AI.DecisionOptions! diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt index 7dc5c58110b..6dd8fb7d4d5 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt @@ -1 +1,174 @@ #nullable enable +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.BinaryDecisionAnswer(string! questionId, double trueProbability, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionAnswer.TrueProbability.get -> double +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.BinaryDecisionQuestion(string! id, string? instructions = null, string? trueDescription = null, string? falseDescription = null) -> void +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.FalseDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.BinaryDecisionQuestion.TrueDescription.get -> string? +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.ChoiceDecisionAnswer(string! questionId, string! selectedCandidateId, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionAnswer.SelectedCandidateId.get -> string! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ChoiceDecisionQuestion.ChoiceDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! candidates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswer.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetBinary(string! questionId) -> Microsoft.Extensions.AI.BinaryDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId) -> Microsoft.Extensions.AI.ChoiceDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetChoice(string! questionId, Microsoft.Extensions.AI.DecisionEnumDefinition! definition) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.GetScore(string! questionId) -> Microsoft.Extensions.AI.ScoreDecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionAnswerSet.Response.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionBindingExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.DecisionCandidate(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionCandidate.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionClientException +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.DecisionClientException(string! message, bool isTransient, System.Exception? innerException = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientException.IsTransient.get -> bool +[MEAI001]Microsoft.Extensions.AI.DecisionClientExtensions +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DecisionClientMetadata(string? providerName = null, System.Uri? providerUri = null, string? defaultModelId = null, System.Collections.Generic.IReadOnlyList? supportedKinds = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.DefaultModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionClientMetadata.SupportedKinds.get -> System.Collections.Generic.IReadOnlyList? +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.AsAIFunction(Microsoft.Extensions.AI.IDecisionClient! client, Microsoft.Extensions.AI.AIFunctionFactoryOptions? functionOptions = null, Microsoft.Extensions.AI.DecisionOptions? decisionOptions = null, System.Text.Json.Serialization.Metadata.JsonTypeInfo? stateTypeInfo = null) -> Microsoft.Extensions.AI.AIFunction! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.BinaryProbability(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Choice(System.Linq.Expressions.Expression!>! selector, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.ExpectedScore(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Builder.Score(System.Linq.Expressions.Expression!>! selector, System.Collections.Generic.IReadOnlyList! levels, string? instructions = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionDefinition.SerializerOptions.get -> System.Text.Json.JsonSerializerOptions! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Candidates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.CreateQuestion(string! id, string? instructions) -> Microsoft.Extensions.AI.ChoiceDecisionQuestion! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.DecisionEnumDefinition(System.Collections.Generic.IEnumerable!>! values) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumDefinition.Parse(string! candidateId) -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.DecisionEnumValue(TEnum value, string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionEnumValue.Value.get -> TEnum +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.DecisionFeatureCoordinate(string! name, string! questionId, Microsoft.Extensions.AI.DecisionFeatureValueKind valueKind, string? memberId = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.MemberId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.QuestionId.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureCoordinate.ValueKind.get -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureProjection +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Coordinates.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.DecisionFeatureSchema(string! id, int version, System.Collections.Generic.IEnumerable! coordinates) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureSchema.Version.get -> int +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.DecisionFeatureValue(string! name, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Name.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValue.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryFalseProbability = 1 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.BinaryTrueProbability = 0 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ChoiceProbability = 2 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ExpectedScore = 5 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.Score = 4 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureValueKind.ScoreProbability = 3 -> Microsoft.Extensions.AI.DecisionFeatureValueKind +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Schema.get -> Microsoft.Extensions.AI.DecisionFeatureSchema! +[MEAI001]Microsoft.Extensions.AI.DecisionFeatureVector.Values.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Binary = 0 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Choice = 1 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionKind.Score = 2 -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionOptions +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.get -> Microsoft.Extensions.AI.AdditionalPropertiesDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.AdditionalProperties.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.DecisionOptions(Microsoft.Extensions.AI.DecisionOptions? other) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.ModelId.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.get -> System.Func? +[MEAI001]Microsoft.Extensions.AI.DecisionOptions.RawRepresentationFactory.set -> void +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.FourDecimalPlaces = 1 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.HighPrecision = 0 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionPrecision.TwoDecimalPlaces = 2 -> Microsoft.Extensions.AI.DecisionPrecision +[MEAI001]Microsoft.Extensions.AI.DecisionProbability +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.DecisionProbability(string! id, double value) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionProbability.Value.get -> double +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException() -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProtocolException.DecisionProtocolException(string! message, System.Exception! innerException) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.DecisionProvenance(string? providerName = null, System.Uri? providerUri = null, string? modelId = null, string? responseId = null, Microsoft.Extensions.AI.DecisionPrecision? precision = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ModelId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.Precision.get -> Microsoft.Extensions.AI.DecisionPrecision? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderName.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ProviderUri.get -> System.Uri? +[MEAI001]Microsoft.Extensions.AI.DecisionProvenance.ResponseId.get -> string? +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Instructions.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionQuestion.Kind.get -> Microsoft.Extensions.AI.DecisionKind +[MEAI001]Microsoft.Extensions.AI.DecisionRequest +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.DecisionRequest(System.Text.Json.JsonElement state, System.Collections.Generic.IReadOnlyList! questions) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.Questions.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionRequest.State.get -> System.Text.Json.JsonElement +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.AdditionalProperties.get -> System.Collections.Generic.IReadOnlyDictionary? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Answers.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.DecisionResponse(Microsoft.Extensions.AI.DecisionRequest! request, System.Collections.Generic.IReadOnlyList! answers, Microsoft.Extensions.AI.DecisionProvenance? provenance = null, Microsoft.Extensions.AI.UsageDetails? usage = null, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetAnswer(string! questionId) -> Microsoft.Extensions.AI.DecisionAnswer! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Provenance.get -> Microsoft.Extensions.AI.DecisionProvenance? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.RawRepresentation.get -> object? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Request.get -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Usage.get -> Microsoft.Extensions.AI.UsageDetails? +[MEAI001]Microsoft.Extensions.AI.DecisionResponse +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Evidence.get -> Microsoft.Extensions.AI.DecisionResponse! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.GetDistribution(System.Linq.Expressions.Expression!>! selector) -> System.Collections.Generic.IReadOnlyDictionary! +[MEAI001]Microsoft.Extensions.AI.DecisionResponse.Result.get -> TResult +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.DecisionResultBinding(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Func! map) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionResultBinding.ResultTypeInfo.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.DecisionScoreLevel(string! id, string! description) -> void +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Description.get -> string! +[MEAI001]Microsoft.Extensions.AI.DecisionScoreLevel.Id.get -> string! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetResponseAsync(Microsoft.Extensions.AI.DecisionRequest! request, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]Microsoft.Extensions.AI.IDecisionClient.GetService(System.Type! serviceType, object? serviceKey = null) -> object? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ExpectedScore.get -> double +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Probabilities.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.Score.get -> double? +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionAnswer.ScoreDecisionAnswer(string! questionId, double? score, System.Collections.Generic.IReadOnlyList! probabilities, Microsoft.Extensions.AI.DecisionPrecision precision = Microsoft.Extensions.AI.DecisionPrecision.HighPrecision, object? rawRepresentation = null, System.Collections.Generic.IReadOnlyDictionary? additionalProperties = null) -> void +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.Levels.get -> System.Collections.Generic.IReadOnlyList! +[MEAI001]Microsoft.Extensions.AI.ScoreDecisionQuestion.ScoreDecisionQuestion(string! id, string? instructions, System.Collections.Generic.IReadOnlyList! levels) -> void +[MEAI001]static Microsoft.Extensions.AI.DecisionBindingExtensions.Bind(this Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionResultBinding! binding) -> TResult +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, System.Text.Json.JsonElement state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, Microsoft.Extensions.AI.DecisionDefinition! definition, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!>! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetResponseAsync(this Microsoft.Extensions.AI.IDecisionClient! client, TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions, Microsoft.Extensions.AI.DecisionOptions? options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task! +[MEAI001]static Microsoft.Extensions.AI.DecisionClientExtensions.GetService(this Microsoft.Extensions.AI.IDecisionClient! client, object? serviceKey = null) -> TService? +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Action.Builder!>! configure, System.Text.Json.JsonSerializerOptions? serializerOptions = null) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionDefinition.Create(System.Text.Json.Serialization.Metadata.JsonTypeInfo! resultTypeInfo, System.Action.Builder!>! configure) -> Microsoft.Extensions.AI.DecisionDefinition! +[MEAI001]static Microsoft.Extensions.AI.DecisionFeatureProjection.Project(Microsoft.Extensions.AI.DecisionResponse! response, Microsoft.Extensions.AI.DecisionFeatureSchema! schema) -> Microsoft.Extensions.AI.DecisionFeatureVector! +[MEAI001]static Microsoft.Extensions.AI.DecisionRequest.Create(TState state, System.Text.Json.Serialization.Metadata.JsonTypeInfo! stateTypeInfo, System.Collections.Generic.IEnumerable! questions) -> Microsoft.Extensions.AI.DecisionRequest! +[MEAI001]virtual Microsoft.Extensions.AI.DecisionOptions.Clone() -> Microsoft.Extensions.AI.DecisionOptions! diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevAIFunction.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevAIFunction.cs new file mode 100644 index 00000000000..45fb819c118 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevAIFunction.cs @@ -0,0 +1,89 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// The created by : its arguments are a +/// and its result is the of the configured mapping or the TypeSafe API. +/// +internal sealed class JevAIFunction : AIFunction +{ + private readonly Func> _systemOneAsync; + + public JevAIFunction(string name, string description, Func> systemOneAsync) + { + this.Name = name; + this.Description = description; + this._systemOneAsync = systemOneAsync; + } + + public override string Name { get; } + + public override string Description { get; } + + public override JsonElement JsonSchema => JevJsonUtilities.RequestSchema; + + public override JsonElement? ReturnJsonSchema => JevJsonUtilities.ResultSchema; + + public override JsonSerializerOptions JsonSerializerOptions => JevJsonUtilities.Options; + + protected override async ValueTask InvokeCoreAsync(AIFunctionArguments arguments, CancellationToken cancellationToken) + { + JevRequest request = ReadRequest(arguments); + JevContractValidator.ValidateRequest(request); + + // FunctionInvokingChatClient sets Services to the IServiceProvider of the agent (ChatClientAgent passes its + // services through), so mappings can resolve per-call dependencies such as a registered client. + JevResult? result = await this._systemOneAsync(request, arguments.Services, cancellationToken).ConfigureAwait(false); + if (result is null) + { + Throw.InvalidOperationException("The Jev mapping returned no result."); + } + + JevContractValidator.ValidateResult(request, result); + + // The result is returned as JSON, as AIFunctionFactory does. Chat clients serialize any other result object + // with AIJsonUtilities.DefaultOptions, which has no metadata for these types when reflection is disabled + // (for example under native AOT); the model would then receive an empty tool output. + try + { + return JsonSerializer.SerializeToElement(result, JevJsonContext.Default.JevResult); + } + catch (Exception ex) when (ex is ArgumentException or JsonException or NotSupportedException) + { + // A result that cannot be written is a mapping fault. Reported as ArgumentException, it would look + // like a mistake in the model's arguments and invite the model to retry the same call. + throw new InvalidOperationException($"The Jev result could not be serialized: {ex.Message}", ex); + } + } + + private static JevRequest ReadRequest(AIFunctionArguments arguments) + { + // The arguments are the top-level properties of the request, so they are reassembled into one object. + var json = new JsonObject(); + foreach (KeyValuePair argument in arguments) + { + json[argument.Key] = JevJsonUtilities.ToNode(argument.Value); + } + + try + { + return json.Deserialize(JevJsonContext.Default.JevRequest) + ?? throw new JsonException("The arguments are null."); + } + catch (Exception ex) when (ex is JsonException or NotSupportedException) + { + // An unknown or missing question type surfaces as NotSupportedException rather than JsonException. + throw new ArgumentException($"The arguments are not a valid Jev request: {ex.Message}", nameof(arguments), ex); + } + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevApiRequest.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevApiRequest.cs new file mode 100644 index 00000000000..a59553f94bd --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevApiRequest.cs @@ -0,0 +1,22 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// The body of POST /v1/systemone: a with the model resolved, like +/// SystemOneRequestPayload of the official TypeSafe SDK. +/// +internal sealed class JevApiRequest +{ + [JsonPropertyName("state")] + public required JevEntry State { get; init; } + + [JsonPropertyName("model")] + public required string Model { get; init; } + + [JsonPropertyName("questions")] + public required IReadOnlyDictionary Questions { get; init; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevContractValidator.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevContractValidator.cs new file mode 100644 index 00000000000..2738cdca56a --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevContractValidator.cs @@ -0,0 +1,217 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Globalization; +using System.Text.Json; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Checks requests before they are sent and results before they are returned to the caller. +/// +/// +/// +/// Request rules follow the official TypeSafe SDK (at least one question; a Score rubric of at least two entries) and +/// the limits the API rejects (at most 255 Choice alternatives and 10 Score entries; a Noul needs instructions or +/// criteria; the state and Score rubric entries may not be null, although the SDK types allow it). Checking them here +/// saves a round trip and gives the model a message that says what to fix. +/// +/// +/// Requests come from a model, so their errors are . Results come from the API or from +/// a custom mapping, so their errors are ; they point at a mapping bug, not at +/// the model. +/// +/// +internal static class JevContractValidator +{ + public const int MaxChoiceCriteria = 255; + public const int MinScoreCriteria = 2; + public const int MaxScoreCriteria = 10; + + // Jev computes scores and probabilities in floating point, so values may exceed their bounds by rounding error. + private const double Tolerance = 1e-6; + + public static void ValidateRequest(JevRequest request) + { + // The SDK types allow a null state, but the API answers 422 ("Field required"). + if (request.State.IsNull) + { + Throw.ArgumentException(nameof(request), "The state must be text or a JSON object or array."); + } + + ValidateQuestions(request.Questions, nameof(request)); + } + + /// + /// Checks the questions of a request, which does too. + /// + /// The questions, keyed by ID. + /// The parameter that the questions came from, for the exception. + public static void ValidateQuestions(IReadOnlyDictionary? questions, string paramName) + { + if (questions is null || questions.Count == 0) + { + Throw.ArgumentException(paramName, "At least one question is required."); + } + + foreach (KeyValuePair entry in questions) + { + string id = entry.Key; + switch (entry.Value) + { + case null: + Throw.ArgumentException(paramName, $"Question '{id}' is null."); + break; + + case JevChoiceQuestion choice: + int alternatives = choice.Criteria?.Count ?? 0; + if (alternatives is < 1 or > MaxChoiceCriteria) + { + Throw.ArgumentException(paramName, $"Choice question '{id}' has {Count(alternatives, "alternative")}; it needs from 1 to {MaxChoiceCriteria}."); + } + + break; + + case JevScoreQuestion score: + int scores = score.Criteria?.Count ?? 0; + if (scores is < MinScoreCriteria or > MaxScoreCriteria) + { + Throw.ArgumentException(paramName, $"Score question '{id}' has {Count(scores, "criterion", "criteria")}; it needs from {MinScoreCriteria} to {MaxScoreCriteria}."); + } + + // The SDK types allow null rubric entries, but the API answers 422 for them. + for (int index = 0; index < scores; index++) + { + if (score.Criteria![index].IsNull) + { + Throw.ArgumentException(paramName, $"Score question '{id}' has a null criterion at index {index.ToString(CultureInfo.InvariantCulture)}; every score needs text or JSON."); + } + } + + break; + + case JevNoulQuestion noul: + if (IsEmpty(noul.Instructions) && IsEmpty(noul.Criteria?.True) && IsEmpty(noul.Criteria?.False)) + { + Throw.ArgumentException(paramName, $"Noul question '{id}' needs instructions or criteria."); + } + + break; + } + } + } + + public static void ValidateResult(JevRequest request, JevResult result) + { + if (result.Answers is null) + { + Throw.InvalidOperationException("The Jev result has no answers."); + } + + foreach (KeyValuePair entry in request.Questions) + { + string id = entry.Key; + if (!result.Answers.TryGetValue(id, out JevResponse? answer) || answer is null) + { + Throw.InvalidOperationException($"The Jev result has no answer for question '{id}'."); + } + + switch (entry.Value, answer) + { + case (JevChoiceQuestion question, JevChoiceResponse choice): + // A label outside the criteria would reach the model as a value it never offered, which is how a + // mapping that converts between labels and a client's own values would fail silently. + if (choice.Choice is null || !question.Criteria.ContainsKey(choice.Choice)) + { + Throw.InvalidOperationException($"The answer to question '{id}' chose '{choice.Choice}', which is not one of its labels."); + } + + EnsureInRange(choice.Confidence, 0, 1, id, "confidence"); + EnsureProbabilities(choice.Probabilities, id, key => question.Criteria.ContainsKey(key), "one of its labels"); + break; + + case (JevScoreQuestion question, JevScoreResponse score): + EnsureInRange(score.Score, 0, question.Criteria.Count - 1, id, "score"); + EnsureInRange(score.Confidence, 0, 1, id, "confidence"); + + // Score responses key their probabilities and legend by score ("0", "1", ...). + int scores = question.Criteria.Count; + bool IsScore(string key) => int.TryParse(key, NumberStyles.None, CultureInfo.InvariantCulture, out int value) && value < scores; + string scoreRange = $"a score from 0 to {(scores - 1).ToString(CultureInfo.InvariantCulture)}"; + EnsureProbabilities(score.Probabilities, id, IsScore, scoreRange); + EnsureKeys(score.Legend?.Keys, id, "legend", IsScore, scoreRange); + break; + + case (JevNoulQuestion, JevNoulResponse noul): + EnsureInRange(noul.Noul, 0, 1, id, "noul"); + break; + + default: + Throw.InvalidOperationException($"The answer to question '{id}' is a {KindOf(answer)} answer, but the question is a {KindOf(entry.Value)} question."); + break; + } + } + } + + private static bool IsEmpty(JevEntry? entry) => + entry is not { } value || value.IsNull || (value.Kind == JsonValueKind.String && string.IsNullOrWhiteSpace(value.Text)); + + /// + /// Checks that every probability is in range and is keyed by something the question offered. A mapping that fills + /// probabilities with a client's own labels would otherwise show the model alternatives it never asked about. + /// + private static void EnsureProbabilities(IReadOnlyDictionary? probabilities, string id, Func isValidKey, string expected) + { + if (probabilities is null) + { + Throw.InvalidOperationException($"The answer to question '{id}' has no probabilities."); + } + + EnsureKeys(probabilities.Keys, id, "probabilities", isValidKey, expected); + foreach (KeyValuePair probability in probabilities) + { + EnsureInRange(probability.Value, 0, 1, id, $"probability '{probability.Key}'"); + } + } + + private static void EnsureKeys(IEnumerable? keys, string id, string field, Func isValidKey, string expected) + { + foreach (string key in keys ?? []) + { + if (!isValidKey(key)) + { + Throw.InvalidOperationException($"The answer to question '{id}' has {field} for '{key}', which is not {expected}."); + } + } + } + + private static void EnsureInRange(double value, double min, double max, string id, string field) + { + // NaN and infinity fail these comparisons too; they cannot be written as JSON at all. + if (!(value >= min - Tolerance && value <= max + Tolerance)) + { + Throw.InvalidOperationException(string.Format( + CultureInfo.InvariantCulture, + "The answer to question '{0}' has {1} {2}, which is outside the range {3} to {4}.", + id, + field, + value, + min, + max)); + } + } + + private static string Count(int count, string singular, string? plural = null) => + count == 1 ? $"1 {singular}" : $"{count.ToString(CultureInfo.InvariantCulture)} {plural ?? singular + "s"}"; + + private static string KindOf(object value) => + value switch + { + JevChoiceQuestion or JevChoiceResponse => "Choice", + JevScoreQuestion or JevScoreResponse => "Score", + JevNoulQuestion or JevNoulResponse => "Noul", + _ => value.GetType().Name, + }; +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevDecisionMapping.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevDecisionMapping.cs new file mode 100644 index 00000000000..08312354247 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevDecisionMapping.cs @@ -0,0 +1,148 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Globalization; +using System.Linq; +using System.Text.Json; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Converts between the Jev contract types and the provider-neutral decision types. +/// +/// +/// +/// A Binary question is a Noul, a Choice question a Choice whose labels are the candidate IDs, and a Score question a +/// Score whose rubric is the level descriptions in order. Jev keys Score probabilities by level index, so answers are +/// mapped back to the level IDs by position. +/// +/// +/// The decision types require complete, correlated answers: every candidate and level needs a probability, and each +/// distribution must sum to 1 within the rounding of . Jev computes its values in floating point, +/// so a value that exceeds its bounds by less than is moved onto the bound, as +/// already accepts it. Nothing else is repaired. +/// +/// +internal static class JevDecisionMapping +{ + /// + /// Gets the precision of Jev probabilities, which the API rounds to two decimal places, so a distribution may sum + /// to slightly more or less than 1. + /// + public const DecisionPrecision Precision = DecisionPrecision.TwoDecimalPlaces; + + /// The name of the entry that holds Jev's confidence. + public const string ConfidenceProperty = "confidence"; + + private const double Tolerance = 1e-6; + + /// Converts a decision state into a Jev state, which is text or a JSON object or array. + public static JevEntry ToEntry(JsonElement state) + { + if (state.ValueKind is not (JsonValueKind.String or JsonValueKind.Object or JsonValueKind.Array)) + { + Throw.ArgumentException(nameof(state), $"Jev answers questions about text or a JSON object or array, but the state is a JSON {state.ValueKind}."); + } + + return new JevEntry(state); + } + + /// Converts a decision question into the Jev question that asks it. + public static JevQuestion ToJevQuestion(DecisionQuestion question) => + question switch + { + BinaryDecisionQuestion binary => new JevNoulQuestion + { + Instructions = ToEntry(binary.Instructions), + Criteria = binary.TrueDescription is null && binary.FalseDescription is null + ? null + : new JevNoulCriteria { True = ToEntry(binary.TrueDescription), False = ToEntry(binary.FalseDescription) }, + }, + ChoiceDecisionQuestion choice => new JevChoiceQuestion + { + Instructions = ToEntry(choice.Instructions), + Criteria = ToCriteria(choice.Candidates), + }, + ScoreDecisionQuestion score => new JevScoreQuestion + { + Instructions = ToEntry(score.Instructions), + Criteria = [.. score.Levels.Select(level => (JevEntry)level.Description)], + }, + _ => throw new NotSupportedException($"Jev does not answer {question.Kind} questions."), + }; + + /// + /// Converts Jev's answer to a question into the decision answer. + /// + /// The answer is not a complete answer to the question. + public static DecisionAnswer ToDecisionAnswer(DecisionQuestion question, JevResponse response) => + (question, response) switch + { + (BinaryDecisionQuestion, JevNoulResponse noul) => new BinaryDecisionAnswer( + question.Id, + OntoBounds(noul.Noul, 1), + Precision, + rawRepresentation: noul), + (ChoiceDecisionQuestion choice, JevChoiceResponse answer) => new ChoiceDecisionAnswer( + question.Id, + answer.Choice, + [.. choice.Candidates.Select(candidate => new DecisionProbability(candidate.Id, GetProbability(answer.Probabilities, candidate.Id, question.Id)))], + Precision, + rawRepresentation: answer, + additionalProperties: Confidence(answer.Confidence)), + (ScoreDecisionQuestion score, JevScoreResponse answer) => new ScoreDecisionAnswer( + question.Id, + OntoBounds(answer.Score, score.Levels.Count - 1), + [.. score.Levels.Select((level, index) => new DecisionProbability(level.Id, GetProbability(answer.Probabilities, ToKey(index), question.Id)))], + Precision, + rawRepresentation: answer, + additionalProperties: Confidence(answer.Confidence)), + _ => throw new DecisionProtocolException($"The Jev answer to question '{question.Id}' does not match its {question.Kind} question."), + }; + + /// Converts Jev token usage into usage details. + public static UsageDetails? ToUsage(JevUsage? usage) => + usage is { } tokens + ? new UsageDetails { InputTokenCount = tokens.InputTokens, OutputTokenCount = tokens.OutputTokens, TotalTokenCount = tokens.InputTokens + tokens.OutputTokens } + : null; + + private static Dictionary ToCriteria(IReadOnlyList candidates) + { + var criteria = new Dictionary(candidates.Count, StringComparer.Ordinal); + foreach (DecisionCandidate candidate in candidates) + { + criteria[candidate.Id] = candidate.Description; + } + + return criteria; + } + + private static JevEntry? ToEntry(string? text) + { + // A null string converts to JevEntry.Null, which is written as JSON null, so an absent text stays absent. + if (string.IsNullOrEmpty(text)) + { + return null; + } + + return JevEntry.FromString(text); + } + + private static string ToKey(int index) => index.ToString(CultureInfo.InvariantCulture); + + private static double GetProbability(IReadOnlyDictionary probabilities, string key, string questionId) => + probabilities.TryGetValue(key, out double probability) + ? OntoBounds(probability, 1) + : throw new DecisionProtocolException($"The Jev answer to question '{questionId}' has no probability for '{key}'."); + + private static double OntoBounds(double value, double maximum) => + value < 0 && value >= -Tolerance ? 0 + : value > maximum && value <= maximum + Tolerance ? maximum + : value; + + private static Dictionary Confidence(double confidence) => + new(StringComparer.Ordinal) { [ConfidenceProperty] = confidence }; +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevEntryJsonConverter.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevEntryJsonConverter.cs new file mode 100644 index 00000000000..3287e38784f --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevEntryJsonConverter.cs @@ -0,0 +1,39 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Text.Json; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Reads and writes a as the JSON value it holds. +/// +internal sealed class JevEntryJsonConverter : JsonConverter +{ + // A JSON null is a valid entry (an undescribed criterion), so the converter reads it instead of the serializer. + public override bool HandleNull => true; + + public override JevEntry Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) + { + JsonElement value = JsonElement.ParseValue(ref reader); + if (value.ValueKind is JsonValueKind.Number or JsonValueKind.True or JsonValueKind.False) + { + throw new JsonException("A Jev entry must be text, a JSON object or array, or null."); + } + + return new JevEntry(value); + } + + public override void Write(Utf8JsonWriter writer, JevEntry value, JsonSerializerOptions options) + { + if (value.Json is { } json) + { + json.WriteTo(writer); + } + else + { + writer.WriteNullValue(); + } + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevHttpClient.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevHttpClient.cs new file mode 100644 index 00000000000..c00c821cae2 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevHttpClient.cs @@ -0,0 +1,101 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel; +using System.ClientModel.Primitives; +using System.Globalization; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Sends a to POST /v1/systemone of the TypeSafe API through a System.ClientModel pipeline, +/// like systemOne of the official TypeSafe SDK. +/// +internal sealed class JevHttpClient +{ + private const int MaxErrorDetailLength = 500; + + private readonly ClientPipeline _pipeline; + + public JevHttpClient(ApiKeyCredential credential, ClientPipelineOptions options, Uri? endpoint, string modelId) + { + this.Endpoint = endpoint ?? new Uri(JevPipelineDefaults.DefaultEndpoint); + this.ModelId = modelId; + + // The credential is applied per try, like the OpenAI client does, so a retried request is signed again. + // Creating the pipeline freezes the options, as with any other client built from them. + this._pipeline = ClientPipeline.Create( + options, + perCallPolicies: [], + perTryPolicies: [ApiKeyAuthenticationPolicy.CreateBearerAuthorizationPolicy(credential)], + beforeTransportPolicies: []); + } + + /// Gets the System One endpoint that requests are sent to. + public Uri Endpoint { get; } + + /// Gets the model that answers requests unless a call selects another. + public string ModelId { get; } + + /// + /// Answers a request with the configured model. The signature matches the mapping of . + /// + public Task SystemOneAsync(JevRequest request, IServiceProvider? services, CancellationToken cancellationToken) => + this.SystemOneAsync(request, this.ModelId, cancellationToken); + + /// + /// Answers a request with the given model. + /// + public async Task SystemOneAsync(JevRequest request, string modelId, CancellationToken cancellationToken) + { + using PipelineMessage message = this._pipeline.CreateMessage(); + message.ResponseClassifier = JevResponseClassifier.Instance; + message.Apply(new RequestOptions { CancellationToken = cancellationToken }); + + PipelineRequest httpRequest = message.Request; + httpRequest.Method = "POST"; + httpRequest.Uri = this.Endpoint; + httpRequest.Headers.Set("Accept", "application/json"); + httpRequest.Headers.Set("Content-Type", "application/json"); + httpRequest.Content = BinaryContent.Create(BinaryData.FromBytes(JsonSerializer.SerializeToUtf8Bytes( + new JevApiRequest { State = request.State, Model = modelId, Questions = request.Questions }, + JevJsonContext.Default.JevApiRequest))); + + // Transports leave the cancellation check to the HTTP handler, so a canceled call is stopped here before + // anything is sent. + cancellationToken.ThrowIfCancellationRequested(); + await this._pipeline.SendAsync(message).ConfigureAwait(false); + + PipelineResponse response = message.Response!; + if (response.IsError) + { + // The service detail says which field was rejected, which is what the model needs to correct its + // arguments, but the default ClientResultException message has only the status. The exception still + // carries the response for GetRawResponse, and never the credential. + string body = response.Content.ToString(); + string detail = body.Length > MaxErrorDetailLength ? string.Concat(body.AsSpan(0, MaxErrorDetailLength), "...") : body; + throw new ClientResultException( + string.Format(CultureInfo.InvariantCulture, "The Jev request failed with status {0} ({1}): {2}", response.Status, response.ReasonPhrase, detail), + response); + } + + return ReadResult(response.Content); + } + + private static JevResult ReadResult(BinaryData content) + { + try + { + return JsonSerializer.Deserialize(content.ToMemory().Span, JevJsonContext.Default.JevResult) + ?? throw new JsonException("The response body is null."); + } + catch (Exception ex) when (ex is JsonException or NotSupportedException) + { + // An answer with an unknown or missing type surfaces as NotSupportedException rather than JsonException. + throw new JsonException($"The Jev API response could not be read: {ex.Message}", ex); + } + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevJsonContext.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevJsonContext.cs new file mode 100644 index 00000000000..2a7c2e73b64 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevJsonContext.cs @@ -0,0 +1,21 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Source-generated serialization metadata for the Jev contract types. +/// +/// +/// Models often write the type discriminator after other properties of a question, so out-of-order metadata +/// is allowed; without it, a valid question such as {"instructions": "...", "type": "noul"} would be rejected. +/// +[JsonSourceGenerationOptions(AllowOutOfOrderMetadataProperties = true)] +[JsonSerializable(typeof(JevRequest))] +[JsonSerializable(typeof(JevResult))] +[JsonSerializable(typeof(JevApiRequest))] +[JsonSerializable(typeof(Dictionary))] +[JsonSerializable(typeof(string))] +internal sealed partial class JevJsonContext : JsonSerializerContext; diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevJsonUtilities.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevJsonUtilities.cs new file mode 100644 index 00000000000..7492e80e7ba --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevJsonUtilities.cs @@ -0,0 +1,120 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Text.Json.Serialization.Metadata; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Serializer options and JSON schemas of the Jev contract types, which the Jev tool uses. +/// +internal static class JevJsonUtilities +{ + private static readonly AIJsonSchemaCreateOptions s_schemaOptions = new() { TransformSchemaNode = DescribeEntries }; + private static readonly Lazy s_requestSchema = new(static () => AIJsonUtilities.CreateJsonSchema(typeof(JevRequest), serializerOptions: Options, inferenceOptions: s_schemaOptions)); + private static readonly Lazy s_resultSchema = new(static () => AIJsonUtilities.CreateJsonSchema(typeof(JevResult), serializerOptions: Options, inferenceOptions: s_schemaOptions)); + + /// + /// Gets the options that resolve the Jev contract types first and every other type through + /// . + /// + public static JsonSerializerOptions Options { get; } = CreateOptions(); + + /// Gets the JSON schema of the tool arguments, which is the schema of . + public static JsonElement RequestSchema => s_requestSchema.Value; + + /// Gets the JSON schema of the tool result, which is the schema of . + public static JsonElement ResultSchema => s_resultSchema.Value; + + /// + /// Converts one tool argument into a JSON node. Chat clients pass arguments as values; + /// callers that invoke the function directly may pass .NET objects instead. + /// + public static JsonNode? ToNode(object? value) => + value switch + { + null => null, + JsonNode node => node.DeepClone(), + JsonElement element => element.ValueKind switch + { + JsonValueKind.Object => JsonObject.Create(element), + JsonValueKind.Array => JsonArray.Create(element), + JsonValueKind.Null or JsonValueKind.Undefined => null, + _ => JsonValue.Create(element), + }, + _ => JsonSerializer.SerializeToNode(value, Options.GetTypeInfo(value.GetType())), + }; + + private static JsonSerializerOptions CreateOptions() + { + var options = new JsonSerializerOptions(JevJsonContext.Default.Options) + { + TypeInfoResolver = JsonTypeInfoResolver.Combine(JevJsonContext.Default, AIJsonUtilities.DefaultOptions.TypeInfoResolver), + }; + + options.MakeReadOnly(); + return options; + } + + /// + /// Gives the schema of the SDK's EntryType, narrowed to what the API accepts. Its + /// custom converter hides the shape from the schema generator, which would otherwise allow any JSON value, and + /// entries inside collections are only reachable from the collection's node. + /// + /// + /// The API rejects a state and Score rubric entries even though the + /// SDK types allow them, so those schemas leave out; the size limits tell the model how many + /// alternatives and scores it may send. + /// + private static JsonNode DescribeEntries(AIJsonSchemaCreateContext context, JsonNode schema) + { + Type type = context.TypeInfo.Type; + if (type == typeof(JevEntry)) + { + // JevRequest.State is the only non-nullable single entry. + return WithEntryType(schema, allowNull: false); + } + + if (type == typeof(JevEntry?)) + { + return WithEntryType(schema, allowNull: true); + } + + if (type == typeof(IReadOnlyList) && schema is JsonObject rubric) + { + rubric["items"] = WithEntryType(new JsonObject(), allowNull: false); + rubric["minItems"] = JevContractValidator.MinScoreCriteria; + rubric["maxItems"] = JevContractValidator.MaxScoreCriteria; + return rubric; + } + + if (type == typeof(IReadOnlyDictionary) && schema is JsonObject map) + { + // Choice criteria may leave an alternative undescribed; a Score legend echoes the rubric, which may not. + bool isChoiceCriteria = context.PropertyInfo?.Name == "criteria"; + map["additionalProperties"] = WithEntryType(new JsonObject(), allowNull: isChoiceCriteria); + if (isChoiceCriteria) + { + map["minProperties"] = 1; + map["maxProperties"] = JevContractValidator.MaxChoiceCriteria; + } + + return map; + } + + return schema; + } + + private static JsonObject WithEntryType(JsonNode schema, bool allowNull) + { + JsonObject entry = schema as JsonObject ?? []; + entry["type"] = allowNull + ? new JsonArray("string", "object", "array", "null") + : new JsonArray("string", "object", "array"); + return entry; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevPipelineDefaults.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevPipelineDefaults.cs new file mode 100644 index 00000000000..06476e6cec8 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevPipelineDefaults.cs @@ -0,0 +1,34 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel.Primitives; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Assigns the pipeline defaults of the official TypeSafe SDK to the options of every Jev client. +/// +internal static class JevPipelineDefaults +{ + public const string DefaultEndpoint = "https://api.typesafe.ai/v1/systemone"; + public const string DefaultModelId = "jev-latest"; + + private static readonly TimeSpan s_defaultNetworkTimeout = TimeSpan.FromSeconds(10); + + /// + /// Sets the SDK retry policy and network timeout where the caller left them unset. + /// + /// + /// Call this from , not from a constructor, because + /// may be set after construction. ClientPipeline.Create + /// freezes the options before it reads them, so the defaults are in place when the pipeline is built. + /// + public static void Apply(ClientPipelineOptions options) + { + options.RetryPolicy ??= new JevRetryPolicy( + JevRetryPolicy.DefaultMaxRetries, + options.ClientLoggingOptions?.EnableLogging ?? true, + options.ClientLoggingOptions?.LoggerFactory); + options.NetworkTimeout ??= s_defaultNetworkTimeout; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevResponseClassifier.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevResponseClassifier.cs new file mode 100644 index 00000000000..8677e243a61 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevResponseClassifier.cs @@ -0,0 +1,44 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel.Primitives; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Classifies System One responses like the official TypeSafe SDK: any 2xx status is a success, and 408, 429, and +/// every 5xx status are retriable. +/// +/// +/// only retries 500, 502, 503, and 504 among the 5xx statuses, which +/// leaves out 529, the status TypeSafe answers when it is overloaded. Network failures are left to the default +/// classifier, which retries them, as the SDK does. +/// +internal sealed class JevResponseClassifier : PipelineMessageClassifier +{ + public static JevResponseClassifier Instance { get; } = new(); + + public override bool TryClassify(PipelineMessage message, out bool isError) + { + if (message.Response is not { } response) + { + isError = false; + return false; + } + + isError = response.Status is < 200 or >= 300; + return true; + } + + public override bool TryClassify(PipelineMessage message, Exception? exception, out bool isRetriable) + { + if (exception is not null || message.Response is not { } response) + { + isRetriable = false; + return false; + } + + isRetriable = response.Status is 408 or 429 or (>= 500 and <= 599); + return true; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevRetryPolicy.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevRetryPolicy.cs new file mode 100644 index 00000000000..0b5725db567 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Core/JevRetryPolicy.cs @@ -0,0 +1,137 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel.Primitives; +using System.Collections.Generic; +using System.Globalization; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.Logging; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// The default retry policy of the Jev clients, with the defaults of the official TypeSafe SDK +/// (DEFAULT_RETRY_POLICY in retry.ts). +/// +/// +/// +/// Up to retries after the first attempt. +/// +/// A server delay from retry-after-ms or Retry-After is honored up to . +/// A longer delay falls back to backoff, because waiting it would block the agent run with no feedback. +/// +/// +/// Otherwise the delay is an exponential backoff from , capped at , +/// minus up to of random jitter so that concurrent callers do not retry in lockstep. +/// +/// +/// Which statuses are retried is decided by . +/// +internal sealed class JevRetryPolicy : ClientRetryPolicy +{ + public const int DefaultMaxRetries = 2; + public const double BackoffJitter = 0.25; + + public static readonly TimeSpan InitialBackoff = TimeSpan.FromMilliseconds(500); + public static readonly TimeSpan MaxBackoff = TimeSpan.FromSeconds(5); + public static readonly TimeSpan MaxRetryAfter = TimeSpan.FromMinutes(1); + + public JevRetryPolicy(int maxRetries = DefaultMaxRetries, bool enableLogging = true, ILoggerFactory? loggerFactory = null) + : base(maxRetries, enableLogging, loggerFactory) + { + } + + /// + /// Gets or sets a list that, when set, receives each delay instead of waiting it, so tests can check the delays + /// without being slowed down by them. + /// + internal List? RecordedWaitsForTests { get; set; } + + protected override TimeSpan GetNextDelay(PipelineMessage message, int tryCount) + { + if (TryGetServerDelayMilliseconds(message.Response, out double serverDelay) && serverDelay <= MaxRetryAfter.TotalMilliseconds) + { + return TimeSpan.FromMilliseconds(serverDelay); + } + + // tryCount is 1 for the first retry, matching attempt 0 of the SDK's retryDelayMs. + double exponential = Math.Min(InitialBackoff.TotalMilliseconds * Math.Pow(2, tryCount - 1), MaxBackoff.TotalMilliseconds); +#pragma warning disable CA5394 // Jitter only spreads retries over time; it needs no cryptographic randomness. + double jitter = Random.Shared.NextDouble() * BackoffJitter; +#pragma warning restore CA5394 + return TimeSpan.FromMilliseconds(Math.Round(exponential * (1 - jitter))); + } + + protected override Task WaitAsync(TimeSpan time, CancellationToken cancellationToken) + { + if (this.RecordedWaitsForTests is { } waits) + { + waits.Add(time); + return Task.CompletedTask; + } + + return base.WaitAsync(time, cancellationToken); + } + + protected override void Wait(TimeSpan time, CancellationToken cancellationToken) + { + if (this.RecordedWaitsForTests is { } waits) + { + waits.Add(time); + return; + } + + base.Wait(time, cancellationToken); + } + + /// + /// Reads retry-after-ms, preferred, or Retry-After in seconds or as an HTTP date, like the SDK's + /// parseRetryAfter, as a number of milliseconds. + /// + /// + /// The delay stays a until it is compared with : a huge value such as + /// 1e300 or the text NaN would make throw and fail the call, where the SDK + /// simply backs off. + /// + private static bool TryGetServerDelayMilliseconds(PipelineResponse? response, out double delay) + { + delay = 0; + if (response is null) + { + return false; + } + + if (response.Headers.TryGetValue("retry-after-ms", out string? milliseconds) && + double.TryParse(milliseconds, NumberStyles.Float, CultureInfo.InvariantCulture, out double ms) && + double.IsFinite(ms) && ms >= 0) + { + delay = ms; + return true; + } + + if (!response.Headers.TryGetValue("Retry-After", out string? retryAfter) || string.IsNullOrWhiteSpace(retryAfter)) + { + return false; + } + + if (double.TryParse(retryAfter, NumberStyles.Float, CultureInfo.InvariantCulture, out double seconds)) + { + if (!double.IsFinite(seconds) || seconds < 0) + { + return false; + } + + delay = seconds * 1000; + return double.IsFinite(delay); + } + + if (DateTimeOffset.TryParse(retryAfter, CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out DateTimeOffset date)) + { + delay = Math.Max(0, (date - DateTimeOffset.UtcNow).TotalMilliseconds); + return true; + } + + return false; + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevAIToolBuilder.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevAIToolBuilder.cs new file mode 100644 index 00000000000..8dd97a2d0c8 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevAIToolBuilder.cs @@ -0,0 +1,232 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Builds an that lets an agent classify, route, score, and check content with Jev, the +/// TypeSafe System One model. +/// +/// +/// +/// Jev does not write text. It answers typed questions about a state and returns calibrated probabilities, which +/// makes it a fast and inexpensive classifier for an agent whose own model writes the replies. The function created by +/// is a thin wrapper around a System One call: its arguments are a written by +/// the agent's model, and its result is the call's , as JSON. +/// +/// +/// With an , the call goes to the TypeSafe System One API through a +/// System.ClientModel pipeline configured by . Any other client can be used instead with +/// or one of the UseClient methods. +/// +/// +/// Every mapping receives the of the agent that calls the tool +/// (, which FunctionInvokingChatClient sets from the services +/// the agent was created with), so it can resolve its dependencies per call. In a host, register the tool with +/// services.AddAIAgent(...).WithAITool(sp => new JevAIToolBuilder(credential, options).Build()). +/// +/// +public sealed class JevAIToolBuilder +{ + private readonly ApiKeyCredential? _credential; + private readonly JevAIToolOptions _options; + private Func>? _systemOneAsync; + + /// + /// Initializes a new instance of the class that answers requests with the + /// TypeSafe System One API. + /// + /// The TypeSafe API key, sent as a bearer token. + /// The tool and client pipeline options. Defaults are used when . + public JevAIToolBuilder(ApiKeyCredential credential, JevAIToolOptions? options = null) + { + this._credential = Throw.IfNull(credential); + this._options = options ?? new JevAIToolOptions(); + } + + /// + /// Initializes a new instance of the class for a custom mapping, which must be set + /// with or a UseClient method before . + /// + /// + /// The tool options. Only and apply + /// to a custom mapping, which uses its own client configuration. Defaults are used when . + /// + public JevAIToolBuilder(JevAIToolOptions? options = null) + { + this._options = options ?? new JevAIToolOptions(); + } + + /// + /// Sets the function that maps each to its , replacing the + /// TypeSafe API. + /// + /// + /// The mapping. It receives the written by the model and the agent's services, which are + /// when the caller provides none, and returns one answer per question. + /// + /// This builder. + /// + /// The agent's services are often the application's root provider, because hosted agents are singletons by + /// default. To use a scoped service, create a scope inside the mapping, or use + /// , which does so for every call. + /// + public JevAIToolBuilder UseMapping(Func> mapAsync) + { + this._systemOneAsync = Throw.IfNull(mapAsync); + return this; + } + + /// + /// Answers requests with another client, converting between the Jev contract types and the client's own types. + /// + /// The request type of the client. + /// The response type of the client. + /// The client operation that answers a request. + /// Converts the written by the model into the client's request. + /// Converts the client's response into a . + /// This builder. + /// + /// The mapped response is checked against the request before it reaches the model: every question needs an answer + /// of the same kind, a Choice answer and its probabilities may only use the question's options, and probabilities + /// and scores must be in range. A mapper mistake therefore fails the call instead of showing the model values it + /// never offered. + /// + public JevAIToolBuilder UseClient( + Func> systemOneAsync, + Func inputMapper, + Func outputMapper) + { + _ = Throw.IfNull(systemOneAsync); + _ = Throw.IfNull(inputMapper); + _ = Throw.IfNull(outputMapper); + + return this.UseMapping(async (request, _, cancellationToken) => + { + TClientRequest clientRequest = inputMapper(request); + TClientResponse clientResponse = await systemOneAsync(clientRequest, cancellationToken).ConfigureAwait(false); + return outputMapper(clientResponse); + }); + } + + /// + /// Answers requests with a client registered in the agent's services, converting between the Jev contract types + /// and the client's own types. + /// + /// The client type, resolved from the agent's services on every call. + /// The request type of the client. + /// The response type of the client. + /// The client operation that answers a request. + /// Converts the written by the model into the client's request. + /// Converts the client's response into a . + /// This builder. + /// + /// The client is resolved from a new service scope on every call, and the scope is disposed when the call ends. + /// Scoped clients therefore live for one call, and disposable transient clients are released after it, even when + /// the agent's services are the application's root provider. The call fails when the agent has no services or + /// is not registered. The mapped response is checked as described for + /// . + /// + public JevAIToolBuilder UseClient( + Func> systemOneAsync, + Func inputMapper, + Func outputMapper) + where TClient : notnull + { + _ = Throw.IfNull(systemOneAsync); + _ = Throw.IfNull(inputMapper); + _ = Throw.IfNull(outputMapper); + + return this.UseMapping(async (request, services, cancellationToken) => + { + if (services is null) + { + Throw.InvalidOperationException( + $"The Jev tool resolves {typeof(TClient).Name} from the agent's services, but this call has none. " + + "Create the agent with an IServiceProvider, for example with AddAIAgent, or pass the client operation to UseClient directly."); + } + + // Hosted agents are singletons that receive the root provider by default. Resolving from it directly would + // reject scoped clients (or keep one forever when scope validation is off) and hold every disposable + // transient client until shutdown, so each call gets its own scope. + if (services.GetService() is not { } scopeFactory) + { + return await CallClientAsync(services).ConfigureAwait(false); + } + + AsyncServiceScope scope = scopeFactory.CreateAsyncScope(); + await using (scope.ConfigureAwait(false)) + { + return await CallClientAsync(scope.ServiceProvider).ConfigureAwait(false); + } + + async Task CallClientAsync(IServiceProvider provider) + { + if (provider.GetService(typeof(TClient)) is not TClient client) + { + Throw.InvalidOperationException($"{typeof(TClient).Name} is not registered in the agent's services."); + return default!; + } + + TClientRequest clientRequest = inputMapper(request); + TClientResponse clientResponse = await systemOneAsync(client, clientRequest, cancellationToken).ConfigureAwait(false); + return outputMapper(clientResponse); + } + }); + } + + /// + /// Creates the function. + /// + /// + /// An whose JSON schema is the schema of and whose result is the + /// call's serialized as JSON. + /// + /// + /// The builder has neither an nor a custom mapping, or an option that it uses is + /// empty or invalid. + /// + /// + /// With the TypeSafe API, building creates the client pipeline, which makes the options read-only. Invalid arguments + /// from the model fail with an that says what to fix; a function-invoking chat client + /// includes that message in the tool result only when its detailed errors are enabled. + /// + public AIFunction Build() + { + if (string.IsNullOrWhiteSpace(this._options.Name) || string.IsNullOrWhiteSpace(this._options.Description)) + { + Throw.InvalidOperationException($"{nameof(JevAIToolOptions)}.{nameof(JevAIToolOptions.Name)} and {nameof(JevAIToolOptions.Description)} must not be empty."); + } + + Func>? systemOneAsync = this._systemOneAsync; + if (systemOneAsync is null) + { + if (this._credential is null) + { + Throw.InvalidOperationException($"Pass an {nameof(ApiKeyCredential)} to the constructor to use the TypeSafe API, or call {nameof(UseMapping)} or UseClient."); + } + + // The model and endpoint only matter to the TypeSafe API; a custom mapping uses its own configuration. + if (string.IsNullOrWhiteSpace(this._options.ModelId)) + { + Throw.InvalidOperationException($"{nameof(JevAIToolOptions)}.{nameof(JevAIToolOptions.ModelId)} must not be empty."); + } + + if (this._options.Endpoint?.IsAbsoluteUri is false) + { + Throw.InvalidOperationException($"{nameof(JevAIToolOptions)}.{nameof(JevAIToolOptions.Endpoint)} must be an absolute URI."); + } + + systemOneAsync = new JevHttpClient(this._credential, this._options, this._options.Endpoint, this._options.ModelId).SystemOneAsync; + } + + return new JevAIFunction(this._options.Name, this._options.Description, systemOneAsync); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevAIToolOptions.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevAIToolOptions.cs new file mode 100644 index 00000000000..e0239af7324 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevAIToolOptions.cs @@ -0,0 +1,109 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel; +using System.ClientModel.Primitives; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Configures the built by and the +/// client pipeline that sends its requests to the TypeSafe System One API. +/// +/// +/// +/// This type follows the pattern of the OpenAI and Azure AI client libraries: +/// selects the HTTP stack (for example an +/// over an HttpClient from IHttpClientFactory), +/// controls retries, and +/// adds custom policies. The pipeline settings, +/// , and apply only when the builder uses the TypeSafe API, that is, when +/// it receives an ; and apply to every +/// mapping. +/// +/// +/// Unset pipeline settings get the defaults of the official TypeSafe SDK. When +/// is , up to two retries follow 408, 429, and +/// 5xx responses and network failures, waiting for the server's retry-after-ms or Retry-After delay up +/// to one minute, or else for an exponential backoff from half a second to five seconds; the policy follows +/// . When +/// is , each attempt times out after 10 seconds. +/// +/// +/// Like other client options, an instance becomes read-only once a tool has been built with it. +/// +/// +public sealed class JevAIToolOptions : ClientPipelineOptions +{ + private const string DefaultDescription = + "Answers named questions about text or structured state with Jev, a classification model. Jev does not write " + + "text: it returns calibrated probabilities. Use it to classify, route, score, or check facts, and ask all related " + + "questions in one call. A 'choice' question selects one of the named alternatives in its criteria. A 'score' " + + "question assigns a score using an ordered rubric of 2 to 10 entries, and the score can fall between entries. A " + + "'noul' question returns the probability that the answer to a yes or no question is yes. Choice and score " + + "answers include a confidence from 0 to 1; treat a low confidence as uncertain."; + + /// + public override void Freeze() + { + JevPipelineDefaults.Apply(this); + base.Freeze(); + } + + /// + /// Gets or sets the System One endpoint. When , https://api.typesafe.ai/v1/systemone is used. + /// + public Uri? Endpoint + { + get; + set + { + this.AssertNotFrozen(); + field = value; + } + } + + /// + /// Gets or sets the Jev model that answers the questions. Defaults to jev-latest. + /// + public string ModelId + { + get; + set + { + this.AssertNotFrozen(); + field = value; + } + } = JevPipelineDefaults.DefaultModelId; + + /// + /// Gets or sets the name of the function that the model sees. Defaults to ask_system_one, after the SDK's + /// systemOne operation. + /// + public string Name + { + get; + set + { + this.AssertNotFrozen(); + field = value; + } + } = "ask_system_one"; + + /// + /// Gets or sets the description of the function that the model sees. + /// + /// + /// The default description explains the Choice, Score, and Noul question kinds. A replacement should explain them + /// too, together with when the agent should call the function. + /// + public string Description + { + get; + set + { + this.AssertNotFrozen(); + field = value; + } + } = DefaultDescription; +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevChoiceQuestion.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevChoiceQuestion.cs new file mode 100644 index 00000000000..a07918fa44d --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevChoiceQuestion.cs @@ -0,0 +1,28 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents a Choice question, which selects one of the named alternatives in . +/// +/// +/// The answer is a . This type mirrors ChoiceQuestion of the official TypeSafe SDK. +/// +[Description("A Choice question: selects one of the named alternatives in criteria.")] +public sealed class JevChoiceQuestion : JevQuestion +{ + /// + /// Gets or sets the alternatives, keyed by the label that the answer returns. + /// + /// + /// Each value describes the alternative as text or JSON, or is when the label is + /// enough. Jev accepts from 1 to 255 alternatives. + /// + [JsonPropertyName("criteria")] + [Description("The alternatives, keyed by the label that the answer returns. Each value describes the alternative as text or JSON, or is null when the label is enough. From 1 to 255 alternatives.")] + public required IReadOnlyDictionary Criteria { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevChoiceResponse.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevChoiceResponse.cs new file mode 100644 index 00000000000..103fb2b12ef --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevChoiceResponse.cs @@ -0,0 +1,38 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents the answer to a : the selected label and its probabilities. +/// +/// +/// This type mirrors ChoiceResponse of the official TypeSafe SDK. +/// +[Description("The answer to a Choice question: the selected label and its probabilities.")] +public sealed class JevChoiceResponse : JevResponse +{ + /// + /// Gets or sets the selected label. + /// + [JsonPropertyName("choice")] + [Description("The selected label.")] + public required string Choice { get; set; } + + /// + /// Gets or sets the reported confidence in the selected label, from 0 to 1. + /// + [JsonPropertyName("confidence")] + [Description("Reported confidence in the selected label, from 0 to 1. Treat low confidence as uncertain.")] + public required double Confidence { get; set; } + + /// + /// Gets or sets the probabilities, keyed by label. They sum to 1. + /// + [JsonPropertyName("probabilities")] + [Description("Probabilities keyed by label. They sum to 1.")] + public required IReadOnlyDictionary Probabilities { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevDecisionClient.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevDecisionClient.cs new file mode 100644 index 00000000000..d72b75606f3 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevDecisionClient.cs @@ -0,0 +1,135 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel; +using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; +using Microsoft.Shared.DiagnosticIds; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Provides an for Jev, the TypeSafe System One model, which answers typed Binary, +/// Choice, and Score questions about a state with probabilities. +/// +/// +/// +/// Binary, Choice, and Score questions become Jev Noul, Choice, and Score questions. A request is checked with the +/// TypeSafe rules before it is sent, such as at most 255 Choice alternatives and 2 to 10 Score levels, and the result is +/// checked against the request before it is converted. Jev reports probabilities rounded to two decimal places, which +/// each answer declares as . +/// +/// +/// The response keeps the as its , each answer +/// keeps its , and Choice and Score answers carry Jev's confidence in the confidence +/// entry of . +/// +/// +/// is the decision API proposed for Microsoft.Extensions.AI. Microsoft.Agents.AI.Abstractions +/// carries a copy of it until it ships, so this client and the API are experimental. +/// +/// +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class JevDecisionClient : IDecisionClient +{ + internal const string ProviderName = "typesafe.ai"; + + private readonly JevHttpClient _client; + private readonly DecisionClientMetadata _metadata; + + /// + /// Initializes a new instance of the class. + /// + /// The TypeSafe API key, sent as a bearer token. + /// The client and pipeline options. Defaults are used when . + /// + /// is empty, or is + /// not an absolute URI. + /// + public JevDecisionClient(ApiKeyCredential credential, JevDecisionClientOptions? options = null) + : this(CreateHttpClient(credential, options ?? new JevDecisionClientOptions())) + { + } + + internal JevDecisionClient(JevHttpClient client) + { + this._client = Throw.IfNull(client); + this._metadata = new DecisionClientMetadata(ProviderName, client.Endpoint, client.ModelId, [DecisionKind.Binary, DecisionKind.Choice, DecisionKind.Score]); + } + + /// + /// The request breaks a TypeSafe rule, such as the number of Choice alternatives. + /// The Jev result does not answer every question as asked. + /// An answer is not a complete, correlated decision answer. + /// The TypeSafe API rejected the request. + public async Task GetResponseAsync(DecisionRequest request, DecisionOptions? options = null, CancellationToken cancellationToken = default) + { + _ = Throw.IfNull(request); + + var questions = new Dictionary(request.Questions.Count, StringComparer.Ordinal); + foreach (DecisionQuestion question in request.Questions) + { + questions[question.Id] = JevDecisionMapping.ToJevQuestion(question); + } + + var jevRequest = new JevRequest { State = JevDecisionMapping.ToEntry(request.State), Questions = questions }; + JevContractValidator.ValidateRequest(jevRequest); + + string modelId = string.IsNullOrWhiteSpace(options?.ModelId) ? this._client.ModelId : options!.ModelId!; + JevResult result = await this._client.SystemOneAsync(jevRequest, modelId, cancellationToken).ConfigureAwait(false); + + // The TypeSafe checks come first, so a result that answers the wrong labels fails as it does for the tool. + JevContractValidator.ValidateResult(jevRequest, result); + + var answers = new List(request.Questions.Count); + foreach (DecisionQuestion question in request.Questions) + { + answers.Add(JevDecisionMapping.ToDecisionAnswer(question, result.Answers[question.Id])); + } + + return new DecisionResponse( + request, + answers, + new DecisionProvenance(ProviderName, this._client.Endpoint, result.Model, precision: JevDecisionMapping.Precision), + JevDecisionMapping.ToUsage(result.Usage), + rawRepresentation: result); + } + + /// + public object? GetService(Type serviceType, object? serviceKey = null) + { + _ = Throw.IfNull(serviceType); + + return serviceKey is not null ? null + : serviceType == typeof(DecisionClientMetadata) ? this._metadata + : serviceType.IsInstanceOfType(this) ? this + : null; + } + + /// + public void Dispose() + { + // The pipeline owns no disposable resources; its default transport shares one HttpClient per process. + } + + private static JevHttpClient CreateHttpClient(ApiKeyCredential credential, JevDecisionClientOptions options) + { + _ = Throw.IfNull(credential); + + if (string.IsNullOrWhiteSpace(options.ModelId)) + { + Throw.ArgumentException(nameof(options), $"{nameof(JevDecisionClientOptions)}.{nameof(JevDecisionClientOptions.ModelId)} must not be empty."); + } + + if (options.Endpoint?.IsAbsoluteUri is false) + { + Throw.ArgumentException(nameof(options), $"{nameof(JevDecisionClientOptions)}.{nameof(JevDecisionClientOptions.Endpoint)} must be an absolute URI."); + } + + return new JevHttpClient(credential, options, options.Endpoint, options.ModelId); + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevDecisionClientOptions.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevDecisionClientOptions.cs new file mode 100644 index 00000000000..b32f55b0ada --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevDecisionClientOptions.cs @@ -0,0 +1,62 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel.Primitives; +using System.Diagnostics.CodeAnalysis; +using Microsoft.Shared.DiagnosticIds; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Configures a and the client pipeline that sends its requests to the TypeSafe System +/// One API. +/// +/// +/// +/// This type follows the pattern of the OpenAI and Azure AI client libraries: +/// selects the HTTP stack, +/// controls retries, and adds custom +/// policies. Unset pipeline settings get the defaults of the official TypeSafe SDK, as described for +/// . +/// +/// +/// Like other client options, an instance becomes read-only once a client has been created with it. +/// +/// +[Experimental(DiagnosticIds.Experiments.AIDecisions, UrlFormat = DiagnosticIds.UrlFormat)] +public sealed class JevDecisionClientOptions : ClientPipelineOptions +{ + /// + public override void Freeze() + { + JevPipelineDefaults.Apply(this); + base.Freeze(); + } + + /// + /// Gets or sets the System One endpoint. When , https://api.typesafe.ai/v1/systemone is used. + /// + public Uri? Endpoint + { + get; + set + { + this.AssertNotFrozen(); + field = value; + } + } + + /// + /// Gets or sets the Jev model that answers the questions, unless + /// selects another for a request. Defaults to jev-latest. + /// + public string ModelId + { + get; + set + { + this.AssertNotFrozen(); + field = value; + } + } = JevPipelineDefaults.DefaultModelId; +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevEntry.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevEntry.cs new file mode 100644 index 00000000000..ae0999a26ad --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevEntry.cs @@ -0,0 +1,138 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Text.Json; +using System.Text.Json.Serialization; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents a Jev entry: text, a JSON object or array, or . +/// +/// +/// This type mirrors EntryType of the official TypeSafe SDK. The state of a , the +/// instructions of a , and every criterion description are entries, so each can be plain +/// text or structured data that questions refer to by field name. A converts implicitly, a +/// converts explicitly because a JSON number or Boolean is not an entry, and +/// is the entry. +/// +[JsonConverter(typeof(JevEntryJsonConverter))] +public readonly struct JevEntry : IEquatable +{ + private readonly JsonElement _value; + + /// + /// Initializes a new instance of the struct from JSON. + /// + /// A JSON string, object, array, or null. + /// is a JSON number or Boolean. + public JevEntry(JsonElement value) + { + if (value.ValueKind is not (JsonValueKind.String or JsonValueKind.Object or JsonValueKind.Array or JsonValueKind.Null or JsonValueKind.Undefined)) + { + Throw.ArgumentException(nameof(value), "A Jev entry must be text, a JSON object or array, or null."); + } + + // Cloning detaches the value from the document it came from, which may be disposed after this call. + this._value = value.ValueKind is JsonValueKind.Null or JsonValueKind.Undefined ? default : value.Clone(); + } + + /// + /// Gets the entry, which leaves a criterion undescribed. + /// + public static JevEntry Null => default; + + /// + /// Gets the kind of the entry: , , + /// , or . + /// + public JsonValueKind Kind => this._value.ValueKind == JsonValueKind.Undefined ? JsonValueKind.Null : this._value.ValueKind; + + /// + /// Gets a value indicating whether the entry is . + /// + public bool IsNull => this.Kind == JsonValueKind.Null; + + /// + /// Gets the text of an entry whose is , or otherwise. + /// + public string? Text => this.Kind == JsonValueKind.String ? this._value.GetString() : null; + + /// + /// Gets the entry as JSON, or for the entry. + /// + public JsonElement? Json => this.IsNull ? null : this._value; + + /// + /// Creates an entry from text. + /// + /// The text, or for the entry. + /// The entry. + public static JevEntry FromString(string? text) => + text is null ? default : new JevEntry(JsonSerializer.SerializeToElement(text, JevJsonContext.Default.String)); + + /// + /// Creates an entry from JSON. + /// + /// A JSON string, object, array, or null. + /// The entry. + public static JevEntry FromJsonElement(JsonElement value) => new(value); + + /// + /// Converts text to an entry. + /// + /// The text, or for the entry. + public static implicit operator JevEntry(string? text) => FromString(text); + + /// + /// Converts JSON to an entry. + /// + /// A JSON string, object, array, or null. + /// is a JSON number or Boolean. + /// + /// The conversion is explicit because it fails for JSON numbers and Booleans, which are not entries. + /// + public static explicit operator JevEntry(JsonElement value) => FromJsonElement(value); + + /// Determines whether two entries have the same JSON value. + /// The first entry. + /// The second entry. + /// when the entries are equal. + public static bool operator ==(JevEntry left, JevEntry right) => left.Equals(right); + + /// Determines whether two entries have different JSON values. + /// The first entry. + /// The second entry. + /// when the entries differ. + public static bool operator !=(JevEntry left, JevEntry right) => !left.Equals(right); + + /// + public bool Equals(JevEntry other) => + this.Kind == other.Kind && (this.IsNull || JsonElement.DeepEquals(this._value, other._value)); + + /// + public override bool Equals(object? obj) => obj is JevEntry other && this.Equals(other); + + /// + /// + /// Objects are equal regardless of property order, so only the kind (and the text of a string) is hashed. + /// + public override int GetHashCode() => + this.Kind == JsonValueKind.String + ? HashCode.Combine(this.Kind, this._value.GetString()) + : this.Kind.GetHashCode(); + + /// + /// Returns the text of a string entry, the JSON of an object or array entry, or an empty string for the + /// entry. + /// + /// The entry as a string. + public override string ToString() => + this.Kind switch + { + JsonValueKind.String => this._value.GetString()!, + JsonValueKind.Null => string.Empty, + _ => this._value.GetRawText(), + }; +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulCriteria.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulCriteria.cs new file mode 100644 index 00000000000..609b9c0b90a --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulCriteria.cs @@ -0,0 +1,28 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Describes the yes and no outcomes of a . +/// +public sealed class JevNoulCriteria +{ + /// + /// Gets or sets the description of the yes outcome, as text or JSON. + /// + [JsonPropertyName("true")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + [Description("Description of the yes outcome, as text or JSON.")] + public JevEntry? True { get; set; } + + /// + /// Gets or sets the description of the no outcome, as text or JSON. + /// + [JsonPropertyName("false")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + [Description("Description of the no outcome, as text or JSON.")] + public JevEntry? False { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulQuestion.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulQuestion.cs new file mode 100644 index 00000000000..cf54a32eefe --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulQuestion.cs @@ -0,0 +1,25 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents a Noul question, a yes or no question whose answer is the probability of yes. +/// +/// +/// The answer is a . A Noul needs , +/// , or both. This type mirrors NoulQuestion of the official TypeSafe SDK. +/// +[Description("A Noul question: a yes or no question whose answer is the probability of yes. Needs instructions, criteria, or both.")] +public sealed class JevNoulQuestion : JevQuestion +{ + /// + /// Gets or sets optional descriptions of the yes and no outcomes. + /// + [JsonPropertyName("criteria")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + [Description("Optional descriptions of the yes and no outcomes.")] + public JevNoulCriteria? Criteria { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulResponse.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulResponse.cs new file mode 100644 index 00000000000..f67e5cab17b --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevNoulResponse.cs @@ -0,0 +1,23 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents the answer to a : the probability of yes. +/// +/// +/// This type mirrors NoulResponse of the official TypeSafe SDK. +/// +[Description("The answer to a Noul question: the probability of yes.")] +public sealed class JevNoulResponse : JevResponse +{ + /// + /// Gets or sets the probability of a yes answer, from 0 to 1. + /// + [JsonPropertyName("noul")] + [Description("Probability of a yes answer, from 0 to 1.")] + public required double Noul { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevQuestion.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevQuestion.cs new file mode 100644 index 00000000000..bbaa8c956c8 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevQuestion.cs @@ -0,0 +1,39 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents one typed question that Jev answers about the state of a . +/// +/// +/// The JSON type property selects the question kind: choice (), +/// score (), or noul (). It mirrors +/// Question of the official TypeSafe SDK. +/// +[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")] +[JsonDerivedType(typeof(JevChoiceQuestion), "choice")] +[JsonDerivedType(typeof(JevScoreQuestion), "score")] +[JsonDerivedType(typeof(JevNoulQuestion), "noul")] +public abstract class JevQuestion +{ + // Only the three question kinds that the Jev API accepts can exist. + private protected JevQuestion() + { + } + + /// + /// Gets or sets what Jev should decide, rate, or check, as text or JSON, or when the + /// criteria say enough. + /// + /// + /// Structured instructions hold the question in one field and data it refers to in others, for example + /// { "potential_duplicate": { ... }, "question": "Is the resume for the same person as `potential_duplicate`?" }. + /// + [JsonPropertyName("instructions")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + [Description("What Jev should decide, rate, or check: text, or a JSON object that holds the question in one field and the data it refers to in others. Optional when the criteria say enough. Describe the idea rather than exact words, because Jev matches on meaning.")] + public JevEntry? Instructions { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevRequest.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevRequest.cs new file mode 100644 index 00000000000..b4529531d26 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevRequest.cs @@ -0,0 +1,41 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.ComponentModel; +using System.Text.Json.Serialization; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents the input of a Jev call: the state and the typed questions to answer about it. +/// +/// +/// This type mirrors SystemOneRequest of the official TypeSafe SDK without the model, which the tool +/// configuration selects. Its JSON form is the argument shape of the that +/// creates. +/// +public sealed class JevRequest +{ + /// + /// Gets or sets the content that the questions are about. + /// + /// + /// Text, or a JSON object or array for structured data, such as a conversation or related records. It mirrors + /// state of SystemOneRequest in the official TypeSafe SDK, except that the API rejects + /// . + /// + [JsonPropertyName("state")] + [Description("The content to answer questions about: text, or a JSON object or array for structured data. Questions can refer to object fields by name in backticks, for example `order`.")] + public required JevEntry State { get; set; } + + /// + /// Gets or sets the questions to answer, keyed by an ID that the caller chooses. + /// + /// + /// Each answer in uses the ID of its question. + /// + [JsonPropertyName("questions")] + [Description("The questions to answer about the state, keyed by an ID you choose. Each answer comes back under the same ID. Ask all related questions in one call.")] + public required IReadOnlyDictionary Questions { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevResponse.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevResponse.cs new file mode 100644 index 00000000000..f04265209d5 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevResponse.cs @@ -0,0 +1,25 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents Jev's answer to one question of a . +/// +/// +/// The JSON type property matches the kind of the question: choice (), +/// score (), or noul (). The derived types +/// mirror ChoiceResponse, ScoreResponse, and NoulResponse of the official TypeSafe SDK. +/// +[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")] +[JsonDerivedType(typeof(JevChoiceResponse), "choice")] +[JsonDerivedType(typeof(JevScoreResponse), "score")] +[JsonDerivedType(typeof(JevNoulResponse), "noul")] +public abstract class JevResponse +{ + // Only the three response kinds that the Jev API returns can exist. + private protected JevResponse() + { + } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevResult.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevResult.cs new file mode 100644 index 00000000000..a847eb2f774 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevResult.cs @@ -0,0 +1,40 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.ComponentModel; +using System.Text.Json.Serialization; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents the result of a Jev call: one typed answer per question of the , with the model +/// and token usage. +/// +/// +/// This type mirrors SystemOneResult of the official TypeSafe SDK. Its JSON form is the result of the +/// that creates. +/// +public sealed class JevResult +{ + /// + /// Gets or sets the model that answered the request. + /// + [JsonPropertyName("model")] + [Description("The model that answered the request.")] + public required string Model { get; set; } + + /// + /// Gets or sets the answers, keyed by the ID of the question they answer. + /// + [JsonPropertyName("answers")] + [Description("One answer per question, keyed by the question ID.")] + public required IReadOnlyDictionary Answers { get; set; } + + /// + /// Gets or sets the token usage of the request. + /// + [JsonPropertyName("usage")] + [Description("The token usage of the request.")] + public required JevUsage Usage { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevScoreQuestion.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevScoreQuestion.cs new file mode 100644 index 00000000000..fde0cc3f19e --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevScoreQuestion.cs @@ -0,0 +1,29 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents a Score question, which assigns a score using the ordered rubric in . +/// +/// +/// The answer is a , whose score is weighted by probability and can fall between +/// levels. This type mirrors ScoreQuestion of the official TypeSafe SDK. +/// +[Description("A Score question: assigns a score using the ordered rubric in criteria.")] +public sealed class JevScoreQuestion : JevQuestion +{ + /// + /// Gets or sets the rubric: one description per score, indexed from zero (the lowest score). + /// + /// + /// Each description is text or JSON. The official SDK types also allow to leave a + /// score undescribed, but the API rejects it. A Score needs from 2 to 10 scores. + /// + [JsonPropertyName("criteria")] + [Description("The rubric: one description per score, as text or JSON, indexed from zero (the lowest score). From 2 to 10 scores.")] + public required IReadOnlyList Criteria { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevScoreResponse.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevScoreResponse.cs new file mode 100644 index 00000000000..30cec062631 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevScoreResponse.cs @@ -0,0 +1,45 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents the answer to a : an expected score with its rubric and probabilities. +/// +/// +/// This type mirrors ScoreResponse of the official TypeSafe SDK. +/// +[Description("The answer to a Score question: an expected score with its rubric and probabilities.")] +public sealed class JevScoreResponse : JevResponse +{ + /// + /// Gets or sets the expected score, which may fall between integer rubric levels. + /// + [JsonPropertyName("score")] + [Description("Expected score, which may fall between integer rubric levels.")] + public required double Score { get; set; } + + /// + /// Gets or sets the reported confidence in the score, from 0 to 1. + /// + [JsonPropertyName("confidence")] + [Description("Reported confidence in the score, from 0 to 1. Treat low confidence as uncertain.")] + public required double Confidence { get; set; } + + /// + /// Gets or sets the rubric descriptions, keyed by score. They echo the rubric of the question. + /// + [JsonPropertyName("legend")] + [Description("Rubric descriptions keyed by score.")] + public required IReadOnlyDictionary Legend { get; set; } + + /// + /// Gets or sets the probabilities, keyed by score. They sum to 1. + /// + [JsonPropertyName("probabilities")] + [Description("Probabilities keyed by score. They sum to 1.")] + public required IReadOnlyDictionary Probabilities { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevUsage.cs b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevUsage.cs new file mode 100644 index 00000000000..34cbff9229f --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/JevUsage.cs @@ -0,0 +1,26 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.ComponentModel; +using System.Text.Json.Serialization; + +namespace Microsoft.Agents.AI.TypeSafe; + +/// +/// Represents the token usage of a Jev call. This type mirrors Usage of the official TypeSafe SDK. +/// +public sealed class JevUsage +{ + /// + /// Gets or sets the number of input tokens. + /// + [JsonPropertyName("input_tokens")] + [Description("The number of input tokens.")] + public required long InputTokens { get; set; } + + /// + /// Gets or sets the number of output tokens. + /// + [JsonPropertyName("output_tokens")] + [Description("The number of output tokens.")] + public required long OutputTokens { get; set; } +} diff --git a/dotnet/src/Microsoft.Agents.AI.TypeSafe/Microsoft.Agents.AI.TypeSafe.csproj b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Microsoft.Agents.AI.TypeSafe.csproj new file mode 100644 index 00000000000..3c319fcef60 --- /dev/null +++ b/dotnet/src/Microsoft.Agents.AI.TypeSafe/Microsoft.Agents.AI.TypeSafe.csproj @@ -0,0 +1,39 @@ + + + + $(TargetFrameworksCore) + Microsoft.Agents.AI.TypeSafe + alpha + + $(NoWarn);MEAI001 + + + + true + true + + + + + + + Microsoft Agent Framework - TypeSafe (Jev) integration + Provides an IDecisionClient and an AIFunction that let agents classify, route, score, and check content with Jev, the TypeSafe System One model. + + + + + + + + + + + + + + + + + + diff --git a/dotnet/src/Shared/DiagnosticIds/DiagnosticsIds.cs b/dotnet/src/Shared/DiagnosticIds/DiagnosticsIds.cs index f9e0d4b15e3..9106273ef1f 100644 --- a/dotnet/src/Shared/DiagnosticIds/DiagnosticsIds.cs +++ b/dotnet/src/Shared/DiagnosticIds/DiagnosticsIds.cs @@ -7,6 +7,11 @@ namespace Microsoft.Shared.DiagnosticIds; /// internal static class DiagnosticIds { + /// + /// The help link format of the MEAI diagnostics, which reuses for MEAI experiment IDs. + /// + internal const string UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}"; + /// /// Experiments supported by this repo. /// @@ -25,6 +30,7 @@ internal static class Experiments internal const string AIMcpServers = MEAIExperiments; internal const string AIFunctionApprovals = MEAIExperiments; internal const string AIOpenAIRequestPolicies = MEAIExperiments; + internal const string AIDecisions = MEAIExperiments; // These diagnostic IDs are defined by the OpenAI package for its experimental APIs. // We use the same IDs so consumers do not need to suppress additional diagnostics diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAIFunctionTests.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAIFunctionTests.cs new file mode 100644 index 00000000000..386c834b9a9 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAIFunctionTests.cs @@ -0,0 +1,548 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.DependencyInjection; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +public sealed class JevAIFunctionTests +{ + [Fact] + public async Task InvokeAsync_ModelArguments_ReachTheMappingAsTypedRequestAsync() + { + // Arrange + JevRequest? received = null; + AIFunction tool = new JevAIToolBuilder().UseMapping((request, _, _) => + { + received = request; + return Task.FromResult(JevTestData.CreateResult()); + }).Build(); + + // Act + await tool.InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + Assert.NotNull(received); + Assert.Equal(JevTestData.TicketText, received.State.Text); + + JevChoiceQuestion department = Assert.IsType(received.Questions["department"]); + Assert.Equal("Which team should handle this", department.Instructions?.Text); + Assert.Equal(["billing", "technical", "sales"], department.Criteria.Keys); + Assert.True(department.Criteria["sales"].IsNull); + + JevScoreQuestion frustration = Assert.IsType(received.Questions["frustration"]); + Assert.Equal(3, frustration.Criteria.Count); + Assert.Equal("Calm, just stating facts", frustration.Criteria[0].Text); + + JevNoulQuestion urgent = Assert.IsType(received.Questions["is_urgent"]); + Assert.Equal("Explicitly time-sensitive", urgent.Criteria!.True?.Text); + Assert.Equal("No urgency expressed", urgent.Criteria.False?.Text); + } + + [Fact] + public async Task InvokeAsync_ReturnsTheResultAsJsonWithWireNamesAsync() + { + // Arrange + AIFunction tool = new JevAIToolBuilder().UseMapping((_, _, _) => Task.FromResult(JevTestData.CreateResult())).Build(); + + // Act + object? result = await tool.InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + JsonElement json = Assert.IsType(result); + Assert.Equal("custom-model", json.GetProperty("model").GetString()); + JsonElement answers = json.GetProperty("answers"); + Assert.Equal("choice", answers.GetProperty("department").GetProperty("type").GetString()); + Assert.Equal("technical", answers.GetProperty("department").GetProperty("choice").GetString()); + Assert.Equal(0.78, answers.GetProperty("department").GetProperty("confidence").GetDouble()); + Assert.Equal("score", answers.GetProperty("frustration").GetProperty("type").GetString()); + Assert.Equal("Frustrated", answers.GetProperty("frustration").GetProperty("legend").GetProperty("1").GetString()); + Assert.Equal(0.97, answers.GetProperty("is_urgent").GetProperty("noul").GetDouble()); + Assert.Equal(10, json.GetProperty("usage").GetProperty("input_tokens").GetInt64()); + Assert.Equal(5, json.GetProperty("usage").GetProperty("output_tokens").GetInt64()); + } + + [Fact] + public async Task InvokeAsync_TypeWrittenLastAndObjectState_AreAcceptedAsync() + { + // Arrange + JevRequest? received = null; + AIFunction tool = new JevAIToolBuilder().UseMapping((request, _, _) => + { + received = request; + return Task.FromResult(Result("paid", new JevNoulResponse { Noul = 0.1 })); + }).Build(); + + // Act + await tool.InvokeAsync(JevTestData.Arguments(""" + { + "questions": { "paid": { "instructions": "Was `order` paid?", "type": "noul" } }, + "state": { "order": { "id": "A-104", "status": "failed" } } + } + """)); + + // Assert + Assert.Equal(JsonValueKind.Object, received!.State.Kind); + Assert.Equal("A-104", received.State.Json!.Value.GetProperty("order").GetProperty("id").GetString()); + Assert.IsType(received.Questions["paid"]); + } + + [Fact] + public async Task InvokeAsync_StructuredEntries_AreAcceptedLikeTheSdkAsync() + { + // Arrange + JevRequest? received = null; + AIFunction tool = new JevAIToolBuilder().UseMapping((request, _, _) => + { + received = request; + return Task.FromResult(new JevResult + { + Model = "m", + Answers = new Dictionary + { + ["same_person"] = new JevNoulResponse { Noul = 0.9 }, + ["team"] = new JevChoiceResponse { Choice = "billing", Confidence = 1, Probabilities = new Dictionary { ["billing"] = 1 } }, + }, + Usage = new JevUsage { InputTokens = 1, OutputTokens = 1 }, + }); + }).Build(); + + // Act + await tool.InvokeAsync(JevTestData.Arguments(""" + { + "state": ["Hi", "The payment failed."], + "questions": { + "same_person": { + "type": "noul", + "instructions": { "potential_duplicate": { "name": "John Smith" }, "question": "Is the resume for the same person as `potential_duplicate`?" } + }, + "team": { "type": "choice", "criteria": { "billing": { "covers": ["payments", "refunds"] } } } + } + } + """)); + + // Assert + Assert.Equal(JsonValueKind.Array, received!.State.Kind); + JevEntry instructions = Assert.IsType(received.Questions["same_person"]).Instructions!.Value; + Assert.Equal(JsonValueKind.Object, instructions.Kind); + Assert.Equal("John Smith", instructions.Json!.Value.GetProperty("potential_duplicate").GetProperty("name").GetString()); + + JevChoiceQuestion team = Assert.IsType(received.Questions["team"]); + Assert.Null(team.Instructions); + Assert.Equal(JsonValueKind.Object, team.Criteria["billing"].Kind); + } + + [Fact] + public async Task InvokeAsync_DotNetObjectArguments_AreAcceptedAsync() + { + // Arrange + JevRequest? received = null; + AIFunction tool = new JevAIToolBuilder().UseMapping((request, _, _) => + { + received = request; + return Task.FromResult(Result("q", new JevNoulResponse { Noul = 0.5 })); + }).Build(); + + // Act + await tool.InvokeAsync(new AIFunctionArguments + { + ["state"] = "The payment failed.", + ["questions"] = new Dictionary { ["q"] = new JevNoulQuestion { Instructions = "Did the payment fail?" } }, + }); + + // Assert + Assert.Equal("The payment failed.", received!.State.Text); + Assert.Equal("Did the payment fail?", Assert.IsType(received.Questions["q"]).Instructions?.Text); + } + + [Theory] + [InlineData("""{"questions":{"q":{"type":"noul","instructions":"x"}}}""", "state")] + [InlineData("""{"state":42,"questions":{"q":{"type":"noul","instructions":"x"}}}""", "must be text, a JSON object or array, or null")] + [InlineData("""{"state":null,"questions":{"q":{"type":"noul","instructions":"x"}}}""", "The state must be text or a JSON object or array")] + [InlineData("""{"state":"x","questions":{}}""", "At least one question is required")] + [InlineData("""{"state":"x","questions":{"q":{"type":"rank","instructions":"x"}}}""", "not a valid Jev request")] + [InlineData("""{"state":"x","questions":{"q":{"instructions":"x"}}}""", "not a valid Jev request")] + [InlineData("""{"state":"x","questions":{"q":null}}""", "Question 'q' is null")] + [InlineData("""{"state":"x","questions":{"q":{"type":"noul","instructions":" "}}}""", "Noul question 'q' needs instructions or criteria")] + [InlineData("""{"state":"x","questions":{"q":{"type":"noul","criteria":{"true":null}}}}""", "Noul question 'q' needs instructions or criteria")] + [InlineData("""{"state":"x","questions":{"q":{"type":"choice","instructions":"x","criteria":{}}}}""", "has 0 alternatives; it needs from 1 to 255")] + [InlineData("""{"state":"x","questions":{"q":{"type":"score","instructions":"x","criteria":["only"]}}}""", "has 1 criterion; it needs from 2 to 10")] + [InlineData("""{"state":"x","questions":{"q":{"type":"score","instructions":"x","criteria":["0","1","2","3","4","5","6","7","8","9","10"]}}}""", "has 11 criteria")] + [InlineData("""{"state":"x","questions":{"q":{"type":"score","instructions":"x","criteria":[1,2]}}}""", "must be text, a JSON object or array, or null")] + [InlineData("""{"state":"x","questions":{"q":{"type":"score","instructions":"x","criteria":[null,"High"]}}}""", "has a null criterion at index 0")] + public async Task InvokeAsync_InvalidArguments_FailBeforeCallingAsync(string arguments, string expectedMessage) + { + // Arrange + int calls = 0; + AIFunction tool = new JevAIToolBuilder().UseMapping((_, _, _) => + { + calls++; + return Task.FromResult(JevTestData.CreateResult()); + }).Build(); + + // Act + ArgumentException exception = await Assert.ThrowsAnyAsync(() => tool.InvokeAsync(JevTestData.Arguments(arguments)).AsTask()); + + // Assert + Assert.Contains(expectedMessage, exception.Message, StringComparison.Ordinal); + Assert.Equal(0, calls); + } + + [Fact] + public async Task InvokeAsync_QuestionsWithoutInstructionsButWithCriteria_AreAcceptedAsync() + { + // Arrange + int calls = 0; + AIFunction tool = new JevAIToolBuilder().UseMapping((_, _, _) => + { + calls++; + return Task.FromResult(new JevResult + { + Model = "m", + Answers = new Dictionary + { + ["urgent"] = new JevNoulResponse { Noul = 0.2 }, + ["level"] = new JevScoreResponse + { + Score = 0, + Confidence = 1, + Legend = new Dictionary { ["0"] = "Low", ["1"] = "High" }, + Probabilities = new Dictionary { ["0"] = 1, ["1"] = 0 }, + }, + }, + Usage = new JevUsage { InputTokens = 1, OutputTokens = 1 }, + }); + }).Build(); + + // Act + await tool.InvokeAsync(JevTestData.Arguments(""" + {"state":"x","questions":{ + "urgent":{"type":"noul","criteria":{"true":"Explicitly urgent"}}, + "level":{"type":"score","criteria":["Low",{"level":"high","signals":["outage"]}]}}} + """)); + + // Assert + Assert.Equal(1, calls); + } + + [Fact] + public async Task InvokeAsync_TooManyChoiceAlternatives_FailBeforeCallingAsync() + { + // Arrange + string alternatives = string.Join(",", Enumerable.Range(0, 256).Select(static i => $"\"o{i}\":null")); + string arguments = "{\"state\":\"x\",\"questions\":{\"q\":{\"type\":\"choice\",\"instructions\":\"x\",\"criteria\":{" + alternatives + "}}}}"; + AIFunction tool = new JevAIToolBuilder().UseMapping((_, _, _) => Task.FromResult(JevTestData.CreateResult())).Build(); + + // Act + ArgumentException exception = await Assert.ThrowsAsync(() => tool.InvokeAsync(JevTestData.Arguments(arguments)).AsTask()); + + // Assert + Assert.Contains("has 256 alternatives", exception.Message, StringComparison.Ordinal); + } + + public static TheoryData, string> InvalidResults => new() + { + { "no answer", static r => Without(r, "is_urgent"), "no answer for question 'is_urgent'" }, + { "wrong kind", static r => With(r, "department", new JevNoulResponse { Noul = 0.5 }), "is a Noul answer, but the question is a Choice question" }, + { "unknown label", static r => With(r, "department", Choice("refunds", 0.9)), "chose 'refunds', which is not one of its labels" }, + { "confidence out of range", static r => With(r, "department", Choice("technical", 1.2)), "has confidence 1.2, which is outside the range 0 to 1" }, + { "score out of range", static r => With(r, "frustration", Score(3)), "has score 3, which is outside the range 0 to 2" }, + { "noul as percent", static r => With(r, "is_urgent", new JevNoulResponse { Noul = 97 }), "has noul 97, which is outside the range 0 to 1" }, + { "no answers", static r => new JevResult { Model = r.Model, Answers = null!, Usage = r.Usage }, "has no answers" }, + { "probability for a label not offered", static r => With(r, "department", ChoiceWith("technical", new() { ["TECHNICAL"] = 1 })), "has probabilities for 'TECHNICAL', which is not one of its labels" }, + { "probability above one", static r => With(r, "department", ChoiceWith("technical", new() { ["technical"] = 42 })), "has probability 'technical' 42, which is outside the range 0 to 1" }, + { "probability not a number", static r => With(r, "department", ChoiceWith("technical", new() { ["technical"] = double.NaN })), "has probability 'technical' NaN" }, + { "score probability for a missing score", static r => With(r, "frustration", ScoreWith(new() { ["3"] = 1 }, [])), "has probabilities for '3', which is not a score from 0 to 2" }, + { "legend for a missing score", static r => With(r, "frustration", ScoreWith([], new() { ["high"] = "Very angry" })), "has legend for 'high', which is not a score from 0 to 2" }, + }; + + [Theory] + [MemberData(nameof(InvalidResults))] + public async Task InvokeAsync_InvalidMappingResult_FailsAsync(string scenario, Func corrupt, string expectedMessage) + { + // Arrange + AIFunction tool = new JevAIToolBuilder().UseMapping((_, _, _) => Task.FromResult(corrupt(JevTestData.CreateResult()))).Build(); + + // Act + InvalidOperationException exception = await Assert.ThrowsAsync(() => tool.InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)).AsTask()); + + // Assert + Assert.True(exception.Message.Contains(expectedMessage, StringComparison.Ordinal), $"{scenario}: {exception.Message}"); + } + + [Fact] + public async Task InvokeAsync_MappingReturnsNull_FailsAsync() + { + // Arrange + AIFunction tool = new JevAIToolBuilder().UseMapping((_, _, _) => Task.FromResult(null!)).Build(); + + // Act + InvalidOperationException exception = await Assert.ThrowsAsync(() => tool.InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)).AsTask()); + + // Assert + Assert.Contains("returned no result", exception.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task InvokeAsync_PassesTheCancellationTokenToTheMappingAsync() + { + // Arrange + using var cancellation = new CancellationTokenSource(); + CancellationToken received = default; + AIFunction tool = new JevAIToolBuilder().UseMapping((_, _, cancellationToken) => + { + received = cancellationToken; + return Task.FromResult(JevTestData.CreateResult()); + }).Build(); + + // Act + await tool.InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson), cancellation.Token); + + // Assert + Assert.Equal(cancellation.Token, received); + } + + [Fact] + public async Task UseClient_MapsBetweenTheContractAndTheClientTypesAsync() + { + // Arrange + var client = new LabelClient(label: "technical"); + AIFunction tool = new JevAIToolBuilder().UseClient( + client.ClassifyAsync, + inputMapper: static request => + { + (string id, JevQuestion question) = request.Questions.Single(); + return new LabelRequest(id, request.State.Text!, ((JevChoiceQuestion)question).Criteria.Keys.ToList()); + }, + outputMapper: static response => Result(response.QuestionId, Choice(response.Label, response.Score))).Build(); + + // Act + object? result = await tool.InvokeAsync(JevTestData.Arguments(""" + {"state":"My integration keeps failing","questions":{"team":{"type":"choice","instructions":"Which team?","criteria":{"billing":null,"technical":null}}}} + """)); + + // Assert + Assert.Equal(new LabelRequest("team", "My integration keeps failing", ["billing", "technical"]), client.Received, LabelRequestComparer.Instance); + JsonElement answer = Assert.IsType(result).GetProperty("answers").GetProperty("team"); + Assert.Equal("technical", answer.GetProperty("choice").GetString()); + } + + [Fact] + public async Task UseClient_MapperReturnsALabelThatWasNotOffered_FailsAsync() + { + // Arrange + var client = new LabelClient(label: "TECHNICAL"); + AIFunction tool = new JevAIToolBuilder().UseClient( + client.ClassifyAsync, + static request => new LabelRequest("team", request.State.Text!, ["billing", "technical"]), + static response => Result("team", Choice(response.Label, response.Score))).Build(); + + // Act + InvalidOperationException exception = await Assert.ThrowsAsync(() => tool.InvokeAsync(JevTestData.Arguments(""" + {"state":"x","questions":{"team":{"type":"choice","instructions":"Which team?","criteria":{"billing":null,"technical":null}}}} + """)).AsTask()); + + // Assert + Assert.Contains("chose 'TECHNICAL'", exception.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task UseMapping_ReceivesTheServicesOfTheCallAsync() + { + // Arrange + using ServiceProvider services = new ServiceCollection().BuildServiceProvider(); + IServiceProvider? received = null; + AIFunction tool = new JevAIToolBuilder().UseMapping((_, callServices, _) => + { + received = callServices; + return Task.FromResult(JevTestData.CreateResult()); + }).Build(); + + AIFunctionArguments arguments = JevTestData.Arguments(JevTestData.RequestJson); + arguments.Services = services; + + // Act + await tool.InvokeAsync(arguments); + + // Assert + Assert.Same(services, received); + } + + [Fact] + public async Task UseClient_RegisteredClient_IsResolvedFromTheServicesOnEveryCallAsync() + { + // Arrange + int created = 0; + using ServiceProvider services = new ServiceCollection() + .AddTransient(_ => + { + created++; + return new LabelClient(label: "technical"); + }) + .BuildServiceProvider(); + + AIFunction tool = new JevAIToolBuilder().UseClient( + static (client, request, cancellationToken) => client.ClassifyAsync(request, cancellationToken), + static request => new LabelRequest("team", request.State.Text!, ["billing", "technical"]), + static response => Result("team", Choice(response.Label, response.Score))).Build(); + + AIFunctionArguments arguments = JevTestData.Arguments(""" + {"state":"x","questions":{"team":{"type":"choice","instructions":"Which team?","criteria":{"billing":null,"technical":null}}}} + """); + arguments.Services = services; + + // Act + await tool.InvokeAsync(arguments); + object? result = await tool.InvokeAsync(arguments); + + // Assert + Assert.Equal(2, created); + Assert.Equal("technical", Assert.IsType(result).GetProperty("answers").GetProperty("team").GetProperty("choice").GetString()); + } + + [Theory] + [InlineData(false, "this call has none")] + [InlineData(true, "LabelClient is not registered")] + public async Task UseClient_ClientNotAvailable_FailsWithWhatIsMissingAsync(bool withServices, string expectedMessage) + { + // Arrange + using ServiceProvider services = new ServiceCollection().BuildServiceProvider(); + AIFunction tool = new JevAIToolBuilder().UseClient( + static (client, request, cancellationToken) => client.ClassifyAsync(request, cancellationToken), + static request => new LabelRequest("q", "x", []), + static response => JevTestData.CreateResult()).Build(); + + AIFunctionArguments arguments = JevTestData.Arguments(JevTestData.RequestJson); + arguments.Services = withServices ? services : null; + + // Act + InvalidOperationException exception = await Assert.ThrowsAsync(() => tool.InvokeAsync(arguments).AsTask()); + + // Assert + Assert.Contains(expectedMessage, exception.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task UseClient_ScopedClientFromTheRootProvider_GetsAScopePerCallAsync() + { + // Arrange + var created = new List(); + using ServiceProvider root = new ServiceCollection() + .AddScoped(_ => + { + var client = new ScopedLabelClient(); + created.Add(client); + return client; + }) + .BuildServiceProvider(new ServiceProviderOptions { ValidateScopes = true }); + + AIFunction tool = new JevAIToolBuilder().UseClient( + static (client, text, _) => Task.FromResult(client.IsDisposed ? "disposed" : "technical"), + static request => request.State.Text!, + static label => Result("team", Choice(label, 0.9))).Build(); + + AIFunctionArguments arguments = JevTestData.Arguments(""" + {"state":"x","questions":{"team":{"type":"choice","instructions":"Which team?","criteria":{"billing":null,"technical":null}}}} + """); + arguments.Services = root; + + // Act + await tool.InvokeAsync(arguments); + await tool.InvokeAsync(arguments); + + // Assert + Assert.Equal(2, created.Count); + Assert.All(created, static client => Assert.True(client.IsDisposed)); + } + + private static JevResult Result(string id, JevResponse answer) => new() + { + Model = "custom-model", + Answers = new Dictionary { [id] = answer }, + Usage = new JevUsage { InputTokens = 1, OutputTokens = 1 }, + }; + + private static JevChoiceResponse Choice(string choice, double confidence) => new() + { + Choice = choice, + Confidence = confidence, + Probabilities = new Dictionary { [choice] = confidence }, + }; + + private static JevScoreResponse Score(double score) => new() + { + Score = score, + Confidence = 1, + Legend = new Dictionary(), + Probabilities = new Dictionary(), + }; + + private static JevChoiceResponse ChoiceWith(string choice, Dictionary probabilities) => new() + { + Choice = choice, + Confidence = 0.5, + Probabilities = probabilities, + }; + + private static JevScoreResponse ScoreWith(Dictionary probabilities, Dictionary legend) => new() + { + Score = 1, + Confidence = 1, + Legend = legend, + Probabilities = probabilities, + }; + + private static JevResult With(JevResult result, string id, JevResponse answer) + { + var answers = new Dictionary(result.Answers) { [id] = answer }; + return new JevResult { Model = result.Model, Answers = answers, Usage = result.Usage }; + } + + private static JevResult Without(JevResult result, string id) + { + var answers = new Dictionary(result.Answers); + answers.Remove(id); + return new JevResult { Model = result.Model, Answers = answers, Usage = result.Usage }; + } + + /// The request type of a hypothetical third-party classification client. + private sealed record LabelRequest(string QuestionId, string Text, List Labels); + + /// The response type of a hypothetical third-party classification client. + private sealed record LabelResponse(string QuestionId, string Label, double Score); + + private sealed class LabelClient(string label) + { + public LabelRequest? Received { get; private set; } + + public Task ClassifyAsync(LabelRequest request, CancellationToken cancellationToken) + { + this.Received = request; + return Task.FromResult(new LabelResponse(request.QuestionId, label, 0.9)); + } + } + + /// A disposable client registered as scoped, as clients holding per-request resources usually are. + private sealed class ScopedLabelClient : IDisposable + { + public bool IsDisposed { get; private set; } + + public void Dispose() => this.IsDisposed = true; + } + + private sealed class LabelRequestComparer : IEqualityComparer + { + public static LabelRequestComparer Instance { get; } = new(); + + public bool Equals(LabelRequest? x, LabelRequest? y) => + x is not null && y is not null && x.QuestionId == y.QuestionId && x.Text == y.Text && x.Labels.SequenceEqual(y.Labels); + + public int GetHashCode(LabelRequest? obj) => obj?.QuestionId.GetHashCode(StringComparison.Ordinal) ?? 0; + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAIToolBuilderTests.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAIToolBuilderTests.cs new file mode 100644 index 00000000000..9c7be795d9e --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAIToolBuilderTests.cs @@ -0,0 +1,190 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel; +using System.Linq; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +public sealed class JevAIToolBuilderTests +{ + [Fact] + public void Build_Defaults_DescribeTheJevContract() + { + // Act + AIFunction tool = new JevAIToolBuilder(new ApiKeyCredential("test-key")).Build(); + + // Assert + Assert.Equal("ask_system_one", tool.Name); + Assert.Contains("'choice'", tool.Description, StringComparison.Ordinal); + Assert.Contains("'score'", tool.Description, StringComparison.Ordinal); + Assert.Contains("'noul'", tool.Description, StringComparison.Ordinal); + + JsonElement schema = tool.JsonSchema; + Assert.Equal(["state", "questions"], schema.GetProperty("required").EnumerateArray().Select(static r => r.GetString())); + Assert.Equal(["string", "object", "array"], schema.GetProperty("properties").GetProperty("state").GetProperty("type").EnumerateArray().Select(static t => t.GetString())); + JsonElement question = schema.GetProperty("properties").GetProperty("questions").GetProperty("additionalProperties"); + Assert.Equal( + ["choice", "score", "noul"], + question.GetProperty("anyOf").EnumerateArray().Select(static b => b.GetProperty("properties").GetProperty("type").GetProperty("const").GetString())); + + JsonElement[] branches = [.. question.GetProperty("anyOf").EnumerateArray()]; + JsonElement choiceCriteria = branches[0].GetProperty("properties").GetProperty("criteria"); + Assert.Equal(["string", "object", "array", "null"], choiceCriteria.GetProperty("additionalProperties").GetProperty("type").EnumerateArray().Select(static t => t.GetString())); + Assert.Equal(1, choiceCriteria.GetProperty("minProperties").GetInt32()); + Assert.Equal(255, choiceCriteria.GetProperty("maxProperties").GetInt32()); + JsonElement scoreCriteria = branches[1].GetProperty("properties").GetProperty("criteria"); + Assert.Equal(["string", "object", "array"], scoreCriteria.GetProperty("items").GetProperty("type").EnumerateArray().Select(static t => t.GetString())); + Assert.Equal(2, scoreCriteria.GetProperty("minItems").GetInt32()); + Assert.Equal(10, scoreCriteria.GetProperty("maxItems").GetInt32()); + Assert.Equal(4, branches[2].GetProperty("properties").GetProperty("instructions").GetProperty("type").GetArrayLength()); + + JsonElement returnSchema = tool.ReturnJsonSchema!.Value; + Assert.Equal(["model", "answers", "usage"], returnSchema.GetProperty("required").EnumerateArray().Select(static r => r.GetString())); + Assert.True(returnSchema.GetProperty("properties").GetProperty("usage").GetProperty("properties").TryGetProperty("input_tokens", out _)); + } + + [Fact] + public void Options_Defaults_MatchTheTypeSafeApi() + { + // Act + var options = new JevAIToolOptions(); + + // Assert + Assert.Null(options.Endpoint); + Assert.Equal("jev-latest", options.ModelId); + Assert.Equal("ask_system_one", options.Name); + Assert.Null(options.RetryPolicy); + } + + [Fact] + public void Build_WithTheTypeSafeApi_AssignsTheSdkDefaultsOnlyWhenUnset() + { + // Arrange + var defaults = new JevAIToolOptions(); + var custom = new JevAIToolOptions + { + RetryPolicy = new System.ClientModel.Primitives.ClientRetryPolicy(maxRetries: 1), + NetworkTimeout = TimeSpan.FromSeconds(30), + }; + + // Act + _ = new JevAIToolBuilder(new ApiKeyCredential("test-key"), defaults).Build(); + _ = new JevAIToolBuilder(new ApiKeyCredential("test-key"), custom).Build(); + + // Assert + Assert.IsType(defaults.RetryPolicy); + Assert.Equal(TimeSpan.FromSeconds(10), defaults.NetworkTimeout); + Assert.IsType(custom.RetryPolicy); + Assert.Equal(TimeSpan.FromSeconds(30), custom.NetworkTimeout); + } + + [Fact] + public void Build_WithACustomMapping_IgnoresTheApiOnlyOptions() + { + // Arrange + var options = new JevAIToolOptions { ModelId = " ", Endpoint = new Uri("/relative", UriKind.Relative) }; + + // Act + AIFunction tool = new JevAIToolBuilder(options).UseMapping(static (_, _, _) => Task.FromResult(JevTestData.CreateResult())).Build(); + + // Assert + Assert.Equal("ask_system_one", tool.Name); + } + + [Fact] + public void Build_WithNameAndDescription_UsesTheOptions() + { + // Arrange + var options = new JevAIToolOptions { Name = "triage_ticket", Description = "Classifies support tickets." }; + + // Act + AIFunction tool = new JevAIToolBuilder(options).UseMapping(static (_, _, _) => Task.FromResult(JevTestData.CreateResult())).Build(); + + // Assert + Assert.Equal("triage_ticket", tool.Name); + Assert.Equal("Classifies support tickets.", tool.Description); + } + + [Fact] + public void Build_WithTheTypeSafeApi_MakesTheOptionsReadOnly() + { + // Arrange + var options = new JevAIToolOptions(); + + // Act + _ = new JevAIToolBuilder(new ApiKeyCredential("test-key"), options).Build(); + + // Assert + Assert.Throws(() => options.Endpoint = new Uri("https://proxy.contoso.com/jev")); + Assert.Throws(() => options.ModelId = "jev-1.13"); + } + + [Fact] + public void Build_WithACustomMapping_LeavesTheOptionsWritable() + { + // Arrange + var options = new JevAIToolOptions(); + + // Act + _ = new JevAIToolBuilder(new ApiKeyCredential("test-key"), options).UseMapping(static (_, _, _) => Task.FromResult(JevTestData.CreateResult())).Build(); + + // Assert + options.ModelId = "jev-1.13"; + Assert.Equal("jev-1.13", options.ModelId); + } + + [Fact] + public void Build_WithoutCredentialOrMapping_Throws() + { + // Act + InvalidOperationException exception = Assert.Throws(() => new JevAIToolBuilder().Build()); + + // Assert + Assert.Contains("ApiKeyCredential", exception.Message, StringComparison.Ordinal); + } + + [Theory] + [InlineData("name")] + [InlineData("description")] + [InlineData("model")] + [InlineData("endpoint")] + public void Build_InvalidOptions_Throw(string invalid) + { + // Arrange + var options = new JevAIToolOptions(); + switch (invalid) + { + case "name": options.Name = " "; break; + case "description": options.Description = ""; break; + case "model": options.ModelId = " "; break; + case "endpoint": options.Endpoint = new Uri("/v1/systemone", UriKind.Relative); break; + } + + // Act & Assert + Assert.Throws(() => new JevAIToolBuilder(new ApiKeyCredential("test-key"), options).Build()); + } + + [Fact] + public void Methods_NullArguments_Throw() + { + // Arrange + var builder = new JevAIToolBuilder(); + Task systemOneAsync(string request, CancellationToken _) => Task.FromResult(request); + string input(JevRequest _) => "request"; + JevResult output(string _) => JevTestData.CreateResult(); + Task systemOneWithClientAsync(object _1, string request, CancellationToken _2) => Task.FromResult(request); + + // Act & Assert + Assert.Throws(() => new JevAIToolBuilder((ApiKeyCredential)null!)); + Assert.Throws(() => builder.UseMapping(null!)); + Assert.Throws(() => builder.UseClient(null!, input, (Func)output)); + Assert.Throws(() => builder.UseClient((Func>)systemOneAsync, null!, output)); + Assert.Throws(() => builder.UseClient(systemOneAsync, input, null!)); + Assert.Throws(() => builder.UseClient((Func>)systemOneWithClientAsync, null!, output)); + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAgentIntegrationTests.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAgentIntegrationTests.cs new file mode 100644 index 00000000000..fee2448f03a --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevAgentIntegrationTests.cs @@ -0,0 +1,116 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel; +using System.ClientModel.Primitives; +using System.Collections.Generic; +using System.Linq; +using System.Net.Http; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.DependencyInjection; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +public sealed class JevAgentIntegrationTests +{ + [Fact] + public async Task RunAsync_AgentCallsTheTool_ModelReceivesTheAnswersAsync() + { + // Arrange + using var handler = new JevTestHttpHandler(); + using var httpClient = new HttpClient(handler); + AIFunction jev = new JevAIToolBuilder( + new ApiKeyCredential("test-key"), + new JevAIToolOptions { Transport = new HttpClientPipelineTransport(httpClient) }).Build(); + + using var model = new ScriptedChatClient( + _ => new ChatResponse(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call_1", jev.Name, JevTestData.CallArguments(JevTestData.RequestJson))])), + _ => new ChatResponse(new ChatMessage(ChatRole.Assistant, "Routed to the technical team as urgent."))); + AIAgent agent = model.AsAIAgent(instructions: "Triage support tickets with the Jev tool.", tools: [jev]); + + // Act + AgentResponse response = await agent.RunAsync(JevTestData.TicketText); + + // Assert + Assert.Equal("Routed to the technical team as urgent.", response.Text); + Assert.Single(handler.Requests); + + FunctionResultContent result = model.Calls[1].SelectMany(static m => m.Contents).OfType().Single(); + Assert.Null(result.Exception); + + // Chat clients serialize tool results with AIJsonUtilities.DefaultOptions before sending them to the model. + string sent = JsonSerializer.Serialize(result.Result, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(object))); + Assert.True(JsonNode.DeepEquals(JsonNode.Parse(JevTestData.ResponseJson), JsonNode.Parse(sent)), sent); + } + + [Fact] + public async Task GetResponseAsync_InvalidArgumentsWithDetailedErrors_TellTheModelWhatToFixAsync() + { + // Arrange + AIFunction jev = new JevAIToolBuilder().UseMapping((_, _, _) => Task.FromResult(JevTestData.CreateResult())).Build(); + const string InvalidArguments = """{"state":"x","questions":{"q":{"type":"score","instructions":"How bad?","criteria":["only"]}}}"""; + + using var model = new ScriptedChatClient( + _ => new ChatResponse(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call_1", jev.Name, JevTestData.CallArguments(InvalidArguments))])), + _ => new ChatResponse(new ChatMessage(ChatRole.Assistant, "done"))); + using var client = new FunctionInvokingChatClient(model) { IncludeDetailedErrors = true }; + + // Act + await client.GetResponseAsync("How bad is it?", new ChatOptions { Tools = [jev] }); + + // Assert + FunctionResultContent result = model.Calls[1].SelectMany(static m => m.Contents).OfType().Single(); + Assert.Contains("has 1 criterion; it needs from 2 to 10", result.Result?.ToString(), StringComparison.Ordinal); + } + + [Fact] + public async Task RunAsync_AgentWithServices_ToolResolvesTheClientFromThemAsync() + { + // Arrange + var classifier = new UrgencyClassifier(probability: 0.93); + using ServiceProvider services = new ServiceCollection().AddSingleton(classifier).BuildServiceProvider(); + + AIFunction jev = new JevAIToolBuilder() + .UseClient( + static (client, text, cancellationToken) => client.ScoreAsync(text, cancellationToken), + inputMapper: static request => request.State.Text!, + outputMapper: static probability => new JevResult + { + Model = "urgency-classifier", + Answers = new Dictionary { ["is_urgent"] = new JevNoulResponse { Noul = probability } }, + Usage = new JevUsage { InputTokens = 0, OutputTokens = 0 }, + }) + .Build(); + + const string Arguments = """{"state":"Please help ASAP","questions":{"is_urgent":{"type":"noul","instructions":"Is this urgent?"}}}"""; + using var model = new ScriptedChatClient( + _ => new ChatResponse(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call_1", jev.Name, JevTestData.CallArguments(Arguments))])), + _ => new ChatResponse(new ChatMessage(ChatRole.Assistant, "Urgent."))); + AIAgent agent = model.AsAIAgent(tools: [jev], services: services); + + // Act + AgentResponse response = await agent.RunAsync("Please help ASAP"); + + // Assert + Assert.Equal("Urgent.", response.Text); + Assert.Equal("Please help ASAP", classifier.Received); + FunctionResultContent result = model.Calls[1].SelectMany(static m => m.Contents).OfType().Single(); + Assert.Equal(0.93, Assert.IsType(result.Result).GetProperty("answers").GetProperty("is_urgent").GetProperty("noul").GetDouble()); + } + + /// A hypothetical third-party client registered in the application's services. + private sealed class UrgencyClassifier(double probability) + { + public string? Received { get; private set; } + + public Task ScoreAsync(string text, CancellationToken cancellationToken) + { + this.Received = text; + return Task.FromResult(probability); + } + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevDecisionClientTests.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevDecisionClientTests.cs new file mode 100644 index 00000000000..6760fd84d1e --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevDecisionClientTests.cs @@ -0,0 +1,216 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel; +using System.ClientModel.Primitives; +using System.Linq; +using System.Net; +using System.Net.Http; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +/// +/// Tests , which answers provider-neutral decision requests with Jev. +/// +public sealed class JevDecisionClientTests +{ + private static readonly JsonElement s_state = JsonDocument.Parse("""{ "ticket": "I was charged twice." }""").RootElement.Clone(); + + [Fact] + public async Task GetResponseAsync_DecisionQuestions_AreAskedAsJevQuestionsAsync() + { + // Arrange + using var handler = new JevTestHttpHandler().Reply(HttpStatusCode.OK, JevResultJson.Result( + JevResultJson.Noul("refund", 0.95), + "\"department\":{\"type\":\"choice\",\"choice\":\"billing\",\"confidence\":0.8,\"probabilities\":{\"technical\":0.1,\"billing\":0.9}}", + JevResultJson.Score("severity", 1.5, 3))); + using var httpClient = new HttpClient(handler); + using JevDecisionClient client = CreateClient(httpClient); + var request = new DecisionRequest(s_state, [ + new BinaryDecisionQuestion("refund", "Does the customer ask for a refund?", trueDescription: "A refund or reversal is requested."), + new ChoiceDecisionQuestion("department", "Which team should handle it?", [new("billing", "Payments"), new("technical", "Bugs")]), + new ScoreDecisionQuestion("severity", null, [new("cosmetic", "Cosmetic"), new("workaround", "Workaround available"), new("blocked", "Fully blocked")]), + ]); + + // Act + DecisionResponse response = await client.GetResponseAsync(request); + + // Assert: the request is the Jev wire shape, with the Score rubric in level order. + JsonNode expected = JsonNode.Parse(""" + { + "state": { "ticket": "I was charged twice." }, + "model": "jev-test", + "questions": { + "refund": { "type": "noul", "instructions": "Does the customer ask for a refund?", "criteria": { "true": "A refund or reversal is requested." } }, + "department": { "type": "choice", "instructions": "Which team should handle it?", "criteria": { "billing": "Payments", "technical": "Bugs" } }, + "severity": { "type": "score", "criteria": ["Cosmetic", "Workaround available", "Fully blocked"] } + } + } + """)!; + string body = Assert.Single(handler.Requests).Body; + Assert.True(JsonNode.DeepEquals(expected, JsonNode.Parse(body)), body); + + // Assert: the answers are in request order, keyed by the caller's IDs, with Jev's values and confidence. + Assert.Equal(0.95, Assert.IsType(response.Answers[0]).TrueProbability); + ChoiceDecisionAnswer department = Assert.IsType(response.Answers[1]); + Assert.Equal("billing", department.SelectedCandidateId); + Assert.Equal([("billing", 0.9), ("technical", 0.1)], department.Probabilities.Select(probability => (probability.Id, probability.Value))); + Assert.Equal(0.8, department.AdditionalProperties![JevDecisionMapping.ConfidenceProperty]); + Assert.IsType(department.RawRepresentation); + ScoreDecisionAnswer severity = Assert.IsType(response.Answers[2]); + Assert.Equal(1.5, severity.Score); + Assert.Equal(1.5, severity.ExpectedScore, 6); + Assert.Equal(["cosmetic", "workaround", "blocked"], severity.Probabilities.Select(probability => probability.Id)); + Assert.Equal([0.0, 0.5, 0.5], severity.Probabilities.Select(probability => probability.Value)); + + // Assert: the provenance, usage, and raw result. + Assert.Equal(JevDecisionClient.ProviderName, response.Provenance!.ProviderName); + Assert.Equal("jev-test", response.Provenance.ModelId); + Assert.Equal(DecisionPrecision.TwoDecimalPlaces, response.Provenance.Precision); + Assert.All(response.Answers, answer => Assert.Equal(DecisionPrecision.TwoDecimalPlaces, answer.Precision)); + Assert.Equal(12, response.Usage!.TotalTokenCount); + Assert.IsType(response.RawRepresentation); + } + + [Fact] + public async Task GetResponseAsync_IncompleteDistribution_ThrowsDecisionProtocolExceptionAsync() + { + // Arrange: the answer leaves out a label, so its distribution is not complete. + using var handler = new JevTestHttpHandler().Reply(HttpStatusCode.OK, JevResultJson.Result( + "\"department\":{\"type\":\"choice\",\"choice\":\"billing\",\"confidence\":0.9,\"probabilities\":{\"billing\":1.0}}")); + using var httpClient = new HttpClient(handler); + using JevDecisionClient client = CreateClient(httpClient); + var request = new DecisionRequest(s_state, [new ChoiceDecisionQuestion("department", "Which team?", [new("billing", "Payments"), new("technical", "Bugs")])]); + + // Act & Assert + DecisionProtocolException exception = await Assert.ThrowsAsync(() => client.GetResponseAsync(request)); + Assert.Contains("'technical'", exception.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task GetResponseAsync_DistributionRoundedToTwoDecimals_IsAcceptedAsync() + { + // Arrange: Jev rounds to two decimals, so three even probabilities sum to 0.99 rather than 1. + using var handler = new JevTestHttpHandler().Reply(HttpStatusCode.OK, JevResultJson.Result( + "\"department\":{\"type\":\"choice\",\"choice\":\"billing\",\"confidence\":0.01,\"probabilities\":{\"billing\":0.33,\"technical\":0.33,\"sales\":0.33}}")); + using var httpClient = new HttpClient(handler); + using JevDecisionClient client = CreateClient(httpClient); + var request = new DecisionRequest(s_state, [new ChoiceDecisionQuestion("department", "Which team?", [new("billing", "Payments"), new("technical", "Bugs"), new("sales", "Plans")])]); + + // Act + DecisionResponse response = await client.GetResponseAsync(request); + + // Assert: the observed values are kept as reported. + ChoiceDecisionAnswer answer = Assert.IsType(Assert.Single(response.Answers)); + Assert.Equal([0.33, 0.33, 0.33], answer.Probabilities.Select(probability => probability.Value)); + } + + [Fact] + public async Task GetResponseAsync_ValueWithinRoundingErrorOfItsBound_IsMovedOntoTheBoundAsync() + { + // Arrange + using var handler = new JevTestHttpHandler().Reply(HttpStatusCode.OK, JevResultJson.Result(JevResultJson.Noul("refund", 1.0000001))); + using var httpClient = new HttpClient(handler); + using JevDecisionClient client = CreateClient(httpClient); + + // Act + DecisionResponse response = await client.GetResponseAsync(new DecisionRequest(s_state, [new BinaryDecisionQuestion("refund", "Refund?")])); + + // Assert + Assert.Equal(1.0, Assert.IsType(Assert.Single(response.Answers)).TrueProbability); + } + + [Fact] + public async Task GetResponseAsync_StateThatIsNotTextObjectOrArray_ThrowsBeforeSendingAsync() + { + // Arrange + using var handler = new JevTestHttpHandler(); + using var httpClient = new HttpClient(handler); + using JevDecisionClient client = CreateClient(httpClient); + JsonElement number = JsonDocument.Parse("5").RootElement.Clone(); + + // Act & Assert + await Assert.ThrowsAsync(() => client.GetResponseAsync(new DecisionRequest(number, [new BinaryDecisionQuestion("refund", "Refund?")]))); + Assert.Empty(handler.Requests); + } + + [Fact] + public async Task GetResponseAsync_ModelInOptions_WinsOverTheClientModelAsync() + { + // Arrange + using var handler = new JevTestHttpHandler().Reply(HttpStatusCode.OK, JevResultJson.Result(JevResultJson.Noul("refund", 0.5))); + using var httpClient = new HttpClient(handler); + using JevDecisionClient client = CreateClient(httpClient); + + // Act + await client.GetResponseAsync(new DecisionRequest(s_state, [new BinaryDecisionQuestion("refund", "Refund?")]), new DecisionOptions { ModelId = "jev-1.14" }); + + // Assert + Assert.Equal("jev-1.14", (string?)JsonNode.Parse(Assert.Single(handler.Requests).Body)!["model"]); + } + + [Fact] + public void GetService_ReturnsTheMetadataAndTheClient() + { + // Arrange + using var httpClient = new HttpClient(new JevTestHttpHandler()); + using JevDecisionClient client = CreateClient(httpClient); + + // Act + DecisionClientMetadata? metadata = client.GetService(); + + // Assert + Assert.Equal(JevDecisionClient.ProviderName, metadata!.ProviderName); + Assert.Equal("jev-test", metadata.DefaultModelId); + Assert.Equal([DecisionKind.Binary, DecisionKind.Choice, DecisionKind.Score], metadata.SupportedKinds); + Assert.Same(client, client.GetService()); + Assert.Null(client.GetService("key")); + } + + [Fact] + public async Task Constructor_WithApiKeyAndOptions_SendsToTheConfiguredEndpointAsync() + { + // Arrange + using var handler = new JevTestHttpHandler().Reply(HttpStatusCode.OK, JevResultJson.Result(JevResultJson.Noul("refund", 0.5))); + using var httpClient = new HttpClient(handler); + using var client = new JevDecisionClient(new ApiKeyCredential("test-key"), new JevDecisionClientOptions + { + Endpoint = new Uri("https://proxy.contoso.com/jev"), + Transport = new HttpClientPipelineTransport(httpClient), + RetryPolicy = new JevRetryPolicy { RecordedWaitsForTests = [] }, + }); + + // Act + await client.GetResponseAsync(new DecisionRequest(s_state, [new BinaryDecisionQuestion("refund", "Refund?")])); + + // Assert + JevTestHttpHandler.CapturedRequest request = Assert.Single(handler.Requests); + Assert.Equal(new Uri("https://proxy.contoso.com/jev"), request.Uri); + Assert.Equal("test-key", request.Authorization!.Parameter); + Assert.Equal("jev-latest", (string?)JsonNode.Parse(request.Body)!["model"]); + } + + [Fact] + public void Constructor_InvalidOptions_Throws() + { + // Act & Assert + Assert.Throws(() => new JevDecisionClient(null!)); + Assert.Throws(() => new JevDecisionClient(new ApiKeyCredential("key"), new JevDecisionClientOptions { ModelId = " " })); + Assert.Throws(() => new JevDecisionClient(new ApiKeyCredential("key"), new JevDecisionClientOptions { Endpoint = new Uri("/jev", UriKind.Relative) })); + } + + internal static JevDecisionClient CreateClient(HttpClient httpClient) + { + var options = new JevDecisionClientOptions + { + Transport = new HttpClientPipelineTransport(httpClient), + RetryPolicy = new JevRetryPolicy { RecordedWaitsForTests = [] }, + }; + + return new JevDecisionClient(new JevHttpClient(new ApiKeyCredential("test-key"), options, endpoint: null, modelId: "jev-test")); + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevEntryTests.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevEntryTests.cs new file mode 100644 index 00000000000..532d670a315 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevEntryTests.cs @@ -0,0 +1,116 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Text.Json; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +public sealed class JevEntryTests +{ + [Fact] + public void Conversions_FromTextAndJson_KeepTheValue() + { + // Arrange + using JsonDocument document = JsonDocument.Parse("""{ "question": "Is `order` paid?" }"""); + + // Act + JevEntry text = "Is this urgent?"; + JevEntry nullText = (string?)null; + var json = (JevEntry)document.RootElement; + + // Assert + Assert.Equal(JsonValueKind.String, text.Kind); + Assert.Equal("Is this urgent?", text.Text); + Assert.Equal("Is this urgent?", text.ToString()); + Assert.True(nullText.IsNull); + Assert.Equal(JevEntry.Null, nullText); + Assert.Equal(JsonValueKind.Object, json.Kind); + Assert.Null(json.Text); + Assert.Equal("""{ "question": "Is `order` paid?" }""", json.ToString()); + } + + [Fact] + public void Default_IsTheNullEntry() + { + // Act + JevEntry entry = default; + + // Assert + Assert.True(entry.IsNull); + Assert.Equal(JsonValueKind.Null, entry.Kind); + Assert.Null(entry.Json); + Assert.Equal(string.Empty, entry.ToString()); + } + + [Fact] + public void Json_OutlivesTheDocumentItCameFrom() + { + // Arrange + JevEntry entry; + using (JsonDocument document = JsonDocument.Parse("""["a", "b"]""")) + { + entry = JevEntry.FromJsonElement(document.RootElement); + } + + // Act & Assert + Assert.Equal(2, entry.Json!.Value.GetArrayLength()); + } + + [Theory] + [InlineData("42")] + [InlineData("true")] + [InlineData("false")] + public void FromJsonElement_NumberOrBoolean_Throws(string json) + { + // Arrange + using JsonDocument document = JsonDocument.Parse(json); + JsonElement element = document.RootElement; + + // Act & Assert + Assert.Throws(() => (JevEntry)element); + Assert.Throws(() => JevEntry.FromJsonElement(element)); + } + + [Fact] + public void Equality_ComparesJsonValuesRegardlessOfPropertyOrder() + { + // Arrange + using JsonDocument first = JsonDocument.Parse("""{ "a": 1, "b": [true] }"""); + using JsonDocument second = JsonDocument.Parse("""{ "b": [true], "a": 1 }"""); + using JsonDocument other = JsonDocument.Parse("""{ "a": 2 }"""); + var left = (JevEntry)first.RootElement; + var right = (JevEntry)second.RootElement; + + // Act & Assert + Assert.True(left == right); + Assert.Equal(left.GetHashCode(), right.GetHashCode()); + Assert.True(left != (JevEntry)other.RootElement); + Assert.Equal((JevEntry)"same", (JevEntry)"same"); + Assert.NotEqual((JevEntry)"same", JevEntry.Null); + } + + [Theory] + [InlineData("\"text\"", JsonValueKind.String)] + [InlineData("{\"k\":\"v\"}", JsonValueKind.Object)] + [InlineData("[\"x\"]", JsonValueKind.Array)] + [InlineData("null", JsonValueKind.Null)] + public void Serialization_RoundTripsTheJsonValue(string json, JsonValueKind kind) + { + // Act + var entry = (JevEntry)JsonSerializer.Deserialize(json, JevJsonUtilities.Options.GetTypeInfo(typeof(JevEntry)))!; + string written = JsonSerializer.Serialize(entry, JevJsonUtilities.Options.GetTypeInfo(typeof(JevEntry))); + + // Assert + Assert.Equal(kind, entry.Kind); + Assert.Equal(json, written); + } + + [Theory] + [InlineData("42")] + [InlineData("true")] + public void Deserialization_NumberOrBoolean_Throws(string json) + { + // Act & Assert + Assert.Throws(() => JsonSerializer.Deserialize(json, JevJsonUtilities.Options.GetTypeInfo(typeof(JevEntry)))); + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevHttpClientTests.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevHttpClientTests.cs new file mode 100644 index 00000000000..a1e0d699931 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevHttpClientTests.cs @@ -0,0 +1,356 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.ClientModel; +using System.ClientModel.Primitives; +using System.Collections.Generic; +using System.Net; +using System.Net.Http; +using System.Net.Http.Headers; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +public sealed class JevHttpClientTests +{ + private const string ApiKey = "test-key-9f2c"; + + [Fact] + public async Task InvokeAsync_PostsTheWireRequestAndReturnsTheResponseAsync() + { + // Arrange + using var handler = new JevTestHttpHandler(); + using var httpClient = new HttpClient(handler); + AIFunction tool = CreateBuilder(httpClient).Build(); + + // Act + object? result = await tool.InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + JevTestHttpHandler.CapturedRequest request = Assert.Single(handler.Requests); + Assert.Equal(HttpMethod.Post, request.Method); + Assert.Equal(new Uri("https://api.typesafe.ai/v1/systemone"), request.Uri); + Assert.Equal("Bearer", request.Authorization!.Scheme); + Assert.Equal(ApiKey, request.Authorization.Parameter); + + JsonObject expected = JsonNode.Parse(JevTestData.RequestJson)!.AsObject(); + expected["model"] = "jev-latest"; + Assert.True(JsonNode.DeepEquals(expected, JsonNode.Parse(request.Body)), request.Body); + + JsonElement json = Assert.IsType(result); + Assert.True(JsonNode.DeepEquals(JsonNode.Parse(JevTestData.ResponseJson), JsonNode.Parse(json.GetRawText())), json.GetRawText()); + } + + [Fact] + public async Task InvokeAsync_CustomModelAndEndpoint_AreUsedAsync() + { + // Arrange + using var handler = new JevTestHttpHandler(); + using var httpClient = new HttpClient(handler); + var options = new JevAIToolOptions { ModelId = "jev-1.13", Endpoint = new Uri("https://proxy.contoso.com/jev") }; + + // Act + await CreateBuilder(httpClient, options).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + JevTestHttpHandler.CapturedRequest request = Assert.Single(handler.Requests); + Assert.Equal(new Uri("https://proxy.contoso.com/jev"), request.Uri); + Assert.Equal("jev-1.13", (string?)JsonNode.Parse(request.Body)!["model"]); + } + + [Fact] + public async Task InvokeAsync_CustomPolicy_RunsInThePipelineAsync() + { + // Arrange + using var handler = new JevTestHttpHandler(); + using var httpClient = new HttpClient(handler); + var options = new JevAIToolOptions(); + options.AddPolicy(new HeaderPolicy("x-tenant", "contoso"), PipelinePosition.PerCall); + + // Act + await CreateBuilder(httpClient, options).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + Assert.Equal("contoso", Assert.Single(handler.Requests).Headers["x-tenant"]); + } + + [Fact] + public async Task InvokeAsync_RateLimitedOrOverloaded_RetriesWithBackoffAsync() + { + // Arrange + using var handler = new JevTestHttpHandler() + .Reply(HttpStatusCode.TooManyRequests, "{}") + .Reply((HttpStatusCode)529, "{}") + .Reply(HttpStatusCode.OK, JevTestData.ResponseJson); + using var httpClient = new HttpClient(handler); + List waits = []; + + // Act + object? result = await CreateBuilder(httpClient, waits: waits).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert: the SDK backoff is 500 ms doubled per attempt, minus up to 25% jitter. + Assert.Equal(3, handler.Requests.Count); + Assert.Equal(2, waits.Count); + Assert.InRange(waits[0], TimeSpan.FromMilliseconds(375), TimeSpan.FromMilliseconds(500)); + Assert.InRange(waits[1], TimeSpan.FromMilliseconds(750), TimeSpan.FromMilliseconds(1000)); + Assert.Equal("technical", Assert.IsType(result).GetProperty("answers").GetProperty("department").GetProperty("choice").GetString()); + } + + [Theory] + [InlineData(503)] + [InlineData(520)] + [InlineData(408)] + public async Task InvokeAsync_TransientStatus_IsRetriedLikeTheSdkAsync(int status) + { + // Arrange + using var handler = new JevTestHttpHandler() + .Reply((HttpStatusCode)status, "{}") + .Reply(HttpStatusCode.OK, JevTestData.ResponseJson); + using var httpClient = new HttpClient(handler); + + // Act + await CreateBuilder(httpClient).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + Assert.Equal(2, handler.Requests.Count); + } + + [Fact] + public async Task InvokeAsync_StillRateLimitedAfterRetries_FailsWithTheStatusAsync() + { + // Arrange + using var handler = new JevTestHttpHandler().Reply(HttpStatusCode.TooManyRequests, """{"detail":"Rate limit exceeded"}"""); + using var httpClient = new HttpClient(handler); + + // Act + ClientResultException exception = await Assert.ThrowsAsync(() => + CreateBuilder(httpClient).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)).AsTask()); + + // Assert: the first attempt plus the SDK's two retries. + Assert.Equal(429, exception.Status); + Assert.Equal(3, handler.Requests.Count); + } + + [Fact] + public async Task InvokeAsync_RetryAfterSeconds_IsWaitedAsync() + { + // Arrange + using var handler = new JevTestHttpHandler() + .Reply(HttpStatusCode.TooManyRequests, "{}", new RetryConditionHeaderValue(TimeSpan.FromSeconds(5))) + .Reply(HttpStatusCode.OK, JevTestData.ResponseJson); + using var httpClient = new HttpClient(handler); + List waits = []; + + // Act + await CreateBuilder(httpClient, waits: waits).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + Assert.Equal(2, handler.Requests.Count); + Assert.Equal(TimeSpan.FromSeconds(5), Assert.Single(waits)); + } + + [Fact] + public async Task InvokeAsync_RetryAfterMilliseconds_IsPreferredAsync() + { + // Arrange + using var handler = new JevTestHttpHandler() + .Reply(HttpStatusCode.TooManyRequests, "{}", new RetryConditionHeaderValue(TimeSpan.FromSeconds(30)), retryAfterMs: "1500") + .Reply(HttpStatusCode.OK, JevTestData.ResponseJson); + using var httpClient = new HttpClient(handler); + List waits = []; + + // Act + await CreateBuilder(httpClient, waits: waits).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + Assert.Equal(TimeSpan.FromMilliseconds(1500), Assert.Single(waits)); + } + + [Fact] + public async Task InvokeAsync_RetryAfterDate_IsWaitedAsync() + { + // Arrange + using var handler = new JevTestHttpHandler() + .Reply((HttpStatusCode)529, "{}", new RetryConditionHeaderValue(DateTimeOffset.UtcNow.AddSeconds(20))) + .Reply(HttpStatusCode.OK, JevTestData.ResponseJson); + using var httpClient = new HttpClient(handler); + List waits = []; + + // Act + await CreateBuilder(httpClient, waits: waits).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert + Assert.Equal(2, handler.Requests.Count); + Assert.InRange(Assert.Single(waits), TimeSpan.FromSeconds(15), TimeSpan.FromSeconds(21)); + } + + [Theory] + [InlineData("Retry-After", "1e300")] + [InlineData("Retry-After", "99999999999999")] + [InlineData("Retry-After", "NaN")] + [InlineData("retry-after-ms", "1e30")] + [InlineData("retry-after-ms", "NaN")] + public async Task InvokeAsync_MalformedOrHugeServerDelay_FallsBackToBackoffAsync(string header, string value) + { + // Arrange + using var handler = new JevTestHttpHandler() + .Reply( + HttpStatusCode.TooManyRequests, + "{}", + retryAfterMs: header == "retry-after-ms" ? value : null, + retryAfterRaw: header == "Retry-After" ? value : null) + .Reply(HttpStatusCode.OK, JevTestData.ResponseJson); + using var httpClient = new HttpClient(handler); + List waits = []; + + // Act + await CreateBuilder(httpClient, waits: waits).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert: like the SDK, an unusable server delay is ignored instead of failing the call. + Assert.Equal(2, handler.Requests.Count); + Assert.InRange(Assert.Single(waits), TimeSpan.FromMilliseconds(375), TimeSpan.FromMilliseconds(500)); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task InvokeAsync_RetryAfterBeyondTheLimit_FallsBackToBackoffAsync(bool asDate) + { + // Arrange + RetryConditionHeaderValue retryAfter = asDate + ? new RetryConditionHeaderValue(DateTimeOffset.UtcNow.AddHours(1)) + : new RetryConditionHeaderValue(TimeSpan.FromHours(1)); + using var handler = new JevTestHttpHandler() + .Reply(HttpStatusCode.TooManyRequests, """{"detail":"Slow down"}""", retryAfter) + .Reply(HttpStatusCode.OK, JevTestData.ResponseJson); + using var httpClient = new HttpClient(handler); + List waits = []; + + // Act + await CreateBuilder(httpClient, waits: waits).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)); + + // Assert: waiting an hour would block the agent run, so the SDK's backoff is used instead. + Assert.Equal(2, handler.Requests.Count); + Assert.InRange(Assert.Single(waits), TimeSpan.FromMilliseconds(375), TimeSpan.FromMilliseconds(500)); + } + + [Fact] + public async Task InvokeAsync_ReplacedRetryPolicy_IsUsedAndStillRetriesOverloadedAsync() + { + // Arrange + using var handler = new JevTestHttpHandler() + .Reply((HttpStatusCode)529, "{}") + .Reply((HttpStatusCode)529, "{}"); + using var httpClient = new HttpClient(handler); + var options = new JevAIToolOptions + { + Transport = new HttpClientPipelineTransport(httpClient), + RetryPolicy = new NoWaitRetryPolicy(maxRetries: 1), + }; + + // Act + ClientResultException exception = await Assert.ThrowsAsync(() => + new JevAIToolBuilder(new ApiKeyCredential(ApiKey), options).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)).AsTask()); + + // Assert + Assert.Equal(529, exception.Status); + Assert.Equal(2, handler.Requests.Count); + } + + [Theory] + [InlineData(HttpStatusCode.Unauthorized, """{"detail":"Invalid API key"}""", "Invalid API key")] + [InlineData(HttpStatusCode.BadRequest, """{"detail":"Too many score levels. Must have at most 10 levels."}""", "Too many score levels")] + [InlineData(HttpStatusCode.UnprocessableEntity, """{"detail":[{"loc":["body","questions"],"msg":"Dictionary should have at least 1 item"}]}""", "Dictionary should have at least 1 item")] + public async Task InvokeAsync_ApiError_FailsWithTheDetailButNotTheKeyAsync(HttpStatusCode status, string body, string expectedMessage) + { + // Arrange + using var handler = new JevTestHttpHandler().Reply(status, body); + using var httpClient = new HttpClient(handler); + + // Act + ClientResultException exception = await Assert.ThrowsAsync(() => + CreateBuilder(httpClient).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)).AsTask()); + + // Assert + Assert.Equal((int)status, exception.Status); + Assert.Contains(expectedMessage, exception.Message, StringComparison.Ordinal); + Assert.DoesNotContain(ApiKey, exception.Message, StringComparison.Ordinal); + Assert.Single(handler.Requests); + } + + [Theory] + [InlineData("choice", "\"confidence\": 0.78, ", "", "confidence")] + [InlineData("unknown type", "\"type\": \"noul\", \"noul\": 0.97", "\"type\": \"rank\", \"noul\": 0.97", "could not be read")] + [InlineData("not json", "{", "", "could not be read")] + public async Task InvokeAsync_UnreadableResponse_FailsAsync(string scenario, string find, string replace, string expectedMessage) + { + // Arrange + using var handler = new JevTestHttpHandler().Reply(HttpStatusCode.OK, ReplaceFirst(JevTestData.ResponseJson, find, replace)); + using var httpClient = new HttpClient(handler); + + // Act + JsonException exception = await Assert.ThrowsAsync(() => + CreateBuilder(httpClient).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson)).AsTask()); + + // Assert + Assert.True(exception.Message.Contains(expectedMessage, StringComparison.Ordinal), $"{scenario}: {exception.Message}"); + } + + [Fact] + public async Task InvokeAsync_Canceled_StopsWithoutSendingAsync() + { + // Arrange + using var handler = new JevTestHttpHandler(); + using var httpClient = new HttpClient(handler); + using var cancellation = new CancellationTokenSource(); + cancellation.Cancel(); + + // Act & Assert + await Assert.ThrowsAnyAsync(() => + CreateBuilder(httpClient).Build().InvokeAsync(JevTestData.Arguments(JevTestData.RequestJson), cancellation.Token).AsTask()); + Assert.Empty(handler.Requests); + } + + private static JevAIToolBuilder CreateBuilder(HttpClient httpClient, JevAIToolOptions? options = null, List? waits = null) + { + options ??= new JevAIToolOptions(); + options.Transport = new HttpClientPipelineTransport(httpClient); + options.RetryPolicy = new JevRetryPolicy { RecordedWaitsForTests = waits ?? [] }; + return new JevAIToolBuilder(new ApiKeyCredential(ApiKey), options); + } + + private static string ReplaceFirst(string text, string find, string replace) + { + int index = text.IndexOf(find, StringComparison.Ordinal); + Assert.True(index >= 0, $"'{find}' is not in the test response."); + return string.Concat(text.AsSpan(0, index), replace, text.AsSpan(index + find.Length)); + } + + private sealed class HeaderPolicy(string name, string value) : PipelinePolicy + { + public override void Process(PipelineMessage message, IReadOnlyList pipeline, int currentIndex) + { + message.Request.Headers.Set(name, value); + ProcessNext(message, pipeline, currentIndex); + } + + public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList pipeline, int currentIndex) + { + message.Request.Headers.Set(name, value); + return ProcessNextAsync(message, pipeline, currentIndex); + } + } + + private sealed class NoWaitRetryPolicy(int maxRetries) : ClientRetryPolicy(maxRetries) + { + protected override Task WaitAsync(TimeSpan time, CancellationToken cancellationToken) => Task.CompletedTask; + + protected override void Wait(TimeSpan time, CancellationToken cancellationToken) + { + } + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevLoopJudgeTests.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevLoopJudgeTests.cs new file mode 100644 index 00000000000..32f494c2211 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevLoopJudgeTests.cs @@ -0,0 +1,79 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Net; +using System.Net.Http; +using System.Text.Json.Nodes; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; + +#pragma warning disable MAAI001 // LoopAgent and its evaluators are experimental. + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +/// +/// Tests Jev as the judge of a , as the loop judge sample does. +/// +public sealed class JevLoopJudgeTests +{ + private static readonly DecisionDefinition s_criteria = DecisionDefinition.Create(builder => + { + builder.BinaryProbability(verdict => verdict.BlueSky, "Does `answer` explain why the sky is blue?"); + builder.BinaryProbability(verdict => verdict.RedSunsets, "Does `answer` explain why sunsets are red?"); + }); + + [Fact] + public async Task RunAsync_DelegateEvaluatorWithJev_LoopsUntilEveryCriterionIsMetAsync() + { + // Arrange: the first answer misses the sunsets, the second covers both. + using var answerer = new ScriptedChatClient( + _ => new ChatResponse(new ChatMessage(ChatRole.Assistant, "Air scatters blue light.")), + _ => new ChatResponse(new ChatMessage(ChatRole.Assistant, "Air scatters blue light, and sunsets are red because light crosses more air."))); + using var handler = new JevTestHttpHandler() + .Reply(HttpStatusCode.OK, JevResultJson.Result(JevResultJson.Noul("blueSky", 0.98), JevResultJson.Noul("redSunsets", 0.03))) + .Reply(HttpStatusCode.OK, JevResultJson.Result(JevResultJson.Noul("blueSky", 0.97), JevResultJson.Noul("redSunsets", 0.95))); + using var httpClient = new HttpClient(handler); + using JevDecisionClient judge = JevDecisionClientTests.CreateClient(httpClient); + + var evaluator = new DelegateLoopEvaluator(async (context, cancellationToken) => + { + string request = string.Join("\n", context.InitialMessages.Select(message => message.Text)); + DecisionResponse decision = await judge.GetResponseAsync(new JudgedAnswer(request, context.LastResponse.Text), s_criteria, cancellationToken: cancellationToken); + List missing = []; + if (decision.Result.BlueSky <= 0.5) + { + missing.Add("blueSky"); + } + + if (decision.Result.RedSunsets <= 0.5) + { + missing.Add("redSunsets"); + } + + return missing.Count == 0 ? LoopEvaluation.Stop() : LoopEvaluation.Continue($"Missing: {string.Join(", ", missing)}."); + }); + var loop = new LoopAgent(answerer.AsAIAgent(), evaluator, new LoopAgentOptions { MaxIterations = 3, NonStreamingReturnsLastResponseOnly = true }); + + // Act + AgentResponse response = await loop.RunAsync("Explain why the sky is blue and why sunsets are red."); + + // Assert: two runs, and the second run received the missing criterion as feedback. + Assert.Equal(2, answerer.Calls.Count); + Assert.Contains(answerer.Calls[1], message => message.Role == ChatRole.User && message.Text == "Missing: redSunsets."); + Assert.Contains("sunsets are red", response.Text, StringComparison.Ordinal); + + // Assert: Jev judged the original request and the latest answer, with one Noul question per criterion. + Assert.Equal(2, handler.Requests.Count); + JsonNode first = JsonNode.Parse(handler.Requests[0].Body)!; + Assert.Equal(["blueSky", "redSunsets"], first["questions"]!.AsObject().Select(question => question.Key)); + Assert.All(first["questions"]!.AsObject(), question => Assert.Equal("noul", (string?)question.Value!["type"])); + Assert.Equal("Explain why the sky is blue and why sunsets are red.", (string?)first["state"]!["request"]); + Assert.Equal("Air scatters blue light.", (string?)first["state"]!["answer"]); + } +} + +public sealed record JudgedAnswer(string Request, string Answer); + +public sealed record LoopVerdict(double BlueSky, double RedSunsets); diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevResultJson.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevResultJson.cs new file mode 100644 index 00000000000..b83f93c972e --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevResultJson.cs @@ -0,0 +1,42 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Globalization; +using System.Linq; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +/// +/// Builds TypeSafe API responses as JSON, one answer at a time. +/// +internal static class JevResultJson +{ + public static string Result(params string[] answers) => + "{\"model\":\"jev-test\",\"answers\":{" + string.Join(",", answers) + "},\"usage\":{\"input_tokens\":10,\"output_tokens\":2}}"; + + public static string Choice(string id, string choice, params string[] labels) + { + string probabilities = string.Join(",", labels.Select(label => $"\"{label}\":{(label == choice ? "1.0" : "0.0")}")); + return $"\"{id}\":{{\"type\":\"choice\",\"choice\":\"{choice}\",\"confidence\":0.9,\"probabilities\":{{{probabilities}}}}}"; + } + + public static string Noul(string id, double noul) => + $"\"{id}\":{{\"type\":\"noul\",\"noul\":{noul.ToString(CultureInfo.InvariantCulture)}}}"; + + /// + /// A Score answer whose probabilities agree with the score, which is their expectation: a fractional score splits + /// the probability between the two levels around it. + /// + public static string Score(string id, double score, int levels) + { + string legend = string.Join(",", Enumerable.Range(0, levels).Select(level => $"\"{level}\":\"Level {level}\"")); + int lower = (int)Math.Floor(score); + double upperShare = score - lower; + string probabilities = string.Join(",", Enumerable.Range(0, levels).Select(level => + { + double probability = level == lower ? 1 - upperShare : level == lower + 1 ? upperShare : 0; + return $"\"{level}\":{probability.ToString(CultureInfo.InvariantCulture)}"; + })); + return $"\"{id}\":{{\"type\":\"score\",\"score\":{score.ToString(CultureInfo.InvariantCulture)},\"confidence\":0.8,\"legend\":{{{legend}}},\"probabilities\":{{{probabilities}}}}}"; + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevTestData.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevTestData.cs new file mode 100644 index 00000000000..e0c045c97e2 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevTestData.cs @@ -0,0 +1,105 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.Text.Json; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +/// +/// A support-ticket request and response taken from the TypeSafe quick start, used across the tests. +/// +internal static class JevTestData +{ + public const string TicketText = "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP."; + + /// The tool arguments a model would write for the ticket, with the three question kinds. + public const string RequestJson = """ + { + "state": "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.", + "questions": { + "department": { + "type": "choice", + "instructions": "Which team should handle this", + "criteria": { "billing": "Payment or subscription issues", "technical": "Bugs or integration problems", "sales": null } + }, + "frustration": { + "type": "score", + "instructions": "How frustrated the customer appears", + "criteria": ["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"] + }, + "is_urgent": { + "type": "noul", + "instructions": "The message conveys urgency or time-sensitivity", + "criteria": { "true": "Explicitly time-sensitive", "false": "No urgency expressed" } + } + } + } + """; + + /// The API response for . + public const string ResponseJson = """ + { + "model": "jev-1.13.0", + "answers": { + "department": { "type": "choice", "choice": "technical", "confidence": 0.78, "probabilities": { "technical": 0.85, "sales": 0.0, "billing": 0.15 } }, + "frustration": { + "type": "score", "score": 1.0, "confidence": 1.0, + "legend": { "0": "Calm, just stating facts", "1": "Frustrated but civil", "2": "Very angry, strong language" }, + "probabilities": { "0": 0.0, "1": 1.0, "2": 0.0 } + }, + "is_urgent": { "type": "noul", "noul": 0.97 } + }, + "usage": { "input_tokens": 392, "output_tokens": 65 } + } + """; + + /// Parses tool arguments the way chat clients do: one per top-level property. + public static AIFunctionArguments Arguments(string json) + { + var arguments = new AIFunctionArguments(); + using JsonDocument document = JsonDocument.Parse(json); + foreach (JsonProperty property in document.RootElement.EnumerateObject()) + { + arguments[property.Name] = property.Value.Clone(); + } + + return arguments; + } + + /// Parses tool arguments into the dictionary shape that carries. + public static Dictionary CallArguments(string json) + { + var arguments = new Dictionary(); + foreach (KeyValuePair argument in Arguments(json)) + { + arguments[argument.Key] = argument.Value; + } + + return arguments; + } + + /// A correct result for , built from the contract types. + public static JevResult CreateResult() => new() + { + Model = "custom-model", + Answers = new Dictionary + { + ["department"] = new JevChoiceResponse + { + Choice = "technical", + Confidence = 0.78, + Probabilities = new Dictionary { ["technical"] = 0.85, ["billing"] = 0.15, ["sales"] = 0 }, + }, + ["frustration"] = new JevScoreResponse + { + Score = 1, + Confidence = 1, + Legend = new Dictionary { ["0"] = "Calm", ["1"] = "Frustrated", ["2"] = "Very angry" }, + Probabilities = new Dictionary { ["0"] = 0, ["1"] = 1, ["2"] = 0 }, + }, + ["is_urgent"] = new JevNoulResponse { Noul = 0.97 }, + }, + Usage = new JevUsage { InputTokens = 10, OutputTokens = 5 }, + }; +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevTestHttpHandler.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevTestHttpHandler.cs new file mode 100644 index 00000000000..178285578f0 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/JevTestHttpHandler.cs @@ -0,0 +1,66 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Net; +using System.Net.Http; +using System.Net.Http.Headers; +using System.Text; +using System.Threading; +using System.Threading.Tasks; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +/// +/// A fake TypeSafe endpoint that records each request and replies with queued responses, repeating the last one. +/// +internal sealed class JevTestHttpHandler : HttpMessageHandler +{ + private readonly Queue<(HttpStatusCode Status, string Body, RetryConditionHeaderValue? RetryAfter, string? RetryAfterMs, string? RetryAfterRaw)> _responses = new(); + private (HttpStatusCode Status, string Body, RetryConditionHeaderValue? RetryAfter, string? RetryAfterMs, string? RetryAfterRaw) _last = (HttpStatusCode.OK, JevTestData.ResponseJson, null, null, null); + + public List Requests { get; } = []; + + public JevTestHttpHandler Reply(HttpStatusCode status, string body, RetryConditionHeaderValue? retryAfter = null, string? retryAfterMs = null, string? retryAfterRaw = null) + { + this._responses.Enqueue((status, body, retryAfter, retryAfterMs, retryAfterRaw)); + return this; + } + + protected override async Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken) + { + string body = await request.Content!.ReadAsStringAsync(cancellationToken); + var headers = new Dictionary(StringComparer.OrdinalIgnoreCase); + foreach (KeyValuePair> header in request.Headers) + { + headers[header.Key] = string.Join(",", header.Value); + } + + this.Requests.Add(new CapturedRequest(request.Method, request.RequestUri!, request.Headers.Authorization, body, headers)); + + if (this._responses.Count > 0) + { + this._last = this._responses.Dequeue(); + } + + var response = new HttpResponseMessage(this._last.Status) + { + Content = new StringContent(this._last.Body, Encoding.UTF8, "application/json"), + }; + response.Headers.RetryAfter = this._last.RetryAfter; + if (this._last.RetryAfterMs is { } retryAfterMs) + { + response.Headers.Add("retry-after-ms", retryAfterMs); + } + + // A raw value lets tests send Retry-After headers that HttpClient would refuse to parse. + if (this._last.RetryAfterRaw is { } raw) + { + response.Headers.TryAddWithoutValidation("Retry-After", raw); + } + + return response; + } + + public sealed record CapturedRequest(HttpMethod Method, Uri Uri, AuthenticationHeaderValue? Authorization, string Body, IReadOnlyDictionary Headers); +} diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/Microsoft.Agents.AI.TypeSafe.UnitTests.csproj b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/Microsoft.Agents.AI.TypeSafe.UnitTests.csproj new file mode 100644 index 00000000000..ee41effe009 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/Microsoft.Agents.AI.TypeSafe.UnitTests.csproj @@ -0,0 +1,18 @@ + + + + $(TargetFrameworksCore) + $(NoWarn);MEAI001 + + + + + + + + + + + + + diff --git a/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/ScriptedChatClient.cs b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/ScriptedChatClient.cs new file mode 100644 index 00000000000..e2b12db3bf7 --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.TypeSafe.UnitTests/ScriptedChatClient.cs @@ -0,0 +1,52 @@ +// Copyright (c) Microsoft. All rights reserved. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Runtime.CompilerServices; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.AI; + +namespace Microsoft.Agents.AI.TypeSafe.UnitTests; + +/// +/// A chat client that stands in for the agent's model: each call returns the next scripted response and records +/// the messages it received. +/// +internal sealed class ScriptedChatClient : IChatClient +{ + private readonly Queue, ChatResponse>> _script; + + public ScriptedChatClient(params Func, ChatResponse>[] script) + { + this._script = new Queue, ChatResponse>>(script); + } + + public List> Calls { get; } = []; + + public Task GetResponseAsync(IEnumerable messages, ChatOptions? options = null, CancellationToken cancellationToken = default) + { + List received = messages.ToList(); + this.Calls.Add(received); + return Task.FromResult(this._script.Dequeue()(received)); + } + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ChatResponse response = await this.GetResponseAsync(messages, options, cancellationToken); + foreach (ChatResponseUpdate update in response.ToChatResponseUpdates()) + { + yield return update; + } + } + + public object? GetService(Type serviceType, object? serviceKey = null) => null; + + public void Dispose() + { + } +}