Support Pydantic models as the output schema

[Fakamoto]

i'd like to define the output as a Pydantic model, pass it to the SDK, and get a validated instance back.

right now, i have to define the questions separately and access results through keys like response.choices["category"].choice. i'd rather define the fields, types, and descriptions once in a model and use result.category.

for example, something like this:

from typing import Literal
from pydantic import BaseModel, Field

class TicketClassification(BaseModel):
    category: Literal["billing", "technical", "other"] = Field(
        description="What is this ticket about?"
    )

# proposed interface, not current SDK syntax
result = client.system_one(
    input="I was charged twice.",
    response_model=TicketClassification,
)

print(result.category)

this is the contract and API i'd like: clear input, one clear output, defined in good old Pydantic that we all know and love.

pass input and a response_model, get a validated instance of that model back. field types and descriptions define what i'm asking for, without a separate question dictionary or manual response mapping.

the exact parameter names are open for discussion, but that's the developer experience i'm after.

i'm looking for the familiar typed output workflow i use with libraries like LangChain, DSPy, Instructor, and the OpenAI SDK. support could start with fields that map to Jev's existing primitives, with clear errors for unsupported types.

this doesn't require replacing the SDK's internal models. an optional Pydantic interface would work too.

Implementation: Pydantic output models PR. The PR is hosted in my fork because this repository currently limits PR creation to collaborators.

[danielgafni]

Hey, we were considering Pydantic but weren't entirely convinced this was the right move initially.

It is however hypothetically possible to use it.

Could you pleas provide some reasoning for your request? Why exactly would you like the SDK to use Pydantic? Is this to integrate with some other library?

[Fakamoto]

yeah, mainly for the developer experience, rather than integration with a specific library. my original issue was a bit too brief 😅

i want to pass a Pydantic model describing the output and get an instance back. that way i can reuse my types instead of defining questions separately, keeping dict keys in sync, and mapping the response back into my models.

it's the workflow i'm used to with LangChain, DSPy, Instructor, and the OpenAI SDK. so the request is more “let me use Pydantic as the output schema” than “replace your internals with Pydantic.” optional support would be enough for me.

i've updated the issue with an example of the desired API: clear input, one clear output, defined in good old Pydantic that we all know and love.

[Fakamoto]

implemented this and opened a PR here: Fakamoto#1

this repo currently only allows collaborators to open PRs, so i published it in my fork for review. it's based on upstream main.

the API is the one discussed above: input + response_model, returning a validated Pydantic instance. both sync and async are covered; msgspec stays in place internally.

582 offline tests pass, plus typing, package checks, and a live API call. happy to open it here once external PRs are allowed.

[danielgafni]

Oh I see! This makes sense.

An inconvenience here would be to manually keep the types/keys of questions and their corresponding answers in sync, because parametrizing on them isn't possible in Python's type system. Also, why did you want to add a new input argument, can't we reuse the existing state?

However I think that this limitation is fine.

Now given that we likely do not want to add an additional pydantic dependency while still using msgspec, how do you feel about doing the same with msgspec.Struct models?

The reason we are using msgspec today is to keep the SDK as performant and lightweight as possible (see benchmarks). But I can see how it may make integrating with other libraries more brittle.

[Fakamoto]

yeah, keeping state is fine.

i'd still prefer Pydantic as the main interface. i ran a small parsing comparison using the SDK's response format. msgspec was around 4x faster, but the absolute difference was about 1 microsecond for one answer and 55 microseconds for 100 answers.

that's a real advantage, but does it make a meaningful difference in a full API call? this test doesn't cover memory or startup, so i'd be interested in those numbers too.

for me, reusing the models, validation, and tooling i already have is worth some overhead. i'd prefer one familiar Pydantic interface over maintaining equivalent models in another library.

[Fakamoto]

thinking about it more, could response_model accept Pydantic models, msgspec.Struct, and standard dataclasses through the same API?

result = client.system_one(
    state="I was charged twice.",
    response_model=TicketClassification,
)

TicketClassification could be defined with any of those three. the SDK would read its fields, types, and descriptions, derive the questions, and return an instance of that same class.

you could keep msgspec for HTTP serialization and parsing internally. users who already use msgspec would get a Struct back; users like me could reuse their Pydantic models. Pydantic would only need to be installed by people choosing it.

that seems like a better approach to me: one public API, with the user choosing their model library and its tradeoffs. the SDK can keep its lightweight core, and users don't have to maintain equivalent models in another library.

i'm thinking of explicit support for those three, not every possible model library. descriptions and validation would need clear mappings—especially since plain dataclasses don't validate types themselves—and fields that Jev can't produce should still fail clearly.

would that fit the direction you have in mind?

[danielgafni]

That's a good point, optional Pydantic support for the response is very much possible!

[Fakamoto]

great, i'd be happy to contribute this! there's already an implementation of optional Pydantic support in my fork: Fakamoto#1

it keeps msgspec internally and covers both sync and async clients. i'm also happy to drop the input alias and keep state, as you suggested.

i checked again, but this repo still limits PR creation to collaborators, so i can't open the PR here. what's the best way to contribute? could you enable external PRs, or is there another workflow you'd prefer?

[danielgafni]

Thanks, there is no need to contribute right now. I am already working on this in our internal repo.

Currently we do not accept PRs, but we will do it in the future!

[Fakamoto]

Thanks

[jb2197]

@danielgafni - thank you for the great model and Python SDK! I have been experimenting with Pydantic schemas for Jev routing in Pydantic Graph, with the graph itself exposed as a PydanticAI agent tool.

I put together a small prototype: https://github.com/jb2197/pydantic-jev. It compiles decision fields into SDK questions and parses answers into the original Pydantic model while preserving the SDK response for probabilities and confidence.

The main benefit for me is putting the routing options, descriptions, and results in one place. Sharing this as an integration use case (although very trivial example), please see the examples/graph.py and examples/graph_agent.py examples.

Looking forward to official implementation!

[danielgafni]

Thanks, I'm releasing exactly this later today. I decided to switch to Pydantic from msgspec (indeed the overhead is negligible according to my benchmarks, while ecosystem value is way higher).

[danielgafni]

Shipped in https://github.com/typesafe-ai/typesafe-sdk-python/releases/tag/v0.7.0

Check out the docs page on typed responses