v2.4.3

PDF Craft v2.4.3

PDF Craft 2.4.3 fixes footnote extraction and translation, including invalid XML
created during translation writeback and missing translated footnotes in PDF
output. It also fixes unbounded waits in optional LLM-assisted table-of-contents
analysis after OCR. LLM operations now have a default total time budget, with
separate allowances for resource cleanup.

Footnotes and translation

• Inline references retain their position inside text fragments through XML
  segmentation, response validation and writeback. This fixes the
  ValueError: <text> contains unknown element: <ref> failure, which could occur
  even when a translation returned the original text unchanged.
• Body text and footnotes now have distinct source identities. Reclassifying
  OCR text preserves its complete original content, printed marker and reading
  position, including column order and full-width blocks.
• Cross-page footnote edits preserve existing definition identities and source
  members. Each continuation has one editable incoming connection; invalid LLM
  candidates are rejected during business validation before being accepted.
• A footnote definition can have multiple references or no matched reference.
  Supported star markers are recognized, unmatched definitions are retained,
  and unresolved text is preserved instead of silently disappearing.
• Translated footnote paragraphs participate in translation coverage and are
  written into PDF output with their printed markers, once per source paragraph.
  Existing PCEX archives and translation layers retain their stored identities;
  the archive format and public configuration APIs are unchanged.

See #508 and
#509.

LLM timeouts and recovery

• Added keyword-only LLM(total_timeout=360.0). Capacity waiting, streaming,
  transport retries and retry backoff share this budget. TOC JSON, schema and
  business-validation repair attempts also share one budget instead of each
  receiving a fresh timeout.
• timeout retains its HTTP connect/read/write/pool timeout meaning. A stream
  that keeps sending data can no longer extend the total operation indefinitely.
  timeout=None does not disable the total budget; use total_timeout=None
  explicitly to opt out. These settings apply to translation requests as well.
• Added LLM(cleanup_timeout=5.0): stream close and client exit each receive half
  of this additional allowance. Slow cleanup no longer waits without a timeout;
  cancellation propagates without detaching cleanup tasks.
• TOC LLM failures, including total-budget exhaustion, fall back to statistical
  analysis so EPUB generation can continue. Caller cancellation propagates
  instead. EPUB output alone does not enable LLM requests.

The budgets rely on a responsive event loop and transports that cooperate with
cancellation. They do not impose a hard deadline on the entire PDF conversion.
Applications still own service watchdogs and failed-task state transitions.

See #506 for the initial deadline
fix and #507 for the follow-up
cleanup and configuration changes.

Logging and verification

• Structured LLM events report requests, retries, success, timeout, failure,
  cancellation and cleanup timeout. Without log_dir_path, events propagate to
  the pdf_craft.llm parent logger; with a directory, they are written to request
  log files.
• Regression coverage includes streaming deadlines, combined transport and TOC
  repair budgets, slow cleanup, repeated cancellation, executor capacity reuse,
  fallback behavior, and synchronous/asynchronous EPUB conversion with and
  without a TOC LLM. Tests use simulated transports, without external API calls
  or OCR model downloads.
• Updated the English and Chinese API references for the timeout options and
  cancellation guarantees.
• Footnote regression tests cover source identity, reading order, ownership
  changes, repeated and unmatched references, cross-page member preservation,
  and translated PDF output. Independent verification on citation_large.pdf
  completed all 26 pages with live JEV review and LLM footnote refinement;
  all 22 references and definitions survived translation, and translated text
  probes for all 32 footnote paragraphs were found in the corresponding PDF pages.

Full Changelog: v2.4.2...v2.4.3