Merge branch 'main' into u/xiaoxuan/fix-ucp-request-optional

Author: damaz91

.github/CODEOWNERS

@@ -0,0 +1,33 @@
+---
+name: PR Governance
+
+on:
+  pull_request_target:
+    types: [
+      opened, 
+      synchronize, 
+      reopened, 
+      ready_for_review, 
+      review_requested, 
+      review_request_removed, 
+      assigned, 
+      unassigned
+    ]
+  pull_request_review:
+    types: [submitted, dismissed]
+
+jobs:
+  governance:
+    name: Reviews
+    # skip for draft PRs
+    if: github.event.pull_request.draft == false
+    permissions:
+      statuses: write
+      contents: read
+      pull-requests: read
+    # Use the reusable workflow defined in the central governance repository
+    # zizmor: ignore[ref-confusion]
+    uses: Universal-Commerce-Protocol/.github/.github/workflows/reusable-governance.yml@main
+    secrets:
+      # Required: An org-level Read token to read team memberships
+      ORG_READ_TOKEN: ${{ secrets.ORG_READ_TOKEN }}

.github/workflows/governance.yml

@@ -24,8 +24,11 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
+    - uses: actions/checkout@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: '3.x'
     - uses: pre-commit/action@v3.0.1
+      env:
+        # workaround for pre-commit/action not being updated to node24
+        FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

.github/workflows/linter.yml

@@ -18,11 +18,11 @@ jobs:
       contents: read
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       # Installs uv (and manages Python automatically)
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v8.2.0
         with:
           enable-cache: true
 

.github/workflows/release.yml

@@ -22,6 +22,12 @@
   <b>Official Python library for the Universal Commerce Protocol (UCP).</b>
 </p>
 
+<p align="center">
+  <a href="https://pypi.org/project/ucp-sdk/"><img src="https://img.shields.io/pypi/v/ucp-sdk" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/ucp-sdk/"><img src="https://img.shields.io/pypi/pyversions/ucp-sdk" alt="Python versions"></a>
+  <a href="https://github.com/Universal-Commerce-Protocol/python-sdk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Universal-Commerce-Protocol/python-sdk" alt="License"></a>
+</p>
+
 ## Overview
 
 This repository contains the Python SDK for the
@@ -31,24 +37,77 @@ Python.
 
 ## Installation
 
-For now, you can install the SDK using the following commands:
+To use this SDK in your own project, install it from PyPI:
 
 ```bash
-# Clone the repository
-git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git
+pip install ucp-sdk
+```
 
-# Navigate to the directory
-cd python-sdk
+Or, if you are managing your project with [uv](https://docs.astral.sh/uv/):
 
-# Install dependencies
-uv sync
+```bash
+uv add ucp-sdk
+```
+
+## Usage
+
+The example below parses a UCP checkout response and reads typed fields:
+
+```python
+from ucp_sdk.models.schemas.shopping.checkout 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
+
+| Package                                 | Description                                         |
+| --------------------------------------- | --------------------------------------------------- |
+| `ucp_sdk.models.schemas.shopping`       | Checkout, cart, order, payment models               |
+| `ucp_sdk.models.schemas.shopping.types` | Line items, totals, buyer, fulfillment, etc.        |
+| `ucp_sdk.models.schemas.transports`     | REST, MCP, and embedded protocol bindings           |
+| `ucp_sdk.models.schemas`                | Service definitions, capabilities, payment handlers |
+
+### Validation
+
+All models support Pydantic validation and serialization:
+
+```python
+from pydantic import ValidationError
+from ucp_sdk.models.schemas.shopping.checkout import Checkout
+
+# Validate data against UCP schemas
+try:
+    checkout = Checkout.model_validate(checkout_data)
+    # Serialize to JSON-compatible dict
+    checkout_dict = checkout.model_dump(exclude_none=True)
+except ValidationError as e:
+    print(e.errors())
 ```
 
 ## Development
 
 ### Prerequisites
 
-This project uses `uv` for dependency management.
+This project uses [`uv`](https://docs.astral.sh/uv/) for dependency management.
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git
+cd python-sdk
+
+# Install dependencies
+uv sync
+```
 
 ### Generating Pydantic Models
 

README.md

@@ -1,4 +1,18 @@
 #!/bin/bash
+# Copyright 2026 UCP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Generate Pydantic models from UCP JSON Schemas
 
 # Ensure we are in the script's directory