fill-template

Fill Template (mail-merge)

Turn one master template + a data table into many filled copies — one per row — swapping only the parts that vary and leaving the master's layout and styling untouched. Document generation only: nothing is sent, posted or signed.

Scope and routing

Use this skill when the user has one template and a list, and wants a filled copy per row; or when they have a filled/example .docx and want a reusable tokenised template derived from it (extract_template). Do not use it to produce a single bespoke letter (just edit one document), or where the host environment mandates a different document pipeline. Extract of .xlsx forms is out of scope this round.

Inputs the user provides

1. The master template — a .docx letter or form, or a .xlsx form. One master per run. This is the source of truth for layout and styling.
2. The data table — a .xlsx or .csv, one row per output, with a header row. Columns supply the values that vary (names, amounts, dates, references…).
3. (Optional) a naming pattern — how each output file is named, e.g. Letter_{Name}. Defaults to <template>_<row-number>.

Workflow (do this, in order)

If the user hands you a filled example rather than a master, run extract first (step 0), show ext["mapping"], and wait for confirmation before generating. Otherwise start at step 1.

1. Extract from a filled .docx (optional reverse path). extract_template(src, out_dir, name=None) writes <name>_tokenised.docx and <name>_data.csv (name defaults to the source stem) and returns a report. Varying values become {{Token}} using the same run-aware replacement as tokenise. The CSV has one row per repeating instance. Show report["mapping"] (literal → token → where) and any report["uncertain"] entries — those spans were left literal rather than guessed. Token names come only from five typed shapes: after Dear → Recipient; $… → Amount; INV-123 → InvoiceRef; dates like 12 Mar 2026 → Date; ACME-0042 → AccountRef. Collisions become Amount2, …. Untyped variation is left literal — a generic Value1/Value2 fallback is not implemented; fall back to manual tokenise for those fields. Then continue from step 3 with the extracted template and skeleton, or let the user edit the mapping and re-tokenise.

   from fill_template import (
       read_content, tokenise, tokens_in, load_rows, generate, extract_template,
   )
   
   ext = extract_template("filled_letters.docx", "extracted")
   print(ext["mapping"])       # confirm-before-reuse digest
   print(ext["uncertain"])     # left literal; do not invent