moonlight-lupin/agent-skills / productivity/receipt-compiler
receipt-compiler
VerifiedUse when compiling phone-camera photos of receipts into an A4 PDF expense-claim pack — straighten, B&W scan look, optional cover/numbering/captions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.7 KB |
| scripts/receipt_compiler.py | script | 40.2 KB |
| tests/receipt_compiler_selftest.py | script | 17.1 KB |
scripts/receipt_compiler.py
View on GitHub#!/usr/bin/env python3
"""receipt_compiler — phone-camera receipts → straightened B&W scans → A4 expense-claim PDF.
Subcommands:
scan INPUT_DIR -o workdir process photos, OCR, write manifest.json
review workdir print the expense table for user confirmation
confirm workdir stamp user approval + bind reviewed data (digest)
pack workdir -o out.pdf build A4 PDF from a CONFIRMED manifest
The confirmation gate is enforced in code: `pack` refuses to run unless the
manifest carries "confirmed": true (set by the confirm subcommand).
"""
from __future__ import annotations
import argparse
import json
import re
import sys
from datetime import date
from pathlib import Path
import numpy as np
try:
import cv2
except ImportError:
cv2 = None
try:
import pytesseract
from pytesseract import Output
except ImportError:
pytesseract = None
from PIL import Image, ImageOps
try:
import pillow_heif
pillow_heif.register_heif_opener()
HEIF_OK = True
except ImportError:
HEIF_OK = False
IMG_EXTS = {".jpg", ".jpeg", ".png", ".heic", ".heif", ".webp", ".bmp", ".tif", ".tiff"}
MANIFEST_VERSION = 1
AMOUNT_RE = re.compile(
# currency code/symbol glued to the number (RM12.50, S$1,234.56, $12.50),
# or a standalone number with word boundaries (no preceding word char).
# (?<![A-Za-z]): TERM 30 / CONFIRM 1 must not read as "RM 30";
# (?<=\d): trailing "." / "," must not be swallowed (RM12.50.)
r"(?<![A-Za-z])(?:S?\$|SGD|RM|USD|EUR|GBP)\s?\d[\d.,]*(?<=\d)"
r"|\b\d{1,3}(?:[.,]\d{3})+(?:[.,]\d{1,2})?"
r"|\b\d{1,6}(?:[.,]\d{1,2})(?!\d)"
r"|\b\d{1,6}(?![.,\d])",
re.IGNORECASE
)
DATE_RES = [
re.compile(r"\b(\d{1,2})[/\-.](\d{1,2})[/\-.](\d{2,4})\b"),
re.compile(r"\b(\d{4})[/\-.](\d{1,2})[/\-.](\d{1,2})\b"),
re.compile(r"\b(\d{1,2})\s+(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s*(\d{2,4})\b", re.IGNORECASE),
]
NOISE_WORDS = {"receipt", "invoice", "tax", "gst", "subtotal", "total", "cash", "change",
"thank", "you", "please", "come", "again", "visa", "master", "net"}
# --------------------------------------------------------------------------- io
def load_image(path: Path) -> np.ndarray | None:
try:
with Image.open(path) as im:
im = ImageOps.exif_transpose(im) # always; not HEIF-conditional
im = im.convert("RGB")
# cap input size; phone cameras are 12MP+, we only need ~2000px
im.thumbnail((2200, 2200), Image.LANCZOS)
return np.ascontiguousarray(np.asarray(im)[:, :, ::-1]) # RGB->BGR for cv2
except Exception as exc:
print(f"WARN cannot read {path.name}: {exc}", file=sys.stderr)
return None
# -------------------------------------------------------------------- geometry
def _order_quad(pts: np.ndarray) -> np.ndarray:
"""Order 4 points: TL, TR, BR, BL."""
pts = pts.reshape(4, 2).astype(np.float32)
s = pts.sum(axis=1)
d = np.diff(pts, axis=1).ravel()
return np.array([pts[np.argmin(s)], pts[np.argmin(d)],
pts[np.argmax(s)], pts[np.argmax(d)]], dtype=np.float32)
def find_receipt_quad(gray: np.ndarray) -> np.ndarray | None:
"""Largest plausible quadrilateral contour, or None."""
blur = cv2.GaussianBlur(gray, (5, 5), 0)
edges = cv2.Canny(blur, 50, 150)
edges = cv2.dilate(edges, np.ones((3, 3), np.uint8), iterations=2)
contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
h, w = gray.shape
img_area = h * w
best = None
for c in sorted(contours, key=cv2.contourArea, reverse=True)[:8]:
area = cv2.contourArea(c)
if area < 0.20 * img_area:
break
peri = cv2.arcLength(c, True)
approx = cv2.approxPolyDP(c, 0.02 * peri, True)
if len(approx) == 4 and cv2.isContourConvex(approx):
best = approx
break
if best is None and area > 0.35 * img_area:
rect = cv2.minAreaRect(c)
best = cv2.boxPoints(rect).astype(np.int32).reshape(4, 1, 2)
if best is None:
return None
quad = _order_quad(best)
# reject degenerate quads (thin slivers)
if cv2.contourArea(quad) < 0.15 * img_area:
return None
return quad
def warp_receipt(bgr: np.ndarray, quad: np.ndarray) -> np.ndarray:
tl, tr, br, bl = quad
wA = np.linalg.norm(br - bl)
wB = np.linalg.norm(tr - tl)
hA = np.linalg.norm(tr - br)
hB = np.linalg.norm(tl - bl)
out_w = int(max(wA, wB))
out_h = int(max(hA, hB))
M = cv2.getPerspectiveTransform(
quad.astype(np.float32),
np.array([[0, 0], [out_w - 1, 0], [out_w - 1, out_h - 1], [0, out_h - 1]],
dtype=np.float32))
out = cv2.warpPerspective(bgr, M, (out_w, out_h))
# quad-corner ordering is only reliable for |rotation| < 45deg; beyond that
# the warp comes out rotated 90deg. Detect by text-ink orientation, not
# aspect: text lines create more ink variance between ROWS (line gaps) than
# between COLUMNS. Rotate only when the ink says the text is vertical.
if _text_is_vertical(out):
out = cv2.rotate(out, cv2.ROTATE_90_COUNTERCLOCKWISE)
return out
def _text_is_vertical(gray: np.ndarray) -> bool:
"""True if the image's ink rows look like vertical text lines."""
if gray.ndim == 3:
gray = cv2.cvtColor(gray, cv2.COLOR_BGR2GRAY)
if min(gray.shape) < 20:
return False
_, bw = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)
ink = bw.astype(np.float64) / 255.0
row_var = np.var(ink.mean(axis=1)) # variance across horizontal text lines
col_var = np.var(ink.mean(axis=0)) # if text is vertical, columns vary more
return col_var > row_var * 1.3
def deskew(gray: np.ndarray) -> np.ndarray:
"""Small-angle deskew for full-frame fallback scans."""
# binarize first: desk/background pixels dominate on dark desks otherwise
_, bw = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)
coords = np.column_stack(np.nonzero(bw))
if len(coords) < 100 or len(coords) > 0.9 * bw.size:
return gray # too little or too much foreground: geometry unreliable
angle = cv2.minAreaRect(coords[:, ::-1].astype(np.float32))[-1]
# normalize to [-45, 45]: minAreaRect returns [-90, 0); a portrait
# foreground reads near -90 but the *page* itself is near-axis-aligned
if angle <= -45:
angle += 90
elif angle > 45:
angle -= 90
if abs(angle) < 0.4 or abs(angle) > 15:
return gray
h, w = gray.shape
M = cv2.getRotationMatrix2D((w / 2, h / 2), angle, 1.0)
return cv2.warpAffine(gray, M, (w, h), flags=cv2.INTER_CUBIC,
borderMode=cv2.BORDER_REPLICATE)
# -------------------------------------------------------------------- scanify
def scanify(gray: np.ndarray, mode: str) -> tuple[np.ndarray, np.ndarray]:
"""Returns (display, ocr_input).
display = photo: grayscale+stretch; bw: photocopy-style threshold.
ocr_input = the stretched grayscale for BOTH modes: tesseract binarizes
internally, and thresholding first can erase faint thermal print — so the
extracted amounts must not depend on the user's look choice.
"""
lo, hi = np.percentile(gray, (2, 98))
if hi > lo:
gray = np.clip((gray - lo) * 255.0 / (hi - lo), 0, 255).astype(np.uint8)
ocr_in = gray
if mode == "photo":
return gray, ocr_in
thr = cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
cv2.THRESH_BINARY, 31, 15)
return thr, ocr_in
# ------------------------------------------------------------------------ ocr
def _extract_date(text: str):
m = DATE_RES[2].search(text)
if m:
months = {n: i + 1 for i, n in enumerate(
["jan", "feb", "mar", "apr", "may", "jun",
"jul", "aug", "sep", "oct", "nov", "dec"])}
mon = months.get(m.group(2).lower()[:3])
if mon is not None:
day, yr = int(m.group(1)), m.group(3)
yr = int(yr) + (2000 if int(yr) < 100 else 0)
try:
return date(yr, mon, day).isoformat()
except ValueError:
pass
m = DATE_RES[0].search(text)
if m:
d_, mo, y = int(m.group(1)), int(m.group(2)), m.group(3)
if mo <= 12:
y = int(y) + (2000 if int(y) < 100 else 0)
try:
return date(y, mo, d_).isoformat()
except ValueError:
pass
m = DATE_RES[1].search(text)
if m:
y, mo, d_ = int(m.group(1)), int(m.group(2)), int(m.group(3))
try:
return date(y, mo, d_).isoformat()
except ValueError:
pass
return None
def _to_float(amt: str):
"""Normalize an OCR amount token to float, or None.
Handles currency prefixes (case-insensitive), thousands separators
(1,234.56 → 1234.56), and comma-decimal (12,30 → 12.30).
"""
s = amt.upper().strip()
s = re.sub(r"(SGD|USD|EUR|GBP|RM|S\$|\$)", "", s).strip()
s = s.replace(" ", "")
# reject 3-decimal fractions (per-litre prices: 1.899) — they'd read as a
# thousands group and inflate 1000x; KWD/BHD/OMR 3-decimal currencies are
# out of scope for SGD/MYR claims
if re.search(r"[.,]\d{3}$", s) and len(s) <= 5:
return None
if not re.fullmatch(r"\d{1,7}([.,]\d{3})*([.,]\d{1,2})?", s):
return None
# decide separators: rightmost group of 2 digits = decimal, groups of 3 = thousands
if re.search(r"[.,]\d{1,2}$", s):
dec_sep = "." if s.rfind(".") > s.rfind(",") else ","
head, _, tail = s.rpartition(dec_sep)
head = re.sub(r"[.,]", "", head)
s = f"{head}.{tail}"
else:
s = re.sub(r"[.,]", "", s)
try:
return float(s)
except ValueError:
return None
def _parse_ocr(lines: list[str]) -> dict:
text = "\n".join(lines)
amounts = []
total_amount = None
for i, ln in enumerate(lines):
for amt in AMOUNT_RE.findall(ln):
val = _to_float(amt)
if val is None:
continue
# bare integers (no decimal part) on non-total lines are usually
# years/quantities/phone fragments — only trust them in total context
if (re.fullmatch(r"\d{1,6}", amt.strip())
and not _TOTAL_KW.search(ln.lower())):
continue
amounts.append((val, ln.lower(), i))
total_amount = _pick_total(lines, amounts)
d = _extract_date(text)
merchant = None
for ln in lines[:8]:
words = re.findall(r"[A-Za-z]{3,}", ln)
kept = [w for w in words if w.lower() not in NOISE_WORDS]
if kept:
# filter noise tokens out but keep the rest of the line
cleaned = re.sub(r"\b(Tax|Invoice|Receipt|Bill|Statement|Official)\b",
"", ln, flags=re.IGNORECASE).strip()
merchant = (cleaned or " ".join(kept))[:40]
break
return {"date": d, "merchant": merchant, "amount": total_amount}
_TOTAL_KW = re.compile(r"grand total|total amount|\btotal\b|\bamount due\b"
r"|\bbalance due\b|\bbalance\b")
_SUB_KW = re.compile(r"sub[- ]?total")
_TENDER_KW = re.compile(r"tender|\bchange\b|\bcash\b|\bpaid\b|visa|master"
r"|\bnets\b|paynow|paylah|debit|credit card")
_QTY_KW = re.compile(r"\bqty\b|\bquantity\b|\bitems?\b|\bno\.?\s*of\b|\bunits?\b")
def _pick_total(lines: list[str], amounts: list[tuple]) -> float | None:
"""Choose the receipt total from OCR amount candidates.
Priority: (1) keyword-total lines excluding tender/change/subtotal/qty
lines; (2) the amount on the line right after a lone 'TOTAL' keyword line
(same exclusions, plus a qty check on the total line itself); (3)
non-tender amounts; (4) anything.
"""
totals = [a for a in amounts
if _TOTAL_KW.search(a[1]) and not _SUB_KW.search(a[1])
and not _TENDER_KW.search(a[1]) and not _QTY_KW.search(a[1])]
if not totals:
for i, ln in enumerate(lines):
low = ln.lower()
if (_TOTAL_KW.search(low) and not _SUB_KW.search(low)
and not _QTY_KW.search(low)):
nxt = lines[i + 1].lower() if i + 1 < len(lines) else ""
if _TENDER_KW.search(nxt) or _SUB_KW.search(nxt):
continue # next line is a payment/subtotal row, not the total
for amt in AMOUNT_RE.findall(nxt):
val = _to_float(amt)
if val is not None:
totals.append((val, nxt, i + 1))
if totals:
return max(totals, key=lambda a: a[0])[0]
if not amounts:
return None
non_tender = [a for a in amounts if not _TENDER_KW.search(a[1])]
pool = non_tender or amounts
return max(pool, key=lambda a: a[0])[0]
def ocr_lines(gray: np.ndarray) -> tuple[list[str], float]:
if pytesseract is None:
return [], 0.0
data = pytesseract.image_to_data(gray, output_type=Output.DICT)
groups: dict[tuple, list] = {}
confs = []
n_low = 0 # dropped low-confidence words count toward the average
for i in range(len(data["text"])):
txt = data["text"][i].strip()
conf = float(data["conf"][i])
if not txt:
continue
if conf < 40:
n_low += 1
continue
confs.append(conf)
key = (data["block_num"][i], data["par_num"][i], data["line_num"][i])
groups.setdefault(key, []).append((data["word_num"][i], txt))
lines = []
for key in sorted(groups):
words = [w for _, w in sorted(groups[key])]
lines.append(" ".join(words))
denom = len(confs) + n_low
avg_conf = sum(confs) / denom if denom else 0.0
return lines, round(avg_conf, 1)
# ----------------------------------------------------------------- digest
def _review_digest(manifest: dict, workdir: Path | None = None) -> str:
"""Stable hash of what the user reviewed: reviewed fields PLUS the SHA256
of each processed image's bytes, so an in-place image swap after confirm
invalidates the digest."""
import hashlib
h = hashlib.sha256()
payload = {
"mode": manifest.get("mode"),
"receipts": [
{k: e.get(k) for k in
("n", "date", "merchant", "description", "amount", "currency",
"include")}
for e in manifest.get("receipts", [])
],
}
h.update(json.dumps(payload, sort_keys=True,
ensure_ascii=False).encode("utf-8"))
if workdir is not None:
# image bytes bind the digest to actual reviewed content; sorted by n so
# the byte-stream order is stable regardless of list order. Note: the
# JSON payload itself keeps list order, so reordering receipts still
# forces re-confirmation (fail-closed, intentional).
for e in sorted(manifest.get("receipts", []), key=lambda e: e.get("n", 0)):
p = workdir / e.get("processed", "")
try:
h.update(p.read_bytes())
except OSError:
h.update(b"<missing>")
return h.hexdigest()
# ----------------------------------------------------------------- sub: scan
def cmd_scan(args) -> int:
if cv2 is None:
print("ERROR opencv-python-headless is required: pip install opencv-python-headless")
return 2
# preflight OCR: silently-degraded scan (exit 0, blank table) is worse
# than a hard failure
if pytesseract is None:
print("ERROR pytesseract is required: pip install pytesseract")
return 2
try:
pytesseract.get_tesseract_version()
except Exception:
print("ERROR tesseract binary not found on PATH: install tesseract-ocr "
"(e.g. apt install tesseract-ocr)")
return 2
src = Path(args.input_dir).expanduser()
outdir = Path(args.out).expanduser()
proc_dir = outdir / "processed"
if not src.is_dir():
print(f"ERROR input dir not found or not a directory: {src}")
return 1
files = sorted(p for p in src.iterdir()
if p.suffix.lower() in IMG_EXTS and p.is_file())
if not files:
print(f"ERROR no images found in {src}")
return 1
heif_needed = any(p.suffix.lower() in (".heic", ".heif") for p in files)
if heif_needed and not HEIF_OK:
print("ERROR pillow-heif is required for .heic/.heif photos: "
"pip install pillow-heif (or ask the user for JPGs)")
return 1
proc_dir.mkdir(parents=True, exist_ok=True)
entries = []
failures = []
for path in files:
bgr = load_image(path)
if bgr is None:
failures.append(str(path))
continue
gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
quad = find_receipt_quad(gray)
if quad is not None:
bgr = warp_receipt(bgr, quad)
gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
method = "perspective_warp"
else:
gray = deskew(gray)
method = "deskew"
scan, ocr_in = scanify(gray, args.mode)
idx = len(entries) + 1 # sequential n, no gaps from skipped files
out_png = proc_dir.resolve() / f"{idx:02d}_{path.stem}.png"
Image.fromarray(scan).save(out_png)
try:
lines, conf = ocr_lines(ocr_in)
except Exception as exc:
print(f"WARN OCR failed for {path.name}: {exc}", file=sys.stderr)
lines, conf = [], 0.0
ocr = _parse_ocr(lines)
h, w = scan.shape
entries.append({
"n": idx, "source": str(path), "processed": str(out_png),
"width": w, "height": h, "aspect": round(h / w, 3),
"method": method, "ocr_confidence": conf,
"ocr": ocr,
# editable caption fields (agent/user fills; all optional)
"date": ocr.get("date") or "",
"merchant": ocr.get("merchant") or "",
"description": "",
"amount": ocr.get("amount"),
"currency": "SGD",
"include": True,
"needs_review": conf < 55 or ocr.get("amount") is None,
})
if not entries:
print(f"ERROR no images could be decoded from {src}; failures: {failures}")
return 1
manifest = {
"version": MANIFEST_VERSION,
"mode": args.mode,
"created": date.today().isoformat(),
"receipts": entries,
"unreadable": failures,
# confirmation gate — set true only after the user approves the table
"confirmed": False,
"confirmations": {},
}
mpath = outdir / "manifest.json"
# NOTE: review_digest is stamped ONLY by the confirm subcommand, never at
# scan time — otherwise hand-editing confirmed=true would pass the gate.
mpath.write_text(json.dumps(manifest, indent=2, ensure_ascii=False))
print(json.dumps({"manifest": str(mpath), "receipts": len(entries),
"unreadable": [Path(f).name for f in failures],
"needs_review": [e["n"] for e in entries if e["needs_review"]]}))
return 0
# --------------------------------------------------------------- sub: review
def cmd_review(args) -> int:
mpath = Path(args.workdir).expanduser() / "manifest.json"
m = json.loads(mpath.read_text())
unreadable = m.get("unreadable") or []
if unreadable:
print(f"WARNING {len(unreadable)} photo(s) could not be read and are NOT "
"in this claim: " + ", ".join(Path(f).name for f in unreadable))
print("If those receipts should be claimed, fix/convert them and re-run scan.")
print(f"{'#':>3} {'date':<11} {'amount':>9} merchant / description (src)")
tot_by_ccy = {}
for e in m["receipts"]:
if not e.get("include", True):
print(f"{e['n']:>3} -- excluded -- {Path(e['source']).name}")
continue
amt = e.get("amount")
if amt is not None and (isinstance(amt, bool)
or not isinstance(amt, (int, float))):
print(f"ERROR receipt #{e['n']} amount is not a number: {amt!r}. "
"Fix manifest.json (JSON number, no currency text), then re-run review.")
return 1
flag = " ?" if e.get("needs_review") else ""
desc = e.get("description") or e.get("merchant") or ""
print(f"{e['n']:>3} {e.get('date') or '-':<11} "
f"{(e.get('currency', '') + ' ' + ('%.2f' % amt)) if amt is not None else '-':>9}"
f" {desc[:44]}{flag} ({Path(e['source']).name})")
if isinstance(amt, (int, float)):
ccy = e.get("currency", "SGD")
tot_by_ccy[ccy] = tot_by_ccy.get(ccy, 0.0) + amt
if len(tot_by_ccy) == 1:
ccy, tot = next(iter(tot_by_ccy.items()))
print(f"\nTotal: {ccy} {tot:.2f}")
elif tot_by_ccy:
print("\nTotals (mixed currencies — no combined total):")
for ccy in sorted(tot_by_ccy):
print(f" {ccy}: {tot_by_ccy[ccy]:.2f}")
print(f"confirmed={m.get('confirmed')}")
return 0
# --------------------------------------------------------------- sub: confirm
def _validate_amounts(m: dict) -> str | None:
"""Return an error message if any non-excluded receipt has a non-numeric
amount, else None. bool is an int subclass — reject it explicitly."""
for e in m["receipts"]:
if not e.get("include", True):
continue
amt = e.get("amount")
if amt is not None and (isinstance(amt, bool)
or not isinstance(amt, (int, float))):
return (f"receipt #{e.get('n', '?')} amount is not a number: {amt!r}. "
"Fix manifest.json (JSON number, no currency text), then "
"re-run review before confirming.")
return None
def cmd_confirm(args) -> int:
"""Stamp user approval: sets confirmed=true and binds review_digest to the
manifest's CURRENT reviewed fields. Any later edit breaks the digest."""
mpath = Path(args.workdir).expanduser() / "manifest.json"
m = json.loads(mpath.read_text())
err = _validate_amounts(m)
if err:
print(f"ERROR {err}")
return 1
m.pop("review_digest", None)
m["confirmed"] = True
m["review_digest"] = _review_digest(m, Path(args.workdir).expanduser())
mpath.write_text(json.dumps(m, indent=2, ensure_ascii=False))
n_inc = sum(1 for e in m["receipts"] if e.get("include", True))
print(json.dumps({"confirmed": True, "receipts": n_inc,
"review_digest": m["review_digest"]}))
return 0
# ------------------------------------------------------------------ sub: pack
def cmd_pack(args) -> int:
workdir = Path(args.workdir).expanduser()
m = json.loads((workdir / "manifest.json").read_text())
if m.get("version") != MANIFEST_VERSION:
print(f"ERROR manifest version {m.get('version')!r} not supported "
f"(expected {MANIFEST_VERSION}) — re-run scan.")
return 1
if m.get("confirmed") is not True:
print("ERROR manifest not confirmed. Run review, get user approval, then "
"the confirm subcommand.")
return 1
if "review_digest" not in m:
print("ERROR manifest has no review_digest — confirmation must be stamped "
"by the confirm subcommand, not hand-edited.")
return 1
if _review_digest(m, workdir) != m["review_digest"]:
print("ERROR manifest or processed images changed after confirmation "
"(review_digest mismatch). Re-review the table, get fresh "
"approval, then pack.")
return 1
err = _validate_amounts(m)
if err:
print(f"ERROR {err}")
return 1
missing = [e.get("processed", "") for e in m["receipts"]
if e.get("include", True) and not (workdir / e.get("processed", "")).is_file()]
if missing:
print(f"ERROR processed images missing (re-run scan, then review + "
f"confirm again): {missing}")
return 1
# required entry keys — hand-edited manifests must fail cleanly, not KeyError
required = ("n", "aspect", "processed", "source")
for e in m["receipts"]:
if e.get("include", True):
for k in required:
if k not in e:
print(f"ERROR manifest entry missing required key {k!r} "
f"(re-run scan): {e}")
return 1
from reportlab.lib.pagesizes import A4
from reportlab.lib.units import mm
from reportlab.pdfgen import canvas
receipts = [e for e in m["receipts"] if e.get("include", True)]
if not receipts:
print("ERROR no receipts marked include=true")
return 1
seen_n = set()
for e in receipts:
if e["n"] in seen_n:
print(f"ERROR duplicate receipt number #{e['n']} in manifest — "
"renumber and re-run confirm.")
return 1
seen_n.add(e["n"])
out = Path(args.out).expanduser()
out.parent.mkdir(parents=True, exist_ok=True)
PW, PH = A4
MARGIN = 15 * mm
FOOTER = 10 * mm
content_w = PW - 2 * MARGIN
content_h = PH - MARGIN - FOOTER
gap = 5 * mm
c = canvas.Canvas(str(out), pagesize=A4)
c.setTitle(args.title or "Expense receipts")
# ---- Unicode-capable font: built-in Helvetica is WinAnsi-only, so CJK/etc
# text needs a TTF (some reportlab builds substitute .notdef boxes silently
# instead of raising — both outcomes are unacceptable for claim text).
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont
def _find_ttf() -> str | None:
cands = [
# CJK-capable faces first (SGD/MYR claims can carry Chinese merchant
# names); DejaVu has Latin/Cyrillic only
"/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
"/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
"/usr/share/fonts/truetype/noto/NotoSans-Regular.ttf",
"/usr/share/fonts/dejavu/DejaVuSans.ttf",
"/System/Library/Fonts/Supplemental/Arial Unicode.ttf"]
try:
from PIL import ImageFont as _IF
for name in ("DejaVuSans.ttf", "LiberationSans-Regular.ttf"):
p = _IF.truetype(name, 10).path
if p and Path(p).is_file():
cands.append(p)
except Exception:
pass
return next((p for p in cands if Path(p).is_file()), None)
_uni_path = _find_ttf()
uni_font = None
uni_bold = None
if _uni_path:
try:
pdfmetrics.registerFont(TTFont("ReceiptUni", _uni_path))
uni_font = "ReceiptUni"
bold_path = (_uni_path.replace("DejaVuSans.ttf", "DejaVuSans-Bold.ttf")
if _uni_path.endswith("DejaVuSans.ttf") else _uni_path)
if bold_path != _uni_path and Path(bold_path).is_file():
pdfmetrics.registerFont(TTFont("ReceiptUni-Bold", bold_path))
uni_bold = "ReceiptUni-Bold"
except Exception:
uni_font = None
def _txt(s, bold=False):
"""(fontname, text) — route through the Unicode font when needed."""
s = "" if s is None else str(s)
if s.isascii():
return ("Helvetica-Bold" if bold else "Helvetica"), s
if uni_font:
f = (uni_bold or uni_font) if bold else uni_font
return f, s
# no Unicode font available: sanitize non-WinAnsi chars with a warning
cleaned = s.encode("latin-1", "replace").decode("latin-1")
print(f"WARN non-Latin text unavailable (no TTF found): {s!r} -> {cleaned!r}",
file=sys.stderr)
return ("Helvetica-Bold" if bold else "Helvetica"), cleaned
# ---- layout: compute receipt pages FIRST so page numbers are known
TALL_RATIO = 2.2
normals = [e for e in receipts if e["aspect"] < TALL_RATIO]
talls = [e for e in receipts if e["aspect"] >= TALL_RATIO]
def cell_for(e, cell_w, cell_h):
"""Largest box preserving aspect that fits cell."""
a = e["aspect"]
w_ = cell_w
h_ = w_ * a
if h_ > cell_h:
h_ = cell_h
w_ = h_ / a
return w_, h_
BADGE_H = 5 * mm
ann_h = (12 * mm if args.number else 0) + (8 * mm if args.captions else 0)
# pack rows: talls go 3-per-row (they are narrow), normals 2-per-row
rows = []
i = 0
while i < len(talls):
rows.append(talls[i:i + 3])
i += 3
i = 0
while i < len(normals):
rows.append(normals[i:i + 2])
i += 2
# assign rows to pages; row_h covers image + reserved annotation strip
pages = []
cur, cur_h = [], 0.0
for row in rows:
tall = row[0]["aspect"] >= TALL_RATIO
img_h = (content_h - ann_h) if tall else min(
max(cell_for(e, (content_w - gap) / 2, content_h)[1] for e in row),
content_h * 0.52)
row_h = img_h + ann_h
if cur_h + row_h + gap > content_h and cur:
pages.append(cur)
cur, cur_h = [], 0.0
cur.append((row, img_h, row_h, tall))
cur_h += row_h + gap # trailing gap tolerated (fits inside footer margin)
if cur:
pages.append(cur)
# ---- cover plan: ONE break computation shared by count + render
cover_plan = [] # list of (page_rows, has_title)
if args.cover:
ROW_H = 5.5 * mm
# totals block height: one bold line per currency + clearance
tot_by_ccy = {}
for e in receipts:
amt = e.get("amount")
if isinstance(amt, (int, float)):
ccy = e.get("currency", "SGD")
tot_by_ccy[ccy] = tot_by_ccy.get(ccy, 0.0) + amt
totals_h = (6 * mm * max(1, len(tot_by_ccy))) + 6 * mm
# title block: heading + meta rows + gap (first page only).
# CONSUME_* must mirror cover_table_header() exactly:
# with title: 10mm title + n_meta*7mm meta + 6mm gap + 6mm header row
# plain page: 6mm header row + 6mm return
n_meta = 1 + (1 if args.claimant else 0) + (1 if args.period else 0) \
+ (1 if args.notes else 0) # Receipts count always shown
CONSUME_TITLE = 10 * mm + n_meta * 7 * mm + 12 * mm
CONSUME_PLAIN = 12 * mm
# capacity = rows that fit between the header and (MARGIN + totals)
first_capacity = (PH - 40 * mm) - CONSUME_TITLE - MARGIN - totals_h
plain_capacity = (PH - MARGIN) - CONSUME_PLAIN - MARGIN - totals_h
cur_rows, room, has_title = [], first_capacity, True
for e in receipts:
if room < ROW_H:
cover_plan.append((cur_rows, has_title))
cur_rows, room, has_title = [], plain_capacity, False
cur_rows.append(e)
room -= ROW_H
if cur_rows or not cover_plan:
cover_plan.append((cur_rows, has_title))
cover_pages = len(cover_plan)
else:
cover_pages = 0
total_pages = len(pages) + cover_pages
def page_footer(pn):
c.setFont("Helvetica", 8)
c.setFillGray(0.35)
c.drawCentredString(PW / 2, FOOTER / 2, f"Page {pn} of {total_pages}")
c.setFillGray(0)
# ---- optional cover page(s): paginated expense index
if args.cover:
def cover_table_header(y, with_title):
if with_title:
f, t = _txt(args.title or "Expense Claim", bold=True)
c.setFont(f, 20)
c.drawString(MARGIN, y, t)
y -= 10 * mm
rows_meta = [("Claimant", args.claimant or ""),
("Period", args.period or ""),
("Receipts", str(len(receipts)))]
if args.notes:
rows_meta.append(("Notes", args.notes))
for k, v in rows_meta:
if v:
fk, tk = _txt(f"{k}:", bold=True)
c.setFont(fk, 11)
c.drawString(MARGIN, y, tk)
fv, tv = _txt(v)
# truncate to the printable width so nothing runs off-page
room = PW - MARGIN - (MARGIN + 75) - 6
shown = tv
while shown and c.stringWidth(shown, fv, 11) > room:
shown = shown[:-1].rstrip()
c.setFont(fv, 11)
c.drawString(MARGIN + 75, y, shown)
y -= 7 * mm
y -= 6 * mm
c.setFont("Helvetica-Bold", 10)
c.drawString(MARGIN, y, "#")
c.drawString(MARGIN + 12 * mm, y, "Date")
c.drawString(MARGIN + 45 * mm, y, "Description")
c.drawRightString(PW - MARGIN, y, "Amount")
return y - 6 * mm
pn = 1
for page_rows, has_title in cover_plan:
y = (PH - 40 * mm) if has_title else (PH - MARGIN)
y = cover_table_header(y, has_title)
for e in page_rows:
amt = e.get("amount")
fd, td = _txt(e.get("date") or "-")
fdesc, tdesc = _txt(e.get("description") or e.get("merchant") or "-")
c.setFont("Helvetica", 10)
c.drawString(MARGIN, y, str(e["n"]))
c.setFont(fd, 10)
c.drawString(MARGIN + 12 * mm, y, td)
c.setFont(fdesc, 10)
c.drawString(MARGIN + 45 * mm, y, tdesc[:70])
if isinstance(amt, (int, float)):
fa, ta = _txt(f"{e.get('currency','')}{amt:,.2f}")
c.setFont(fa, 10)
c.drawRightString(PW - MARGIN, y, ta)
y -= ROW_H
pn += 1
if pn <= cover_pages:
page_footer(pn - 1)
c.showPage()
# totals + page footer on the last cover page
yy = y - 4 * mm
if len(tot_by_ccy) == 1:
ccy, tot = next(iter(tot_by_ccy.items()))
ft, tt = _txt(f"Total: {ccy} {tot:,.2f}", bold=True)
c.setFont(ft, 11)
c.drawRightString(PW - MARGIN, yy, tt)
elif tot_by_ccy:
for ccy in sorted(tot_by_ccy):
ft, tt = _txt(f"Total {ccy}: {tot_by_ccy[ccy]:,.2f}", bold=True)
c.setFont(ft, 11)
c.drawRightString(PW - MARGIN, yy, tt)
yy -= 6 * mm
page_footer(pn - 1)
c.showPage()
# ---- receipt pages
pn = cover_pages # receipt pages start after the cover
for page in pages:
y = PH - MARGIN
for row, img_h, row_h, tall in page:
n_cols = len(row)
col_w = (content_w - gap * (n_cols - 1)) / n_cols
x = MARGIN
for e in row:
w_, h_ = cell_for(e, col_w, img_h)
img_path = workdir / e["processed"] # same resolution as digest/missing checks
c.drawImage(str(img_path), x, y - h_, width=w_, height=h_,
preserveAspectRatio=True)
# numbering badge (drawn below image, inside reserved strip)
if args.number:
badge_top = y - h_ - 1.5 * mm # gap below the image edge
c.setFont("Helvetica-Bold", 10)
badge_w = c.stringWidth(f"#{e['n']}", "Helvetica-Bold", 10) + 6
c.rect(x, badge_top - BADGE_H, badge_w, BADGE_H, stroke=0, fill=1)
c.setFillGray(1)
c.drawString(x + 3, badge_top - BADGE_H + 3.2, f"#{e['n']}")
c.setFillGray(0)
# caption (below badge; merchant truncated to fit, amount never cut)
if args.captions:
amt_txt = (f"{e.get('currency','')}{e['amount']:,.2f}"
if isinstance(e.get("amount"), (int, float)) else None)
n_txt = f"#{e['n']}"
date_txt = e.get("date") or None
merch_txt = e.get("merchant") or e.get("description") or None
sep = " · "
# resolve fonts ONCE for the whole caption; mixed-font
# captions aren't worth the complexity — if any part is
# non-Latin the whole caption uses the Unicode font
parts_all = [n_txt, date_txt or "", amt_txt or "",
merch_txt or ""]
cap_font = "Helvetica"
cap_warn = False
if any(not p.isascii() for p in parts_all):
if uni_font:
cap_font = uni_font
else:
cap_warn = True # _txt-equivalent sanitize fallback
amt_w = c.stringWidth(amt_txt, cap_font, 8.5) if amt_txt else 0
sep_w = c.stringWidth(sep, cap_font, 8.5)
# fixed fields (#n, date) and amount stay whole; only the
# merchant/description slot is ellipsized to fit
base = sep.join([p for p in (n_txt, date_txt) if p])
base_w = c.stringWidth(base, cap_font, 8.5)
avail = col_w - base_w - sep_w - amt_w - sep_w # base·tail·amt
ell = "…"
tail = ""
if merch_txt:
tail = merch_txt
while tail and c.stringWidth(tail, cap_font, 8.5) > avail:
cut = max(len(tail) - 1 - len(ell), 0)
if cut <= 0:
tail = ""
break
tail = tail[:cut].rstrip() + ell
chunks = [p for p in (base, tail) if p]
if amt_txt:
chunks.append(amt_txt)
cap = sep.join(chunks)
if cap_warn:
# no Unicode font: same sanitize fallback as _txt()
cap = cap.encode("latin-1", "replace").decode("latin-1")
print(f"WARN non-Latin caption unavailable (no TTF found): "
f"{cap!r}", file=sys.stderr)
c.setFont(cap_font, 8.5)
c.setFillGray(0.3)
cap_y = y - h_ - BADGE_H - 14 if args.number else y - h_ - 12
c.drawString(x, cap_y, cap)
c.setFillGray(0)
x += col_w + gap
y -= row_h + gap
pn += 1
page_footer(pn)
c.showPage()
c.save()
print(json.dumps({"out": str(out), "pages": total_pages, "receipts": len(receipts)}))
return 0
# ----------------------------------------------------------------------- main
def main(argv=None):
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
sub = ap.add_subparsers(dest="cmd", required=True)
p = sub.add_parser("scan", help="process photos + OCR -> manifest.json")
p.add_argument("input_dir")
p.add_argument("-o", "--out", required=True, help="workdir for manifest+processed/")
p.add_argument("--mode", choices=["bw", "photo"], default="bw",
help="bw = photocopy-style threshold (default), photo = grayscale")
p.set_defaults(fn=cmd_scan)
p = sub.add_parser("review", help="print expense table for confirmation")
p.add_argument("workdir")
p.set_defaults(fn=cmd_review)
p = sub.add_parser("confirm", help="stamp user approval into the manifest "
"(run AFTER the user approves the reviewed table; edits "
"made before confirm are included, edits after are blocked)")
p.add_argument("workdir")
p.set_defaults(fn=cmd_confirm)
p = sub.add_parser("pack", help="build A4 PDF from CONFIRMED manifest")
p.add_argument("workdir")
p.add_argument("-o", "--out", required=True)
p.add_argument("--title", default="Expense Claim")
p.add_argument("--claimant", default="")
p.add_argument("--period", default="")
p.add_argument("--notes", default="")
p.add_argument("--cover", action="store_true")
p.add_argument("--captions", action="store_true")
p.add_argument("--number", action="store_true")
p.set_defaults(fn=cmd_pack)
args = ap.parse_args(argv)
return args.fn(args)
if __name__ == "__main__":
sys.exit(main())Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |