quadra-core 0.1.0__tar.gz

quadra_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefano Mazzoleni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quadra_core-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: quadra-core
+Version: 0.1.0
+Summary: Deterministic, LLM-free parser for supermarket till receipts.
+Keywords: receipt,ocr,tesseract,parser,supermarket,budgeting
+Author: Stefano Mazzoleni
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pillow>=11
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/SteMazzO/quadra-core
+Project-URL: Repository, https://github.com/SteMazzO/quadra-core
+Project-URL: Issues, https://github.com/SteMazzO/quadra-core/issues
+Description-Content-Type: text/markdown
+
+# Quadra core
+
+Reads a supermarket till receipt from a photo. No ML model, no network calls: Tesseract does the OCR, then geometry and arithmetic do the rest.
+
+```python
+from pathlib import Path
+from quadra_core import parse_image
+
+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 whatever went wrong listed in `validation.warnings`.
+
+    pip install quadra-core
+    sudo apt install tesseract-ocr tesseract-ocr-ita   # for images
+
+## How it works
+
+The line totals plus any discounts have to equal the printed total, so the parser can check its own work.
+
+When the sums don't match it crops out the price column and OCRs that on its own, which gives a second independent reading of every price. Where the two readings disagree it keeps both and picks the combination that hits the printed total. That also recovers lines whose price was unreadable the first time. If two different combinations both add up it changes nothing and flags the receipt.
+
+## Adding a shop
+
+Everything shop-specific is a TOML profile in `src/quadra_core/profiles/`. The code knows how to find a price column, the profile says what a price looks like.
+
+Start with a stub, since `calibrate.py` needs a profile to report against:
+
+```toml
+# src/quadra_core/profiles/myshop.toml
+[profile]
+id = "myshop"
+version = 1
+calibrated = false
+
+[format]
+money = '\d{1,3},\d{2}'
+```
+
+Then point it at a photo:
+
+    python tools/calibrate.py receipt.jpg --profile myshop
+
+It prints what Tesseract read, where the price column landed, which rule matched each line, and whether the totals add up. Add `[[rules]]` and `[regions]` anchors until the lines stop coming back as `unknown`. Rules are tried in order and the first match wins, so put the specific ones first.
+
+Add `[fingerprint]` anchors so the shop is recognised without `--profile`. A VAT number is more stable than a branch address. Save the OCR as a fixture with `--save-fixture NAME` so later changes have something to regress against. Set `calibrated = true` once it balances, otherwise every parse carries a `profile_not_calibrated` warning.
+
+Before committing a fixture, check it for personal data: the address, the loyalty card number, the points balance. `tools/scrub.py` covers the Esselunga ones.
+
+## Development
+
+    uv run pytest
+
+## Licence
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

quadra_core-0.1.0/README.md

@@ -0,0 +1,56 @@
+# Quadra core
+
+Reads a supermarket till receipt from a photo. No ML model, no network calls: Tesseract does the OCR, then geometry and arithmetic do the rest.
+
+```python
+from pathlib import Path
+from quadra_core import parse_image
+
+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 whatever went wrong listed in `validation.warnings`.
+
+    pip install quadra-core
+    sudo apt install tesseract-ocr tesseract-ocr-ita   # for images
+
+## How it works
+
+The line totals plus any discounts have to equal the printed total, so the parser can check its own work.
+
+When the sums don't match it crops out the price column and OCRs that on its own, which gives a second independent reading of every price. Where the two readings disagree it keeps both and picks the combination that hits the printed total. That also recovers lines whose price was unreadable the first time. If two different combinations both add up it changes nothing and flags the receipt.
+
+## Adding a shop
+
+Everything shop-specific is a TOML profile in `src/quadra_core/profiles/`. The code knows how to find a price column, the profile says what a price looks like.
+
+Start with a stub, since `calibrate.py` needs a profile to report against:
+
+```toml
+# src/quadra_core/profiles/myshop.toml
+[profile]
+id = "myshop"
+version = 1
+calibrated = false
+
+[format]
+money = '\d{1,3},\d{2}'
+```
+
+Then point it at a photo:
+
+    python tools/calibrate.py receipt.jpg --profile myshop
+
+It prints what Tesseract read, where the price column landed, which rule matched each line, and whether the totals add up. Add `[[rules]]` and `[regions]` anchors until the lines stop coming back as `unknown`. Rules are tried in order and the first match wins, so put the specific ones first.
+
+Add `[fingerprint]` anchors so the shop is recognised without `--profile`. A VAT number is more stable than a branch address. Save the OCR as a fixture with `--save-fixture NAME` so later changes have something to regress against. Set `calibrated = true` once it balances, otherwise every parse carries a `profile_not_calibrated` warning.
+
+Before committing a fixture, check it for personal data: the address, the loyalty card number, the points balance. `tools/scrub.py` covers the Esselunga ones.
+
+## Development
+
+    uv run pytest
+
+## Licence
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

quadra_core-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[project]
+name = "quadra-core"
+version = "0.1.0"
+description = "Deterministic, LLM-free parser for supermarket till receipts."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "receipt",
+    "ocr",
+    "tesseract",
+    "parser",
+    "supermarket",
+    "budgeting",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = ["Pillow>=11"]
+
+[[project.authors]]
+name = "Stefano Mazzoleni"
+
+[project.urls]
+Homepage = "https://github.com/SteMazzO/quadra-core"
+Repository = "https://github.com/SteMazzO/quadra-core"
+Issues = "https://github.com/SteMazzO/quadra-core/issues"
+
+[project.optional-dependencies]
+
+[project.scripts]
+quadra-core = "quadra_core.cli:main"
+
+[dependency-groups]
+dev = [
+    "pre-commit",
+    "ruff",
+    { include-group = "test" },
+]
+test = [
+    "pytest",
+    "pytest-cov",
+    "jsonschema",
+]
+
+[tool.uv.build-backend]
+source-include = [
+    "tests/**",
+    "tools/**",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "F",
+    "E",
+    "W",
+    "I",
+    "D",
+    "N",
+    "UP",
+    "PL",
+    "RUF",
+    "ERA",
+    "PERF",
+    "B",
+    "G",
+    "Q",
+    "C4",
+    "YTT",
+    "T20",
+    "SIM",
+    "PIE",
+    "FIX",
+    "ICN",
+    "LOG",
+    "PYI",
+    "RET",
+]
+ignore = [
+    "B008",
+    "D104",
+    "D203",
+    "D205",
+    "D213",
+    "E741",
+    "PLR0912",
+    "PLR0913",
+    "PLR2004",
+    "T201",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = [
+    "S101",
+    "D",
+    "T20",
+]

quadra_core-0.1.0/pyproject.toml.orig

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[project]
+name = "quadra-core"
+version = "0.1.0"
+description = "Deterministic, LLM-free parser for supermarket till receipts."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Stefano Mazzoleni" }]
+keywords = ["receipt", "ocr", "tesseract", "parser", "supermarket", "budgeting"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "Pillow>=11",
+]
+
+[project.urls]
+Homepage = "https://github.com/SteMazzO/quadra-core"
+Repository = "https://github.com/SteMazzO/quadra-core"
+Issues = "https://github.com/SteMazzO/quadra-core/issues"
+
+[project.optional-dependencies]
+[dependency-groups]
+dev = [
+    "pre-commit",
+    "ruff",
+    {include-group = "test"},
+]
+test = [
+    "pytest",
+    "pytest-cov",
+    "jsonschema",
+]
+
+[project.scripts]
+quadra-core = "quadra_core.cli:main"
+
+[tool.uv.build-backend]
+source-include = ["tests/**", "tools/**"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "F",
+    "E",
+    "W",
+    "I",
+    "D",
+    "N",
+    "UP",
+    "PL",
+    "RUF",
+    "ERA",
+    "PERF",
+    "B",
+    "G",
+    "Q",
+    "C4",
+    "YTT",
+    "T20",
+    "SIM",
+    "PIE",
+    "FIX",
+    "ICN",
+    "LOG",
+    "PYI",
+    "RET",
+]
+ignore = [
+    "B008",     # function-call-in-default-argument
+    "D104",     # undocumented-public-package
+    "D203",     # incorrect-blank-line-before-class
+    "D205",     # missing-blank-line-after-summary
+    "D213",     # multi-line-summary-second-line
+    "E741",     # ambiguous-variable-name
+    "PLR0912",  # too-many-branches
+    "PLR0913",  # too-many-arguments
+    "PLR2004",  # magic-value-comparison
+    "T201",     # print
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = ["S101", "D", "T20"]

quadra_core-0.1.0/src/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-0.1.0/src/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())