feat(format): B3.5 — PDF smart-fit rewrite + critical fontname=None fix
All checks were successful
Deploy to Production / Build and Deploy (push) Successful in 2m44s

ROOT CAUSE FIX: PyMuPDF silently raised AttributeError when fontname=None
was passed to insert_textbox. The try/except in _try_insert was swallowing
the error and returning None, causing every block to be skipped via the
graceful failure path. Setting fontname='helv' as the default unblocks
the entire PDF translation pipeline.

SMART-FIT: rewrite _write_translated_block with proper tier-fallback:
  - Tier 0: original bbox at original size
  - Tier 1: expanded horizontal
  - Tier 2: expanded vertical (3x original height)
  - Tier 3: shrink once (0.93x)
  - Tier 4: shrink twice (0.87x cumulative)
  - Tier 5: min size floor (90% for headings, 75% for body)
  - Tier 6: graceful skip with visible placeholder

REDACTION: single redaction per block (was per sub-bbox, creating 100+
redaction rectangles per page). Now only 1 redaction per text block.

FEATURE FLAG: PDF_SMART_FIT_ENABLED (default true, observation-first).

METRICS: text_overflow -> format_elements_lost_total.

RESULT ON REAL PDF:
  Before: fonts shrunk 22pt->5.6pt, hierarchy destroyed
  After:  fonts EXACT match: [8, 11, 12, 14, 16, 22] preserved
This commit is contained in:
2026-07-14 18:36:12 +02:00
parent 12cd0c6893
commit e706cef5d6
16 changed files with 1294 additions and 62 deletions

View File

@@ -104,6 +104,19 @@ class Config:
# When true, only Pro+ plans can use L2. Otherwise, all plans can.
QUALITY_L2_TIER_GATE = os.getenv("QUALITY_L2_TIER_GATE", "true").lower() == "true"
# ============== PDF Smart-Fit (Track B3.5) ==============
# When true, the PDF translator uses a smart overflow strategy:
# 1. Try original bbox at original size
# 2. Expand bbox vertically (3x original height)
# 3. Shrink font ONCE (0.93x) with expanded bbox
# 4. Shrink font AGAIN (0.87x cumulative) with expanded bbox
# 5. For headings (font >= 14pt): never below 90% of original
# 6. For body: never below 75% of original
# 7. If still overflow: skip block, log format_loss, write placeholder
#
# Set to false to use the legacy aggressive-shrink strategy (NOT recommended).
PDF_SMART_FIT_ENABLED = os.getenv("PDF_SMART_FIT_ENABLED", "true").lower() == "true"
# ============== API Configuration ==============
API_TITLE = "Document Translation API"