messages.create() takes a JSON schema dict but messages.stream() takes a Pydantic model

[simonw]

Just ran into this slight inconsistency in the API relating to structured content support.

Here's the messages.create() idea of output_format=:

anthropic-sdk-python/src/anthropic/resources/beta/messages/messages.py

Line 106 in d9aea38

output_format: Optional[BetaJSONOutputFormatParam] | Omit = omit,

Which uses:

anthropic-sdk-python/src/anthropic/types/beta/beta_json_output_format_param.py

Lines 11 to 15 in d9aea38

	class BetaJSONOutputFormatParam(TypedDict, total=False):
	schema: Required[Dict[str, object]]
	"""The JSON schema of the format"""
	type: Required[Literal["json_schema"]]

So it accepts a Python dictionary that represents a JSON schema.

But the messages.stream() method:

anthropic-sdk-python/src/anthropic/resources/beta/messages/messages.py

Line 1351 in d9aea38

output_format: Optional[type[ResponseFormatT]] | Omit = omit,

Later does this:

anthropic-sdk-python/src/anthropic/resources/beta/messages/messages.py

Lines 1385 to 1386 in d9aea38

	if is_given(output_format) and output_format is not None:
	adapted_type: TypeAdapter[ResponseFormatT] = TypeAdapter(output_format)

TypeAdapter is a Pydantic concept, so this has the effect of only allowing Pydantic types to be passed to messages.stream().

It's confusing and inconsistent that messages.create() requires a JSON schema dictionary but messages.stream() instead requires a Pydantic model.

[karpetrosyan]

Hey @simonw !

The .stream() method is essentially a streaming-oriented alternative to .parse(). It still allows event accumulation, while also accepting a pydantic type so it can parse the raw message into that type and provide proper type information. That’s why it requires a pydantic model.

I think we could add raw schema support to .stream(), though it would no longer automatically parse the raw structured response into a pydantic type. Is that something you expect?

[simonw]

Yeah, my software is built around JSON schemas - I do have a Pydantic option but I turn those into JSON schema before passing them further down the stack.

I ended up working around this limitation using https://pypi.org/project/json-schema-to-pydantic