PDFCLOUD-5523 Direct extract text to Pydantic models

[datalogics-kam]

PDFCLOUD-5523

Please review/merge #23 first

Summary

This PR makes JSON text extraction a first-class SDK experience by adding typed
extract_pdf_text APIs (sync + async), rich response models, and full test/live
coverage. The goal is to let consumers work directly with structured text, word
coordinates, and style metadata without manual JSON parsing.

Intent and Outcomes

Why

Today, extracted-text workflows are harder than they need to be when callers want
structured word/page data. They must rely on lower-level handling or file-based
flows.

What this enables

• Callers can now request extracted text as a typed Python object directly.
• Word-level metadata (coordinates/style) is easier to consume safely.
• The feature is validated across sync/async unit tests and live integration tests.
• A runnable example demonstrates real-world usage and output rendering.

Key Changes

Client API

• Added extract_pdf_text(...) -> ExtractedTextDocument to:
  • PdfRestClient
  • AsyncPdfRestClient
• Supports options for:
  • pages
  • full_text (off, by_page, document)
  • preserve_line_breaks
  • word_style
  • word_coordinates
  • request customization (extra_query, extra_headers, extra_body, timeout)

Models

• Introduced public extracted-text model hierarchy (exported via pdfrest.models)
  for structured parsing and safer downstream usage, including:
  • document-level payload
  • full-text document/page representations
  • word, coordinates, font, and color structures

Testing

• Added dedicated unit coverage for extract_pdf_text:
  • sync + async success cases
  • both pages omitted/provided paths
  • request customization propagation
  • invalid option/path validation
  • server error translation
• Added dedicated live tests under tests/live/:
  • sync + async success matrices across supported option combinations
  • negative invalid-pages cases that reach the server
• Added model-focused tests for extracted-text schema behavior and round-trip
  serialization.

Examples & Developer Experience

• Added examples/extract_text/extract_pdf_text_example.py showing practical usage
  with word coordinates/style rendered in a Rich table.
• Updated examples README with the new extraction example.
• Added rich as a dev dependency for example output formatting.

Repo Hygiene

• .gitignore updated to ignore /coverage.json.

Behavior Notes

• No breaking changes to existing endpoints.
• This extends the API surface with a more ergonomic typed pathway for extracted
  text JSON results.

Validation

• Unit tests added for client + model behavior.
• Live tests added for sync/async parity and server-side error cases.
• Lint/type checks were used during iteration (ruff, basedpyright) and
  targeted test modules were run while fixing coverage branches.

CI / Workflow Impact

• No workflow file changes in this PR.
• Existing CI behavior remains:
  • pre-commit workflow
  • Test and Publish matrix on Python 3.10–3.14
• This PR is expected to run within the existing matrix and checks.