tinydoc 0.1.1__tar.gz → 0.2.0__tar.gz

tinydoc-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include MANIFEST.in
+recursive-include tinydoc/schemas *.json

tinydoc-0.2.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: tinydoc
+Version: 0.2.0
+Summary: Local-first grounded document extraction SDK — schema, evidence, confidence. Free Ollama/Qwen engine by default; no API key.
+Home-page: https://github.com/eulogik/TinyDoc-VLM
+Author: eulogik
+Author-email: hello@eulogik.com
+Project-URL: Model status, https://github.com/eulogik/TinyDoc-VLM/blob/main/docs/v3_plan.md
+Project-URL: HuggingFace Space, https://huggingface.co/spaces/eulogik/TinyDoc-VLM
+Project-URL: Bug Tracker, https://github.com/eulogik/TinyDoc-VLM/issues
+Project-URL: Documentation, https://github.com/eulogik/TinyDoc-VLM#readme
+Project-URL: Benchmarks, https://github.com/eulogik/TinyDoc-VLM/blob/main/docs/BENCHMARKS.md
+Project-URL: Website, https://eulogik.github.io/TinyDoc-VLM/
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: jsonschema>=4.20.0
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
+Provides-Extra: ocr-pp
+Requires-Dist: rapidocr-onnxruntime>=1.3.0; extra == "ocr-pp"
+Provides-Extra: smolvlm2
+Requires-Dist: torch>=2.2.0; extra == "smolvlm2"
+Requires-Dist: transformers>=4.48.0; extra == "smolvlm2"
+Requires-Dist: numpy>=1.26.0; extra == "smolvlm2"
+Requires-Dist: sentencepiece>=0.2.0; extra == "smolvlm2"
+Provides-Extra: onnx
+Requires-Dist: onnxruntime>=1.19.0; extra == "onnx"
+Requires-Dist: optimum>=1.22.0; extra == "onnx"
+Provides-Extra: all
+Requires-Dist: pytesseract>=0.3.10; extra == "all"
+Requires-Dist: rapidocr-onnxruntime>=1.3.0; extra == "all"
+Requires-Dist: torch>=2.2.0; extra == "all"
+Requires-Dist: transformers>=4.48.0; extra == "all"
+Requires-Dist: numpy>=1.26.0; extra == "all"
+Requires-Dist: sentencepiece>=0.2.0; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# TinyDoc 0.2.0 — local-first grounded document extraction
+
+Extract receipt/invoice fields as **schema-validated JSON** with per-field
+**evidence** (quote + OCR bbox) and **confidence**. Runs locally with Ollama;
+no API key, no cloud, no telemetry.
+
+> **Status (2026-11-06):** the SDK and evaluation harness are measured. The
+> first-party 256M model is retired (OCRBench 0.0%) and the SmolVLM2-2.2B SFT
+> track is closed (no gain over base). The working product is the engine +
+> trust layer, not the old checkpoint. Full analysis:
+> [docs/v3_plan.md](https://github.com/eulogik/TinyDoc-VLM/blob/main/docs/v3_plan.md).
+
+## Measured results (SROIE public-train-derived clean-100, n=100)
+
+| Engine | Field F1 | Address | Schema | Median latency | Errors |
+|---|---:|---:|---:|---:|---:|
+| **Qwen2.5-VL-3B** (`ollama:qwen2.5vl:3b`) | **0.9475** | 0.86 | 1.00 | 14.1 s | 0 |
+| **Qwen3-VL-2B-Instruct** (`ollama:qwen3-vl:2b-instruct`) | **0.9200** | 0.84 | 1.00 | 7.0 s | 0 |
+| Hybrid v2 first-party (`hybrid_2p2b`) | 0.603 | 0.37 | 0.93 | ~8 s | — |
+| PP-OCR + heuristics | 0.376 | 0.03 | — | — | — |
+| Tesseract + regex | 0.227 | — | 0.60 | — | — |
+
+> **Caveat:** these are **not external benchmark numbers**. The 100-doc set is a
+> duplicate-filtered split of the public SROIE **train** pool; Qwen may have seen
+> it during pretraining. The original 100-doc set is 60% leaked. Use the numbers
+> for same-document engine comparisons, not as a generalization claim. The next
+> eval adds CORD/FUNSD/invoices and a private wild set.
+
+## Install
+
+From PyPI (use this once 0.2.0 is published):
+
+```bash
+pip install tinydoc
+```
+
+From the repo:
+
+```bash
+pip install ./sdk
+# editable for development:
+pip install -e ./sdk
+```
+
+If `pip install tinydoc` resolves to **0.1.2**, that is the legacy 256M API; use
+the source install above until 0.2.0 is uploaded. Core deps: `pydantic`,
+`pillow`, `jsonschema`. Optional extras:
+
+```bash
+pip install './sdk[ocr]'      # pytesseract for evidence + ocr_regex
+pip install './sdk[ocr-pp]'   # RapidOCR ONNX evidence
+pip install './sdk[smolvlm2]' # optional local HF SmolVLM2 engine
+```
+
+For the default engine, install [Ollama](https://ollama.com) and pull a base:
+
+```bash
+ollama pull qwen2.5vl:3b            # quality default
+ollama pull qwen3-vl:2b-instruct    # fast tier (use -instruct, not the thinking tag)
+```
+
+System `tesseract` is needed for OCR-span evidence (`brew install tesseract` on macOS).
+
+## Quick start
+
+```python
+from tinydoc import ReceiptPipeline
+
+# Quality default: Qwen2.5-VL-3B
+pipe = ReceiptPipeline("ollama:qwen2.5vl:3b")
+
+# Fast tier: Qwen3-VL-2B-Instruct, ~2x faster
+# pipe = ReceiptPipeline("ollama:qwen3-vl:2b-instruct")
+
+result = pipe.extract("receipt.jpg")
+print(result.fields)        # {"company": ..., "date": ..., "address": ..., "total": ...}
+print(result.schema_valid)  # True/False (JSON Schema)
+print(result.confidence)    # 0..1 aggregate
+for field in result.field_results:
+    print(field.name, field.value, field.confidence, field.evidence)
+```
+
+CLI:
+
+```bash
+tinydoc extract ./receipts/ --engine ollama:qwen2.5vl:3b \
+    --out results.jsonl --overlay overlays/
+```
+
+Overlay PNGs draw OCR-span evidence boxes and field labels (`tinydoc.draw_overlay`).
+
+## Engines
+
+| Engine id | What it does |
+|---|---|
+| `ollama` / `ollama:qwen2.5vl:3b` | Quality default; free, local |
+| `ollama:qwen3-vl:2b-instruct` | Fast tier; 1.9 GB Q4, ~2x faster |
+| `auto` | Ollama if reachable; OCR floor if the schema would fail |
+| `ocr_regex` | Offline floor (Tesseract + rules) |
+| `mlx_2p2b` | First-party v2 edge engine (MLX SmolVLM2-2.2B 4-bit) |
+| `hybrid_2p2b` | v2 product path: MLX fields + frozen F3 OCR address |
+
+**Do not** set Ollama `format: "json"` — constrained decoding truncates long
+addresses and can drop `total`. The SDK uses unconstrained prompts, JSON salvage,
+and prompt-v1.
+
+### Environment
+
+- `TINYDOC_OLLAMA_TIMEOUT` (default 180 s) — raise to 600 for slow local runs.
+- `TINYDOC_OLLAMA_NUM_CTX` (default 8192) — Ollama context window. The implicit
+  4096 rejected 2481×3508 scans with HTTP 400; keep 8192 for full pages.
+
+## Evidence and honesty
+
+- Evidence kind is always `ocr_span` (RapidOCR word boxes), **not** VLM-predicted
+  boxes. Treat it as provenance, not as model grounding. A 100-box probe measured
+  VLM bbox hit@0.5 of **0.20** (2B) and **0.04** (3B), below the 0.70 product gate,
+  so OCR spans remain the shipped path.
+- The schema is packaged (`tinydoc/schemas/sroie_receipt.schema.json`); validation
+  uses `jsonschema`.
+- Confidence is a heuristic, not a probability. Evidence-off runs are constant
+  (0.4025; field ECE 0.52–0.55). The default evidence-on path measures field ECE
+  **0.115–0.135** raw and **0.005–0.014** after document-grouped isotonic OOF;
+  document-level confidence is **not** calibrated (ECE 0.09–0.10). Use field-level
+  scores for review routing only.
+- Every published number must recompute from `evaluation/phase0/results/`:
+  `python3 evaluation/phase0/recompute_scores.py` must exit 0.
+- The 256M model card and the v2 decision are kept for reproducibility; neither is
+  a current performance claim.
+
+## Layout
+
+```
+sdk/tinydoc/
+  pipeline.py   # engines, schema, sanitize, confidence, ReceiptPipeline
+  evidence.py   # OCR-span evidence
+  overlay.py    # draw bboxes + labels
+  cli.py        # tinydoc extract
+  schemas/      # JSON Schema per doc type
+```
+
+## License
+
+Apache 2.0

tinydoc-0.2.0/README.md

@@ -0,0 +1,144 @@
+# TinyDoc 0.2.0 — local-first grounded document extraction
+
+Extract receipt/invoice fields as **schema-validated JSON** with per-field
+**evidence** (quote + OCR bbox) and **confidence**. Runs locally with Ollama;
+no API key, no cloud, no telemetry.
+
+> **Status (2026-11-06):** the SDK and evaluation harness are measured. The
+> first-party 256M model is retired (OCRBench 0.0%) and the SmolVLM2-2.2B SFT
+> track is closed (no gain over base). The working product is the engine +
+> trust layer, not the old checkpoint. Full analysis:
+> [docs/v3_plan.md](https://github.com/eulogik/TinyDoc-VLM/blob/main/docs/v3_plan.md).
+
+## Measured results (SROIE public-train-derived clean-100, n=100)
+
+| Engine | Field F1 | Address | Schema | Median latency | Errors |
+|---|---:|---:|---:|---:|---:|
+| **Qwen2.5-VL-3B** (`ollama:qwen2.5vl:3b`) | **0.9475** | 0.86 | 1.00 | 14.1 s | 0 |
+| **Qwen3-VL-2B-Instruct** (`ollama:qwen3-vl:2b-instruct`) | **0.9200** | 0.84 | 1.00 | 7.0 s | 0 |
+| Hybrid v2 first-party (`hybrid_2p2b`) | 0.603 | 0.37 | 0.93 | ~8 s | — |
+| PP-OCR + heuristics | 0.376 | 0.03 | — | — | — |
+| Tesseract + regex | 0.227 | — | 0.60 | — | — |
+
+> **Caveat:** these are **not external benchmark numbers**. The 100-doc set is a
+> duplicate-filtered split of the public SROIE **train** pool; Qwen may have seen
+> it during pretraining. The original 100-doc set is 60% leaked. Use the numbers
+> for same-document engine comparisons, not as a generalization claim. The next
+> eval adds CORD/FUNSD/invoices and a private wild set.
+
+## Install
+
+From PyPI (use this once 0.2.0 is published):
+
+```bash
+pip install tinydoc
+```
+
+From the repo:
+
+```bash
+pip install ./sdk
+# editable for development:
+pip install -e ./sdk
+```
+
+If `pip install tinydoc` resolves to **0.1.2**, that is the legacy 256M API; use
+the source install above until 0.2.0 is uploaded. Core deps: `pydantic`,
+`pillow`, `jsonschema`. Optional extras:
+
+```bash
+pip install './sdk[ocr]'      # pytesseract for evidence + ocr_regex
+pip install './sdk[ocr-pp]'   # RapidOCR ONNX evidence
+pip install './sdk[smolvlm2]' # optional local HF SmolVLM2 engine
+```
+
+For the default engine, install [Ollama](https://ollama.com) and pull a base:
+
+```bash
+ollama pull qwen2.5vl:3b            # quality default
+ollama pull qwen3-vl:2b-instruct    # fast tier (use -instruct, not the thinking tag)
+```
+
+System `tesseract` is needed for OCR-span evidence (`brew install tesseract` on macOS).
+
+## Quick start
+
+```python
+from tinydoc import ReceiptPipeline
+
+# Quality default: Qwen2.5-VL-3B
+pipe = ReceiptPipeline("ollama:qwen2.5vl:3b")
+
+# Fast tier: Qwen3-VL-2B-Instruct, ~2x faster
+# pipe = ReceiptPipeline("ollama:qwen3-vl:2b-instruct")
+
+result = pipe.extract("receipt.jpg")
+print(result.fields)        # {"company": ..., "date": ..., "address": ..., "total": ...}
+print(result.schema_valid)  # True/False (JSON Schema)
+print(result.confidence)    # 0..1 aggregate
+for field in result.field_results:
+    print(field.name, field.value, field.confidence, field.evidence)
+```
+
+CLI:
+
+```bash
+tinydoc extract ./receipts/ --engine ollama:qwen2.5vl:3b \
+    --out results.jsonl --overlay overlays/
+```
+
+Overlay PNGs draw OCR-span evidence boxes and field labels (`tinydoc.draw_overlay`).
+
+## Engines
+
+| Engine id | What it does |
+|---|---|
+| `ollama` / `ollama:qwen2.5vl:3b` | Quality default; free, local |
+| `ollama:qwen3-vl:2b-instruct` | Fast tier; 1.9 GB Q4, ~2x faster |
+| `auto` | Ollama if reachable; OCR floor if the schema would fail |
+| `ocr_regex` | Offline floor (Tesseract + rules) |
+| `mlx_2p2b` | First-party v2 edge engine (MLX SmolVLM2-2.2B 4-bit) |
+| `hybrid_2p2b` | v2 product path: MLX fields + frozen F3 OCR address |
+
+**Do not** set Ollama `format: "json"` — constrained decoding truncates long
+addresses and can drop `total`. The SDK uses unconstrained prompts, JSON salvage,
+and prompt-v1.
+
+### Environment
+
+- `TINYDOC_OLLAMA_TIMEOUT` (default 180 s) — raise to 600 for slow local runs.
+- `TINYDOC_OLLAMA_NUM_CTX` (default 8192) — Ollama context window. The implicit
+  4096 rejected 2481×3508 scans with HTTP 400; keep 8192 for full pages.
+
+## Evidence and honesty
+
+- Evidence kind is always `ocr_span` (RapidOCR word boxes), **not** VLM-predicted
+  boxes. Treat it as provenance, not as model grounding. A 100-box probe measured
+  VLM bbox hit@0.5 of **0.20** (2B) and **0.04** (3B), below the 0.70 product gate,
+  so OCR spans remain the shipped path.
+- The schema is packaged (`tinydoc/schemas/sroie_receipt.schema.json`); validation
+  uses `jsonschema`.
+- Confidence is a heuristic, not a probability. Evidence-off runs are constant
+  (0.4025; field ECE 0.52–0.55). The default evidence-on path measures field ECE
+  **0.115–0.135** raw and **0.005–0.014** after document-grouped isotonic OOF;
+  document-level confidence is **not** calibrated (ECE 0.09–0.10). Use field-level
+  scores for review routing only.
+- Every published number must recompute from `evaluation/phase0/results/`:
+  `python3 evaluation/phase0/recompute_scores.py` must exit 0.
+- The 256M model card and the v2 decision are kept for reproducibility; neither is
+  a current performance claim.
+
+## Layout
+
+```
+sdk/tinydoc/
+  pipeline.py   # engines, schema, sanitize, confidence, ReceiptPipeline
+  evidence.py   # OCR-span evidence
+  overlay.py    # draw bboxes + labels
+  cli.py        # tinydoc extract
+  schemas/      # JSON Schema per doc type
+```
+
+## License
+
+Apache 2.0

tinydoc-0.2.0/setup.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+
+from setuptools import setup, find_packages
+
+setup(
+    name="tinydoc",
+    version="0.2.0",
+    packages=find_packages(),
+    include_package_data=True,
+    package_data={
+        "tinydoc": ["schemas/*.json"],
+    },
+    install_requires=[
+        "pydantic>=2.8.0",
+        "pillow>=10.0.0",
+        "jsonschema>=4.20.0",
+    ],
+    extras_require={
+        "ocr": ["pytesseract>=0.3.10"],
+        "ocr-pp": ["rapidocr-onnxruntime>=1.3.0"],
+        "smolvlm2": [
+            "torch>=2.2.0",
+            "transformers>=4.48.0",
+            "numpy>=1.26.0",
+            "sentencepiece>=0.2.0",
+        ],
+        "onnx": ["onnxruntime>=1.19.0", "optimum>=1.22.0"],
+        "all": [
+            "pytesseract>=0.3.10",
+            "rapidocr-onnxruntime>=1.3.0",
+            "torch>=2.2.0",
+            "transformers>=4.48.0",
+            "numpy>=1.26.0",
+            "sentencepiece>=0.2.0",
+        ],
+    },
+    entry_points={
+        "console_scripts": [
+            "tinydoc=tinydoc.cli:main",
+        ],
+    },
+    author="eulogik",
+    author_email="hello@eulogik.com",
+    description=(
+        "Local-first grounded document extraction SDK — schema, evidence, "
+        "confidence. Free Ollama/Qwen engine by default; no API key."
+    ),
+    long_description=(Path(__file__).parent / "README.md").read_text(encoding="utf-8"),
+    long_description_content_type="text/markdown",
+    url="https://github.com/eulogik/TinyDoc-VLM",
+    project_urls={
+        "Model status": "https://github.com/eulogik/TinyDoc-VLM/blob/main/docs/v3_plan.md",
+        "HuggingFace Space": "https://huggingface.co/spaces/eulogik/TinyDoc-VLM",
+        "Bug Tracker": "https://github.com/eulogik/TinyDoc-VLM/issues",
+        "Documentation": "https://github.com/eulogik/TinyDoc-VLM#readme",
+        "Benchmarks": "https://github.com/eulogik/TinyDoc-VLM/blob/main/docs/BENCHMARKS.md",
+        "Website": "https://eulogik.github.io/TinyDoc-VLM/",
+    },
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: Apache Software License",
+        "Operating System :: OS Independent",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+        "Intended Audience :: Developers",
+    ],
+    python_requires=">=3.9",
+)

tinydoc-0.2.0/tinydoc/__init__.py

@@ -0,0 +1,28 @@
+from .models import ExtractionResult, QAResult, TableResult
+from .pipeline import ReceiptPipeline, DocumentResult, FieldResult, build_engine
+from .evidence import Evidence, attach_evidence
+from .overlay import draw_overlay
+
+__all__ = [
+    "ExtractionResult",
+    "QAResult",
+    "TableResult",
+    "ReceiptPipeline",
+    "DocumentResult",
+    "FieldResult",
+    "build_engine",
+    "Evidence",
+    "attach_evidence",
+    "draw_overlay",
+    # legacy name kept for import compatibility
+    "TinyDocExtractor",
+]
+
+
+def __getattr__(name: str):
+    # Lazy legacy extractor (256M path) so pipeline imports do not load torch models
+    if name == "TinyDocExtractor":
+        from .extractor import TinyDocExtractor
+
+        return TinyDocExtractor
+    raise AttributeError(name)

tinydoc-0.2.0/tinydoc/cli.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""TinyDoc Phase-1 CLI: folder → schema-valid JSON + evidence + confidence.
+
+Usage:
+  python -m tinydoc.cli extract <folder_or_image> [--engine auto|ollama|ocr_regex|smolvlm2]
+      [--out results.jsonl] [--limit N] [--no-evidence]
+
+Writes JSONL (one doc per line) and prints a summary table.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main(argv=None) -> int:
+    # allow running from repo without install
+    sdk_root = Path(__file__).absolute().parent.parent
+    if str(sdk_root) not in sys.path:
+        sys.path.insert(0, str(sdk_root))
+
+    from tinydoc.pipeline import ReceiptPipeline  # noqa: E402
+
+    ap = argparse.ArgumentParser(prog="tinydoc", description=__doc__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    ex = sub.add_parser("extract", help="Extract fields from an image or folder")
+    ex.add_argument("path", help="Image file or directory")
+    ex.add_argument("--engine", default="auto")
+    ex.add_argument("--out", default=None, help="Write JSONL here")
+    ex.add_argument("--limit", type=int, default=None)
+    ex.add_argument("--no-evidence", action="store_true")
+    ex.add_argument("--model", default=None, help="Engine-specific model id")
+    ex.add_argument(
+        "--overlay",
+        default=None,
+        metavar="DIR",
+        help="Write evidence-overlay PNGs into DIR (red/blue boxes + labels)",
+    )
+
+    args = ap.parse_args(argv)
+
+    p = Path(args.path)
+    if not p.exists():
+        print(f"path not found: {p}", file=sys.stderr)
+        return 2
+    kwargs = {}
+    if args.model:
+        kwargs["model"] = args.model
+    pipe = ReceiptPipeline(args.engine, **kwargs)
+    with_ev = not args.no_evidence
+
+    if p.is_dir():
+        results = pipe.extract_folder(p, limit=args.limit, with_evidence=with_ev)
+    else:
+        results = [pipe.extract(p, with_evidence=with_ev)]
+
+    out_path = Path(args.out) if args.out else None
+    if out_path:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        with out_path.open("w") as f:
+            for r in results:
+                f.write(json.dumps(r.to_dict()) + "\n")
+
+    if args.overlay:
+        from tinydoc.overlay import draw_overlay
+
+        odir = Path(args.overlay)
+        odir.mkdir(parents=True, exist_ok=True)
+        for r in results:
+            name = Path(r.image_path).stem + "_overlay.png"
+            try:
+                draw_overlay(r.image_path, r.field_results, odir / name)
+            except Exception as e:
+                print(f"  overlay failed for {r.image_path}: {e}")
+        print(f"wrote overlays → {odir}")
+
+    n = len(results)
+    if n == 0:
+        print("no images found")
+        return 1
+    schema_rate = sum(r.schema_valid for r in results) / n
+    mean_conf = sum(r.confidence for r in results) / n
+    ev_rate = sum(r.evidence_coverage for r in results) / n
+    mean_lat = sum(r.latency_ms for r in results) / n
+    print(
+        f"engine={pipe.engine.name} n={n} "
+        f"schema={schema_rate:.3f} conf={mean_conf:.3f} "
+        f"evidence={ev_rate:.3f} latency_ms={mean_lat:.0f}"
+    )
+    for r in results[:5]:
+        print(
+            f"  {Path(r.image_path).name}: schema={r.schema_valid} "
+            f"conf={r.confidence:.2f} fields={r.fields}"
+        )
+    if out_path:
+        print(f"wrote {out_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())