spec-sync(v2): parse: add per-word atomic_grounding confidence score

[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 score to word-granularity atomic_grounding segments in parse responses, alongside a spec-only addition of the (unimplemented) /v1/extract/build-schema routes.

Changes:

• V2ParseNodeGrounding gains an optional confidence field ([0, 1]), populated only on word-granularity atomic_grounding entries from dpt-3-fast, and None elsewhere.
• atomic_grounding documentation updated to clarify granularity varies by model: one entry per line for dpt-3-pro, one per word for dpt-3-fast.
• Documented new edge case where atomic_grounding can be [] for table_cell elements on word-granularity models when word offsets can't be reliably located.
• docs/v2-testing.md updated to describe the new confidence field and per-model granularity behavior.
• Spec snapshot also adds /v1/extract/build-schema (and its jobs sub-routes), but this surface is not wired into the client and is not part of this PR's SDK changes.

[Copilot]

Pull request overview

Updates the automated V2 specification snapshot and regenerated reference models to track upstream drift.

Changes:

• Refreshes the V2 OpenAPI snapshot.
• Regenerates reference models, including updated grounding metadata and endpoint schemas.

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 V2 specification snapshot.
specs/_generated/v2_models.py	Regenerates Python 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 (2)

tests/contract/test_v2_smoke.py:113

• This call uses the documented default DPT-3 Pro model (README.md:88), whose line-granularity segments do not carry confidence. Since the assertion below is conditional, this contract test can pass without ever observing the new field. Request dpt-3-fast and require at least one non-None confidence value.

    resp = staging_client.v2.parse(document=pdf, options={"atomic_grounding": True})
    assert isinstance(resp, V2ParseResponse)
    assert resp.structure is not None and resp.structure.children

docs/v2-testing.md:47

• The PR description says this guide documents the new empty-list edge case, but this paragraph only explains when the field is omitted. Document that table_cell.atomic_grounding can legitimately be [] when word offsets cannot be located in escaped rendered table text, so consumers do not treat that response as malformed.

  - Leaf elements additionally carry `atomic_grounding` -- a list of
    `V2ParseNodeGrounding` segments at whichever granularity the model reads at:
    one entry per visual line for `dpt-3-pro`, one per word (each with its
    `confidence`) for `dpt-3-fast`. Omitted when `options.atomic_grounding` is
    `false`.

[yzld2002]

⚠️ New V2 spec drift beyond this PR (live-spec cbd7ba918a89). This PR is a snapshot of earlier drift and is now stale relative to the live spec — merge or close it and the next spec-sync run will open a fresh PR covering the rest.