spec-sync: track V2 spec drift by yzld2002 · Pull Request #122 · landing-ai/ade-python

yzld2002 · 2026-07-21T13:30:25Z

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

Synchronizes the V2 OpenAPI snapshot and regenerated reference models with upstream contract drift.

Changes:

Adds Ground APIs and standardized error responses.
Updates extraction metadata, async delivery, and job contracts.
Regenerates Pydantic reference models.

Reviewed changes

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

File	Description
`specs/v2-aide.json`	Updates the V2 API specification snapshot.
`specs/_generated/v2_models.py`	Regenerates reference models from the updated specification.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

      }
    },
-    "/v2/parse": {
+    "/v2/ground": {


                    "default": null,
                    "description": "Extraction options (``strict``). Omit for defaults."
                  },
+                  "output_save_url": {


+                      "description": "Request metadata (job_id, model_version, duration_ms, doc_id, billing)."
                    },
-                    "output_ref": {
+                    "schema_violation_error": {


            "title": "Duration Ms",
            "type": "integer"
          },
+          "input_markdown_chars": {


+                    },
+                    "metadata": {
+                      "$ref": "#/components/schemas/V2GroundMetadata",
+                      "description": "Request metadata (job_id, duration_ms, credit_usage)."


+                            },
+                            "metadata": {
+                              "$ref": "#/components/schemas/V2GroundMetadata",
+                              "description": "Request metadata (job_id, duration_ms, credit_usage)."


Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (2)

specs/v2-aide.json:1971

This description still advertises credit_usage, but V2GroundMetadata now contains openapi_spec and billing instead. Keep the inline result schema consistent so generated documentation does not expose a nonexistent metadata field.

                      "description": "Request metadata (job_id, duration_ms, credit_usage)."

specs/v2-aide.json:2354

The ground-job result repeats the stale credit_usage description even though the referenced V2GroundMetadata schema exposes openapi_spec and billing. Correct this copy as well so the polling contract matches the synchronous contract.

                              "description": "Request metadata (job_id, duration_ms, credit_usage)."

+    if is_given(output_save_url) and output_save_url is not None:
+        body["output_save_url"] = output_save_url


+                cast_to=V2GroundResult,
+            )
+        except APIStatusError as exc:
+            raise_if_sync_timeout(exc)


+class AsyncGroundResource(V2ResourceMixin, AsyncAPIResource):
+    async def run(


+    # Deprecated: renamed to `schema_violation_error` upstream; retained for
+    # backward compatibility and populated only by older gateway responses.


-(`V2ExtractMetadata`): `job_id`, `model_version`, `duration_ms`, `doc_id`,
-`credit_usage`, `range_units`, `openapi_spec`, and `billing` (`V2ExtractBilling`
-with `input_markdown_chars` / `output_extraction_chars`).
+`output_ref` (deprecated; renamed to `schema_violation_error` upstream),


pyright reportUnnecessaryIsInstance: after the BaseModel branch returns, `value` is narrowed to `Mapping[str, object]`, so `isinstance(value, Mapping)` is always true. Return `dict(value)` directly; malformed runtime input still raises from `dict()`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

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

Comments suppressed due to low confidence (4)

src/landingai_ade/types/v2/extract_response.py:54

output_ref was not renamed to schema_violation_error: the former represented out-of-band output, while the latter reports a partial extraction caused by unsupported schema fields. Describing this as a rename gives callers the wrong migration guidance; document it as a removed legacy field instead.

    # Deprecated: renamed to `schema_violation_error` upstream; retained for
    # backward compatibility and populated only by older gateway responses.

docs/v2-testing.md:57

This repeats the incorrect claim that output_ref was renamed. output_ref represented out-of-band output; schema_violation_error is an unrelated partial-extraction diagnostic. Please describe output_ref as a removed legacy field instead.

`output_ref` (deprecated; renamed to `schema_violation_error` upstream),

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

The new async ground surface is untested: the added tests exercise only LandingAIADE, while comparable parse/extract resources have mocked AsyncLandingAIADE coverage in tests/api_resources/v2/test_async_smoke.py. Add async tests for the sync-style call and ground-job create/get/list/wait paths so await/routing/polling regressions are covered.

class AsyncGroundResource(V2ResourceMixin, AsyncAPIResource):

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

The synced /v2/ground/jobs request schema only defines extraction_metadata and structure (specs/v2-aide.json:2144-2174), and its completed-job schema has no output_url. Exposing output_save_url can therefore result in an ignored field or 422 instead of the promised out-of-band delivery. Remove this option from the helper/public ground-job APIs and docs, or first add it to the upstream contract and implementation.

    output_save_url: object = omit,

@@ -95,8 +98,9 @@ from landingai_ade.types.v2 import (

 - <code><a href="./src/landingai_ade/types/v2/job.py">Job</a></code> -- unified job shape: `job_id`, `status` (<code><a href="./src/landingai_ade/types/v2/job.py">JobStatus</a></code>: `pending` / `processing` / `completed` / `failed` / `cancelled`), `created_at`, `completed_at`, `progress`, `result` (a `V2ParseResponse` for parse jobs, a `V2ExtractResult` for extract jobs, or `None` until completion), `error` (<code><a href="./src/landingai_ade/types/v2/job.py">JobError</a></code>), `raw` (the full original envelope as a `dict`), and the `.is_terminal` property.


        markdown_url: Optional[str] | Omit = omit,
        model: Optional[str] | Omit = omit,
        strict: Optional[bool] | Omit = omit,
+        output_save_url: Optional[str] | Omit = omit,


chore(spec-sync): update V2 spec snapshot + regenerated reference models

8bbdfd8

Copilot AI review requested due to automatic review settings July 21, 2026 13:30

yzld2002 requested a deployment to spec-sync-contract July 21, 2026 13:30 — with GitHub Actions Waiting

Copilot started reviewing on behalf of yzld2002 July 21, 2026 13:30 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

feat(spec-sync): wire client.v2 to spec diff (AI)

02a0cef

Copilot AI review requested due to automatic review settings July 21, 2026 13:43

yzld2002 requested a deployment to spec-sync-contract July 21, 2026 13:43 — with GitHub Actions Waiting

Copilot started reviewing on behalf of yzld2002 July 21, 2026 13:43 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 22, 2026 03:15

tian-lan-landing requested a deployment to spec-sync-contract July 22, 2026 03:15 — with GitHub Actions Waiting

Copilot started reviewing on behalf of tian-lan-landing July 22, 2026 03:15 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

tian-lan-landing approved these changes Jul 22, 2026

View reviewed changes

tian-lan-landing merged commit 342870f into main Jul 22, 2026
5 of 6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

spec-sync: track V2 spec drift#122

spec-sync: track V2 spec drift#122
tian-lan-landing merged 3 commits into
mainfrom
spec-sync/v2

yzld2002 commented Jul 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		if is_given(output_save_url) and output_save_url is not None:
		body["output_save_url"] = output_save_url

		class AsyncGroundResource(V2ResourceMixin, AsyncAPIResource):
		async def run(

		# Deprecated: renamed to `schema_violation_error` upstream; retained for
		# backward compatibility and populated only by older gateway responses.

		@@ -95,8 +98,9 @@ from landingai_ade.types.v2 import (

		- <code><a href="./src/landingai_ade/types/v2/job.py">Job</a></code> -- unified job shape: `job_id`, `status` (<code><a href="./src/landingai_ade/types/v2/job.py">JobStatus</a></code>: `pending` / `processing` / `completed` / `failed` / `cancelled`), `created_at`, `completed_at`, `progress`, `result` (a `V2ParseResponse` for parse jobs, a `V2ExtractResult` for extract jobs, or `None` until completion), `error` (<code><a href="./src/landingai_ade/types/v2/job.py">JobError</a></code>), `raw` (the full original envelope as a `dict`), and the `.is_terminal` property.

Uh oh!

Conversation

yzld2002 commented Jul 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants