[FEATURE REQ] Consider allowing instantiation of the types NOT via Json only.

[DeagleGross]

Describe the feature or improvement you are requesting

Hey, thanks for building this OpenAI SDK.

I am working on integration OpenAI Responses into the agent framework, and I've faced many problems operating with the OpenAI SDK types because:

1. most of the types can be constructed only via the JSON
2. some of the type properties are internal
3. some of the types! are internal

My scenario is that I have an "abstract AIAgent", which can respond with OpenAI Responses, but also can respond with for example OpenAI ChatCompletions or MCP or . Its undetermenistic. Moreover, we have our own subset of types to represent the response in a generic way - for example AIContent.

1. The biggest frustration is that I am not able to implement streaming of the response via OpenAI SDK types, because I can not instantiate the types needed (e.g. StreamingResponseCreatedUpdate and others). I had to define my own types to stream the response for that.

2. Moreover, ResponseCreationOptions has internal fields / properties, which ARE parsed. I would like to use this type in my endpoint handler input, but I cant, and I have to write manual deserialization logic + access e.g. Stream property via reflection code. That complicates the code incredibly.

3. Some of the types are simply internal, and without building up tons of reflection code I dont see a clear way to use them.

I really like that there is an SDK carefully defining the types per spec, but these design decisions heavily restrict SDK manipulation. I would like to suggest opening up constructors and avoid internal members. That would definitley allow easier integration. I've seen other issues (e.g. #306) asking for similar thing.

Additional context

No response

[jsquire]

Hi @DeagleGross. Thanks for reaching out and for your inquiry. As the discussion in #306 indicates, the scenario that you're describing falls outside of the mainline scenarios that the OpenAI types are intended to support, and the recommended path would be to use the protocol overloads.

This area falls under the governance of @KrzysztofCwalina and @christothes, so I'll ask that they share their thoughts.

[KrzysztofCwalina]

@DeagleGross, you can use "ModelFactory" types (one per namespace) instead of ctors.
As to internal properties, @christothes's protocol models should help with this.

[DeagleGross]

@KrzysztofCwalina thanks for reply! What will be the "ModelFactory" to create StreamingResponseCreatedUpdate for instance? I would appreciate a specific example. Also it feels ModelFactory instantiation is a bit "undiscoverable", since one has to find a factory and create via it. If there is a way to construct an object via factory, what is really stopping from exposing constructors?

Also dont understand what "protocol models" mean here, sorry!

[KrzysztofCwalina]

@DeagleGross, I meant the OpenAIResponsesModelFactory type. Unfortunately, I noticed the factory does not have a factory method to create some of the recently added types, including StreamingResponseCreatedUpdate. I filed an issue to fix that: #746

The model factory APIs are not discoverable on purpose. Constructing these types is not a mainline scenario. The mainline scenario is to use the OpenAI SDK to call OpenAI services and so many model types don't need ctors as they are what we call output types. Having some members (ctors, property setters) hidden/internal simplifies the surface area for mainline scenarios.

[DeagleGross]

Thanks for reply!

Unfortunately, I noticed the factory does not have a factory method to create some of the recently added types, including StreamingResponseCreatedUpdate

I am pretty sure this will be an ongoing and constant effort to make a factory method per every type, which is very hard to ever achieve. And it heavily complicates development - you would need to not only change a constructor, but also a factory method, and test both at least.

Constructing these types is not a mainline scenario.

I understand that the main idea is client-side JSON compatibility and making library useful for this scenario (which is does well, and thanks for that); but I personally dont see any problem with opening up the same types that you have defined already for your own inner purposes. Like what really bad would happen if I could be able to construct some of the types and set "Id" of the ResponseItem? For example that is not possible today, and I am having to do the following: reflection access.

Just to note: I am not trying to offend / say that this is a bad library etc. Just trying to understand the design decisions, and whether this will change in future; because if not, then it can become a heavy blocker for some of scenarios me and other devs are trying to implement; meaning we would need to write our own type definitions or rely on reflection to access some of hidden members in this library - basically we will need to decide how to move forward.