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. Do not use it to get data out of documents (that's an extraction task), to produce a single bespoke letter (just edit one document), or where the host environment mandates a different document pipeline.

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)

1. Analyse the master. Read it with read_content(path) and identify the parts that vary row to row — names, salutations, amounts, dates, reference numbers — versus the boilerplate that stays fixed. read_content shows repeated paragraph text once with a (×N) count — that's how many places tokenise will replace it (e.g. a name in both the body and the header). See references/tokenising-guide.md for what to tokenise and how to name tokens well.
2. Propose a tokenised template. Build a mapping of each varying phrase → a token name, and present it to the user as a plain list ("Ms Jordan Lee → {{Name}}, $1,000,000 → {{Amount}}, …"). Token names should match the data file's column headers where possible — that makes the mapping automatic.
3. Confirm with the user. Show the proposed tokens (and, if helpful, save the tokenised template and show its text) and wait for explicit confirmation before generating anything. This is the review gate — get the template right once, then fan it out.

   from fill_template import read_content, tokenise, tokens_in, load_rows, generate
   
   print(read_content("Letter_master.docx"))                       # step 1
   
   rep = tokenise("Letter_master.docx",                            # step 2
                  "Letter_tokenised.docx",
                  [{"find": "Ms Jordan Lee", "token": "Name"},
                   {"find": "$1,000,000",    "token": "Amount"},
                   {"find": "01 Jul 2026",   "token": "EffectiveDate"},
                   {"find": "REF-0001",      "token": "Reference"}])
   # rep["not_found"] lists any phrase that wasn't located — fix those before generating.
   print(tokens_in("Letter_tokenised.docx"))
   

   tokenise finds each exact phrase and replaces it with {{Token}}, preserving the formatting of the run/cell it sits in (a bold figure stays bold). It reports a hit count per token and flags any phrase it could not find, so a typo in the find text is caught before you generate 200 letters.
4. Load the data and check the mapping. headers, rows = load_rows("recipients.xlsx"). The token→column map defaults to token name == column header (case-insensitive); override any that differ. Any template token with no column, or a mapped column blank for a given row, becomes a visible «MISSING: Token» flag — never a guess.
5. Generate one file per row.

   report = generate(
       "Letter_tokenised.docx", rows,
       token_to_column={"Name": "Recipient"},   # only the ones whose token != column
       outdir="out",
       name_pattern="Letter_{Recipient}",
   )
   

   report lists every file written, the rows skipped (e.g. a name-pattern column missing from the data), any unmapped_tokens, and per-file missing tokens.
6. Report back honestly. Tell the user how many files were produced and where, and surface every missing flag and unmapped_tokens entry so blanks are dealt with before the batch is used. Outputs are drafts for a person to review before they go out.