feat: port OpenAI ChatKit Python SDK to C#/MAF

.github/dependabot.yml

@@ -5,6 +5,9 @@ updates:
     schedule:
       interval: "weekly"
       day: "wednesday"
+    ignore:
+      - dependency-name: "dotnet-sdk"
+        versions: [">=11.0.0-0"]
 
   - package-ecosystem: "nuget"
     directory: "/"

Directory.Packages.props

@@ -13,6 +13,8 @@
 
   <ItemGroup>
     <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="$(MicrosoftExtensionsAIAbstractionsVersion)" />
+    <PackageVersion Include="OpenAI" Version="$(OpenAIVersion)" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="$(MicrosoftExtensionsAIOpenAIVersion)" />
   </ItemGroup>
 
   <ItemGroup Label="Test">

Version.props

@@ -6,5 +6,7 @@
     <MicrosoftNETTestSdkVersion>18.3.0</MicrosoftNETTestSdkVersion>
     <RoslynVersion>5.3.0</RoslynVersion>
     <MicrosoftExtensionsAIAbstractionsVersion>10.4.1</MicrosoftExtensionsAIAbstractionsVersion>
+    <OpenAIVersion>2.9.1</OpenAIVersion>
+    <MicrosoftExtensionsAIOpenAIVersion>10.4.1</MicrosoftExtensionsAIOpenAIVersion>
   </PropertyGroup>
 </Project>

netagents.slnx

@@ -4,6 +4,7 @@
         <Project Path="src/Qyl.Agents.Abstractions/Qyl.Agents.Abstractions.csproj"/>
         <Project Path="src/Qyl.Agents.Generator/Qyl.Agents.Generator.csproj"/>
         <Project Path="src/Qyl.Agents/Qyl.Agents.csproj"/>
+        <Project Path="src/Qyl.ChatKit/Qyl.ChatKit.csproj"/>
     </Folder>
     <Folder Name="/tests/">
         <Project Path="tests/NetAgents.Tests/NetAgents.Tests.csproj"/>

src/Qyl.ChatKit/Actions.cs

@@ -0,0 +1,61 @@
+using System.Text.Json.Serialization;
+
+namespace Qyl.ChatKit;
+
+/// <summary>Whether the action is handled on the client or the server.</summary>
+[JsonConverter(typeof(JsonStringEnumConverter<Handler>))]
+public enum Handler
+{
+    [JsonStringEnumMemberName("client")]
+    Client,
+
+    [JsonStringEnumMemberName("server")]
+    Server
+}
+
+/// <summary>Visual loading behavior when the action executes.</summary>
+[JsonConverter(typeof(JsonStringEnumConverter<LoadingBehavior>))]
+public enum LoadingBehavior
+{
+    [JsonStringEnumMemberName("auto")]
+    Auto,
+
+    [JsonStringEnumMemberName("none")]
+    None,
+
+    [JsonStringEnumMemberName("self")]
+    Self,
+
+    [JsonStringEnumMemberName("container")]
+    Container
+}
+
+/// <summary>Fully resolved action configuration sent over the wire.</summary>
+public sealed record ActionConfig
+{
+    [JsonPropertyName("type")]
+    public required string Type { get; init; }
+
+    [JsonPropertyName("payload")]
+    public object? Payload { get; init; }
+
+    [JsonPropertyName("handler")]
+    public Handler Handler { get; init; } = Handler.Server;
+
+    [JsonPropertyName("loadingBehavior")]
+    public LoadingBehavior LoadingBehavior { get; init; } = LoadingBehavior.Auto;
+
+    [JsonPropertyName("streaming")]
+    public bool Streaming { get; init; } = true;
+}
+
+/// <summary>Generic action carrying a type discriminator and payload.</summary>
+public sealed record Action<TType, TPayload>
+    where TType : notnull
+{
+    [JsonPropertyName("type")]
+    public required TType Type { get; init; }
+
+    [JsonPropertyName("payload")]
+    public TPayload? Payload { get; init; }
+}

src/Qyl.ChatKit/AgentContext.cs

@@ -0,0 +1,178 @@
+using System.Threading.Channels;
+using Qyl.ChatKit.Widgets;
+
+namespace Qyl.ChatKit;
+
+/// <summary>
+/// Context object passed to agent callbacks, providing access to the store,
+/// thread metadata, and a channel for emitting events back to the stream processor.
+/// </summary>
+public sealed class AgentContext<TContext>
+{
+    public required ThreadMetadata Thread { get; init; }
+    public required IStore<TContext> Store { get; init; }
+    public required TContext RequestContext { get; init; }
+    public TimeProvider TimeProvider { get; init; } = TimeProvider.System;
+
+    public string? PreviousResponseId { get; set; }
+    public ClientToolCall? ClientToolCall { get; set; }
+    public WorkflowItem? WorkflowItem { get; set; }
+    public GeneratedImageItem? GeneratedImageItem { get; set; }
+
+    private readonly Channel<ThreadStreamEvent> _events = Channel.CreateUnbounded<ThreadStreamEvent>();
+
+    /// <summary>Reader for the event channel, consumed by the stream processor.</summary>
+    internal ChannelReader<ThreadStreamEvent> EventReader => _events.Reader;
+
+    /// <summary>Signal that no more events will be written.</summary>
+    internal void Complete() => _events.Writer.TryComplete();
+
+    /// <summary>Generate a new store-backed id for the given item type.</summary>
+    public string GenerateId(StoreItemType type, ThreadMetadata? thread = null) =>
+        type == StoreItemType.Thread
+            ? Store.GenerateThreadId(RequestContext)
+            : Store.GenerateItemId(type, thread ?? Thread, RequestContext);
+
+    /// <summary>Stream a widget into the thread by enqueueing widget events.</summary>
+    public async ValueTask StreamWidgetAsync(
+        WidgetRoot widget, string? copyText = null, CancellationToken ct = default)
+    {
+        await foreach (var evt in WidgetDiff.StreamWidgetAsync(
+            Thread, widget, copyText,
+            t => Store.GenerateItemId(t, Thread, RequestContext),
+            TimeProvider, ct))
+        {
+            await _events.Writer.WriteAsync(evt, ct);
+        }
+    }
+
+    /// <summary>Stream an async sequence of widget roots into the thread.</summary>
+    public async ValueTask StreamWidgetAsync(
+        IAsyncEnumerable<WidgetRoot> widgetStream, string? copyText = null,
+        CancellationToken ct = default)
+    {
+        await foreach (var evt in WidgetDiff.StreamWidgetAsync(
+            Thread, widgetStream, copyText,
+            t => Store.GenerateItemId(t, Thread, RequestContext),
+            TimeProvider, ct))
+        {
+            await _events.Writer.WriteAsync(evt, ct);
+        }
+    }
+
+    /// <summary>Begin streaming a new workflow item.</summary>
+    public async ValueTask StartWorkflowAsync(Workflow workflow, CancellationToken ct = default)
+    {
+        WorkflowItem = new WorkflowItem
+        {
+            Id = GenerateId(StoreItemType.Workflow),
+            CreatedAt = TimeProvider.GetUtcNow().UtcDateTime,
+            Workflow = workflow,
+            ThreadId = Thread.Id,
+        };
+
+        if (workflow.Type != "reasoning" && workflow.Tasks.Count == 0)
+            return; // Defer sending added event until we have tasks
+
+        await StreamAsync(new ThreadItemAddedEvent { Item = WorkflowItem }, ct);
+    }
+
+    /// <summary>Append a workflow task and stream the appropriate event.</summary>
+    public async ValueTask AddWorkflowTaskAsync(ChatKitTask task, CancellationToken ct = default)
+    {
+        WorkflowItem ??= new WorkflowItem
+        {
+            Id = GenerateId(StoreItemType.Workflow),
+            CreatedAt = TimeProvider.GetUtcNow().UtcDateTime,
+            Workflow = new Workflow { Type = "custom", Tasks = [] },
+            ThreadId = Thread.Id,
+        };
+
+        var tasks = WorkflowItem.Workflow.Tasks.ToList();
+        tasks.Add(task);
+        WorkflowItem = WorkflowItem with
+        {
+            Workflow = WorkflowItem.Workflow with { Tasks = tasks },
+        };
+
+        if (WorkflowItem.Workflow.Type != "reasoning" && tasks.Count == 1)
+        {
+            await StreamAsync(new ThreadItemAddedEvent { Item = WorkflowItem }, ct);
+        }
+        else
+        {
+            await StreamAsync(new ThreadItemUpdatedEvent
+            {
+                ItemId = WorkflowItem.Id,
+                Update = new WorkflowTaskAdded
+                {
+                    Task = task,
+                    TaskIndex = tasks.Count - 1,
+                },
+            }, ct);
+        }
+    }
+
+    /// <summary>Update an existing workflow task and stream the delta.</summary>
+    public async ValueTask UpdateWorkflowTaskAsync(
+        ChatKitTask task, int taskIndex, CancellationToken ct = default)
+    {
+        if (WorkflowItem is null)
+            throw new InvalidOperationException("Workflow is not set");
+
+        var tasks = WorkflowItem.Workflow.Tasks.ToList();
+        tasks[taskIndex] = task;
+        WorkflowItem = WorkflowItem with
+        {
+            Workflow = WorkflowItem.Workflow with { Tasks = tasks },
+        };
+
+        await StreamAsync(new ThreadItemUpdatedEvent
+        {
+            ItemId = WorkflowItem.Id,
+            Update = new WorkflowTaskUpdated
+            {
+                Task = task,
+                TaskIndex = taskIndex,
+            },
+        }, ct);
+    }
+
+    /// <summary>Finalize the active workflow item, optionally attaching a summary.</summary>
+    public async ValueTask EndWorkflowAsync(
+        WorkflowSummary? summary = null, bool expanded = false, CancellationToken ct = default)
+    {
+        if (WorkflowItem is null)
+            return;
+
+        var finalSummary = summary ?? WorkflowItem.Workflow.Summary;
+        if (finalSummary is null)
+        {
+            var delta = TimeProvider.GetUtcNow().UtcDateTime - WorkflowItem.CreatedAt;
+            finalSummary = new DurationSummary { Duration = (int)delta.TotalSeconds };
+        }
+
+        WorkflowItem = WorkflowItem with
+        {
+            Workflow = WorkflowItem.Workflow with
+            {
+                Summary = finalSummary,
+                Expanded = expanded,
+            },
+        };
+
+        await StreamAsync(new ThreadItemDoneEvent { Item = WorkflowItem }, ct);
+        WorkflowItem = null;
+    }
+
+    /// <summary>Enqueue a ThreadStreamEvent for downstream processing.</summary>
+    public async ValueTask StreamAsync(ThreadStreamEvent evt, CancellationToken ct = default) =>
+        await _events.Writer.WriteAsync(evt, ct);
+}
+
+/// <summary>Returned from tool methods to indicate a client-side tool call.</summary>
+public sealed record ClientToolCall
+{
+    public required string Name { get; init; }
+    public required Dictionary<string, object?> Arguments { get; init; }
+}

src/Qyl.ChatKit/Attachments.cs

@@ -0,0 +1,101 @@
+using System.Text.Json.Serialization;
+
+namespace Qyl.ChatKit;
+
+/// <summary>Base metadata shared by all attachments.</summary>
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")]
+[JsonDerivedType(typeof(FileAttachment), "file")]
+[JsonDerivedType(typeof(ImageAttachment), "image")]
+public abstract record AttachmentBase
+{
+    [JsonPropertyName("id")]
+    public required string Id { get; init; }
+
+    [JsonPropertyName("name")]
+    public required string Name { get; init; }
+
+    [JsonPropertyName("mime_type")]
+    public required string MimeType { get; init; }
+
+    /// <summary>
+    /// Two-phase upload instructions.
+    /// Should be set to null after upload is complete or when using direct upload.
+    /// </summary>
+    [JsonPropertyName("upload_descriptor")]
+    public AttachmentUploadDescriptor? UploadDescriptor { get; init; }
+
+    /// <summary>
+    /// The thread the attachment belongs to, if any.
+    /// Added when the user message that contains the attachment is saved to store.
+    /// </summary>
+    [JsonPropertyName("thread_id")]
+    public string? ThreadId { get; init; }
+
+    /// <summary>
+    /// Integration-only metadata stored with the attachment.
+    /// Ignored by ChatKit and not returned in server responses.
+    /// </summary>
+    [JsonPropertyName("metadata")]
+    public Dictionary<string, object?>? Metadata { get; init; }
+}
+
+/// <summary>Attachment representing a generic file.</summary>
+public sealed record FileAttachment : AttachmentBase;
+
+/// <summary>Attachment representing an image resource.</summary>
+public sealed record ImageAttachment : AttachmentBase
+{
+    [JsonPropertyName("preview_url")]
+    public required Uri PreviewUrl { get; init; }
+}
+
+/// <summary>Two-phase upload instructions.</summary>
+public sealed record AttachmentUploadDescriptor
+{
+    [JsonPropertyName("url")]
+    public required Uri Url { get; init; }
+
+    /// <summary>The HTTP method to use when uploading the file for two-phase upload.</summary>
+    [JsonPropertyName("method")]
+    public required string Method { get; init; }
+
+    /// <summary>Optional headers to include in the upload request.</summary>
+    [JsonPropertyName("headers")]
+    public Dictionary<string, string> Headers { get; init; } = new();
+}
+
+/// <summary>Metadata needed to initialize an attachment.</summary>
+public sealed record AttachmentCreateParams
+{
+    [JsonPropertyName("name")]
+    public required string Name { get; init; }
+
+    [JsonPropertyName("size")]
+    public required int Size { get; init; }
+
+    [JsonPropertyName("mime_type")]
+    public required string MimeType { get; init; }
+}
+
+/// <summary>Audio input data for transcription.</summary>
+public sealed record AudioInput
+{
+    /// <summary>Audio data bytes.</summary>
+    [JsonPropertyName("data")]
+    public required byte[] Data { get; init; }
+
+    /// <summary>Raw MIME type for the audio payload, e.g. "audio/webm;codecs=opus".</summary>
+    [JsonPropertyName("mime_type")]
+    public required string MimeType { get; init; }
+
+    /// <summary>Media type for the audio payload, e.g. "audio/webm".</summary>
+    [JsonIgnore]
+    public string MediaType => MimeType.Split(';', 2)[0];
+}
+
+/// <summary>Input speech transcription result.</summary>
+public sealed record TranscriptionResult
+{
+    [JsonPropertyName("text")]
+    public required string Text { get; init; }
+}

src/Qyl.ChatKit/ChatKitJsonOptions.cs

@@ -0,0 +1,14 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Qyl.ChatKit;
+
+/// <summary>Shared JSON serializer options for the ChatKit wire protocol.</summary>
+internal static class ChatKitJsonOptions
+{
+    public static JsonSerializerOptions Default { get; } = new()
+    {
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+        PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
+    };
+}