Backwards compatibility guarantees for storing and loading message history?

[metanivek]

Question

We recently upgraded to the 1.0 beta (congrats, btw 🎉) and had some code break that reads stored message history.

ValidationError
3 validation errors for list[tagged-union[ModelRequest,ModelResponse]]
1.response.usage.details
  Input should be a valid dictionary [type=dict_type, input_value=None, input_type=NoneType]
    For further information visit https://errors.pydantic.dev/2.11/v/dict_type
3.response.usage.details
  Input should be a valid dictionary [type=dict_type, input_value=None, input_type=NoneType]
    For further information visit https://errors.pydantic.dev/2.11/v/dict_type
5.response.usage.details
  Input should be a valid dictionary [type=dict_type, input_value=None, input_type=NoneType]
    For further information visit https://errors.pydantic.dev/2.11/v/dict_type

What sort of guarantees will there be post-1.0 of these types (ModelRequest, ModelResponse) being stable such that ModelMessagesTypeAdapter.validate_python will work? Should we be looking into other ways of storing message history other than the guidance in the docs? Thanks!

Additional Context

No response

[DouweM]

What sort of guarantees will there be post-1.0 of these types (ModelRequest, ModelResponse) being stable such that ModelMessagesTypeAdapter.validate_python will work?

@metanivek As strong as it gets -- once v1 is out, we will not have breaking changes to the public interface until v2 (which we will not release for at least another 6 months), which extends to deserialization. We'll also support v1 (with security fixes or to fix support for major model providers) for at least a year after we release v2.

So the issue you're seeing would be something we'll be careful not to introduce, and would treat as a bug to be fixed asap if it does slip in.

The issue you're seeing I can likely still fix between v1 by interpreting None as {}. No reason to break if we don't absolutely have to. Can you share the usage part of the payload you're deserializing so I can make sure any other fields in there are also handled correctly?

[metanivek]

This is the essence of code we ran to migrate our data:

def migrate_message(message):
    if "vendor_details" in message:
        message["provider_details"] = message.pop("vendor_details") or {}
    if "vendor_id" in message:
        message["provider_request_id"] = message.pop("vendor_id")
  
    if "usage" in message and isinstance(message["usage"], dict):
        usage = message["usage"]
        if "request_tokens" in usage:
            usage["input_tokens"] = usage.pop("request_tokens") or 0
        if "response_tokens" in usage:
            usage["output_tokens"] = usage.pop("response_tokens") or 0
        for field, default in [("input_tokens", 0), ("output_tokens", 0), ("details", {})]:
            if usage.get(field) is None:
                usage[field] = default

[DouweM]

@metanivek Great, those are exactly the changes from #2378 I was looking at.