feat(v2): type the parse ParseResponse structure & grounding trees

[yzld2002]

Summary

The V2 gateway now publishes a typed ParseResponse for POST /v2/parse (confirmed against the updated dev OpenAPI spec). Previously structure and grounding were modeled as loose Optional[object] (raw dicts). This PR models them as proper typed trees so callers get attribute access + autocomplete instead of dict indexing.

Follow-up to #106 (which covered service_tier + billing).

New models (types/v2/parse_response.py)

Field	Before	After
structure	Optional[object]	V2ParseStructure → V2ParsePage → V2ParseElement
grounding	Optional[object]	V2ParseGrounding → V2ParseGroundingPage → V2ParseGroundingElement → V2ParseGroundingEntry

V2ParseElement and V2ParseGroundingElement are self-recursive (a table's children are its table_cells).

r = client.v2.parse(document=...)
page = r.structure.children[0]
page.width, page.status                      # 800, "ok"
cell = page.children[1].children[0]
cell.row, cell.col, cell.colspan             # typed ints
box = r.grounding.children[0].children[0].box  # [left, top, right, bottom]

Why it's safe / not breaking

• client.v2 is unreleased — additive typed surface, no released consumers.
• Deliberately permissive to avoid deserialization failures on spec drift: element type and page status are plain str (not Literal), spans/boxes are List[int], all non-required fields default, and BaseModel's extra="allow" keeps unknown keys. structure/grounding remain Optional.

Note on tolerance

The old test_parse_response_tolerates_loose_shape fed structure=[{"type":"text"}] (a bare list) to assert the maximally-loose object contract. That contract is what we're intentionally tightening, so the test was updated (test_parse_response_builds_from_dicts) to build from the real typed shape while still covering metadata/billing tolerance and unknown-key retention.

Test plan

• TDD: typed-access + tolerance tests added first (red), then models implemented (green)
• New tests: full nested structure/grounding typed access; unknown element type + extra keys tolerated
• ✅ Full suite: 587 passed, 240 skipped
• ✅ ruff check ., mypy . (77 files), and import landingai_ade all clean

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a typed ParseResponse surface for client.v2.parse() by replacing the previously loose structure/grounding objects with explicit, recursive tree models that mirror the gateway schema, and updates tests/docs accordingly.

Changes:

• Introduces typed V2ParseStructure/V2ParseGrounding model trees (document → page → element/entry) on V2ParseResponse.
• Updates V2 parse tests to validate typed attribute access and tolerance for unknown element types/extra keys.
• Exposes the new models from landingai_ade.types.v2 and documents them in api.md.

Reviewed changes

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

Show a summary per file

File	Description
src/landingai_ade/types/v2/parse_response.py	Defines the new typed structure/grounding tree models and updates V2ParseResponse to use them.
src/landingai_ade/types/v2/__init__.py	Re-exports the new parse/grounding model types from the v2 types package.
tests/test_v2_types.py	Updates the parse response type test to build from dicts matching the new typed shape.
tests/api_resources/v2/test_parse.py	Adds richer mocked parse responses and assertions for typed access and tolerance behavior.
api.md	Documents the newly exported parse/grounding tree types and their relationships.

---

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

[Copilot]

Pull request overview

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

[yzld2002]

Thanks for the review. All six comments point at the same thing — mutable [] defaults on the list fields — so addressed together in bcb1b72.

Verification first: the specific "shared list across instances" leak doesn't reproduce on this SDK's construct_type fast path — each constructed instance gets a fresh list and mutating one doesn't affect another (defaults are copied). So it wasn't an active bug.

Applied anyway because it's the right convention: switched all five non-optional list fields (V2ParsePage.children, V2ParseStructure.children, V2ParseGroundingElement.parts, V2ParseGroundingPage.children, V2ParseGrounding.children) to Field(default_factory=list), matching the existing repo pattern (Job.raw uses Field(default_factory=dict)) and the Field import is now present. The Optional[...] = None recursive children fields were already fine (no mutable default).

Tests + ruff/mypy green.

[Copilot]

Pull request overview

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

[yzld2002]

Correction to my previous comment: I initially applied Field(default_factory=list), but it breaks the repo's strict pyright gate — a bare list factory infers list[Unknown], which pyright reports as "Type of children is partially unknown" against the List[TypedModel] annotation. (Job.raw gets away with default_factory=dict only because its value type is object, which absorbs Unknown; that doesn't hold for List[V2ParseElement] etc.)

So I've reverted to literal = [] defaults (ef3e256). This is:

• pyright-clean (verified: 0 errors in the file),
• safe on this SDK — I confirmed the shared-mutable-default leak does not reproduce on the construct_type fast path: two constructed instances get separate lists and mutating one doesn't affect the other.

Net: the review's underlying concern (cross-instance list sharing) is real in general but doesn't manifest here, and the suggested fix conflicts with the type-checker config — so the literal default is the correct form for this codebase. ruff/mypy/pyright and the full test suite are green.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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