README.md

---
license: apache-2.0
library_name: pytorch
pipeline_tag: object-detection
tags:
  - document-ai
  - pdf
  - acroform
  - form-field-detection
  - object-detection
  - research
---

# AcroMELD

🪄 **Turns a flat PDF into a fillable form.** Give it a PDF that looks like a form but has
no form fields — it finds every field and writes a real, clickable AcroForm.

```sh
pip install acromeld
acromeld input.pdf output.pdf
```

That is all you need; the weights below are downloaded on first use.

![A PDF with no form fields on the left, the same page with 54 generated form fields on the right](assets/hero.png)

*AcroMELD = **Acro**Form **M**ulti-source **E**vidence **L**inking **D**ecoder.*

## What it detects

Three field types — **Text**, **Choice**, **Signature** — plus a learned link that merges
several visual candidates into one field instead of emitting duplicates. It reads two
channels at once: the rendered page, and the PDF's own drawing primitives (lines,
rectangles, glyph runs), which a purely visual detector ignores. Scanned pages have no
primitives; the model was trained with that channel dropped on 12 % of pages, so it degrades
rather than fails.

39.4M parameters. Up to 896 fields per page, so dense forms are not silently truncated.

![41 detected fields on a form page, coloured by class with confidence scores](assets/detections.png)

## How well it works

Measured **once** on a sealed holdout of 1,996 PDFs / 6,843 pages the model never saw during
training, against a pass/fail threshold registered before training started.

| | containment micro-F1 |
|---|---|
| Registered baseline — the number to beat | 0.82903655889853 |
| **AcroMELD** | **0.8476748634830094** |
| Verdict | **passed** |

The model was frozen and hash-locked before the holdout was opened, so the score could not
be tuned after the fact.

**Read this before using it:**

- **Signature detection does not work.** At the calibrated threshold the model predicts
  essentially no signature fields — per-class F1 `0.0677`. Text and Choice carry the entire
  score. Treat any signature output as unusable.
- Under a stricter IoU/COCO adapter the same model reaches only `0.28996` mAP, below a
  locally evaluated CommonForms-L reference. The two adapters use different ground-truth
  counts and are **not comparable to each other**; the strict number is the less flattering
  one and it is reported here for that reason.
- Measured on **German-language forms**. Other languages and layouts are untested.
- Rotated pages are rejected rather than silently misplaced.
- One sealed run, one seed. No stability claim, no component ablations.

This is a **research artifact**, not a product.

## Files

| | | |
|---|---|---|
| `acromeld-inference.pt` | 158 MB | the model — EMA weights, what the `acromeld` package loads |
| `operating-point.json` | 199 B | the calibrated thresholds, frozen before the holdout was opened |

```json
{
  "class_thresholds": [0.769, 0.812, 0.99],
  "link_probability": 0.95,
  "nms_iou": 1.0
}
```

Class order is `[Text, Choice, Signature]`. `nms_iou: 1.0` means suppression is effectively
disabled — the graph-set decoder produces exclusive queries, so duplicate suppression is not
needed.

## Architecture

384 ECDet-L visual queries + 384 structure-seeded queries + 128 free recovery queries →
896 exclusive queries → 4 sparse geometry-weighted graph layers → boxes, 3 classes +
no-object, localization quality, same-field links.

The visual branch is vendored ECDet-L (EdgeCrafter, Apache-2.0). The label-free PDF-structure
encoder and the graph-set decoder are this project's contribution.

Trained on 35,388 PDFs / 119,418 pages, 2× NVIDIA RTX A6000, effective batch 32, epoch 32 of
33 selected on a development split by the same containment metric the gate uses. The external
holdout was excluded from the training index by document hash.

## What is not here

- **The training corpus.** Third-party form documents with heterogeneous redistribution
  rights and potentially sensitive content; releasing it would require a rights and
  data-protection assessment that has not been done.
- **The training code.** The objective, the Hungarian matching, the calibration procedure and
  the evaluation harness are not published.
- **The sealed run record** — the frozen candidate checkpoint, the full per-epoch history, the
  one-shot holdout report and every provenance digest that binds them. Held privately and
  available for hash audit on request.

## Licence

Apache-2.0, inherited from the source project and from vendored ECDet-L.

The two example pages above are blank third-party form templates, rendered from the model's
own output and shown only to illustrate what it does. They carry their publishers' rights.