From 644a98d4f83e74ffc6805ff9c64c4b0ab0990a79 Mon Sep 17 00:00:00 2001
From: "Patrick R. Jordan" <patrick.r.jordan@gmail.com>
Date: Thu, 16 Apr 2026 09:17:15 -0700
Subject: [PATCH 1/2] docs: improve README with PyPI install, usage examples,
 and badges

Replace clone-based installation with PyPI instructions (pip/uv),
add usage examples showing model imports and validation, add a
model package reference table, and add PyPI/license badges.

Closes #1
---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 70 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 810a977..e8743ac 100644
--- a/README.md
+++ b/README.md
@@ -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,80 @@ Python.
 
 ## Installation
 
-For now, you can install the SDK using the following commands:
+Install 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 with [uv](https://docs.astral.sh/uv/):
 
-# Install dependencies
-uv sync
+```bash
+uv add ucp-sdk
+```
+
+## Usage
+
+The SDK provides typed [Pydantic v2](https://docs.pydantic.dev/) models for all
+UCP schemas. Import models from `ucp_sdk.models.schemas`:
+
+```python
+from ucp_sdk.models.schemas.shopping.checkout import Checkout
+from ucp_sdk.models.schemas.shopping.types.line_item import LineItem
+from ucp_sdk.models.schemas.shopping.types.total import Total
+
+# 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
+
+# Validate data against UCP schemas
+try:
+    checkout = Checkout.model_validate(data)
+except ValidationError as e:
+    print(e.errors())
+
+# Serialize to JSON-compatible dict
+checkout_dict = checkout.model_dump(exclude_none=True)
 ```
 
 ## 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
 

From b7b90782fc53b4b4b090f10596e5fc26d09c16bc Mon Sep 17 00:00:00 2001
From: "Patrick R. Jordan" <patrick.r.jordan@gmail.com>
Date: Thu, 16 Apr 2026 09:35:43 -0700
Subject: [PATCH 2/2] docs: address review feedback on README examples

Remove unused LineItem and Total imports from usage example.
Move serialization inside try-except block and add missing
Checkout import in validation example.
---
 README.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index e8743ac..01c0920 100644
--- a/README.md
+++ b/README.md
@@ -56,8 +56,6 @@ UCP schemas. Import models from `ucp_sdk.models.schemas`:
 
 ```python
 from ucp_sdk.models.schemas.shopping.checkout import Checkout
-from ucp_sdk.models.schemas.shopping.types.line_item import LineItem
-from ucp_sdk.models.schemas.shopping.types.total import Total
 
 # Parse a UCP checkout response
 checkout = Checkout.model_validate(checkout_data)
@@ -84,15 +82,15 @@ 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(data)
+    # Serialize to JSON-compatible dict
+    checkout_dict = checkout.model_dump(exclude_none=True)
 except ValidationError as e:
     print(e.errors())
-
-# Serialize to JSON-compatible dict
-checkout_dict = checkout.model_dump(exclude_none=True)
 ```
 
 ## Development