feat: spec-sync pipeline (Problem 3)

.github/workflows/pr-gates.yml

@@ -0,0 +1,43 @@
+name: PR Gates
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  surface-lock:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0     # tags for the release-tag baseline
+      - name: Install Rye
+        run: |
+          curl -sSf https://rye.astral.sh/get | bash
+          echo "$HOME/.rye/shims" >> "$GITHUB_PATH"
+        env:
+          RYE_VERSION: '0.44.0'
+          RYE_INSTALL_OPTION: '--yes'
+      - name: Install dependencies
+        run: rye sync --all-features
+      - name: Surface lock (no breaking change to released API)
+        run: ./scripts/spec-sync/surface-lock.sh
+
+  contract-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install Rye
+        run: |
+          curl -sSf https://rye.astral.sh/get | bash
+          echo "$HOME/.rye/shims" >> "$GITHUB_PATH"
+        env:
+          RYE_VERSION: '0.44.0'
+          RYE_INSTALL_OPTION: '--yes'
+      - name: Install dependencies
+        run: rye sync --all-features
+      - name: Contract tests vs staging
+        env:
+          LANDINGAI_ADE_STAGING_APIKEY: ${{ secrets.LANDINGAI_ADE_STAGING_APIKEY }}
+        run: rye run pytest tests/contract -m contract -v

.github/workflows/spec-sync.yml

@@ -0,0 +1,98 @@
+name: Spec Sync
+on:
+  schedule:
+    - cron: '0 */6 * * *'   # every ~6h; cron covers correctness, dispatch cuts latency
+  workflow_dispatch: {}
+
+permissions:
+  contents: read            # writes happen via the app token, not GITHUB_TOKEN
+
+jobs:
+  spec-sync:
+    if: github.repository == 'landing-ai/ade-python'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      V1_SPEC_URL: https://api.va.staging.landing.ai/v1/ade/openapi.json  # staging drives the loop
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # SPEC_SYNC_TOKEN is a fine-grained PAT (Contents: RW, Pull requests: RW)
+          # scoped to this repo. It must NOT be the default GITHUB_TOKEN: pushes/PRs
+          # authored by GITHUB_TOKEN do not trigger the gate workflows (anti-recursion).
+          token: ${{ secrets.SPEC_SYNC_TOKEN }}
+          fetch-depth: 0     # tags needed for surface-lock baseline
+
+      - name: Install Rye
+        run: |
+          curl -sSf https://rye.astral.sh/get | bash
+          echo "$HOME/.rye/shims" >> "$GITHUB_PATH"
+        env:
+          RYE_VERSION: '0.44.0'
+          RYE_INSTALL_OPTION: '--yes'
+
+      - name: Install dependencies
+        run: rye sync --all-features
+
+      - name: Detect drift
+        id: drift
+        run: |
+          set +e
+          ./scripts/spec-sync/check-drift.sh "$V1_SPEC_URL" specs/v1-ade.json
+          echo "code=$?" >> "$GITHUB_OUTPUT"
+
+      - name: No drift
+        if: steps.drift.outputs.code == '0'
+        run: echo "specs in sync; nothing to do."
+
+      - name: Fail on fetch error
+        if: steps.drift.outputs.code != '0' && steps.drift.outputs.code != '10'
+        run: |
+          echo "spec fetch/normalize failed (exit ${{ steps.drift.outputs.code }})"
+          exit 1
+
+      # ---- Phase 1: mechanical ----
+      - name: Mechanical commit (snapshot + reference models)
+        if: steps.drift.outputs.code == '10'
+        id: mech
+        run: |
+          git config user.name "spec-sync[bot]"
+          git config user.email "spec-sync@users.noreply.github.com"
+          branch="spec-sync/v1-$(date -u +%Y%m%dT%H%M%SZ)"
+          git checkout -b "$branch"
+          ./scripts/spec-sync/gen-models.sh specs/v1-ade.json specs/_generated/v1_models.py
+          git add specs/v1-ade.json specs/_generated/v1_models.py
+          git commit -m "chore(spec-sync): update V1 spec snapshot + regenerated reference models"
+          git push -u origin "$branch"
+          echo "branch=$branch" >> "$GITHUB_OUTPUT"
+
+      # ---- Phase 2: AI wiring (same checkout/branch) ----
+      - name: AI wiring commit
+        if: steps.drift.outputs.code == '10'
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.SPEC_SYNC_TOKEN }}
+          prompt: |
+            The previous commit updated specs/v1-ade.json and regenerated reference
+            models in specs/_generated/v1_models.py. Update the SDK to match the spec
+            diff: add or adjust resource classes, method signatures, param TypedDicts,
+            response models, tests, api.md, and README examples, mirroring the existing
+            conventions in src/landingai_ade/resources/parse_jobs.py.
+            Rules: PURELY ADDITIVE — never modify or remove an existing public signature
+            (the surface-lock CI job will fail the PR); follow existing code style;
+            run ./scripts/format; commit to the current branch.
+          claude_args: |
+            --max-turns 40
+            --allowedTools "Edit,Write,Read,Bash(git *),Bash(rye *),Bash(./scripts/*)"
+
+      - name: Open sync PR
+        if: steps.drift.outputs.code == '10'
+        env:
+          GH_TOKEN: ${{ secrets.SPEC_SYNC_TOKEN }}
+        run: |
+          gh pr create \
+            --base main \
+            --head "${{ steps.mech.outputs.branch }}" \
+            --title "spec-sync: track V1 spec drift" \
+            --body $'Automated spec-sync PR.\n\n- **Commit 1 (mechanical):** normalized spec snapshot + regenerated reference models.\n- **Commit 2 (AI):** resources/methods/tests/docs wired from the spec diff.\n\nGates (surface-lock, contract tests, lint/test/typecheck) must pass. **Human review required before merge.**'

CONTRIBUTING.md

@@ -126,3 +126,44 @@ You can release to package managers by using [the `Publish PyPI` GitHub action](
 
 If you need to manually release a package, you can run the `bin/publish-pypi` script with a `PYPI_TOKEN` set on
 the environment.
+
+## Spec-sync pipeline
+
+The SDK tracks the live ADE OpenAPI spec automatically via `.github/workflows/spec-sync.yml`
+(cron ~6h + manual `workflow_dispatch`). It is driven by the **staging** spec; releases gate on
+the **production** spec ("staging in, production out").
+
+On each run it fetches and normalizes the live spec (`scripts/spec-sync/fetch-normalize.sh`) and
+diffs it against the committed snapshot `specs/v1-ade.json` (`scripts/spec-sync/check-drift.sh`).
+On drift it opens one PR with two attributed commits:
+
+1. **Mechanical** — updated `specs/v1-ade.json` snapshot plus regenerated *reference* models in
+   `specs/_generated/v1_models.py` (`scripts/spec-sync/gen-models.sh`, `datamodel-code-generator`).
+   These reference models are an input for the AI step and for review — they are **not** shipped and
+   do **not** replace `src/landingai_ade/types/*`.
+2. **AI** — `anthropics/claude-code-action` (automation mode) wires the resources, methods, param
+   types, tests, and docs from the spec diff, following existing conventions.
+
+Every spec-sync PR (and any PR to `main`) must pass `.github/workflows/pr-gates.yml`:
+
+- **surface-lock** (`scripts/spec-sync/surface-lock.sh`, `griffe`) — baseline is the **last release
+  tag**, so any change to *released* public surface fails mechanically. Merged-but-unreleased surface
+  stays mutable.
+- **contract-tests** — `tests/contract` (marker `contract`) run against staging when
+  `LANDINGAI_ADE_STAGING_APIKEY` is set; skipped otherwise.
+
+Spec-sync PRs are AI-drafted and **require human review** before merge.
+
+**Secrets required:** `SPEC_SYNC_TOKEN` (a fine-grained PAT scoped to this repo with
+`Contents: Read and write` and `Pull requests: Read and write`), `ANTHROPIC_API_KEY`, and
+`LANDINGAI_ADE_STAGING_APIKEY`. `SPEC_SYNC_TOKEN` must **not** be the default `GITHUB_TOKEN`:
+pushes and PRs authored by `GITHUB_TOKEN` do not trigger the gate workflows (GitHub
+anti-recursion), so the gates would never run on the sync PR. A GitHub App installation token
+(org-owned) is the cleaner long-term choice and can replace the PAT without other workflow
+changes.
+
+**V2:** once the aide gateway serves its curated spec unauthenticated, add `specs/v2-aide.json` and
+its URL as a second drift-check in the workflow; the two-phase machinery is unchanged.
+
+The same pipeline shape ports to `ade-typescript` with `openapi-typescript` (mechanical) and
+`api-extractor` (surface-lock), tracked separately.

pyproject.toml

@@ -59,6 +59,8 @@ dev-dependencies = [
     "importlib-metadata>=6.7.0",
     "rich>=13.7.1",
     "pytest-xdist>=3.6.1",
+    "datamodel-code-generator>=0.45",
+    "griffe>=1.14",
 ]
 
 [tool.rye.scripts]
@@ -134,6 +136,9 @@ addopts = "--tb=short -n auto"
 xfail_strict = true
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
+markers = [
+  "contract: hits the live staging API; requires LANDINGAI_ADE_STAGING_APIKEY",
+]
 filterwarnings = [
   "error"
 ]
@@ -150,6 +155,7 @@ exclude = [
     ".venv",
     ".nox",
     ".git",
+    "specs",
 ]
 
 reportImplicitOverride = true
@@ -168,7 +174,7 @@ show_error_codes = true
 #
 # We also exclude our `tests` as mypy doesn't always infer
 # types correctly and Pyright will still catch any type errors.
-exclude = ['src/landingai_ade/_files.py', '_dev/.*.py', 'tests/.*']
+exclude = ['src/landingai_ade/_files.py', '_dev/.*.py', 'tests/.*', 'specs/.*']
 
 strict_equality = true
 implicit_reexport = true
@@ -214,6 +220,9 @@ ignore_missing_imports = true
 line-length = 120
 output-format = "grouped"
 target-version = "py38"
+# specs/_generated holds datamodel-code-generator reference models (not shipped);
+# they are not held to the SDK's lint standards.
+extend-exclude = ["specs"]
 
 [tool.ruff.format]
 docstring-code-format = true

requirements-dev.lock

@@ -23,6 +23,7 @@ anyio==4.12.1
     # via httpx
     # via landingai-ade
 argcomplete==3.6.3
+    # via datamodel-code-generator
     # via nox
 async-timeout==5.0.1
     # via aiohttp
@@ -31,11 +32,18 @@ attrs==25.4.0
     # via nox
 backports-asyncio-runner==1.2.0
     # via pytest-asyncio
+black==25.11.0
+    # via datamodel-code-generator
 certifi==2026.1.4
     # via httpcore
     # via httpx
+click==8.1.8
+    # via black
+colorama==0.4.6
+    # via griffe
 colorlog==6.10.1
     # via nox
+datamodel-code-generator==0.45.0
 dependency-groups==1.3.1
     # via nox
 dirty-equals==0.11
@@ -53,6 +61,9 @@ filelock==3.19.1
 frozenlist==1.8.0
     # via aiohttp
     # via aiosignal
+genson==1.3.1
+    # via datamodel-code-generator
+griffe==1.14.0
 h11==0.16.0
     # via httpcore
 httpcore==1.0.9
@@ -70,35 +81,53 @@ idna==3.11
     # via httpx
     # via yarl
 importlib-metadata==8.7.1
+    # via isort
+    # via typeguard
+inflect==7.5.0
+    # via datamodel-code-generator
 iniconfig==2.1.0
     # via pytest
+isort==6.1.0
+    # via datamodel-code-generator
+jinja2==3.1.6
+    # via datamodel-code-generator
 markdown-it-py==3.0.0
     # via rich
+markupsafe==3.0.3
+    # via jinja2
 mdurl==0.1.2
     # via markdown-it-py
+more-itertools==10.8.0
+    # via inflect
 multidict==6.7.0
     # via aiohttp
     # via yarl
 mypy==1.17.0
 mypy-extensions==1.1.0
+    # via black
     # via mypy
 nodeenv==1.10.0
     # via pyright
 nox==2025.11.12
 packaging==25.0
+    # via black
+    # via datamodel-code-generator
     # via dependency-groups
     # via nox
     # via pytest
 pathspec==1.0.3
+    # via black
     # via mypy
 platformdirs==4.4.0
+    # via black
     # via virtualenv
 pluggy==1.6.0
     # via pytest
 propcache==0.4.1
     # via aiohttp
     # via yarl
 pydantic==2.12.5
+    # via datamodel-code-generator
     # via landingai-ade
 pydantic-core==2.41.5
     # via pydantic
@@ -113,6 +142,10 @@ pytest-asyncio==1.2.0
 pytest-xdist==3.8.0
 python-dateutil==2.9.0.post0
     # via time-machine
+pytokens==0.4.1
+    # via black
+pyyaml==6.0.3
+    # via datamodel-code-generator
 respx==0.22.0
 rich==14.2.0
 ruff==0.14.13
@@ -122,13 +155,18 @@ sniffio==1.3.1
     # via landingai-ade
 time-machine==2.19.0
 tomli==2.4.0
+    # via black
+    # via datamodel-code-generator
     # via dependency-groups
     # via mypy
     # via nox
     # via pytest
+typeguard==4.5.2
+    # via inflect
 typing-extensions==4.15.0
     # via aiosignal
     # via anyio
+    # via black
     # via exceptiongroup
     # via landingai-ade
     # via multidict
@@ -137,6 +175,7 @@ typing-extensions==4.15.0
     # via pydantic-core
     # via pyright
     # via pytest-asyncio
+    # via typeguard
     # via typing-inspection
     # via virtualenv
 typing-inspection==0.4.2

scripts/spec-sync/check-drift.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Compare a live spec against its committed snapshot.
+#   exit 0  -> no drift
+#   exit 10 -> drift detected; <committed-path> updated in place with the live spec
+#   other   -> operational error (e.g. fetch failure)
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+  echo "usage: check-drift.sh <spec-url> <committed-path>" >&2
+  exit 2
+fi
+
+url="$1"
+committed="$2"
+here="$(cd "$(dirname "$0")" && pwd)"
+tmp="$(mktemp)"
+trap 'rm -f "$tmp"' EXIT
+
+"$here/fetch-normalize.sh" "$url" > "$tmp"
+
+if [ -f "$committed" ] && diff -q "$committed" "$tmp" >/dev/null; then
+  echo "no drift: $committed"
+  exit 0
+fi
+
+mkdir -p "$(dirname "$committed")"
+cp "$tmp" "$committed"
+echo "drift detected -> updated $committed"
+exit 10