spec-sync(v2): parse: add confidence to word-level atomic grounding

[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.

What changed

AI-generated from the PR diff — verify against the actual changes.

This PR adds a confidence field to word-granularity atomic grounding segments in parse responses; the spec snapshot also gains new /v1/extract* routes but those are not wired into the client surface.

Changes:

• Added optional confidence field to V2ParseNodeGrounding, populated only on word-granularity (dpt-3-fast) atomic_grounding entries.
• Updated documentation for atomic_grounding to clarify granularity varies by model (line-level for dpt-3-pro, word-level for dpt-3-fast) and to describe the new confidence semantics, including the empty-list cases for table cells.
• Clarified that table-cell atomic_grounding may be [] when word offsets can't be reliably located in escaped pipe/HTML table text.
• Spec snapshot gained new /v1/extract, /v1/extract/build-schema, and related job-polling routes plus V1ExtractMetadata/V1BuildSchemaMetadata models, but these are not exposed through the SDK client.

[Copilot]

Pull request overview

Updates the mirrored V2 OpenAPI snapshot and regenerated reference models to track upstream drift.

Changes:

• Refreshes the V2 specification snapshot.
• Regenerates reference Pydantic models from the updated specification.

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 mirrored upstream specification.
specs/_generated/v2_models.py	Regenerates reference models from the snapshot.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (1)

tests/contract/test_v2_smoke.py:104

• This live test can pass without exercising the new field: it does not select dpt-3-fast, and it never requires an atomic segment or a non-None confidence. A default line-granularity response—or a regression that drops all confidence values—therefore leaves the test green. Request the word-granularity model and require at least one segment plus a valid confidence on every returned segment.

    resp = staging_client.v2.parse(document=pdf, options={"atomic_grounding": True})

[Copilot]

Pull request overview

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

Suppressed comments (2)

tests/contract/test_v2_smoke.py:105

• This contract test can pass without exercising the new wire field: it neither selects dpt-3-fast nor requires any atomic segment or confidence value to exist. A line-granularity response, an empty atomic_grounding, or a client that drops confidence all satisfy the current assertions. Request the word-granularity model and require at least one bounded confidence value so the staging contract is actually verified.

def test_parse_atomic_grounding_confidence(staging_client: LandingAIADE) -> None:
    # `atomic_grounding` segments carry an optional per-segment `confidence` in
    # [0, 1] on word-granularity models (`dpt-3-fast`); line-granularity models
    # omit it. Tolerate either: assert every present value is a valid probability.
    pdf = Path(__file__).parent / "sample.pdf"
    resp = staging_client.v2.parse(document=pdf, options={"atomic_grounding": True})

docs/v2-testing.md:47

• The PR description says the table-cell empty-list cases are documented, but this guide only explains when the field is omitted. Consumers still cannot tell that [] is expected for table cells on line-granularity models or when escaped pipe/HTML rendering prevents reliable word offsets. Add those cases here (and the suppressed-Markdown case) to keep the reviewable SDK documentation aligned with the stated behavior.

    Each segment reuses the node-grounding shape (`page`, `range`, `box`) and, on
    word-granularity models only, an optional `confidence` in `[0, 1]` (the
    lowest per-character OCR confidence in the word; `None` on line-granularity
    models and on node-level grounding). Omitted when `options.atomic_grounding`
    is `false`.