spec-sync: track V2 spec drift

[yzld2002]

Automated V2 spec-sync PR (client.v2).

• Commit 1 (mechanical): normalized V2 spec snapshot + regenerated reference models.
• Commit 2 (AI, only if the spec diff needs SDK changes): client.v2 resources/methods/tests/docs wired from the diff, added after this PR opened. Workflow-only drift is excluded and an AI no-op is skipped, so some drifts produce a mechanical-only PR with no second commit.

Gates (surface-lock, V2 contract tests, lint/test/typecheck) must pass. When present, the AI commit is a draft a human finishes (the V2 ergonomic layer — unified Job, dual-host, schema coercion — is not in the spec). Human review required before merge.

[Copilot]

Pull request overview

Refreshes the tracked V2 OpenAPI snapshot and generated reference models. This is a mechanical-only spec-sync update; no client.v2 wiring is expected yet.

Changes:

• Adds build-schema sync/async contracts, metadata, and warnings.
• Updates the V2 endpoint inventory and removes obsolete schemas.
• Regenerates corresponding Pydantic reference models.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
specs/v2-aide.json	Updates the normalized V2 OpenAPI snapshot.
specs/_generated/v2_models.py	Regenerates reference models from the snapshot.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/landingai_ade/resources/v2/build_schema.py:51

• Because str is a Sequence[str], the public annotation permits markdown_urls="https://x/y.md"; this conversion turns that URL into a list of characters and sends an invalid request. Normalize a bare string to a single URL (or reject it explicitly).

        urls_list = list(cast(Sequence[str], markdown_urls))

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

src/landingai_ade/resources/v2/build_schema.py:51

• Passing a single URL string is valid for this Sequence[str] parameter, but list(...) splits it into characters, so the API receives ['h', 't', ...] instead of one URL. Normalize a string as one URL, as the markdowns branch does.

        urls_list = list(cast(Sequence[str], markdown_urls))

src/landingai_ade/resources/v2/build_schema.py:233

• This 504 path also reuses timeout remediation that only mentions parse_jobs and extract_jobs, so async-client users are not directed to the new build_schema_jobs resource. Pass endpoint-specific guidance through the shared helper here as well.

        except APIStatusError as exc:
            raise_if_sync_timeout(exc)
            raise

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

src/landingai_ade/resources/v2/ground.py:128

• The async mirror also recommends client.v2.ground_jobs, although the updated spec no longer contains /v2/ground/jobs. A 504 therefore points users at an unsupported route unless the spec removal is accidental; please reconcile the async remediation with the current contract.

            raise_if_sync_timeout(exc, jobs_resource="ground_jobs")

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (4)

src/landingai_ade/resources/v2/build_schema.py:64

• Empty markdowns or markdown_urls lists bypass this check even when no prompt or schema is supplied, so the method sends a request with no usable input despite its documented “at least one” requirement. Treat empty collections as absent here.

    if md_list is None and urls_list is None and prompt_val is None and schema_val is None:
        raise ValueError("build_schema requires at least one of `markdowns`, `markdown_urls`, `prompt`, or `schema`.")

src/landingai_ade/resources/v2/ground.py:99

• The synced spec removes both /v2/ground/jobs operations, so this new 504 remediation directs callers to a jobs endpoint that is no longer in the current contract. Keep the error non-specific or confirm/reintroduce the ground-jobs route before advertising ground_jobs.

            raise_if_sync_timeout(exc, jobs_resource="ground_jobs")

src/landingai_ade/resources/v2/ground.py:128

• The synced spec removes both /v2/ground/jobs operations, so this new 504 remediation directs async-client callers to a jobs endpoint that is no longer in the current contract. Keep the error non-specific or confirm/reintroduce the ground-jobs route before advertising ground_jobs.

            raise_if_sync_timeout(exc, jobs_resource="ground_jobs")

src/landingai_ade/lib/v2_errors.py:20

• This updated timeout documentation lists ground_jobs as a matching async route, but the synced OpenAPI snapshot removes the ground-jobs collection and item paths. The documented remediation should not promise that route unless it remains an explicitly supported compatibility API.

    The server cancels the work; use the endpoint's matching async jobs route
    (`client.v2.parse_jobs` / `extract_jobs` / `build_schema_jobs` / `ground_jobs`),
    then `.wait(...)`, for long-running inputs. The raised message names the route
    for the specific endpoint that timed out."""

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

src/landingai_ade/types/v2/build_schema_response.py:46

• openapi_spec is the sole required field of V2BuildSchemaMetadata in the updated spec, but this model exposes it as optional with a None default. Make it required so the shipped response type accurately represents the new contract.

    openapi_spec: Optional[str] = None

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (5)

src/landingai_ade/resources/v2/build_schema.py:51

• markdown_urls is annotated as Sequence[str], so a caller can validly pass a single string. Converting that string with list(...) sends one array entry per character instead of one URL. Mirror the markdowns normalization and wrap a string as a singleton list.

    if is_given(markdown_urls) and markdown_urls is not None:
        urls_list = list(cast(Sequence[str], markdown_urls))

api.md:67

• ground_jobs is removed from V2Resource and GroundJobsResource is deleted in this PR, so this public API overview now advertises an attribute that raises AttributeError. Remove it from the unified-job resource list.

`client.v2.parse_jobs`, `client.v2.extract_jobs`, `client.v2.build_schema_jobs`, and `client.v2.ground_jobs` all return a single, unified <a href="./src/landingai_ade/types/v2/job.py">`Job`</a> shape, even though the underlying parse/extract/build-schema/ground job envelopes differ upstream -- `Job.raw` retains the full original envelope as an escape hatch for any field not surfaced on the typed model.

api.md:162

• This pagination note still lists the removed ground_jobs resource. Keeping it here directs users to a nonexistent API.

- `parse_jobs.list` / `extract_jobs.list` / `build_schema_jobs.list` / `ground_jobs.list` all return a `JobList` (a `list[Job]` subclass) carrying pagination metadata: `.has_more`, `.org_id`, `.page`, `.page_size`.

docs/v2-testing.md:12

• normalize_ground_job is deleted from _normalize.py in this PR, so the testing matrix should not claim that this nonexistent normalizer is covered.

| Job normalization | `tests/test_v2_normalize.py` | `normalize_parse_job` / `normalize_extract_job` / `normalize_build_schema_job` / `normalize_ground_job`: envelope → unified `Job` (status, timestamps, `result`, `error`). |

docs/v2-testing.md:115

• This section still documents normalize_ground_job, but that function and the ground jobs surface are removed by the PR. Remove it so the documented normalization surface matches the shipped code.

`normalize_parse_job`, `normalize_extract_job`, `normalize_build_schema_job`, and
`normalize_ground_job` fold the upstream job envelopes into the unified `Job`. All
are tolerant of field-name drift:

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.