Migrate C# library and samples from Betalgo.Ranul.OpenAI to official OpenAI NuGet package

[scottaddie]

Summary

The C# library and several samples currently depend on Betalgo.Ranul.OpenAI, a community-maintained OpenAI client library. We should migrate to the official OpenAI NuGet package, which is maintained by OpenAI in collaboration with Microsoft and generated from the OpenAI OpenAPI
specification.

Motivation

• Official support: The OpenAI package is maintained by OpenAI and Microsoft, ensuring long-term support, timely updates, and alignment with the OpenAI API.
• API parity: Generated from the OpenAPI spec, the official package guarantees accurate coverage of the OpenAI REST API surface.
• Ecosystem alignment: As a Microsoft project, Foundry Local should align with the official Microsoft-collaborated library rather than a community alternative.
• Partial migration already exists: Two samples (foundry-local-web-server and tool-calling-foundry-local-web-server) already use the official OpenAI package (v2.5.0), demonstrating feasibility.

Scope

Library (core dependency)

• sdk/cs/src/Microsoft.AI.Foundry.Local.csproj — references Betalgo.Ranul.OpenAI v9.1.0
• Source files with Betalgo using statements:
  • sdk/cs/src/OpenAI/ChatClient.cs
  • sdk/cs/src/OpenAI/AudioClient.cs
  • sdk/cs/src/OpenAI/ChatCompletionRequestResponseTypes.cs
  • sdk/cs/src/OpenAI/AudioTranscriptionRequestResponseTypes.cs
  • sdk/cs/src/OpenAI/LiveAudioTranscriptionTypes.cs
  • sdk/cs/src/OpenAI/ToolCallingExtensions.cs
  • sdk/cs/src/Detail/JsonSerializationContext.cs

Tests

• sdk/cs/test/FoundryLocal.Tests/ChatCompletionsTests.cs

Samples (4 projects via Central Package Management)

• samples/cs/tutorial-chat-assistant
• samples/cs/tutorial-tool-calling
• samples/cs/tutorial-voice-to-text
• samples/cs/tutorial-document-summarizer

Samples (direct Betalgo usage in code)

• samples/cs/native-chat-completions
• samples/cs/model-management-example
• samples/cs/tool-calling-foundry-local-sdk

Configuration files

• samples/cs/Directory.Packages.props — central version Betalgo.Ranul.OpenAI v9.2.0

Documentation

• sdk/cs/README.md
• sdk/cs/docs/api/microsoft.ai.foundry.local.openaiaudioclient.md
• sdk/cs/docs/api/microsoft.ai.foundry.local.openaichatclient.md

Considerations

• Breaking change for library consumers: This is a public API change since the library exposes Betalgo types (e.g., ChatCompletionCreateRequest, ChatCompletionCreateResponse). Consumers using
  these types directly will need to update their code.
• Type mapping: The two libraries have different type hierarchies and namespaces. A mapping guide for commonly used types would be helpful.
• Realtime API: The library uses Betalgo's RealtimeModels for live audio transcription (LiveAudioTranscriptionTypes.cs). Verify the official package has equivalent Realtime API support.
• Version alignment: The samples already on the official package use v2.5.0. The library should target a stable version.

[baijumeswani]

While we've explored transitioning to the official openai and azure-openai packages in response to recent requests, we've identified some technical blockers that currently prevent us from moving forward.

Foundry Local exposes the same C# SDK surface over two completely different transports:

1. Native FFI path (in-process) - default
   • The C# SDK loads the native Foundry Local Core and marshals JSON over a custom native ABI

    - User C# code
       → constructs DTOs (ChatMessage, ChatCompletionCreateRequest…)
       → SDK serializes to JSON (System.Text.Json)
       → FFI call into native core (Marshal.AllocHGlobal buffers)
       → native returns JSON bytes
       → SDK deserializes back into DTOs
       → user reads DTOs
   

2. Web-server path (HTTP/OpenAI-compatible) - opt-in
   • FoundryLocalManager.StartWebServiceAsync() spins the native core up as an HTTP server exposing OpenAI-spec endpoints:

    POST /v1/chat/completions (streaming + non-streaming; tool calls)
    POST /v1/responses (+ /v1/responses/{id}, /cancel, /input_items)
    POST /v1/audio/transcriptions
   
   

The two transports impose fundamentally different requirements:

Requirements for native FFI path:

1. Request types constructable with public ctors/setters
2. Response types constructable / mutable
3. Standard System.Text.Json attributes ([JsonPropertyName], etc.)
4. AOT- and trim-safe
5. Inheritable / extensible
6. Nice to have but not necessary:
   • Small binary footprint
   • No HTTP/transport baggage

Requirements for web-server path:

1. Speaks OpenAI /v1/* REST + SSE
2. Response types don't need to be constructable by the caller
3. Extensibility via additionalBinaryDataProperties or raw JSON pass-through

Summary:

Requirement	Betalgo (current)	Official OpenAI	Azure.AI.OpenAI
Response types constructable	✅	❌	❌
STJ JsonSerializer compatible	✅	❌	❌
[JsonSerializable] source-gen (AOT)	✅	❌	❌
Inheritable/extensible types	✅	❌	❌
AOT/Trimming compatible	✅	❌	❌
Binary size optimized	⚠️ 2.3 MB	⚠️ 2.9 MB	⚠️ 3.8 MB
No HTTP client baggage	✅	⚠️ brings System.ClientModel	❌ brings Azure.Core
Official support	❌	✅	✅

For Foundry Local's SDK's FFI scenario, the official OpenAI package cannot be used.
For Foundry Local's SDK's web-server scenario, the official OpenAI can be used (and is being used as illustrated in some of the examples.

Another option is to define custom types that combine the best features of both. While this offers the most flexibility, it does come with a significant maintenance burden.

Let us know if you have any thoughts or suggestions.

[scottaddie]

@baijumeswani A couple of things regarding the official OpenAI package:

• AOT/trimming support is there as of the 2.2.0 release. See the CHANGELOG entry at https://github.com/openai/openai-dotnet/blob/main/CHANGELOG.md#other-changes-5. Are you seeing specific issues in this area?
• The binary size is expected to decrease over time. There's already work in flight to move Responses API surface area at Factor Responses into a separate package openai/openai-dotnet#1039. It's possible this extraction will be done for other OpenAI APIs too. What is an acceptable binary size for you?

[samuel100]

@scottaddie are the

Request types constructable with public ctors/setters
Response types constructable / mutable

? When we looked these were private implementation details.

[jsquire]

@samuel100 : For the higher-level convenience surface, Input types are always creatable, output types are indirectly creatable via factory or ModelReaderWriter, as they're expected to be returned by the service. The latest releases added a mid-level surface, exposing protocol-focused models with full mutability.

Many of these changes were driven by collaboration with the Agent Server team whose needs are aligned with your own. To our knowledge there are no scenarios with gaps for what you would need, and there are approachable work -around should any be found. We're happy to provide pattern guidance for use.

[jsquire]

@baijumeswani: That graph above is quite outdated and inaccurate.