Repository navigation
Add experimental provider-neutral decision abstractions (Layer 1) - #7795
luisquintanilla wants to merge 11 commits into
Conversation
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
JSON deserialization and validation of rounded probabilities need correction before approval.
Review effort: Balanced
Findings: 1
Open (5)
JSON constructors use mismatched additionalProperties types · New Null distribution entries cause NullReferenceException · New Distribution validation rejects valid rounded probabilities · New Rounded scores bypass score consistency validation · New Register DecisionClientMetadata in generated JSON roots · New
What changed in this PR
This PR adds experimental, provider-neutral decision contracts to Microsoft.Extensions.AI.Abstractions without changing the existing chat-routing API.
Changes:
- Adds binary, choice, and ordinal-score requests and responses, plus a non-generic decision client.
- Adds explicit typed binding and versioned, named feature projection.
- Registers JSON contracts, records the public API, and adds tests.
| File | Description |
|---|---|
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/TestJsonSerializerContext.cs |
Registers decision types for test serialization. |
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Decisions/DecisionTests.cs |
Tests binding, projection, cancellation, and snapshots. |
src/Shared/DiagnosticIds/DiagnosticIds.cs |
Adds the experimental diagnostic alias. |
src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Defaults.cs |
Registers decision JSON contracts. |
src/Libraries/Microsoft.Extensions.AI.Abstractions/Microsoft.Extensions.AI.Abstractions.json |
Records the new public APIs. |
src/Libraries/Microsoft.Extensions.AI.Abstractions/Decisions/README.md |
Describes the layer’s scope and ownership rules. |
src/Libraries/Microsoft.Extensions.AI.Abstractions/Decisions/DecisionQuestions.cs |
Defines questions, candidates, and requests. |
src/Libraries/Microsoft.Extensions.AI.Abstractions/Decisions/DecisionFeatures.cs |
Defines schemas and feature projection. |
src/Libraries/Microsoft.Extensions.AI.Abstractions/Decisions/DecisionClient.cs |
Defines the client, options, and responses. |
src/Libraries/Microsoft.Extensions.AI.Abstractions/Decisions/DecisionBinding.cs |
Defines enum mapping and typed binding. |
src/Libraries/Microsoft.Extensions.AI.Abstractions/Decisions/DecisionAnswers.cs |
Defines probability and score answers. |
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
🎉 Good job! The coverage increased 🎉
Full code coverage report: https://dev.azure.com/dnceng-public/public/_build/results?buildId=1618628&view=codecoverage-tab |
🎉 Good job! The coverage increased 🎉
Full code coverage report: https://dev.azure.com/dnceng-public/public/_build/results?buildId=1618858&view=codecoverage-tab |
🎉 Good job! The coverage increased 🎉
Full code coverage report: https://dev.azure.com/dnceng-public/public/_build/results?buildId=1619606&view=codecoverage-tab |
🎉 Good job! The coverage increased 🎉
Full code coverage report: https://dev.azure.com/dnceng-public/public/_build/results?buildId=1619765&view=codecoverage-tab |
🎉 Good job! The coverage increased 🎉
Full code coverage report: https://dev.azure.com/dnceng-public/public/_build/results?buildId=1620045&view=codecoverage-tab |
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Unresolved validation and serializer-compatibility defects prevent reliable use of the new contracts.
Review effort: Balanced
Findings: 1
Open (5)
JSON constructors use mismatched additionalProperties types Validate scores against feasible normalized distribution expectations · New Populate missing TypeInfoResolver before freezing custom options · New Compare materialized values instead of reserialized JSON tokens · New Fix correlation fixtures to use scores matching their distributions · New
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b735e048-cd3e-4bfb-ad05-3f68ad46082e
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b735e048-cd3e-4bfb-ad05-3f68ad46082e
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b735e048-cd3e-4bfb-ad05-3f68ad46082e
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b735e048-cd3e-4bfb-ad05-3f68ad46082e
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b735e048-cd3e-4bfb-ad05-3f68ad46082e
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b735e048-cd3e-4bfb-ad05-3f68ad46082e
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b735e048-cd3e-4bfb-ad05-3f68ad46082e
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b735e048-cd3e-4bfb-ad05-3f68ad46082e
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eb4b11ad-53ed-4f67-8760-60c0e53c4083
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eb4b11ad-53ed-4f67-8760-60c0e53c4083
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eb4b11ad-53ed-4f67-8760-60c0e53c4083
fe3bce1 to
02e54f0
Compare
|
can[t wait to see it and use wiht MS Dessign model |


Background and motivation
Applications sometimes need to ask several business questions about the same input and retain the probability evidence behind the answers. For a customer-support ticket, that might mean selecting a category, estimating whether a refund is being requested, and assessing urgency against an ordered rubric.
MEAI already supports typed chat output and tool calling. This proposal adds a distinct provider-neutral capability for Binary, Choice, and Score observations, including complete distributions. It does not treat ordinary structured chat output as a source of model probabilities.
Layer 1 provides a non-generic provider contract and an optional typed application-facing convenience API. Related proposal: #7764. Function and routing composition follow in #7796. Native stack #7797 is ordered #7795 -> #7796.
Review scope: this PR contains the foundation contracts, typed binding, and optional named feature projection, not provider implementations or a function/routing framework. Its current source is
02e54f023bdf3c8c2729353b110c22f5f8593957. The thinDecisionDefinition<TResult>.AsAIFunction<TState>convenience member belongs to the upper PR, not this foundation slice.API Proposal
All additions are experimental (
MEAI001). Experimental annotations are omitted from the selected signatures below for readability.Provider contract and typed application API
Providers return the neutral response. Applications can use the typed overloads to materialize an ordinary result while keeping the original response in
.Evidence. Materialization and distribution access do not make another inference call.Choicedeclares an enum-backed domain.BinaryProbabilitymaps a Binary observation's true probability to adouble; it is not an ordinal Score.Scorerequires an explicit ordered rubric and represents only a provider-reported native scalar.ExpectedScoreuses the unmodified complete observed distribution and may fall outside the ordinal bounds after probability rounding; it is not normalized or clamped. A definition can contain multiple questions of each supported kind.Supporting request and observation signatures
The selected signatures below show the lower-level shape. The complete API additions and implementation also include constructors, precision/provenance, request options, failure types, explicit result bindings, and optional named feature projection.
API Usage
A retailer wants to categorize a support ticket and estimate whether the customer is requesting a refund. The host supplies an
IDecisionClient client; no default backend or chat-to-decision conversion is inferred.The application owns these ordinary business types. Standard descriptions provide question instructions and separate candidate criteria; no custom attributes or
property:target are required here.When needed, the application can inspect the full typed category distribution separately:
There is no mandatory result mapper, handwritten question ID, enum dictionary, or feature schema in this flow. Fluent instructions can override attribute defaults. The result is an annotation, not an automatic refund authorization.
Applications that want observations without a business result can call the neutral client directly. Typed state/result metadata overloads support an explicit source-generated JSON boundary. Deployment examples and optional feature export remain in the source-pinned README.
Alternative Designs
Current implementation evidence
The current stack source is foundation
02e54f023bdf3c8c2729353b110c22f5f8593957plus uppere87f1126cf22108fb27f6391c7826fb91c25138e. The external native-provider proof is independently pinned toce28e92b338b0edfbc22cca3c62101fa75c008f7.net10.0,net9.0,net8.0,net462, andnetstandard2.0. The public API baseline was inspected/parsed. This is not a new unfiltered foundation-assembly run.Microsoft.Extensions.AI.Abstractions/10.10.4-nativeinterop, built from exact upper sourcee87f1126cf22108fb27f6391c7826fb91c25138e, whose foundation ancestor is the lower source above. Full five-target Debug build: zero warnings/errors. Archive SHA256:872468F5D0DB6E6D8980459F8C173DBEBBDDDD39425062505D7537D71A522E0F.IDecisionCliententrypoints. Main constructors/loaders require no public generator plus adapter. Existing codecs/transports/stages and deliberate legacy compatibility remain. These implementations are external and not shipped by this PR.4AFFD1ACF34DA6C24347988744F18DB54562AC3EB7A79C07FA2E895DFAC38434). All 24 restored asset graphs select the private package; 10 current Debug output copies match that DLL. All 12 exact file-app--helppaths compiled and exited successfully; native/live hosts compiled only.require/trusted-signers policy and CI workflow remain unchanged. Fresh closure checked 99 signed external archives across 24 projects; an unsigned non-upstream archive was rejected withNU3004. Existing external lock versions/hashes were preserved. Provider proof publication used[skip ci]; no hosted run was triggered.The immutable validation guide and requirement/command/quality map are in a private repository and require authorized access. They are reported external implementation evidence; the source and regression tests in this public stack are directly reviewable. No private source/receipts are published here and no visibility or public NuGet-release availability change is implied.
Execution boundary: the new provider proof is strictly managed-only. Local Julia/Laya/Qwen tests use bounded internal execution/tokenizer seams with actual orchestration/preparation/decode; they do not establish production tokenizer/model equivalence or successful native loading. The 188 native/FFI/ORT/loading core cases were retained but excluded from the positive managed selection, and the live project was not executed. They are not new skips or passes.
Historical evidence - earlier source/package revisions, not current executions
fe3bce1a1c9f386661f1fc0a49e9ebe4d7ea46f5added rounded reported-score feasibility, existing MEAI missing-resolver fallback, materialized CLR-value checks independent of write-only JSON formatting, and self-validating correlation fixtures. These changes were preserved by the normal rebase to the current foundation source; no new foundation runtime change was made for the native-client migration.4aaae08abd86f21221fbcb2d715976cdd24d7b53, based onfe3bce1a1c9f386661f1fc0a49e9ebe4d7ea46f5, passed 1,703 affected-assembly cases with zero failures and one pre-existing skip per target. Its private10.10.3-providerproofarchive SHA256 isE5EDA04732E7A72FE0F9A6E34CB939A8E8D13A907498E7EBE85D4E17AAADBCBE; that archive and its receipts remain unchanged.94be097/f32125f/832a3f8, the 2,112-test integration baseline, and trimmed-consumer results remain historical. ApiChief's internal breaking-check exception and NuGet vulnerability-endpoint TLS limitations remain limitations, not passed compatibility/security certifications.Risks and review questions
Review should focus on the neutral provider/typed-consumer split, explicit Binary/Choice/Score registrations, ordinal rubric and nullable-native-score semantics, strict CLR/correlation boundaries, and whether the optional binding/feature surface belongs in the initial foundation.
Microsoft Reviewers: Open in CodeFlow