Office files and legacy Word (.doc)
Users sometimes upload old Word files (.doc, the Word 97–2003 format). The agent's document tools only understand the modern .docx format, so AION converts .doc files to .docx automatically at upload time, using LibreOffice on the server. Users do not have to do anything. This page is for administrators (who must make sure LibreOffice is installed) and developers (conversion flow and API fields).
Why conversion on the API host?
Legacy .doc files (Word 97–2003, OLE binary) are not OpenXML ZIP archives. Tools that work on .docx — unpack.py, docx2txt, docx-js — cannot read them.
Design choice: convert once at upload time on the API process (same host as FastAPI), not in the session sandbox:
| Approach | Problem |
|---|---|
Sandbox soffice.py | LibreOffice is not installed in the sandbox; agent must discover conversion and often fails |
docx2txt / unpack on .doc | Wrong format — expects ZIP/OpenXML |
| User manual re-save | Poor UX for chat uploads |
Production Docker images ship libreoffice-writer-nogui in docker/Dockerfile.backend. Local dev on macOS: brew install --cask libreoffice.
Conversion runs in src/tools/office_convert.py, triggered from src/api/session_uploads.py and src/api/v1/files.py via apply_legacy_word_conversion().
Upload flow
- File is stored under
uploads/<uuid>_<name>(plus stable aliasuploads/<original_name>). - If extension/MIME indicates legacy Word,
sofficeconverts toderived/converted/<stem>.docx. - Response JSON and chat
attachments/turn_attachmentsinclude:legacy_word: trueconversion_status:ok|unavailable|failedconverted_docx_path: e.g.derived/converted/report.docx(whenok)
AgentPipeline._format_attachments_blockinjects a prompt block telling the agent to use only the.docxpath (never unpack the binary.doc).
Misnamed files (.doc extension but ZIP/OpenXML payload) are copied to .docx without LibreOffice.
Environment variables
| Variable | Default | Description |
|---|---|---|
AION_OFFICE_AUTO_CONVERT_LEGACY_WORD | 1 | Enable auto-conversion on upload |
AION_SOFFICE_PATH | (auto) | Explicit path to soffice if not on PATH |
AION_OFFICE_CONVERT_TIMEOUT_SEC | 90 | Max seconds per conversion |
macOS dev example:
AION_SOFFICE_PATH=/Applications/LibreOffice.app/Contents/MacOS/soffice
Ubuntu / Docker: soffice is on PATH after libreoffice-writer-nogui is installed.
Agent workflow
- User uploads
report.doc. - Agent sees in the attachments block:
derived/converted/report.docx. skill_view("docx")→ unpack/edit/pack on the.docxpath only.- Deliver corrected file from
workspace/oruploads/after pack.
Do not run scripts/office/soffice.py --convert-to docx in the sandbox for uploads — conversion is already done (or failed with a clear conversion_status).
See also Skills and system prompt (docx skill) and Filesystem policy (allowlisted python for office scripts on .docx only).
MCP registry merge (new builtins)
config/mcp_registry.yaml is never overwritten by sync_config.py --force (local marketplace servers stay intact). New std servers (e.g. geocoding) are merged with:
python scripts/merge_mcp_registry_from_std.py
This runs automatically from:
scripts/dev-api.shscripts/setup_core.py(aftersync_mcp_servers.py)docker/backend-entrypoint.sh(withAION_SYNC_ON_BOOT=1)
Use --dry-run to list slugs that would be added.
Troubleshooting
conversion_status: unavailable
LibreOffice not found on the API host (not the sandbox).
- Docker: rebuild backend image (
docker compose build backend) solibreoffice-writer-noguiis present. - macOS dev:
brew install --cask libreofficeand optionally setAION_SOFFICE_PATH. - Re-upload the
.docafter fixing the host (or send a new chat message — retry runs if manifest wasunavailable).
Agent still calls soffice in sandbox
Reload profile/skill or restart backend after upgrading; proprietary docx skill documents API-side conversion. Ensure converted_docx_path is present in turn_attachments (chat-ui passes upload response fields).
New MCP missing in Admin → Profiles
Run python scripts/merge_mcp_registry_from_std.py and restart the API.
For PDF → Word reports with evidence screenshots, see PDF evidence images.
Related source files
| File | Role |
|---|---|
src/tools/office_convert.py | LibreOffice conversion logic |
src/tools/office_auto_convert.py | Async wrapper + manifest persistence |
src/agent_pipeline.py | Attachments block hints for legacy Word |
docker/Dockerfile.backend | libreoffice-writer-nogui package |
scripts/merge_mcp_registry_from_std.py | Merge new MCP slugs from config_std |