[RFC] Consiser adding type hints for API Payloads

[fgmacedo]

One good example of how to help users of your library to integrate and to validate requests, is to use custom models or objects to ensure the declared properties are correct.

Example of Python API SDK with type hints: OpenAI

One good example of this is the OpenAI Python SDK:

Given the Completions as an API example:

class Completions(SyncAPIResource):
    def parse(
        self,
        *,
        messages: Iterable[ChatCompletionMessageParam],
        model: Union[str, ChatModel],
        response_format: type[ResponseFormatT] | NotGiven = NOT_GIVEN,
        frequency_penalty: Optional[float] | NotGiven = NOT_GIVEN,
        function_call: completion_create_params.FunctionCall | NotGiven = NOT_GIVEN,
        functions: Iterable[completion_create_params.Function] | NotGiven = NOT_GIVEN,
        logit_bias: Optional[Dict[str, int]] | NotGiven = NOT_GIVEN,
        ...

See how the params are declared: messages: Iterable[ChatCompletionMessageParam].

And ChatCompletionMessageParam is a type alias:

ChatCompletionMessageParam: TypeAlias = Union[
    ChatCompletionSystemMessageParam,
    ChatCompletionUserMessageParam,
    ChatCompletionAssistantMessageParam,
    ChatCompletionToolMessageParam,
    ChatCompletionFunctionMessageParam,
]

Union of distinct TypedDict, that act like normal python dicts but with type hints, like ChatCompletionSystemMessageParam:

class ChatCompletionSystemMessageParam(TypedDict, total=False):
    content: Required[Union[str, Iterable[ChatCompletionContentPartTextParam]]]
    """The contents of the system message."""

    role: Required[Literal["system"]]
    """The role of the messages author, in this case `system`."""

    name: str
    """An optional name for the participant.

    Provides the model information to differentiate between participants of the same
    role.
    """

See TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys.

[kelvincarvalhosilva]

Hi @fgmacedo

Thank you very much for contacting us!
We will review your request and, if it makes sense, add it to our backlog so that it can be implemented/the error fixed.
If you wish to contribute directly to the code, we also accept contributions in the format of Pull Requests.