Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* 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
+invoice_classifier_fp32.onnx.data filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,3 +1,240 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+tags:
+  - image-classification
+  - onnx
+  - onnxruntime
+  - mobilenet
+  - mobile
+  - on-device
+  - document-classification
+  - quantized
+  - int8
+  - qdq
+library_name: onnx
+pipeline_tag: image-classification
+metrics:
+  - accuracy
+base_model: timm/mobilenetv3_small_100.lamb_in1k
+datasets: []
+---
+
+# tally-ocr-document-classifier
+
+A small on-device document classifier that sorts a single image into one of:
+
+- `bank_statement`
+- `invoice`
+- `other`
+
+It is the first-stage triage model in the [Tally OCR](https://github.com/) Flutter
+app — every uploaded or scanned page hits this model before any OCR or
+downstream extraction is attempted, so it has to be **fast, small, and run
+fully offline**.
+
+The repo ships two artifacts:
+
+| File | Format | Size | Use |
+|------|--------|-----:|------|
+| `invoice_classifier_int8_qdq.onnx` | ONNX, **QDQ static int8** | ~1.7 MB | **Ship this on-device.** Runs on ONNX Runtime Mobile. |
+| `invoice_classifier_fp32.onnx` | ONNX, fp32 | ~5.8 MB | Reference / desktop / accuracy comparisons. |
+
+## Model details
+
+- **Architecture**: MobileNetV3-Small (torchvision `mobilenet_v3_small`),
+  ImageNet-1k pretrained backbone, final 1000-class head replaced with a
+  3-class linear layer.
+- **Parameters**: ~1.5 M.
+- **Input**: 1 × 3 × 224 × 224, float32, NCHW, ImageNet-normalized.
+- **Output**: `logits` — 1 × 3 unnormalized scores. Apply softmax to get
+  per-class confidence.
+- **Class index order** (alphabetical, must match `labels.json`):
+
+  ```
+  0  bank_statement
+  1  invoice
+  2  other
+  ```
+
+- **Opset**: 18.
+- **Quantization**: static, **QDQ format**, per-channel,
+  `QuantType.QUInt8` activations / `QuantType.QInt8` weights, calibrated
+  on ~200 in-domain images.
+
+### Why QDQ?
+
+ONNX Runtime Mobile (the kernel set used by the
+[`onnxruntime` Flutter package](https://pub.dev/packages/onnxruntime))
+does **not** include `ConvInteger` / `MatMulInteger` operators. A model
+quantized with `QuantFormat.QOperator` or `quantize_dynamic` will load
+fine on desktop ORT and then fail at runtime on mobile with
+`code=9 (NOT_IMPLEMENTED)`. QDQ keeps the original `Conv` / `MatMul`
+nodes and surrounds them with `QuantizeLinear` / `DequantizeLinear`,
+which is the path ORT Mobile actually executes. Use the QDQ build for
+any phone deployment.
+
+## Intended use
+
+- Triage page on whether an uploaded document is worth running heavyweight
+  invoice / statement extraction on.
+- Lightweight client-side filtering before backend OCR to save round-trips.
+
+### Out of scope
+
+- **Not an OCR model** — it doesn't extract text, totals, dates, or
+  account numbers. Pair it with a downstream OCR stage.
+- **Not a fraud / authenticity detector.**
+- **Not a layout analyzer.** It looks at the page as a whole, not at
+  regions.
+- Any class outside `{bank_statement, invoice}` collapses into `other`.
+  Don't expect meaningful gradients between `other` sub-types
+  (receipts vs IDs vs photos).
+
+## How to use
+
+### Python (ONNX Runtime)
+
+```python
+import json
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+
+session = ort.InferenceSession("invoice_classifier_int8_qdq.onnx")
+labels = json.load(open("labels.json"))
+mean = np.array([0.485, 0.456, 0.406], dtype=np.float32).reshape(3, 1, 1)
+std  = np.array([0.229, 0.224, 0.225], dtype=np.float32).reshape(3, 1, 1)
+
+img = Image.open("page.jpg").convert("RGB").resize((256, 256))
+left = (256 - 224) // 2
+img = img.crop((left, left, left + 224, left + 224))
+x = np.asarray(img, dtype=np.float32).transpose(2, 0, 1) / 255.0
+x = ((x - mean) / std)[None].astype(np.float32)
+
+logits = session.run(["logits"], {"input": x})[0][0]
+probs = np.exp(logits - logits.max())
+probs /= probs.sum()
+print(labels[int(probs.argmax())], float(probs.max()))
+```
+
+### Flutter (ONNX Runtime Mobile)
+
+The companion Flutter app loads the model at startup, verifies its SHA-256,
+and runs inference per uploaded image / first PDF page. See `pinned_model.dart`
+in the app repo. The preprocessing pipeline (resize 256 → center-crop 224 →
+ImageNet normalize → NCHW) matches the Python snippet above byte-for-byte.
+
+## Preprocessing
+
+| Step | Value |
+|------|-------|
+| Resize | shorter edge → 256 |
+| Crop | center crop to 224 × 224 |
+| Color | RGB |
+| Scale | divide by 255 |
+| Normalize mean | `[0.485, 0.456, 0.406]` |
+| Normalize std | `[0.229, 0.224, 0.225]` |
+| Layout | NCHW |
+| Dtype | float32 |
+
+These are the standard ImageNet stats — also captured in
+`preprocess.json` for programmatic loading.
+
+## Training
+
+- **Backbone weights**: torchvision `MobileNet_V3_Small_Weights.IMAGENET1K_V1`.
+- **Head**: replaced with `nn.Linear(in, 3)`.
+- **Optimizer**: AdamW, weight decay 1 × 10⁻⁴.
+- **Schedule**: cosine annealing across all epochs.
+- **Stage 1**: backbone frozen for 2 epochs, only the new head trains
+  (lr = 3 × 10⁻⁴).
+- **Stage 2**: backbone unfrozen at lr / 10, head stays at base lr
+  (discriminative learning rates).
+- **Loss**: `CrossEntropyLoss` with inverse-frequency class weights and
+  label smoothing 0.05.
+- **Augmentation**: Resize(256) → RandomResizedCrop(224, scale 0.7–1.0)
+  → ColorJitter (brightness/contrast/saturation/hue) → small RandomRotation
+  → occasional grayscale → ImageNet normalize.
+- **Best checkpoint**: selected by validation accuracy.
+
+The training, export, and quantization scripts are open-sourced in the
+[Tally OCR Flutter repo](https://github.com/) under `training/`.
+
+## Evaluation
+
+> **TODO**: replace with measured numbers from your held-out test set.
+
+Recommended metrics to fill in before publishing a v1.0 model card:
+
+| Metric | fp32 | int8 (QDQ) |
+|--------|-----:|-----------:|
+| Top-1 accuracy (val) | _–_ | _–_ |
+| Macro F1 (val) | _–_ | _–_ |
+| Per-class F1 | _–_ | _–_ |
+| Top-1 disagreement vs fp32 | n/a | _–_ |
+
+## Quantization quality check
+
+Always validate the int8 build before shipping:
+
+```bash
+python -m src.infer --model outputs/invoice_classifier_fp32.onnx     --image test/...
+python -m src.infer --model outputs/invoice_classifier_int8_qdq.onnx --image test/...
+```
+
+If int8 disagrees with fp32 on more than ~1–2% of held-out test images,
+retry with more calibration data, switch to per-tensor weights, or fall
+back to fp32 (still only ~6 MB).
+
+## Limitations and bias
+
+- **Domain bias toward English-language, Western-format documents.**
+  Performance on non-Latin scripts, right-to-left layouts, and regional
+  statement / invoice formats has not been systematically measured.
+- **Photo conditions matter.** Heavy glare, motion blur, extreme skew
+  (>~15°), or occlusion shifts predictions toward `other`.
+- **`other` is an open set.** Its decision boundary is determined entirely
+  by what is present in the training data's `other/` folder. Receipts,
+  IDs, screenshots, and shipping labels were included; any class not seen
+  in training may be classified inconsistently.
+- **No PII handling.** Documents are processed as opaque pixels; the model
+  does not redact or filter sensitive fields. Add your own redaction layer
+  if uploading user data anywhere downstream.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `invoice_classifier_int8_qdq.onnx` | Mobile-ready int8 model (ship this). |
+| `invoice_classifier_fp32.onnx` | fp32 reference model. |
+| `labels.json` | Class name list, in model index order. |
+| `preprocess.json` | Input shape + ImageNet mean/std. |
+| `sha256.txt` | SHA-256 hashes + file sizes for pinned downloads. |
+
+### Pinning hashes
+
+```
+8f006366fcd633caae958ce511cdba87eb4a6d9d5de302e3d0cb8dd070d774dc  invoice_classifier_fp32.onnx     6084524
+c39c3352d38379ee707642a056e55926719d7940f3e886be40e7afcc05526687  invoice_classifier_int8_qdq.onnx 1779282
+```
+
+These are referenced verbatim in the Flutter app's `pinned_model.dart`
+to refuse any downloaded model whose hash doesn't match.
+
+## License
+
+Apache-2.0. The pretrained ImageNet backbone is also Apache-2.0
+(torchvision MobileNetV3 weights).
+
+## Citation
+
+If you use this model, please cite:
+
+```bibtex
+@software{tally_ocr_document_classifier,
+  title  = {Tally OCR Document Classifier (MobileNetV3-Small, QDQ int8)},
+  author = {Tally OCR contributors},
+  year   = {2026},
+  url    = {https://huggingface.co/<your-username>/tally-ocr-document-classifier}
+}
+```

best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:91711e8e0c38af4c39801bcbf46cb509b90c4a3db5d5ea9221c3a3579dc9ae81
+size 6203497

invoice_classifier_fp32.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8f006366fcd633caae958ce511cdba87eb4a6d9d5de302e3d0cb8dd070d774dc
+size 6084524

invoice_classifier_fp32.onnx.data

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

invoice_classifier_int8_qdq.onnx

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

labels.json

@@ -0,0 +1,5 @@
+[
+  "bank_statement",
+  "invoice",
+  "other"
+]

preprocess.json

@@ -0,0 +1,7 @@
+{
+  "input_name": "input",
+  "output_name": "logits",
+  "input_size": 224,
+  "mean": [0.485, 0.456, 0.406],
+  "std": [0.229, 0.224, 0.225]
+}

sha256.txt

@@ -0,0 +1,2 @@
+8f006366fcd633caae958ce511cdba87eb4a6d9d5de302e3d0cb8dd070d774dc  invoice_classifier_fp32.onnx  6084524
+c39c3352d38379ee707642a056e55926719d7940f3e886be40e7afcc05526687  invoice_classifier_int8_qdq.onnx  1779282