Skip to content

Latest commit

 

History

History
237 lines (174 loc) · 8.56 KB

README.md

File metadata and controls

237 lines (174 loc) · 8.56 KB

UCP Python SDK

Official Python library for the Universal Commerce Protocol (UCP).

PyPI version Python versions License

Overview

This repository contains the Python SDK for the Universal Commerce Protocol (UCP). It provides Pydantic models for UCP schemas, making it easy to build UCP-compliant applications in Python.

UCP Version Compatibility

Starting with the 2026-08-25 UCP specification release, PyPI releases use spec-aligned YYYYMMDD.MINOR.PATCH versioning (for example, 20260825.0.0 for UCP 2026-08-25), while main tracks the draft UCP schema (0.0.0.dev0) pinned in ucp-lock.json:

SDK Version UCP Schema Version Channel
YYYYMMDD.MINOR.PATCH YYYY-MM-DD (>= 2026-08-25) PyPI
0.0.0.dev0 (main git commit) draft (ucp@main in ucp-lock) Git (main)
0.5.x 2026-08-25 PyPI (legacy 0.x)
0.4.x 2026-04-08 PyPI
0.3.x 2026-01-23 PyPI
0.2.x / 0.1.x 2026-01-11 PyPI

Installation

Published Releases (PyPI)

Install the latest published UCP release from PyPI:

pip install ucp-sdk

Or with uv:

uv add ucp-sdk

To pin a specific UCP specification release epoch (for example, 2026-08-25):

uv add "ucp-sdk>=20260825.0.0,<20260826.0.0"

Unreleased draft Schemas (Git-Native)

To build against unreleased draft schemas on main, install directly from a commit SHA on Universal-Commerce-Protocol/python-sdk:

uv add "ucp-sdk @ git+https://github.com/Universal-Commerce-Protocol/python-sdk.git@<commit-sha>"

Usage

The example below parses a UCP checkout response and reads typed fields:

from ucp_sdk.models import Checkout

# Parse a UCP checkout response
checkout = Checkout.model_validate(checkout_data)

# Access typed fields
print(checkout.status)  # "incomplete" | "ready_for_complete" | ...
print(checkout.currency)  # ISO 4217 currency code
for item in checkout.line_items:
    print(f"{item.item.title}: {item.quantity}")

Available model packages

Generated Pydantic models and type aliases for the Shopping vertical (shopping, common, and transports schemas) are lazily re-exported from both ucp_sdk.models and ucp_sdk.models.schemas:

Package Description
ucp_sdk.models Top-level lazy re-export of all generated UCP models (checkout, cart, order, fulfillment, profile, etc.)
ucp_sdk.models.schemas Lazy re-export of Pydantic v2 models synthesized from the UCP Shopping, Common, and Transports JSON Schema

Validation

Pydantic models in ucp_sdk.models provide Tier 1 wire DTO structural typing and tolerant-reader deserialization (preserving unknown extension fields for forward compatibility) rather than full UCP protocol conformance.

In particular, open discriminated unions (such as FulfillmentDestination, FulfillmentMethod, and Provider) are emitted as untagged unions with an open *Base fallback (type: str), so payloads carrying a known type discriminator that fail a variant-specific field constraint will deserialize into *Base unless validated upfront against the compiled JSON Schema.

To enforce normative UCP constraints (capability profile composition, directional ucp_request / ucp_response visibility, dependentRequired, if/then, uniqueItems, contains, propertyNames, not.enum, and closed-schema rules):

  1. In-Memory Runtime Validation (Production Services): Compile your UCP discovery profile once at build or startup time into a standard JSON Schema Draft 2020-12 bundle (ucp-schema generate-types --profile profile.json -o ucp.types.json) or OpenAPI 3.1 specification (ucp-schema generate-openapi --profile profile.json -o openapi.json). Because ucp-schema resolves all UCP-specific annotations and capability extensions into standard JSON Schema 2020-12, you can validate incoming payloads in memory on every request using jsonschema (install pip install "jsonschema[format-nongpl]" to enable uri and date-time format validation via MIT-licensed validators without pulling in GPL dependencies) or OpenAPI ASGI middleware before deserializing into Pydantic DTOs:
import json
from pathlib import Path
from jsonschema import Draft202012Validator
from ucp_sdk.models import Checkout

# At startup: load the pre-compiled schema bundle once into memory
bundle = json.loads(Path("ucp.types.json").read_text(encoding="utf-8"))
checkout_validator = Draft202012Validator(
    {**bundle["$defs"]["Checkout"], "$defs": bundle["$defs"]},
    format_checker=Draft202012Validator.FORMAT_CHECKER,
)

# Per request: validate in-memory, then parse into typed Pydantic DTO
checkout_validator.validate(raw_payload)
checkout = Checkout.model_validate(raw_payload)
  1. CLI & CI Conformance Testing: Verify fixture payloads or live traffic dumps from the command line or CI pipelines with ucp-schema validate:
# Self-describing response or JSON-RPC envelope
ucp-schema validate payload.json --op read

# REST request against a discovery profile (or --schema checkout.json --request --op create)
ucp-schema validate payload.json --profile profile.json --op create

Development

Prerequisites

This project uses uv for dependency management and ucp-schema (cargo install ucp-schema) to synthesize the flat $defs bundle for model generation.

Setup

# Clone the repository
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git
cd python-sdk

# Install dependencies
uv sync

Generating Pydantic Models

The models are automatically generated from the JSON schemas in the UCP Specification using ucp-schema generate-types and datamodel-codegen, with provenance recorded in ucp-lock.json.

To regenerate the models:

uv sync

# Reproduce committed models from the exact commit pinned in ucp-lock.json
./generate_models.sh

# Advance ucp-lock.json and regenerate models from ucp@main (draft channel)
./generate_models.sh --ref main --write-lock

# Pin ucp-lock.json to a release branch
./generate_models.sh --ref release/2026-08-25 --write-lock

# Regenerate models from a local UCP checkout without modifying ucp-lock.json
./generate_models.sh --spec-dir /path/to/ucp

The generated code is automatically formatted using ruff.

Running Tests

Run the test suite with:

uv run python -m unittest discover -s tests -p "test_*.py"

Contributing

We welcome community contributions. See our Contribution Guide for details.

License

UCP is an open-source project under the Apache License 2.0.