Word Formula Conversion

intent

convert manually typed formula text in Word documents (.doc, .docx, .wps) into editable Word equations while preserving document layout. use this skill for academic manuscripts, staged formula review, local batch conversion, or optional AI-assisted formula classification. formulas stay local by default. external AI classification happens only when you explicitly request it.

inputs

document file

• input word document (.doc, .docx, .wps)
• file must be readable on your local system
• no size limit enforced, but very large docs (>100 MB) may slow scanning

project workspace

• default: resources/latex_convert_project/
• contains CLI, scripts, and dependencies
• if you have a custom checkout, pass its path to commands

microsoft word or libreoffice

• required for .doc and .wps conversion
• windows/macos: word automation (COM) preferred, falls back to libreoffice if unavailable
• linux: libreoffice only
• must be installed locally, not in a container or remote session

optional: openai api key (for ai-assisted formula classification)

• env var: OPENAI_API_KEY
• required only if you use --provider ai in decide step
• base url defaults to https://api.openai.com/v1
• model defaults to gpt-4-mini

optional: custom ai endpoint

• --base-url: override openai endpoint (e.g., self-hosted llm)
• --model: specify model name your endpoint recognizes

procedure

step 1: scan the document

input: source word document (input.docx) output: candidates.json (list of formula candidates), optional candidates.docx (review doc with highlighted candidates)

run scan to locate all formula-like text in the document:

cd resources/latex_convert_project
python3 -m latex_convert.cli scan input.docx --out candidates.json --review-doc candidates.docx

the scanner identifies patterns matching likely formulas (math symbols, subscripts, superscripts, greek letters, operators). review candidates.docx to verify the scanner found real formulas and didn't over-match.

step 2a: decide locally (rule-based, no network)

input: candidates.json output: decisions.json (conversion decisions for each candidate)

classify candidates using built-in rules:

cd resources/latex_convert_project
python3 -m latex_convert.cli decide candidates.json -o decisions.json --provider rule

this converts formula candidates to openxml math markup using local heuristics. no external calls. fast. suitable for most documents.

step 2b: decide with ai assistance (optional)

input: candidates.json, openai api key output: ai_decisions.json (ai-classified decisions)

if you want ai to normalize latex or improve confidence scores:

cd resources/latex_convert_project
python3 -m latex_convert.cli decide candidates.json \
  -o ai_decisions.json \
  --provider ai \
  --api-key "$OPENAI_API_KEY" \
  --base-url "https://api.openai.com/v1" \
  --model "gpt-4-mini"

ai receives candidate id, formula text, nearby context, local latex draft, and confidence. the full word file is not sent. if the request times out or fails, the tool retries once and falls back to rule-based decisions automatically.

step 3: apply conversions

input: source document (input.docx), decisions.json or ai_decisions.json output: converted document (output.docx), apply_report.json (conversion log)

apply the conversion decisions to the source document:

cd resources/latex_convert_project
python3 -m latex_convert.cli apply input.docx --decisions decisions.json -o output.docx --report apply_report.json

the tool modifies only openxml formula nodes (math elements in the document.xml). it does not rebuild the document using high-level libraries. layout is preserved. the original source file is not modified.

step 4 (one-step alternative): direct conversion

input: source word document (input.docx) output: converted document (output.docx), report.json

if you want scan, decide, and apply in one call:

cd resources/latex_convert_project
python3 -m latex_convert.cli convert input.docx -o output.docx --report report.json

this uses rule-based decisions by default. suitable for quick batch jobs. does not create intermediate review or decision files.

step 5: verify output

input: output.docx, report.json output: visual confirmation

open output.docx in microsoft word or compatible editor. confirm:

• document layout matches original (no text reflow, image displacement, or style corruption)
• converted formulas are editable word equations, not images or plain text
• formulas render in word's native equation editor

check the report.json for summary:

• formulas_converted: count of successful conversions
• formulas_kept: count of text left unchanged
• failed: count of conversion errors

spot-check a few formulas: fractions, subscripts, superscripts, greek letters, summation, integrals, inequalities.

decision points

if you have .doc or .wps files (not .docx)

• windows/macos: cli tries microsoft word automation first (COM). if word is not installed or automation fails, it falls back to libreoffice. set --engine auto (default) to enable this fallback.
• linux: libreoffice is used. word automation is not available.

if you want to skip bibliography sections

• by default, bibliography protection is enabled. formulas inside <w:tblPr> or marked as bibliography are not converted. if your formulas appear inside the bibliography, disable protection: --skip-bibliography false.

if ai classification times out or fails

• the tool retries once internally. if the second attempt also fails, it falls back to rule-based decisions. no manual intervention required. the conversion completes using local rules.

if the output document doesn't open in word

• openxml corruption is rare but possible if the source document is malformed or uses uncommon word features. confirm the input document opens cleanly in word first. if it does, file a bug with the input, output, and report.json.

if you have no internet or want zero external calls

• use --provider rule in the decide step (step 2a). ai-assisted classification requires network access. rule-based classification is always local and fast.

if you want to review decisions before applying

• use the staged workflow (steps 1, 2a/2b, 3). after step 2a/2b, you can inspect decisions.json or ai_decisions.json manually before running apply. this is recommended for important manuscripts.

if you want to batch-convert multiple documents

• run convert or the staged pipeline once per file. no bulk mode yet. loop over your file list in bash or python.

output contract

candidates.json (output of scan)

{
  "document_path": "input.docx",
  "scan_timestamp": "2025-01-15T10:30:00Z",
  "candidates": [
    {
      "id": "cand_001",
      "text": "E=mc^2",
      "context": "Einstein proved that E=mc^2 in 1905.",
      "location": "paragraph_5",
      "confidence": 0.92
    }
  ]
}

decisions.json (output of decide with rule provider)

{
  "candidates_processed": 42,
  "decisions": [
    {
      "candidate_id": "cand_001",
      "action": "convert",
      "latex_draft": "E = mc^2",
      "openxml_markup": "<m:oMath>...</m:oMath>",
      "confidence": 0.92
    }
  ],
  "provider": "rule"
}

ai_decisions.json (output of decide with ai provider)

• same structure as decisions.json, with "provider": "ai"
• includes ai-normalized latex and revised confidence scores

output.docx (output of apply or convert)

• binary word document
• formulas replaced with openxml math elements
• layout and styles preserved from source
• opens in microsoft word 2016 or later, libreoffice writer 6.0+, google docs (may not edit equations natively)

apply_report.json (output of apply or convert)

{
  "document_path": "input.docx",
  "output_path": "output.docx",
  "conversion_timestamp": "2025-01-15T10:35:00Z",
  "summary": {
    "formulas_converted": 40,
    "formulas_kept": 2,
    "failed": 0
  },
  "conversions": [
    {
      "candidate_id": "cand_001",
      "status": "success",
      "original_text": "E=mc^2",
      "formula_type": "equation"
    }
  ]
}

candidates.docx (output of scan, optional)

• copy of the source document with formula candidates highlighted or marked for visual review
• useful for validating scanner output before deciding

outcome signal

• document opens cleanly: output.docx loads in word without corruption or recovery dialogs
• formulas are editable: double-click a converted formula in word's equation editor. the formula opens as an editable math object, not an image or static text
• layout unchanged: compare output.docx to input.docx side-by-side. text, page breaks, images, tables, and styles match
• report confirms conversions: apply_report.json shows formulas_converted > 0 and failed == 0
• spot-check passes: manually inspect 3-5 converted formulas for correct brackets, subscripts, superscripts, and symbols
• no ai errors on fallback: if you used ai classification and