Python 3.14: compatibility issue with default lazy annotations

[ncoghlan]

Highlighting the Python 3.14 compatibility requirements:

• base any data model classes passed to the SDK on Pydantic rather than lmstudio.BaseModel; or
• specify from __future__ import annotations to use string annotations instead of lazy ones (since msgspec handles those)

---

lmstudio-python is affected by jcrist/msgspec#847, so running on Python 3.14+ currently requires the use of from __future__ import annotations when defining structured response formats based on lmstudio.BaseModel.

The main SDK schema export classes already used string annotations to avoid forward referencing problems, so the PR adding 3.14 to CI (#154) works around the issue by also adding from __future__ import annotations to the affected test modules.

Client applications relying on Pydantic for their data model classes won't be affected (beyond needing to update to Pydantic 2.12.0a1 or later), but those relying on lmstudio.BaseModel to define their structured response formats will currently also need to use from __future__ import annotations for their struct fields to actually get defined.

[baonudesifeizhai]

i will try to fix it

[ncoghlan]

@baonudesifeizhai This isn't one we can really workaround at the SDK level (see jcrist/msgspec#847 (comment) for a couple of the things I already tried and found wouldn't work).

There is still a month and a half before Python 3.14 final is released, and demand for 3.14 support isn't likely to be immediate, so we have time to wait for a new msgspec release with the compatibility fix incorporated.

One thing I am currently doing is confirming that the submitted compatibility fix PR does solve the problem for us.

[ncoghlan]

Confirmed with c20473c that pulling in the jcrist/msgspec#852 changes resolves the structured response test failures without needing the from __future__ import annotations workaround.

[ncoghlan]

Hmm, re-reading my comment on the msgspec issue, I'm not sure I ever tried __init_subclass__ as a potential workaround. I'll see if using that to eagerly populate __annotations__ at class definition time (before calling super().__init_subclass__ works).

I think I tried it and it didn't work, but I didn't record that experiment if so.

Edit: experiment has been (re)tried in #158, and it doesn't work (which makes me suspect the "didn't record the result" situation, rather than "didn't try it at all")

[ncoghlan]

jcrist/msgspec#875 (comment) indicates full Python 3.14 support in msgspec shouldn't be too far away.