Use pydantic models for requests instead of TypedDict

[Vegoo89]

Confirm this is a feature request for the Python library and not the underlying OpenAI API.

• This is a feature request for the Python library

Describe the feature or improvement you're requesting

Hello,
I have been using library for some time now and lately started to update from 0.x to newest (1.7.x)
From the start we are using pydantic models for requests and responses handling, mostly due to being very type-safe but also because it works nicely with FastApi.

Let's take chat completion as example.
Right now you are creating different dictionary type for every role, then you have one common return type which is Union of these possible values.
Couldn't it be replaced by one pydantic model?

I am wondering why was there a choice to use TypedDict instead of pydantic models for requests objects?
Searched the issues/PRs but couldn't find anything.

Thanks in advance for response!

Additional context

No response

[antont]

We discussed this in December there, and OpenAI folks said they understood the feedback and will work on improvements, and perhaps make a new way where they might be pydantic models, #911 (comment)

I'm using simple handle factory functions that I shared there earlier, #911 (comment)

The reason why they chose TypedDict was they they wanted the lib to work so that folks can just give dict literals as the params, without needing to create Python objects of some parameter type. This may well be a good choice for people who don't know Python but are using the lib, which is fine.

However many I guess more experiences devs, and folks building larger systems, prefer using types .. I for one always try to get rid of string constants anywhere.

[itissid]

@antont IIRC the point of pydantic is to validate model creation at runtime. I feel that a pointed enough case was not quite made in #911 to change the user facing part of lib to use pydantic instead of TypedDict. If the objective is to do runtime validation, one can just as easily use pydantics TypeAdaptors internally in the library to validate the data without changing the signatures. WDYT?

[antont]

@itissid change the user facing part of lib to use pydantic instead of TypedDict.

The first link does say it directly:

@rattrayalex My guess is that yes, these would be pydantic models, as suggested here. (Though Robert and I will take this offline to discuss details/internals)

Sure, it's there in the comments, and not direclty what started the issue, but I just wanted to mention that they already started looking into this in December. There is no issue for it though, so maybe this is a good one to continue the talks.

Maybe the original idea of Pydantic was runtime validation (though they say that it's a parsing lib, not a validation lib..), but I find it very useful nowadays for development time type info. So that Pyright shows me an error right away in VSCode if I'm trying to use a wrong / incompatible type somewhere.

[rattrayalex]

Thank you @antont for the useful links and context.

We use TypedDicts instead of Pydantic Models in requests to enable much more convenient syntax for nested params, eg:

client.chat.completions.create(
  response_format={"type": "json_object"}
)

instead of:

from openai.types.chat.completions import ResponseFormat

client.chat.completions.create(
  response_format=ResponseFormat(type="json_object")
)

In the specific case of messages, @antont is correct that we plan to add helper functions to make this more ergonomic (but that ask is best tracked in the ticket he linked).