Cheque Reading: How to Build It

from decimal import Decimal

# STEP 4. TWO AMOUNTS, BOTH HANDWRITTEN, ON THE SAME CHEQUE.
#   CAR — Courtesy Amount Recognition — the amount in FIGURES
#   LAR — Legal Amount Recognition   — the amount in WORDS
# Read them independently. Never derive one from the other: an engine that
# parses the figures and "confirms" the words has one reading and a
# rationalisation, which is exactly the check you needed.

def read_amounts(grey_image):
    car = read_car(grey_image)      # {"value": Decimal, "confidence": float}
    lar = read_lar(grey_image)      # {"value": Decimal, "confidence": float}
    assert car["source_region"] != lar["source_region"], "same region read twice"
    return car, lar

# STEP 5. WHEN THEY DISAGREE. THE LAW ALREADY DECIDED THIS.
# Negotiable Instruments Act, 1881, section 18: where the amount is stated
# differently in figures and in words, THE AMOUNT IN WORDS is the amount
# ordered to be paid.
#
# So the words are not a check on the figures. The words ARE the amount, and
# the figures are the check. Most pipelines are built the other way round
# because figures are easier to read.

def resolve_amount(car, lar, policy):
    if car["value"] == lar["value"]:
        return {"amount": car["value"], "route": "auto", "agreed": True}
    # A disagreement is not an error to resolve with a confidence score.
    # It is a legal question with an answer, and a human should see it.
    return {
        "amount": lar["value"],          # section 18: words govern
        "route": "manual_review",        # do not auto-pay a disagreement
        "agreed": False,
        "car": car["value"], "lar": lar["value"],
        "why": "figures and words differ; words govern, review before paying",
    }

# Confidence thresholds are a business decision, not a model setting.
def route(car, lar, policy):
    if min(car["confidence"], lar["confidence"]) < policy["min_confidence"]:
        return "manual_review"
    if car["value"] >= policy["always_review_above"]:
        return "manual_review"           # value, not confidence
    return "auto"

# STEP 6. POSITIVE PAY. THE DRAWER ALREADY TOLD THE BANK WHAT THIS SAYS.
# For cheques of Rs 50,000 and above the issuer submits the date, the payee
# and the amount to their bank in advance. CTS cross-checks the presented
# cheque against that declaration and flags any discrepancy to both banks.

def positive_pay_check(extracted, declared):
    if declared is None:
        return {"status": "no_declaration", "action": "follow_bank_policy"}
    mismatches = [f for f in ("date", "payee", "amount")
                  if normalise(extracted[f]) != normalise(declared[f])]
    return {"status": "match" if not mismatches else "mismatch",
            "fields": mismatches,
            # A payee mismatch is the alteration case Positive Pay exists for.
            "action": "pay" if not mismatches else "flag_to_both_banks"}

# WHAT TO CHECK
# [ ] CAR and LAR read INDEPENDENTLY, from different regions, by paths that
#     cannot see each other's output
# [ ] a disagreement routes to a human. Never auto-resolve by confidence
# [ ] where you must act on one, act on the WORDS. Section 18 is not a
#     preference
# [ ] normalise before comparing payee names, or Positive Pay flags every
#     cheque over a full stop
# [ ] a value threshold for manual review, independent of confidence. A
#     confident wrong reading on a large cheque is the expensive failure
# [ ] reconcile magnetic and optical MICR reads and treat disagreement as a
#     fraud signal, not a retry

from datetime import datetime, timedelta

# STEP 7. CONTINUOUS CLEARING. THE DEADLINE IS NOW PER ITEM, NOT PER DAY.
# Before 4 October 2025 an item joined a batch and the batch had a deadline.
# Now each item has its own confirmation window, bounded by the Item Expiry
# Time. A review that used to "make today's cut-off" now has to make an hour.

def review_deadline(presented_at, cutoffs):
    """When this specific item stops being yours to decide."""
    return min(presented_at + cutoffs["confirmation_window"],
               cutoffs["item_expiry_time_for"](presented_at))

def route_with_clock(item, policy, staffing):
    decision = route(item["car"], item["lar"], policy)   # auto | manual_review
    if decision == "auto":
        return {"action": "auto", "by": None}
    due = review_deadline(item["presented_at"], policy["cutoffs"])
    # The question is not "is a human available" but "is one available BEFORE
    # this item expires". A queue drained at day end answers the first.
    if not staffing.reviewer_available_before(due):
        # Do not let it expire silently. An expiry is a return the customer
        # did not earn and nobody decided.
        return {"action": "escalate_now", "due_ist": due, "why": "no reviewer in window"}
    return {"action": "manual_review", "due_ist": due}

# STEP 8. RETURNS.
def handle_return(item, reason_code, store):
    # Keep the evidence WITH the return. The dispute arrives later and the
    # question is always what the instrument actually said.
    store.attach(item["id"], images=item["image_triple"],
                 extraction=item["extraction"], positive_pay=item["pp_result"])
    return {
        "reason_code": reason_code,
        # Plain language reaches the customer; the code reaches the system.
        "customer_message": PLAIN[reason_code],
        "at_ist": now_ist(),
    }

def return_rate_by_reason(window, baseline):
    """A rising 'signature differs' rate is a capture or model problem wearing
    a customer-behaviour costume. Nothing else in the reporting shows it."""
    rates = group(window, "reason_code")
    return {r: {"rate": v, "drifted": v > baseline[r] * 1.5} for r, v in rates.items()}

# WHAT TO CHECK
# [ ] compute the deadline PER ITEM, not per session. The batch mental model
#     is the single biggest carry-over risk from the old cycle
# [ ] alert when no reviewer is available before an item expires, rather
#     than discovering it in the return file
# [ ] never let an item expire silently into a return. That is a decision
#     nobody made, reaching a customer who did not earn it
# [ ] attach the images and the extraction to every return. The dispute is
#     later and the evidence is not reconstructable
# [ ] track return rate BY REASON against a baseline, and treat a jump in a
#     capture-sensitive reason as a pipeline alert
# [ ] every timestamp in IST against the clearing calendar, never a UTC day