uvrt/docx-agent

An AI-editable Word (.docx) layer for Python: inspect a document, change it through a
semantic API (optionally as tracked changes), read and write it through Markdown that
carries stable ids, render the pages back, repeat. The counterpart of
pptx-agent for Word.
It builds on ooxml-edit (the lxml-based OPC
package, ordered insertion and undo, and its charts subpackage) and renders and lays out
through docx2svg.
To give a model the document as tool calls (Claude, or OpenAI's Responses and Chat
Completions APIs): using the tools with a model provider.
Install
Not on PyPI yet. Python 3.10+. The siblings install from git:
Fonts
Rendering and reflow feedback lay the document out with docx2svg, which measures every
glyph with the face Word uses. Install the document's faces where the layout runs:
- **Office installed:** nothing to do.
- **No Office:** install the open metric compatible substitutes (Debian/Ubuntu: sudo
apt-get install fonts-crosextra-carlito fonts-crosextra-caladea fonts-liberation;
macOS: brew install --cask font-carlito font-caladea font-liberation). With Carlito in place
of Calibri, and Liberation Sans, Serif and Mono in place of Arial, Times New Roman and
Courier New, lines and pages break where they do in Word. Symbol and Wingdings bullets are laid out from
metrics recorded from Word's copies.
- **Without a face and its substitute** (Aptos, Cambria, Calibri Light...), the layout
stops at the first paragraph in that face, and everything after it is unknown, never
guessed.
docx2svg reports every substitution, and never uses a substitute when the real face is
installed. Details and the fidelity to expect:
docx2svg's README.
check (with reflow), render and save_document return the layout's **coverage**,
so a check that passed is told apart from one that could not see everything. It holds:
- complete
- the pages laid out, with Word's saved page count when the layout stopped
- the blocks laid out, out of the total
- where the layout stopped, by block id
- header and footer stops
- the faces substituted or missing
In the library, doc.layout().coverage_facts() returns the same.
The user's regional settings -- the separator a decimal tab stop aligns on, a chart's
decimal and thousands separators, the language of new chart text in a document that states
none, a new document's language and number separators -- are Document.locale (or
Toolbox(locale=...)), an ooxml_common.locales.Locale; en-US unless given, never the
server's own.
Example
python
doc = Document.open("report.docx")
for address, record in doc.provenance().items():
print(address, record["source"], record.get("document")) # t:60D6847F d:checks budget.xlsx
More recipes -- find and replace, tracked changes, comments, revisions, Markdown in the
template's own styles, tables, pictures, charts, sections, rendering, templates,
validation -- each run as written by the tests: docs/common-tasks.md.
What is supported
- **Library:** phases E0 to E6 of ROADMAP.md, and charts and SmartArt: text
ranges and anchors, find and replace across runs, styles and direct formatting, lists,