formcast

formcast is a Python library. It turns a blank PDF form and a JSON Schema into a template, and a template, the blank form and a record into a filled PDF with a report. This page runs the fill in your browser, and the detector too where the device allows (elsewhere, such as on phones, it plays back the detector's saved results), but not the agent. For each sample form, Auto map loads the mapping the agent built for it in the eval and pairs it with your boxes by position; on a PDF of your own you link the boxes by hand. Fill shows the filled PDF on the page, the same file Download saves.

1 · Page map. The form first becomes a page map: its words and lines of text with their positions, the form fields it already has, the printed rules near each blank, and the boxes the CommonForms detector proposes. Each box comes with its nearest label. A page without a usable text layer is read with OCR.

2 · Agent. An AI model gets the page map as compact text and writes Python that runs against it. Query helpers find words, the text to the right of or below an item, and the candidate boxes on a page. Edit operations link a box to a schema path, add or split boxes, group choices and build tables. The agent starts from a seeded template, one box per form field and per detector box, and edits it step by step; each step reports what changed and what was refused.

3 · Template. The result is JSON: every box with its page, position and type, the schema path it reads, and any transforms, such as a date format or a tick when a value is true. A person reviews and corrects it, and it reruns on new records with no model call.

4 · Fill. Filling writes real PDF form fields, so the output is still a form. The fill report lists text that had to shrink or didn't fit, and record data with no box to go in.

Here, the agent's work is replayed, not run. The detector only proposes boxes. For each sample form, the agent built a template in the eval on the form as published; Auto map takes that mapping and pairs each of its fields with the box the detector found on the same blank. What it can't pair, and every box on a PDF of your own, you link by hand, and you can add the boxes the detector missed and fix or remove the wrong ones.

In the library, the agent does it with tools, without vision. It never sees the page image. It reads the page map as text and geometry and works through the edit operations. Its tools are built for:

• linking each box to a schema path, with transforms where the form needs them;
• adding the fields the detector missed, most often checkboxes, signature lines and date lines;
• reading an underline in front of an option as a checkbox to mark;
• splitting one long line into parts using the small labels under it, such as street, city, state and ZIP;
• marking “circle one” choices, grouping choices, and building tables from rows of cells.

How well it does these is measured under Results.

It keeps the detector's boxes. Without the image, the agent placed boxes worse than the detector: in earlier runs most of its moves and resizes left a box further from its blank. With the current code it can't move or resize a detected box, and it is told to add a box only where none sits on or next to a blank. Its job is the mapping.

Loading the results…

CommonForms. The detector is FFDNet from CommonForms, by Joe Barrow (the paper). Its dataset is Apache-2.0. This page loads the model weights from the author's Hugging Face pages, FFDNet-S and FFDNet-L, and only when you run the detector.

Libraries. pdf.js (Apache-2.0) draws the page, ONNX Runtime Web (MIT) runs the model and pdf-lib (MIT) writes the filled PDF. They are copied into the page, not loaded from a CDN.

Sample forms. The W-9, W-4 and I-9 are US federal government forms, in the public domain. The North Dakota National Guard release and the City of Grandview job application are published by those agencies for public use. The sample records are made up.

Code. The formcast repository holds the library, the eval and this page.