form-field-v1 release

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,88 @@
+---
+license: apache-2.0
+pipeline_tag: image-classification
+library_name: onnxruntime
+language: [en]
+tags:
+  - image-classification
+  - document-ai
+  - form-field-detection
+  - onnx
+  - open-weights
+metrics:
+  - accuracy
+---
+
+# form-field-v1-state — open-weight
+
+**A 96k-parameter filled/empty classifier for detected form fields.** Given a cropped field, it reads whether
+the field is **filled** (filled / checked / signed) or **empty** (empty / unchecked / blank) — a single shared,
+detector-agnostic model that supplies state for any of the `form-field-v1` detectors. ~0.4 MB, CPU-fast,
+Apache-2.0, runs via ONNX Runtime with no custom code.
+
+Part of the `form-field-v1` family — pair it with [`-nano`](https://huggingface.co/nutrientdocs/form-field-v1-nano)
+(open) or [`-small`](https://huggingface.co/nutrientdocs/form-field-v1-small) /
+[`-medium`](https://huggingface.co/nutrientdocs/form-field-v1-medium) (commercial).
+
+- 🎯 **Try it:** [form-field-v1-demo](https://huggingface.co/spaces/nutrientdocs/form-field-v1-demo)
+- 🏆 **Leaderboard:** [form-field-v1-leaderboard](https://huggingface.co/spaces/nutrientdocs/form-field-v1-leaderboard)
+- 📊 **Benchmark:** [form-field-v1-benchmark](https://huggingface.co/datasets/nutrientdocs/form-field-v1-benchmark)
+
+## What it does
+
+Field detectors locate `Text`, `Choice`, and `Signature` widgets; this model answers the follow-up question
+**"is that field filled?"** on the detected crop. It takes a grayscale field crop, letterboxes it to **40×160**
+(aspect-preserving — form fields are wide, median aspect ~3.3, so a square resize destroys thin printed text),
+and outputs a binary **empty (0) / filled (1)** label. State is mapped per type: Text → filled/empty,
+Choice → checked/unchecked, Signature → signed/blank.
+
+## Results
+
+Binary field-state accuracy, one shared evaluation.
+
+| | Accuracy |
+|---|---|
+| **form-field-v1-state** (this model) | **0.981** |
+| Training-free ink heuristic | 0.915 |
+
+On a held-out synthetic split it reaches **0.981** vs a training-free ink-presence heuristic's **0.915**. On a
+real filled form (the ACME credit-card application, 25 fields) it matches the heuristic at **23/25**.
+
+## What's in this repo
+| File | |
+|---|---|
+| `model.onnx` | ONNX graph, input `1×1×40×160` grayscale, output `logits [n,2]` |
+| `state_cnn.pt` | PyTorch state dict (depthwise-separable CNN, 96k params) |
+
+Classes: `0 = empty`, `1 = filled`.
+
+## Usage (ONNX Runtime)
+
+```python
+import numpy as np, onnxruntime as ort
+from PIL import Image
+
+sess = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
+
+def letterbox(crop, th=40, tw=160):                         # aspect-preserving, pad 255 (paper)
+    g = crop.convert("L"); w, h = g.size
+    s = min(tw / w, th / h); nw, nh = max(1, round(w * s)), max(1, round(h * s))
+    out = Image.new("L", (tw, th), 255); out.paste(g.resize((nw, nh), Image.BILINEAR), ((tw - nw) // 2, (th - nh) // 2))
+    return np.asarray(out, np.uint8)
+
+crop = Image.open("field_crop.png")                          # a detected field, cropped from the page
+x = (((letterbox(crop).astype(np.float32) / 255) - 0.5) / 0.5)[None, None]   # normalize, shape [1,1,40,160]
+filled = int(sess.run(None, {sess.get_inputs()[0].name: x})[0].argmax(1)[0]) == 1
+```
+
+## License & data
+Apache-2.0. Trained on synthetic form renders (empty + filled + handwritten field crops, with on-the-fly
+augmentation for scan robustness); no PII.
+
+## About the author
+
+<a href="https://nutrient.io/">
+  <img src="https://avatars2.githubusercontent.com/u/1527679?v=3&s=200" height="80" />
+</a>
+
+This project is maintained and funded by [Nutrient](https://nutrient.io/) - The deterministic document infrastructure enterprises run their highest-stakes workflows on: replayable output, clear exceptions, and full audit trails on the messy, regulated documents where AI alone breaks.

model.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7afb50c85247174b5384e4fa857b8a56a1736a40057981904f995952c2444974
+size 383549

state_cnn.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:88560abc622a1a6aae911512881093550819f06c3e53a3b9927ed370b52919a6
+size 416457