Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/linter.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ name: Lint

on:
push:
branches: [main]
branches: [main, "release/**"]
pull_request:
branches: [main]
branches: [main, "release/**"]

permissions:
contents: read
Expand All @@ -27,10 +27,10 @@ jobs:
pre-commit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: '3.x'
- uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
Expand Down
43 changes: 23 additions & 20 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ name: Tests

on:
push:
branches: [main]
branches: [main, "release/**"]
pull_request:
branches: [main]
branches: [main, "release/**"]

permissions:
contents: read
Expand All @@ -40,7 +40,7 @@ jobs:
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: ${{ matrix.python-version }}
- name: Install package (generated-model tests import it)
- name: Install package
run: pip install -e .
- name: Run unit tests
run: python -m unittest discover -s tests -p "test_*.py"
Expand All @@ -56,12 +56,17 @@ jobs:
- name: Install uv
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
enable-cache: true
- name: Install ucp-schema CLI
env:
UCP_SCHEMA_VERSION: "2.0.0"
enable-cache: false
- name: Regenerate models from ucp-lock.json and verify zero drift
run: |
set -euo pipefail
LOCK_FIELDS="$(jq -er '
(.ucp_sha | select(type == "string" and test("^[0-9a-f]{40}$"))) as $sha |
(.ucp_schema_version | select(type == "string" and test("^[0-9]+\\.[0-9]+\\.[0-9]+$"))) as $ver |
"\($sha) \($ver)"
' ucp-lock.json)"
read -r UCP_SHA UCP_SCHEMA_VERSION <<< "$LOCK_FIELDS"

tmp_dir="$(mktemp -d)"
trap 'rm -rf "$tmp_dir"' EXIT
base_url="https://github.com/Universal-Commerce-Protocol/ucp-schema/releases/download/v${UCP_SCHEMA_VERSION}"
Expand All @@ -70,18 +75,16 @@ jobs:
(cd "$tmp_dir" && sha256sum -c --ignore-missing SHA256SUMS)
mkdir -p "$HOME/.local/bin"
install -m 0755 "$tmp_dir/ucp-schema-linux-x86_64" "$HOME/.local/bin/ucp-schema"
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Regenerate models from the pinned spec version
# SDK 0.6.x targets UCP 2026-08-25 (see the README compatibility
# table). Bump this pin together with the SDK version line.
run: ./generate_models.sh 2026-08-25
- name: Fail if regeneration does not reproduce the committed models
run: |
git add -A -- src/ucp_sdk/models/schemas
if ! git diff --cached --quiet -- src/ucp_sdk/models/schemas; then
echo "::error::Committed models differ from regeneration against the pinned UCP spec. Either the generation pipeline is broken, or the models were edited without regenerating. Run ./generate_models.sh 2026-08-25 and commit the result."
git --no-pager diff --cached --stat -- src/ucp_sdk/models/schemas
git --no-pager diff --cached -- src/ucp_sdk/models/schemas
export PATH="$HOME/.local/bin:$PATH"

rm -rf "$RUNNER_TEMP/ucp-spec"
git clone --filter=blob:none --no-checkout https://github.com/Universal-Commerce-Protocol/ucp.git "$RUNNER_TEMP/ucp-spec"
git -C "$RUNNER_TEMP/ucp-spec" checkout --detach "$UCP_SHA"
./generate_models.sh --from-lock --spec-dir "$RUNNER_TEMP/ucp-spec"

if [ -n "$(git status --porcelain -- src/ucp_sdk pyproject.toml ucp-lock.json)" ]; then
echo "::error::Committed models differ from regeneration against ucp-lock.json. Run ./generate_models.sh --from-lock and commit the result."
git status --short -- src/ucp_sdk pyproject.toml ucp-lock.json
git --no-pager diff -- src/ucp_sdk pyproject.toml ucp-lock.json
exit 1
fi
echo "Committed models match regeneration."
64 changes: 45 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,31 +37,51 @@ Python.

### UCP Version Compatibility

Each version of the Python SDK is generated against a specific version of the
UCP schema:

| SDK Version | UCP Schema Version |
| ----------------- | ------------------ |
| **`0.6.x`** | **`2026-08-25`** |
| `0.5.x` | `2026-08-25` |
| `0.4.x` | `2026-04-08` |
| `0.3.x` | `2026-01-23` |
| `0.2.x` / `0.1.x` | `2026-01-11` |
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`](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

To use this SDK in your own project, install it from PyPI:
### Published Releases (PyPI)

Install the latest published UCP release from PyPI:

```bash
pip install ucp-sdk
```

Or, if you are managing your project with [uv](https://docs.astral.sh/uv/):
Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add ucp-sdk
```

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

```bash
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`:

```bash
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:
Expand Down Expand Up @@ -175,20 +195,26 @@ 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`.
Specification using `ucp-schema generate-types` and `datamodel-codegen`, with
provenance recorded in [`ucp-lock.json`](ucp-lock.json).

To regenerate the models:

```bash
uv sync
./generate_models.sh <version-or-path>
```

Where `<version-or-path>` is a UCP release version (for example, `2026-08-25`),
a branch or commit SHA, or a path to a local UCP repository checkout.
# Reproduce committed models from the exact commit pinned in ucp-lock.json
./generate_models.sh

If no argument is specified, the `main` branch of the
[UCP repo](https://github.com/Universal-Commerce-Protocol/ucp) will be used.
# 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`.

Expand Down
Loading
Loading