ci: add spec drift check script and workflow

[hewliyang]

Stacked on #110.

Summary

Adds scripts/spec_drift.py, a structural comparison between the SDK types and https://reducto.ai/openapi.json, and a workflow that runs it on pull requests.

How it works

Schema names in the spec do not match SDK type names, so nothing is matched by name.

1. Anchor on endpoints. The script parses src/reducto/resources/*.py and _client.py with ast and finds each self._post("/path", body=maybe_transform(..., ParamsType), cast_to=ResponseType, query=...). New spec endpoints with no SDK method are reported too.
2. Normalize both sides into one shape model (object / enum / primitive / array / map / union). Spec: $ref, anyOf/oneOf/allOf, const, format: binary. SDK: runtime introspection of TypedDicts and pydantic models, honoring Required[], PropertyInfo(alias=...), Literal, Optional, Iterable, SequenceNotStr, FileTypes.
3. Walk in parallel from request, query, and response of each endpoint. Union members are paired by structural similarity, then compared.

Noise controls: response required drift is skipped when the spec field is nullable (SDK models those as Optional = None); each (spec schema, SDK class) pair is compared once, in spec path order; /upload merges body and query since one params type feeds both.

Spec snapshot

spec/openapi.json is a committed copy of the public spec. The PR check runs against it, so it is reproducible, needs no network, and an upstream API change cannot turn an unrelated PR red.

Workflows

• .github/workflows/spec-drift.yml replaces sdksync from reductoai/sdk-utils. It runs the script against the snapshot on PR open, reopen, and push. The full report goes to the job summary. The job fails when drift is found.
• Refreshing the snapshot is manual: uv run python scripts/spec_drift.py --update-snapshot, sync the SDK, commit both together.

Usage

uv run python scripts/spec_drift.py                    # committed snapshot
uv run python scripts/spec_drift.py --live              # https://reducto.ai/openapi.json
uv run python scripts/spec_drift.py --spec other.json   # any URL or file
uv run python scripts/spec_drift.py --update-snapshot   # refresh spec/openapi.json, then check
uv run python scripts/spec_drift.py --json
uv run python scripts/spec_drift.py --ignore extra --warn-only

Current result against the snapshot (v1.12.12-114)

57 drift items: endpoint=2, enum=4, extra=1, missing=50. Highlights: missing DELETE /job/{job_id} and DELETE /upload/{file_id}; parse settings embed_pdf_metadata_dpi, extract_document_properties, hybrid_vpc, tenant_throttling, TableAgentic.mode; extract queue_priority, citations.parent_block; split deep_split, auto_partition; classify category_groups, model; queue_priority enum lacks standard; response_type discriminator missing on every response model.

Because of this, the check will be red on this PR until #113 (the SDK sync) lands on top. If you prefer a soft check in the meantime, change the run step to --warn-only.

Verification

• ruff, pyright (strict), mypy clean on the script
• ./scripts/lint and ./scripts/test pass

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}