Structured Outputs: Reliable JSON from LLMs in C#

using Microsoft.Extensions.AI;

public sealed class FakeChatClient(params string[] replies) : IChatClient
{
    private readonly Queue<string> _replies = new(replies);

    public List<ChatOptions?> Calls { get; } = [];

    public Task<ChatResponse> GetResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        Calls.Add(options);
        var reply = new ChatMessage(ChatRole.Assistant, _replies.Dequeue());
        return Task.FromResult(new ChatResponse(reply) { FinishReason = ChatFinishReason.Stop });
    }

    public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        CancellationToken cancellationToken = default) => throw new NotSupportedException();

    public object? GetService(Type serviceType, object? serviceKey = null) => null;

    public void Dispose() { }
}

using System.Text.Json.Nodes;
using Microsoft.Extensions.AI;
using Xunit;

public class TriageTests
{
    [Fact]
    public async Task Repairs_an_out_of_range_confidence_once()
    {
        var invalid = """
            {"rationale": "Charged twice.", "category": "Billing", "priority": "High",
             "productArea": null, "confidence": 7}
            """;
        var valid = """
            {"rationale": "Charged twice.", "category": "Billing", "priority": "High",
             "productArea": null, "confidence": 0.9}
            """;
        var client = new FakeChatClient(invalid, valid);

        var triage = await client.GetValidatedAsync<TicketTriage>(
            [new ChatMessage(ChatRole.User, "I was charged twice this month.")], maxAttempts: 2);

        Assert.Equal(TicketCategory.Billing, triage.Category);
        Assert.Equal(2, client.Calls.Count);
    }

    [Fact]
    public async Task Enum_replies_are_unwrapped_from_the_data_property()
    {
        var client = new FakeChatClient("""{"data":"Negative"}""");

        var response = await client.GetResponseAsync<Sentiment>("Worst support call ever.");

        Assert.Equal(Sentiment.Negative, response.Result);
    }

    [Fact]
    public void Triage_schema_matches_the_approved_contract()
    {
        var format = ChatResponseFormat.ForJsonSchema<TicketTriage>();
        var actual = JsonNode.Parse(format.Schema!.Value.GetRawText());
        var approved = JsonNode.Parse(File.ReadAllText("Schemas/ticket-triage.json"));

        Assert.True(JsonNode.DeepEquals(approved, actual),
            "Schema changed; review and re-approve it.");
    }
}