quadra-core 0.1.0__py3-none-any.whl

quadra_core/__init__.py

@@ -0,0 +1,41 @@
+"""Read a supermarket till receipt from a photo.
+
+Tesseract does the OCR, then geometry and arithmetic do the rest. The same
+receipt always parses the same way, and when it gets one wrong you can see why.
+
+    from quadra_core import parse_image, parse_tsv
+
+    document, status = parse_image(Path("receipt.jpg"), profile_id="esselunga")
+
+`status` is "ok", "partial" or "failed". It never raises just because a receipt
+was hard to read: you get a document back either way, with the problems listed
+in `validation.warnings`.
+
+Everything shop-specific lives in a TOML profile rather than in this code, so
+adding a shop means writing a profile.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from quadra_core.parse import parse_image, parse_tsv, read_input
+from quadra_core.pipeline.document import no_review
+from quadra_core.profiles.loader import Profile, ProfileError, available, load, select
+
+# The JSON Schema every document validates against. Shipped with the package so
+# callers can check output without keeping their own copy in sync.
+SCHEMA_PATH = Path(__file__).parent / "schema" / "receipt-1.0.0.schema.json"
+
+__all__ = [
+    "SCHEMA_PATH",
+    "Profile",
+    "ProfileError",
+    "available",
+    "load",
+    "no_review",
+    "parse_image",
+    "parse_tsv",
+    "read_input",
+    "select",
+]

quadra_core/cli.py

@@ -0,0 +1,88 @@
+"""`quadra-core` on the command line: read a receipt, print the document.
+
+Small on purpose. It is here so you can try the library and check a profile
+against a photo without writing a script. Storing, reviewing and exporting
+receipts are jobs for whatever gets built on top.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from quadra_core.parse import IMAGE_SUFFIXES, parse_image, parse_tsv, read_input
+from quadra_core.profiles import loader
+
+# Exit code carries the result, so a shell script or worker does not have to
+# parse stdout.
+EXIT_OK, EXIT_PARTIAL, EXIT_FAILED, EXIT_ERROR = 0, 1, 2, 3
+
+_STATUS_EXIT = {"ok": EXIT_OK, "partial": EXIT_PARTIAL, "failed": EXIT_FAILED}
+
+
+def _run_parse(args: argparse.Namespace) -> int:
+    source: Path | None = args.path
+    if source is not None and source.suffix.lower() in IMAGE_SUFFIXES:
+        document, status = parse_image(
+            source, profile_id=args.profile, printed_total=args.total
+        )
+        # Only of use to something archiving the originals.
+        document.pop("_tsv", None)
+        document.pop("_prepared", None)
+    else:
+        tsv, ocr_meta = read_input(source)
+        document, status = parse_tsv(
+            tsv, profile_id=args.profile, ocr_meta=ocr_meta, printed_total=args.total
+        )
+
+    json.dump(document, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return _STATUS_EXIT.get(status, EXIT_ERROR)
+
+
+def _run_profiles(_args: argparse.Namespace) -> int:
+    for profile in loader.available():
+        state = "calibrated" if profile.calibrated else "UNCALIBRATED"
+        print(f"{profile.id:<12} v{profile.version}  {state}")
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Assemble the command line."""
+    ap = argparse.ArgumentParser(prog="quadra-core", description=__doc__)
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    parse = sub.add_parser("parse", help="read a receipt image or Tesseract TSV")
+    parse.add_argument(
+        "path",
+        nargs="?",
+        type=Path,
+        help="image or .tsv file; omit to read TSV from stdin",
+    )
+    parse.add_argument("--profile", help="force a profile instead of fingerprinting")
+    parse.add_argument(
+        "--total",
+        type=int,
+        help="printed total in minor units, when the receipt's own is unreadable",
+    )
+    parse.set_defaults(handler=_run_parse)
+
+    profiles = sub.add_parser("profiles", help="list the shop profiles available")
+    profiles.set_defaults(handler=_run_profiles)
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point. Returns the exit code rather than raising on a bad receipt."""
+    args = build_parser().parse_args(argv)
+    try:
+        return args.handler(args)
+    except (loader.ProfileError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

quadra_core/parse.py

@@ -0,0 +1,232 @@
+"""Photo or Tesseract TSV in, receipt document out.
+
+The entry point for the library. `parse_tsv` takes Tesseract output directly,
+so the parsing side runs with neither Tesseract nor Pillow installed; the image
+path imports both lazily to keep it that way.
+
+Bad receipt content never raises. A receipt that could not be read comes back
+as a document saying so, so a batch of receipts does not fail on one bad photo.
+"""
+
+from __future__ import annotations
+
+import sys
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from quadra_core.pipeline import document as document_module
+from quadra_core.pipeline.document import build
+from quadra_core.pipeline.extract import extract
+from quadra_core.pipeline.lines import (
+    drop_speckle,
+    group_lines,
+    load_tsv,
+    median_glyph_height,
+)
+from quadra_core.pipeline.ocr import run_on_path
+from quadra_core.pipeline.validate import validate
+from quadra_core.profiles import loader
+
+IMAGE_SUFFIXES = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp", ".webp"}
+
+DEFAULT_OCR_META = {"engine": "tesseract", "lang": "ita", "psm": 4, "oem": 1}
+
+
+def read_input(path: Path | None) -> tuple[str, dict]:
+    """Return TSV plus OCR metadata, from an image, a TSV file, or stdin.
+
+    Taking TSV directly keeps the parsing core usable without Tesseract or
+    Pillow installed; the image branch imports them lazily.
+    """
+    if path is None:
+        return sys.stdin.read(), dict(DEFAULT_OCR_META)
+
+    if path.suffix.lower() in IMAGE_SUFFIXES:
+        result, report, prepared = run_on_path(path)
+        return result.tsv, {
+            "engine": "tesseract",
+            "engine_version": result.engine_version,
+            "lang": result.lang,
+            "psm": result.psm,
+            "oem": result.oem,
+            "preprocessing": report.steps,
+            "_prepared": prepared,
+        }
+
+    return path.read_text(), dict(DEFAULT_OCR_META)
+
+
+def parse_tsv(
+    tsv: str,
+    *,
+    profile_id: str | None,
+    receipt_id: str | None = None,
+    ocr_meta: dict | None = None,
+    prepared: object | None = None,
+    printed_total: int | None = None,
+    review: dict[str, Any] | None = None,
+) -> tuple[dict, str]:
+    """TSV -> receipt document. Never raises on bad receipt content.
+
+    `prepared` is the image the TSV was read from. Given one, a receipt that fails
+    to add up gets its price column read a second time; see pipeline.recheck.
+
+    `printed_total` overrides whatever total the receipt itself yielded, for the
+    case where someone typed it in because it was unreadable.
+
+    `review` says whether a person should check this receipt. That is the
+    caller's decision, not this library's, so whatever is passed in is recorded
+    as given.
+    """
+    words = drop_speckle(load_tsv(tsv))
+    lines = group_lines(words)
+    texts = [l.text for l in lines]
+
+    confidence = 0.0
+    if profile_id:
+        matches = [p for p in loader.available() if p.id == profile_id]
+        if not matches:
+            raise loader.ProfileError(f"no such profile: {profile_id}")
+        profile = matches[0]
+        confidence = 1.0
+    else:
+        selected = loader.select(texts)
+        if selected is None:
+            raise loader.ProfileError(
+                "no profile fingerprint matched. That is a real signal: either the "
+                "receipt is from another store, or the layout changed."
+            )
+        profile, confidence = selected
+
+    extraction = extract(lines, profile)
+    if printed_total is not None:
+        # Someone read the total off the paper because the parser could not, so
+        # it beats anything OCR produced.
+        extraction.printed_total_minor = printed_total
+        extraction.printed_total_supplied = True
+    validation = validate(extraction, profile)
+
+    if prepared is not None and not validation.balanced:
+        from .pipeline import recheck  # noqa: PLC0415 - only needed with an image
+
+        agreed = recheck.repair(extraction, validation, prepared, profile, lines)
+        if agreed is not None:
+            recheck.apply(extraction, agreed, lines)
+            # Re-run the whole check instead of patching the totals, so the
+            # per-line arithmetic and warnings match the new prices.
+            validation = validate(extraction, profile)
+            validation.warnings.append(
+                f"price_column_reread:{len(agreed.changes)}_of_{agreed.disputed}"
+            )
+            if agreed.recovered:
+                validation.warnings.append(f"lines_recovered:{len(agreed.recovered)}")
+
+    rid = receipt_id or uuid.uuid4().hex
+
+    doc = build(
+        receipt_id=rid,
+        lines=lines,
+        extraction=extraction,
+        validation=validation,
+        profile=profile,
+        profile_confidence=confidence,
+        ocr_meta=ocr_meta or {"engine": "tesseract", "lang": "ita", "psm": 4, "oem": 1},
+        source={"ingested_at": datetime.now(UTC).isoformat()},
+        review=(
+            review
+            if review is not None
+            else document_module.default_review(validation, extraction)
+        ),
+    )
+    return doc, validation.status
+
+
+# Below 26px Tesseract starts losing lines, so a second pass at a larger size is
+# worth the time. A receipt at 25px was fine; one at 20px lost two lines.
+SMALL_GLYPH = 26
+COMFORTABLE_GLYPH = 30
+
+
+def _closer(candidate: dict, current: dict) -> bool:
+    """Whether a second reading is the better of the two.
+
+    Balancing wins. Failing that, the smaller delta wins. With no total to
+    compare against, more lines found wins, since a missed line takes its
+    money with it.
+    """
+    a, b = candidate["totals"], current["totals"]
+    if a["balanced"] != b["balanced"]:
+        return bool(a["balanced"])
+    if a["delta_minor"] is not None and b["delta_minor"] is not None:
+        return abs(a["delta_minor"]) < abs(b["delta_minor"])
+    if (a["printed_total_minor"] is None) != (b["printed_total_minor"] is None):
+        return b["printed_total_minor"] is None
+    return len(a and candidate["line_items"]) > len(current["line_items"])
+
+
+def _read_larger(prepared, tsv: str, **kwargs):
+    """Read the photo again, enlarged, when the first read came out small.
+
+    Only runs on a receipt that did not add up, so a good one never pays for it.
+    Enlarging adds no detail, but Tesseract's line model does better at the size
+    it expects: on one real receipt it found 33 lines instead of 31.
+    """
+    from PIL import Image  # noqa: PLC0415 - the parsing core runs without Pillow
+
+    from .pipeline.ocr import run  # noqa: PLC0415
+
+    glyph = median_glyph_height(drop_speckle(load_tsv(tsv)))
+    if not glyph or glyph >= SMALL_GLYPH:
+        return None
+
+    scale = COMFORTABLE_GLYPH / glyph
+    bigger = prepared.resize(
+        (round(prepared.width * scale), round(prepared.height * scale)),
+        Image.Resampling.LANCZOS,
+    )
+    result = run(bigger, psm=4)
+    document, status = parse_tsv(result.tsv, prepared=bigger, **kwargs)
+    return document, status, result.tsv, bigger
+
+
+def parse_image(
+    path: Path,
+    *,
+    profile_id: str | None,
+    review: dict[str, Any] | None = None,
+    printed_total: int | None = None,
+):
+    """Parse a photo, carrying the raw TSV along for archiving.
+
+    The document comes back with two private keys, `_tsv` and `_prepared`: the
+    OCR it was built from and the image OCR actually saw. Whoever archives them
+    pops them off first. Item bounding boxes use the prepared image's
+    coordinates, so cropping by box needs that image, not the original photo.
+    """
+    tsv, ocr_meta = read_input(path)
+    # Removed before parse_tsv: build() copies ocr_meta into the document, and a
+    # PIL image in there makes it unserialisable.
+    prepared = ocr_meta.pop("_prepared", None)
+    shared = {
+        "profile_id": profile_id,
+        "review": review,
+        "ocr_meta": ocr_meta,
+        "printed_total": printed_total,
+    }
+    document, status = parse_tsv(tsv, prepared=prepared, **shared)
+
+    if prepared is not None and not document["totals"]["balanced"]:
+        second = _read_larger(prepared, tsv, **shared)
+        if second is not None and _closer(second[0], document):
+            # The archived image must be the one the TSV describes, or crops on
+            # the review page point at the wrong pixels.
+            document, status, tsv, prepared = second
+
+    # Handed to the archiver, which pops both before the document is written.
+    document["_tsv"] = tsv
+    document["_prepared"] = prepared
+    return document, status
+
+

quadra_core/pipeline/document.py

@@ -0,0 +1,159 @@
+"""Building the JSON document for one receipt.
+
+Money leaves here as whole cents, with a _minor suffix so the unit is obvious at
+the call site. Unreadable fields come out null with a warning, never guessed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from decimal import Decimal
+from typing import Any
+
+from quadra_core.pipeline.extract import Extraction
+from quadra_core.pipeline.lines import Line
+from quadra_core.pipeline.validate import Validation
+from quadra_core.profiles.loader import Profile
+
+SCHEMA_VERSION = "1.0.0"
+
+# Below this, the least confident word in a description is too poor to file
+# unseen. Arithmetic cannot catch a misread product name, so this is the only
+# thing that sends one for review.
+LOW_CONFIDENCE_DESCRIPTION = 0.5
+
+
+def no_review(state: str = "not_required") -> dict[str, Any]:
+    """Build the review block for a document nobody has decided anything about.
+
+    Who gets checked is up to whatever uses this library, so the default says
+    only that no decision has been made yet, rather than claiming the receipt
+    was checked or does not need checking.
+    """
+    return {
+        "required": False,
+        "reason": None,
+        "sampled": False,
+        "mode": "none",
+        "state": state,
+        "blind_item_indexes": [],
+    }
+
+
+def default_review(
+    validation: Validation, extraction: Extraction
+) -> dict[str, Any]:
+    """Whether a person has to look, when the caller has not said.
+
+    The caller owns this decision and can pass its own block instead. This is
+    the default, and it errs towards asking: a receipt that does not add up, or
+    that carries a description nobody could read, is not one to file unseen.
+    """
+    reasons = []
+    if not validation.balanced:
+        reasons.append("totals_do_not_balance")
+    if not extraction.items:
+        reasons.append("no_items")
+    worst = min((i.confidence for i in extraction.items), default=1.0)
+    if worst < LOW_CONFIDENCE_DESCRIPTION:
+        reasons.append(f"unreadable_description:{worst:.2f}")
+
+    if not reasons:
+        return no_review()
+    return {
+        "required": True,
+        "reason": "; ".join(reasons),
+        "sampled": False,
+        "mode": "full",
+        "state": "pending",
+        "blind_item_indexes": [],
+    }
+
+
+def _quantity(value: Decimal | None) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    # A string rather than a float, since weighed goods need fractions that
+    # binary floats cannot hold exactly.
+    return {"value": format(value.normalize(), "f"), "unit": "each"}
+
+
+def build(
+    *,
+    receipt_id: str,
+    lines: list[Line],
+    extraction: Extraction,
+    validation: Validation,
+    profile: Profile,
+    profile_confidence: float,
+    ocr_meta: dict[str, Any],
+    source: dict[str, Any],
+    review: dict[str, Any],
+) -> dict[str, Any]:
+    """Assemble the full receipt document."""
+    mean_conf = sum(l.conf for l in lines) / len(lines) if lines else 0.0
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "receipt_id": receipt_id,
+        "source": source,
+        "profile": {
+            "id": profile.id,
+            "version": profile.version,
+            "calibrated": profile.calibrated,
+            "match_confidence": round(profile_confidence, 3),
+        },
+        "ocr": {**ocr_meta, "mean_word_confidence": round(mean_conf, 1)},
+        "merchant": {"name": None, "store_id": None, "address": None, "vat_id": None},
+        "transaction": {
+            "datetime": None,
+            "currency": profile.currency,
+            "receipt_number": None,
+            "payment_method": None,
+        },
+        "line_items": [
+            {
+                "index": i,
+                "description_raw": item.description_raw,
+                "description": item.description,
+                "quantity": _quantity(item.quantity),
+                "quantity_source": item.quantity_source,
+                "unit_price_minor": item.unit_price_minor,
+                "line_total_minor": item.line_total_minor,
+                "discounts_minor": 0,
+                "vat_code": item.vat_code,
+                "confidence": item.confidence,
+                "provenance": {"line_index": item.line_index, "bbox": list(item.bbox)},
+                "flags": item.flags,
+            }
+            for i, item in enumerate(extraction.items)
+        ],
+        "adjustments": [
+            {
+                "kind": adjustment.kind,
+                "label": adjustment.label,
+                "amount_minor": adjustment.amount_minor,
+                "provenance": {"line_index": adjustment.line_index},
+            }
+            for adjustment in extraction.adjustments
+        ],
+        "totals": {
+            "items_subtotal_minor": validation.items_subtotal_minor,
+            "discounts_minor": sum(a.amount_minor for a in extraction.adjustments),
+            "printed_total_minor": validation.printed_total_minor,
+            "computed_total_minor": validation.items_subtotal_minor,
+            "balanced": validation.balanced,
+            "delta_minor": validation.delta_minor,
+        },
+        "validation": {
+            "status": validation.status,
+            "checks": [asdict(c) for c in validation.checks],
+            "warnings": validation.warnings,
+        },
+        "review": {
+            **review,
+            "reviewed_at": None,
+            "duration_ms": None,
+            "rows_expanded": 0,
+            "corrections": [],
+        },
+    }