recskit 0.1.0__py3-none-any.whl

recskit/__init__.py

@@ -0,0 +1,45 @@
+"""
+recskit -- reconcile a supplier or customer statement against your own
+accounting ledger: match invoices, credit notes, and payments, flag
+mismatches and missing items, and compare balances.
+
+The core logic has no dependencies at all and doesn't care where your
+data came from -- CSV, a PDF you parsed by hand, Sage, Xero,
+QuickBooks. recskit.sage_adapter is one optional, concrete way to pull
+the ledger side out of Sage 50 (via sagekit); write your own equivalent
+for anything else.
+
+    from recskit import StatementItem, LedgerInvoice, LedgerPayment
+    from recskit import reconcile_statement, calc_due_date
+
+See README.md for the full walkthrough.
+"""
+
+from .due_dates import DUE_FROM_MODES, calc_due_date
+from .matching import find_best_name_match, match_invoice, match_payment, normalize_name
+from .models import (
+    LedgerInvoice,
+    LedgerPayment,
+    MatchResult,
+    ReconciliationResult,
+    StatementItem,
+)
+from .reconcile import reconcile_statement
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "StatementItem",
+    "LedgerInvoice",
+    "LedgerPayment",
+    "MatchResult",
+    "ReconciliationResult",
+    "reconcile_statement",
+    "match_invoice",
+    "match_payment",
+    "normalize_name",
+    "find_best_name_match",
+    "calc_due_date",
+    "DUE_FROM_MODES",
+    "__version__",
+]

recskit/due_dates.py

@@ -0,0 +1,77 @@
+"""
+recskit.due_dates
+==================
+Calculates an invoice's due date from its invoice date and a supplier's
+(or customer's) payment terms. Different trading partners quote terms
+in different ways -- "30 days", "29 days from the end of the month
+following", "last day of the month after invoice month" -- and getting
+this wrong is exactly what makes an "overdue" flag either useless
+(triggers too early) or dangerous (triggers too late).
+"""
+
+from datetime import date, timedelta
+
+# The four due-date conventions this covers. If a trading partner uses
+# something not listed here, "invoice_date" (a flat N days from the
+# invoice date) is the safest fallback -- it's the most common by far.
+DUE_FROM_MODES = (
+    "invoice_date",
+    "start_of_following_month",
+    "end_of_month",
+    "end_of_following_month",
+)
+
+
+def _last_day_of_month(year: int, month: int) -> date:
+    if month == 12:
+        return date(year, 12, 31)
+    return date(year, month + 1, 1) - timedelta(days=1)
+
+
+def calc_due_date(invoice_date: date, terms_days: int, due_from: str = "invoice_date") -> date:
+    """
+    Calculate an invoice's due date.
+
+    due_from options:
+        "invoice_date"             -- N days from the invoice date
+                                       (the default, and most common)
+        "start_of_following_month" -- N days from the 1st of the month
+                                       after the invoice date, e.g.
+                                       "29 days" meaning the 30th of
+                                       the month after next
+        "end_of_month"             -- N days from the last day of the
+                                       invoice's own month, e.g.
+                                       "14 days EOM"
+        "end_of_following_month"   -- the last day of the month AFTER
+                                       the invoice month, no day offset
+                                       (terms_days is ignored for this
+                                       mode -- it's a fixed rule, e.g.
+                                       "last day of the month following
+                                       the invoice")
+
+    Raises ValueError for an unrecognised due_from value, rather than
+    silently falling back to a default -- an unnoticed typo here would
+    quietly miscalculate every due date for that trading partner.
+    """
+    if due_from not in DUE_FROM_MODES:
+        raise ValueError(f"Unknown due_from {due_from!r} -- must be one of {DUE_FROM_MODES}")
+
+    if due_from == "start_of_following_month":
+        if invoice_date.month == 12:
+            first_next = date(invoice_date.year + 1, 1, 1)
+        else:
+            first_next = date(invoice_date.year, invoice_date.month + 1, 1)
+        return first_next + timedelta(days=terms_days)
+
+    if due_from == "end_of_month":
+        return _last_day_of_month(invoice_date.year, invoice_date.month) + timedelta(days=terms_days)
+
+    if due_from == "end_of_following_month":
+        if invoice_date.month == 12:
+            target_year, target_month = invoice_date.year + 1, 1
+        else:
+            target_year, target_month = invoice_date.year, invoice_date.month + 1
+        return _last_day_of_month(target_year, target_month)
+
+    # "invoice_date"
+    return invoice_date + timedelta(days=terms_days)

recskit/matching.py

@@ -0,0 +1,116 @@
+"""
+recskit.matching
+=================
+Matches individual statement lines against ledger transactions.
+
+The core lesson baked into this module: **always try an exact
+reference match before falling back to a substring match.** A short
+reference like "9910" can accidentally turn up as a *substring* of an
+unrelated, older invoice's reference on a long-standing account. If you
+match on substring first, you silently pair the statement line with
+the wrong ledger invoice -- and report a confident-looking "mismatch"
+amount instead of correctly reporting no match at all. This bit a real
+reconciliation run before the exact-match-first rule was added, so
+it's not a hypothetical -- keep the ordering.
+"""
+
+import re
+from typing import List, Optional, Tuple
+
+from .models import LedgerInvoice, LedgerPayment, MatchResult, StatementItem
+
+
+def normalize_name(name: str) -> str:
+    """
+    Strip everything except letters and digits and uppercase the rest.
+    Account/company names are rarely entered consistently ("N.D. John"
+    vs "ND John", "St." vs "St", extra spaces) -- comparing on
+    letters/digits only avoids false negatives from punctuation alone.
+    """
+    return re.sub(r"[^A-Z0-9]", "", (name or "").upper())
+
+
+def find_best_name_match(
+    search_term: str, candidates: List[Tuple[str, str]], tie_breaker_counts: Optional[dict] = None
+) -> Optional[Tuple[str, str]]:
+    """
+    Find the best match for `search_term` among `candidates`, a list of
+    (id, name) tuples, using normalize_name() for a punctuation-
+    insensitive comparison.
+
+    Returns the matching (id, name) tuple, or None if nothing matches.
+    If more than one candidate matches, `tie_breaker_counts` (a dict of
+    id -> some comparable score, e.g. transaction count) picks the
+    highest-scoring one; without it, the first match wins.
+    """
+    norm_search = normalize_name(search_term)
+    matches = [c for c in candidates if norm_search in normalize_name(c[1])]
+
+    if not matches:
+        return None
+    if len(matches) == 1 or not tie_breaker_counts:
+        return matches[0]
+
+    return max(matches, key=lambda c: tie_breaker_counts.get(c[0], 0))
+
+
+def match_invoice(
+    item: StatementItem, ledger_invoices: List[LedgerInvoice], tolerance: float = 0.01
+) -> MatchResult:
+    """
+    Match one invoice/credit-note statement line against the ledger.
+
+    Tries an exact match on `ref` (and `alt_ref`, if the statement
+    supplied a second reference for this line) first. Only if nothing
+    matches exactly does it fall back to a substring match -- see the
+    module docstring for why the ordering matters.
+    """
+    refs_to_try = [item.ref.upper()]
+    if item.alt_ref:
+        refs_to_try.append(item.alt_ref.upper())
+
+    exact = [inv for inv in ledger_invoices if inv.ref.upper() in refs_to_try]
+    candidates = exact or [
+        inv for inv in ledger_invoices if any(r in inv.ref.upper() for r in refs_to_try)
+    ]
+
+    if not candidates:
+        return MatchResult(item=item, status="missing", note=f"No ledger entry for ref {item.ref!r}")
+
+    ledger_invoice = candidates[0]
+    if abs(ledger_invoice.amount - item.amount) < tolerance:
+        return MatchResult(
+            item=item, status="ok", ledger_ref=ledger_invoice.ref, ledger_amount=ledger_invoice.amount
+        )
+
+    return MatchResult(
+        item=item,
+        status="mismatch",
+        ledger_ref=ledger_invoice.ref,
+        ledger_amount=ledger_invoice.amount,
+        note=f"Statement £{item.amount:,.2f} vs ledger £{ledger_invoice.amount:,.2f}",
+    )
+
+
+def match_payment(
+    item: StatementItem, ledger_payments: List[LedgerPayment], tolerance: float = 0.01
+) -> MatchResult:
+    """
+    Match one payment statement line against the ledger.
+
+    Payments are matched by **amount first**, then by reference text --
+    the opposite order to invoices. This is deliberate: payment
+    references (BACS refs, bank descriptions) very often differ
+    between what a supplier's statement shows and what actually lands
+    in your ledger, whereas the amount is reliable.
+    """
+    by_amount = [p for p in ledger_payments if abs(p.amount - item.amount) < tolerance]
+    candidates = by_amount or [
+        p for p in ledger_payments if item.ref and item.ref.upper() in (p.ref or "").upper()
+    ]
+
+    if not candidates:
+        return MatchResult(item=item, status="missing", note=f"No ledger payment matching £{item.amount:,.2f}")
+
+    payment = candidates[0]
+    return MatchResult(item=item, status="ok", ledger_ref=payment.ref, ledger_amount=payment.amount)

recskit/models.py

@@ -0,0 +1,96 @@
+"""
+recskit.models
+==============
+Plain data containers used throughout recskit. Nothing in this module
+talks to any external system -- these are just the shapes that
+statement lines and ledger transactions get put into before matching.
+"""
+
+from dataclasses import dataclass, field
+from datetime import date as date_type
+from typing import List, Optional
+
+VALID_ITEM_TYPES = ("invoice", "credit_note", "payment")
+
+
+@dataclass
+class StatementItem:
+    """
+    One line from a supplier or customer statement.
+
+    `amount` is always positive, regardless of how the statement itself
+    signs it (some show purchases as negative, some don't -- normalise
+    to positive before creating this).
+
+    `alt_ref` covers statements that print two references for the same
+    line (e.g. an internal "Reference" plus their own "Invoice No.") --
+    your ledger might have it booked under either one.
+    """
+
+    type: str
+    ref: str
+    amount: float
+    date: Optional[date_type] = None
+    alt_ref: str = ""
+    due_date: Optional[date_type] = None
+
+    def __post_init__(self):
+        if self.type not in VALID_ITEM_TYPES:
+            raise ValueError(
+                f"StatementItem.type must be one of {VALID_ITEM_TYPES}, got {self.type!r}"
+            )
+
+
+@dataclass
+class LedgerInvoice:
+    """An invoice or credit note as it exists in your accounting ledger."""
+
+    ref: str
+    amount: float  # gross amount, positive
+    date: Optional[date_type] = None
+    outstanding: float = 0.0
+
+
+@dataclass
+class LedgerPayment:
+    """A payment as it exists in your accounting ledger."""
+
+    ref: str
+    amount: float  # positive
+    date: Optional[date_type] = None
+
+
+@dataclass
+class MatchResult:
+    """The outcome of trying to match one statement item against the ledger."""
+
+    item: StatementItem
+    status: str  # "ok", "mismatch", or "missing"
+    ledger_ref: Optional[str] = None
+    ledger_amount: Optional[float] = None
+    note: str = ""
+
+
+@dataclass
+class ReconciliationResult:
+    """
+    Everything you need to report on a single statement's reconciliation
+    against your ledger.
+    """
+
+    invoice_results: List[MatchResult] = field(default_factory=list)
+    payment_results: List[MatchResult] = field(default_factory=list)
+    extra_in_ledger: List[LedgerInvoice] = field(default_factory=list)
+    statement_balance: float = 0.0
+    ledger_balance: float = 0.0
+    balance_difference: float = 0.0
+    issue_count: int = 0
+    agreed: bool = True
+
+    @property
+    def missing_items(self) -> List[MatchResult]:
+        return [r for r in self.invoice_results + self.payment_results if r.status == "missing"]
+
+    @property
+    def mismatched_items(self) -> List[MatchResult]:
+        return [r for r in self.invoice_results + self.payment_results if r.status == "mismatch"]

recskit/pdf_statement.py

@@ -0,0 +1,194 @@
+"""
+recskit.pdf_statement
+======================
+Optional module: turns a statement PDF into a list of StatementItem
+objects, using pdfplumber to pull out the text and the Claude API to
+turn that text into structured data.
+
+This is the part of a real reconciliation workflow that's actually
+hard -- matching and arithmetic (the rest of recskit) is comparatively
+easy once you have clean structured data. Every supplier or customer
+formats their statement differently, and hand-writing a parser per
+format doesn't scale. Handing the raw extracted text to an LLM with a
+strict output shape does, and adapts to a new statement layout with no
+code changes.
+
+Requires the optional "parse-pdf" extra:
+
+    pip install recskit[parse-pdf]
+
+and an Anthropic API key (ANTHROPIC_API_KEY environment variable, or
+passed explicitly) -- extract_pdf_text() has no such requirement and
+works standalone if you'd rather wire up a different parser.
+"""
+
+import json
+from datetime import datetime
+from typing import List, Optional
+
+from .models import StatementItem
+
+PARSING_SYSTEM_PROMPT = """You are extracting structured data from a supplier or customer \
+account statement PDF, for automated reconciliation against an accounting ledger.
+
+Return ONLY valid JSON (no markdown code fences, no commentary) matching exactly this shape:
+
+{
+  "statement_date": "DD/MM/YYYY",
+  "statement_balance": <number, the total balance due printed at the bottom of the statement>,
+  "items": [
+    {
+      "type": "invoice" | "credit_note" | "payment",
+      "ref": "the reference shown on the statement for this line",
+      "alt_ref": "a second reference for the same line, if the statement prints two (optional)",
+      "amount": <number, always positive regardless of how it is signed on the statement>,
+      "date": "DD/MM/YYYY",
+      "due_date": "DD/MM/YYYY (optional -- only include if a due date is explicitly printed next to this line)"
+    }
+  ]
+}
+
+Rules:
+- Do NOT include a brought-forward / balance-forward line as an item -- it is a summary of
+  older transactions, not a document in its own right.
+- A payment shown with no document reference (BACS, a bank transfer, etc.) should get a
+  short generic "ref" like "bacs" rather than being left blank.
+- Credit notes use "type": "credit_note".
+- If unsure whether a line is an invoice or credit note, use the sign or column it's shown
+  in as a guide.
+- Keep dates in whichever format the statement itself uses, consistently, as DD/MM/YYYY
+  unless the statement is clearly in another locale's date format.
+"""
+
+
+def extract_pdf_text(pdf_path_or_bytes) -> str:
+    """
+    Extract all text from a statement PDF, page by page, joined with
+    newlines. Accepts a file path (str/Path) or raw PDF bytes.
+
+    This has no dependency on the Claude API -- useful on its own if
+    you'd rather feed the text to a different parser (a regex-based
+    one for a single known format, another LLM, etc).
+    """
+    import io
+
+    import pdfplumber
+
+    source = io.BytesIO(pdf_path_or_bytes) if isinstance(pdf_path_or_bytes, bytes) else pdf_path_or_bytes
+
+    parts = []
+    with pdfplumber.open(source) as pdf:
+        for page in pdf.pages:
+            parts.append(page.extract_text() or "")
+    return "\n".join(parts)
+
+
+def parse_statement_text(
+    statement_text: str,
+    counterparty_name: str = "",
+    parsing_notes: str = "",
+    api_key: Optional[str] = None,
+    model: str = "claude-sonnet-5",
+) -> dict:
+    """
+    Send extracted statement text to the Claude API and get back the
+    raw parsed dict (statement_date, statement_balance, items) --
+    matching PARSING_SYSTEM_PROMPT's shape exactly.
+
+    `counterparty_name` (the supplier or customer's name) and
+    `parsing_notes` (any known quirks of their statement format, e.g.
+    "this supplier prints two references per line -- put the second
+    one in alt_ref") are optional context that measurably improves
+    parsing accuracy for tricky or unusual layouts; both are free text.
+
+    `api_key` falls back to the ANTHROPIC_API_KEY environment variable
+    if not passed explicitly -- this function does not read a .env
+    file itself.
+
+    Raises whatever the anthropic client raises on an API error, and
+    json.JSONDecodeError if the model's response isn't valid JSON
+    despite the prompt (rare, but don't assume it's impossible).
+    """
+    from anthropic import Anthropic
+
+    client = Anthropic(api_key=api_key) if api_key else Anthropic()
+
+    user_prompt = ""
+    if counterparty_name:
+        user_prompt += f"Statement is from: {counterparty_name}\n"
+    if parsing_notes:
+        user_prompt += f"Known quirks for this statement format: {parsing_notes}\n"
+    user_prompt += f"\nStatement text:\n\n{statement_text}"
+
+    response = client.messages.create(
+        model=model,
+        max_tokens=4000,
+        system=PARSING_SYSTEM_PROMPT,
+        messages=[{"role": "user", "content": user_prompt}],
+    )
+
+    raw = response.content[0].text.strip()
+    if raw.startswith("```"):
+        raw = raw.strip("`")
+        if raw.lower().startswith("json"):
+            raw = raw[4:]
+    return json.loads(raw.strip())
+
+
+def statement_items_from_parsed(parsed: dict) -> List[StatementItem]:
+    """
+    Convert the raw dict from parse_statement_text() (or your own
+    parser, provided it matches the same shape) into a list of
+    StatementItem objects, ready for reconcile_statement().
+
+    Does not touch statement_date / statement_balance -- read those
+    directly off `parsed` yourself; reconcile_statement() takes the
+    balance as a separate argument rather than as part of this list.
+    """
+    items = []
+    for raw_item in parsed.get("items", []):
+        items.append(
+            StatementItem(
+                type=raw_item["type"],
+                ref=raw_item["ref"],
+                amount=float(raw_item["amount"]),
+                date=_parse_date(raw_item.get("date")),
+                alt_ref=raw_item.get("alt_ref", "") or "",
+                due_date=_parse_date(raw_item.get("due_date")),
+            )
+        )
+    return items
+
+
+def parse_pdf_to_statement(
+    pdf_path_or_bytes,
+    counterparty_name: str = "",
+    parsing_notes: str = "",
+    api_key: Optional[str] = None,
+    model: str = "claude-sonnet-5",
+) -> tuple:
+    """
+    End-to-end convenience: PDF in, (statement_date, statement_balance,
+    items) out, ready to hand straight to reconcile_statement().
+
+        from recskit.pdf_statement import parse_pdf_to_statement
+        from recskit import reconcile_statement
+
+        stmt_date, stmt_balance, items = parse_pdf_to_statement("statement.pdf", "Acme Supplies")
+        result = reconcile_statement(items, ledger_invoices, ledger_payments, stmt_balance)
+    """
+    text = extract_pdf_text(pdf_path_or_bytes)
+    parsed = parse_statement_text(text, counterparty_name, parsing_notes, api_key, model)
+    items = statement_items_from_parsed(parsed)
+    return _parse_date(parsed.get("statement_date")), float(parsed.get("statement_balance", 0)), items
+
+
+def _parse_date(value):
+    if not value:
+        return None
+    for fmt in ("%d/%m/%Y", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(value, fmt).date()
+        except ValueError:
+            continue
+    return None

recskit/reconcile.py

@@ -0,0 +1,73 @@
+"""
+recskit.reconcile
+==================
+Ties matching.py and models.py together into one call: hand over a
+statement's line items plus your ledger's invoices and payments for
+that account, get back a ReconciliationResult with every line matched,
+mismatched, or flagged missing, plus a balance comparison.
+
+This module doesn't care where the statement or ledger data came from
+-- CSV, a PDF you parsed by hand, Sage, Xero, QuickBooks, whatever.
+See recskit.sage_adapter for one concrete way to get ledger data out of
+Sage 50, or write your own equivalent for another system.
+"""
+
+from typing import List, Optional
+
+from .matching import match_invoice, match_payment
+from .models import LedgerInvoice, LedgerPayment, ReconciliationResult, StatementItem
+
+
+def reconcile_statement(
+    items: List[StatementItem],
+    ledger_invoices: List[LedgerInvoice],
+    ledger_payments: List[LedgerPayment],
+    statement_balance: float,
+    ledger_balance: Optional[float] = None,
+    balance_tolerance: float = 0.02,
+) -> ReconciliationResult:
+    """
+    Reconcile one statement against your ledger.
+
+    `ledger_balance` defaults to the sum of `outstanding` across
+    `ledger_invoices` if not supplied directly -- pass it explicitly if
+    your ledger's outstanding figure needs to come from somewhere else.
+
+    An item only counts as a discrepancy (invoice/credit-note or
+    payment) if it's "mismatch" or "missing" -- an exact match is never
+    counted, no matter which fallback path found it.
+    """
+    doc_items = [i for i in items if i.type in ("invoice", "credit_note")]
+    payment_items = [i for i in items if i.type == "payment"]
+
+    invoice_results = [match_invoice(item, ledger_invoices) for item in doc_items]
+    payment_results = [match_payment(item, ledger_payments) for item in payment_items]
+
+    if ledger_balance is None:
+        ledger_balance = sum(inv.outstanding for inv in ledger_invoices)
+
+    # Ledger invoices that don't appear (even as a substring match) on
+    # any statement line -- usually older items sitting in a brought-
+    # forward balance, but worth surfacing rather than silently ignoring.
+    stmt_refs = {i.ref.upper() for i in doc_items}
+    extra_in_ledger = [
+        inv for inv in ledger_invoices if not any(r in inv.ref.upper() for r in stmt_refs)
+    ]
+
+    balance_difference = round(ledger_balance - statement_balance, 2)
+
+    issue_count = sum(1 for r in invoice_results + payment_results if r.status != "ok")
+    balance_ok = abs(balance_difference) < balance_tolerance
+    if not balance_ok:
+        issue_count += 1
+
+    return ReconciliationResult(
+        invoice_results=invoice_results,
+        payment_results=payment_results,
+        extra_in_ledger=extra_in_ledger,
+        statement_balance=statement_balance,
+        ledger_balance=ledger_balance,
+        balance_difference=balance_difference,
+        issue_count=issue_count,
+        agreed=(issue_count == 0),
+    )

recskit/sage_adapter.py

@@ -0,0 +1,125 @@
+"""
+recskit.sage_adapter
+=====================
+Optional adapter that pulls a purchase-ledger account's invoices,
+credit notes, and payments out of Sage 50 (via sagekit) and converts
+them into recskit's LedgerInvoice / LedgerPayment shapes, ready for
+reconcile_statement().
+
+This is one concrete data source -- recskit's reconciliation logic
+itself doesn't know or care where the ledger side came from. If you're
+on Xero, QuickBooks, or anything else, write your own equivalent that
+returns the same two lists; everything downstream is unchanged.
+
+Requires the optional "sage" extra:
+
+    pip install recskit[sage]
+
+or install sagekit directly -- see its own README for the Sage 50
+ODBC connection details (DSN, credentials, column auto-detection).
+"""
+
+import re
+from typing import List, Tuple
+
+from .models import LedgerInvoice, LedgerPayment
+
+
+def _normalize_name(name: str) -> str:
+    return re.sub(r"[^A-Z0-9]", "", (name or "").upper())
+
+
+def find_purchase_ledger_account(cursor, search_term: str) -> Tuple[str, str]:
+    """
+    Find a supplier account in Sage's PURCHASE_LEDGER by a fuzzy name
+    match (ignoring punctuation/spacing, since account names aren't
+    entered consistently). If more than one account matches, picks the
+    one with the most PI/PC/PP transactions.
+
+    Returns (account_ref, account_name). Raises LookupError if nothing
+    matches.
+    """
+    cursor.execute("SELECT ACCOUNT_REF, NAME FROM PURCHASE_LEDGER")
+    all_accounts = cursor.fetchall()
+
+    norm_search = _normalize_name(search_term)
+    matches = [a for a in all_accounts if norm_search in _normalize_name(a[1])]
+
+    if not matches:
+        raise LookupError(f"No PURCHASE_LEDGER account matching {search_term!r}")
+
+    if len(matches) == 1:
+        return matches[0][0], matches[0][1]
+
+    best, best_count = matches[0], -1
+    for account_ref, name in matches:
+        safe = account_ref.replace("'", "''")
+        cursor.execute(
+            f"""
+            SELECT COUNT(*) FROM AUDIT_HEADER
+            WHERE ACCOUNT_REF = '{safe}'
+              AND TYPE IN ('PI', 'PC', 'PP')
+              AND DELETED_FLAG = 0
+            """
+        )
+        count = cursor.fetchone()[0]
+        if count > best_count:
+            best_count = count
+            best = (account_ref, name)
+
+    return best[0], best[1]
+
+
+def pull_purchase_ledger(
+    cursor, account_ref: str
+) -> Tuple[List[LedgerInvoice], List[LedgerPayment]]:
+    """
+    Pull outstanding invoices/credit notes (type PI/PC) and payments
+    (type PP) for a Sage purchase ledger account, converted to
+    recskit's LedgerInvoice / LedgerPayment dataclasses.
+
+    Amounts come back from Sage's ODBC layer as negative for purchase
+    transactions -- this converts them to positive, matching the
+    convention recskit uses everywhere.
+    """
+    safe_ref = account_ref.replace("'", "''")
+
+    cursor.execute(
+        f"""
+        SELECT INV_REF, DATE, OUTSTANDING, GROSS_AMOUNT
+        FROM AUDIT_HEADER
+        WHERE ACCOUNT_REF = '{safe_ref}'
+          AND TYPE IN ('PI', 'PC')
+          AND DELETED_FLAG = 0
+          AND OUTSTANDING <> 0
+        ORDER BY DATE
+        """
+    )
+    invoice_rows = cursor.fetchall()
+
+    cursor.execute(
+        f"""
+        SELECT INV_REF, DATE, GROSS_AMOUNT
+        FROM AUDIT_HEADER
+        WHERE ACCOUNT_REF = '{safe_ref}'
+          AND TYPE = 'PP'
+          AND DELETED_FLAG = 0
+        ORDER BY DATE DESC
+        """
+    )
+    payment_rows = cursor.fetchall()
+
+    invoices = [
+        LedgerInvoice(
+            ref=str(r[0]),
+            amount=abs(float(r[3] or 0)),
+            date=r[1],
+            outstanding=float(r[2] or 0),
+        )
+        for r in invoice_rows
+    ]
+    payments = [
+        LedgerPayment(ref=str(r[0]), amount=abs(float(r[2] or 0)), date=r[1]) for r in payment_rows
+    ]
+
+    return invoices, payments

recskit-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: recskit
+Version: 0.1.0
+Summary: Reconcile a supplier or customer statement against your accounting ledger: match invoices, credit notes, and payments, flag mismatches and missing items, compare balances. No dependencies in the core -- works with any data source.
+Author: Duckboard
+License: MIT
+Project-URL: Homepage, https://github.com/Duckboard/recskit
+Project-URL: Buy me a coffee, https://ko-fi.com/duckboard
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: sage
+Requires-Dist: sagekit>=0.1.0; extra == "sage"
+Provides-Extra: parse-pdf
+Requires-Dist: pdfplumber>=0.10; extra == "parse-pdf"
+Requires-Dist: anthropic>=0.30; extra == "parse-pdf"
+Dynamic: license-file
+
+# recskit
+
+Reconcile a supplier or customer statement against your own accounting
+ledger: match invoices, credit notes, and payments; flag mismatches
+and missing items on either side; compare balances. The core has
+**zero dependencies** and doesn't care where your data came from --
+CSV, a PDF you parsed by hand, Sage, Xero, QuickBooks, anything.
+
+If this saves you time, consider [buying me a coffee](https://ko-fi.com/duckboard).
+
+## What problem this solves
+
+Checking a supplier statement against your own ledger by eye is slow
+and error-prone, especially once an account has more than a handful of
+open items. Two things make it worse than it looks:
+
+1. **A tied-up total balance doesn't mean every line is right.** Two
+   errors can cancel out -- a mismatched invoice and a missing one can
+   add up to the same total as if nothing were wrong. recskit checks
+   every line, not just the bottom-line figure.
+2. **Reference matching is a trap.** A short reference like `991` can
+   turn up as a *substring* of an unrelated, older invoice's reference
+   (`INV-99910`) on a long-standing account. Match on substring first
+   and you'll silently pair the statement line with the wrong invoice,
+   reporting a confident-looking "mismatch" instead of correctly
+   reporting no match at all. recskit always tries an **exact**
+   reference match before ever falling back to substring matching.
+
+## Features
+
+- Matches invoices/credit notes by reference (with support for
+  statements that print two references for the same line), payments
+  by amount first then reference
+- Exact-match-first, substring-fallback matching order -- see above
+- Configurable payment-terms due-date calculation (flat N days,
+  N days from the start of the following month, N days from end of
+  month, or end of the following month with no offset)
+- Flags items in your ledger that never show up on the statement at
+  all (commonly an old item sitting in a brought-forward balance)
+- Zero required dependencies in the core -- add the optional `sage`
+  extra only if you want the bundled Sage 50 adapter
+- Two worked examples: pure CSV (no external system at all), and Sage
+  50 via [sagekit](https://github.com/Duckboard/sagekit)
+
+## Installation
+
+```bash
+pip install -r requirements.txt      # core only, zero dependencies
+pip install -e .                     # or, as an editable package
+pip install -e ".[sage]"             # + the optional Sage 50 adapter
+```
+
+## Usage
+
+```python
+from recskit import StatementItem, LedgerInvoice, LedgerPayment, reconcile_statement
+
+items = [
+    StatementItem(type="invoice", ref="INV-100", amount=500.00),
+    StatementItem(type="invoice", ref="INV-101", amount=320.00),
+    StatementItem(type="payment", ref="bacs", amount=300.00),
+]
+
+ledger_invoices = [
+    LedgerInvoice(ref="INV-100", amount=500.00, outstanding=500.00),
+    LedgerInvoice(ref="INV-101", amount=300.00, outstanding=300.00),
+]
+ledger_payments = [LedgerPayment(ref="BACS-9001", amount=300.00)]
+
+result = reconcile_statement(items, ledger_invoices, ledger_payments, statement_balance=800.00)
+
+print(result.agreed, result.issue_count, result.balance_difference)
+for r in result.mismatched_items + result.missing_items:
+    print(r.item.ref, r.status, r.note)
+```
+
+### Payment-terms due dates
+
+```python
+from datetime import date
+from recskit import calc_due_date
+
+calc_due_date(date(2026, 5, 14), 30)                                   # 30 days from invoice date
+calc_due_date(date(2026, 5, 14), 29, "start_of_following_month")       # 29 days from 1 June
+calc_due_date(date(2026, 5, 3), 14, "end_of_month")                    # 14 days from 31 May
+calc_due_date(date(2026, 5, 3), 0, "end_of_following_month")           # 30 June, terms_days ignored
+```
+
+### Examples
+
+```bash
+python examples/reconcile_csv.py                         # runs on the bundled sample CSVs
+python examples/reconcile_csv.py statement.csv ledger.csv 1063.45   # your own files
+python examples/reconcile_sage.py                         # requires the "sage" extra + a live Sage 50
+```
+
+`reconcile_csv.py` needs no external system at all -- a good starting
+point for wiring recskit up to whatever export your own accounting
+software produces. `reconcile_sage.py` shows the same reconciliation
+against a live Sage 50 purchase ledger account, using
+`recskit.sage_adapter` to fetch the ledger side and
+[sagekit](https://github.com/Duckboard/sagekit) for the ODBC
+connection and column auto-detection.
+
+### Concept reference
+
+| Concept | Meaning |
+|---|---|
+| `StatementItem` | One line from the statement you're checking (invoice, credit note, or payment) |
+| `LedgerInvoice` / `LedgerPayment` | The equivalent transaction as it exists in your own ledger |
+| `MatchResult.status` | `"ok"`, `"mismatch"` (found but wrong amount), or `"missing"` (no match at all) |
+| `extra_in_ledger` | Ledger invoices never referenced by any statement line -- check these aren't being missed, or are simply old brought-forward items |
+| `balance_difference` | `ledger_balance - statement_balance` |
+
+## Bring your own data source
+
+The reconciliation logic never touches a database, file, or network --
+you build `StatementItem` / `LedgerInvoice` / `LedgerPayment` lists
+however suits your setup, and call `reconcile_statement()`. Options:
+
+- Parse a PDF or CSV statement export yourself (see
+  `examples/reconcile_csv.py`)
+- Pull the ledger side from Sage 50 with `recskit.sage_adapter` (see
+  `examples/reconcile_sage.py`)
+- Write your own adapter for Xero, QuickBooks, or anything else --
+  `sage_adapter.py` is about 100 lines and a reasonable template to
+  copy
+
+## Testing
+
+```bash
+pip install pytest
+pytest
+```
+
+The core test suite has no dependencies to mock -- it's all plain
+Python objects in, plain Python objects out.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| A statement line matches the wrong ledger invoice | Shouldn't happen -- recskit always tries an exact ref match before substring | If you see this, please open an issue with the two refs involved |
+| Balance agrees but you still see mismatches/missing items | This is expected and correct -- see "What problem this solves" above | Investigate each flagged line; a tied total doesn't guarantee every line is right |
+| Payment shows as missing despite being in the ledger | Amount differs by more than the tolerance, and the reference also doesn't appear as a substring | Widen `tolerance` in `match_payment()`, or check the payment was recorded correctly |
+| `ImportError` on `sagekit` | The `sage` extra wasn't installed | `pip install -e ".[sage]"`, or install sagekit directly |
+
+## License
+
+MIT -- see [LICENSE](LICENSE). Do whatever you like with this; a
+credit or a [Ko-fi tip](https://ko-fi.com/duckboard) is appreciated
+but never required.

recskit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+recskit/__init__.py,sha256=9AHjirPc4w9P3Is8ZnE9mk43GxEKs4OG5XnmhU5uswE,1346
+recskit/due_dates.py,sha256=Di7ZZBzoXEBnOEq2vndusVpnHEcC1GPn2u_NqQFgUYM,3386
+recskit/matching.py,sha256=325qNVOH4AU14noegYH16JLgcvgqB0qYleUSpvrMXKQ,4664
+recskit/models.py,sha256=IQhRmEnA5J2cyQ3GJEPZy-o3TZu2b-A6wEHmeoCcmo8,2890
+recskit/pdf_statement.py,sha256=Czu7jBy6H4el-qf1sVuBtg0B3poaywEBliWM6tkfmzs,7245
+recskit/reconcile.py,sha256=88e-nEGmXKnJ_M4xWeV1cx6T_SBZHXggfmj73bcG9E8,3004
+recskit/sage_adapter.py,sha256=UV0BO-2fXPGFZbEAcHGbDuPAy1-VGl2Pxg0iotNnQ3c,3962
+recskit-0.1.0.dist-info/licenses/LICENSE,sha256=cCyz-t_gcRxOT076nbb_MjadJUXfbQXEi_aSqvemsVw,1087
+recskit-0.1.0.dist-info/METADATA,sha256=M42puf7V3MUGA7IGbggAWXSVhjrHABH1ggt2Q520A-4,7956
+recskit-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+recskit-0.1.0.dist-info/top_level.txt,sha256=mHFs_EZcE9kTNSmafjHmP6P3z7krLmLegrWXWv0X4io,8
+recskit-0.1.0.dist-info/RECORD,,

recskit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

recskit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duckboard
+
+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.

recskit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+recskit