add README.md

README.md

@@ -0,0 +1,120 @@
+---
+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.