Python server won't start when following the README: samples main is incompatible with python-sdk main (ap2_mandate.Checkout removed in sdk #48)

[vishkaty]

Symptom

Following rest/python/server/README.md exactly on fresh clones (both repos at today's main), the database step succeeds but the server fails to start:

File ".../samples/rest/python/server/models.py", line 23, in <module>
    from ucp_sdk.models.schemas.shopping.ap2_mandate import Checkout as Ap2Checkout
ImportError: cannot import name 'Checkout' from 'ucp_sdk.models.schemas.shopping.ap2_mandate'

Since the README instructs an unpinned git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git (and pyproject.toml uses an unversioned path dependency), every new contributor following the README hits this today.

Bisect

• python-sdk @ f54858e (pre-Dołącz do nas – Świątynia Wampira #48): import OK, server boots and serves (HTTP 200) ✅
• python-sdk @ 298c295 (PR Dołącz do nas – Świątynia Wampira #48, "upgrade Python SDK to UCP v2026-04-08", merged 2026-06-30): ImportError ❌
• python-sdk @ current main (ee3a15c): ImportError ❌

PR #48 regenerated the models for the 04-08 schemas; ap2_mandate now exports Ap2MandateExtension/Ap2WithCheckoutMandate/… and no longer has the composed Checkout that models.py L23 and integration_test.py L48 import. Verified reproducible: samples @ 827c522, sdk @ ee3a15c, macOS + uv.

Why CI didn't catch it

The samples workflows are lint/governance only — nothing builds or boot-tests the Python server against the SDK, so this class of cross-repo breakage is silent.

Suggested fixes (in order)

1. Interim unblock: pin the SDK in the README until the migration lands — add git checkout f54858e after the clone (verified: server starts and serves with this pin).
2. Real fix: migrate the Python server to the 04-08 SDK models (the removed class is used in models.py and integration_test.py; there's no drop-in rename, so this is part of the broader 2026-04-08 upgrade).
3. Prevention: add a CI job that runs uv sync + boots the server (or just imports server.py) against sdk main — it would have flagged this on 2026-06-30.

Found while building an unofficial UCP conformance test suite (https://spck.dev). Happy to help with any of the above.

[vishkaty]

One clarification in case it "works on your machine" — that's expected, and it's the crux of the bug:

ucp-sdk is an editable path dependency (pyproject.toml: { path = "../../../../python-sdk/", editable = true }), and uv.lock references that path rather than pinning a git rev. uv sync therefore installs whatever commit is currently checked out at that path — it does not update the SDK's contents. So any contributor who cloned python-sdk before 2026-06-30 (PR #48) still has the working Checkout export locally, and the server runs fine for them. The break only surfaces on a fresh setup that clones python-sdk at main, i.e. exactly what the README tells a new contributor to do. That's also why no CI caught it — the workflows are lint/governance only, nothing does a clean uv sync + server boot against sdk main.

Repro is a clean-room clone of both repos at main (samples 827c522, sdk ee3a15c).

[vishkaty]

Two CI follow-ups now open: #120 adds an end-to-end workflow for the Python server (install → integration tests → boot → happy-path client), with the python-sdk sibling checkout pinned to the last compatible commit — it would have caught this drift the day python-sdk#48 merged. Universal-Commerce-Protocol/conformance#48 applies the same pin to the conformance nightly, which has been red on this exact ImportError since 2026-07-01.

The dependency pin for the README path is still the open decision above — happy to PR it in whichever direction you prefer.

[damaz91]

Thanks for flagging this. We fixed the Python SDK in Universal-Commerce-Protocol/python-sdk#29 - the server should be able to start now, please verify and feel free to reopen if that still doesn't work. Thanks again!

[vishkaty]

Verified on fresh clones of samples + python-sdk main — the README steps boot the server and discovery answers 200. Thanks for the quick fix.