Prefer uv for dependency management.
Python packages:
uv pip install python-docx pdf2image
If uv is unavailable:
python3 -m pip install python-docx pdf2image
System tools (for rendering):
# macOS (Homebrew)
brew install libreoffice poppler
# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils
If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.
Environment
No required environment variables.
Rendering commands
DOCX -> PDF:
soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX
PDF -> PNGs:
pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME
Bundled helper:
python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages
Quality expectations
-
Deliver a client-ready document: consistent typography, spacing, margins, and clear hierarchy.
-
Avoid formatting defects: clipped/overlapping text, broken tables, unreadable characters, or default-template styling.
-
Charts, tables, and visuals must be legible in rendered pages with correct alignment.
-
Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
-
Citations and references must be human-readable; never leave tool tokens or placeholder strings.
Final checks
-
Re-render and inspect every page at 100% zoom before final delivery.
-
Fix any spacing, alignment, or pagination issues and repeat the render loop.
-
Confirm there are no leftovers (temp files, duplicate renders) unless the user asks to keep them.