cashapply 0.1.0__tar.gz

cashapply-0.1.0/LICENSE

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

cashapply-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: cashapply
+Version: 0.1.0
+Summary: Deterministic cash application: match bank payments to open invoices with an auditable trail
+Author: SybilGambleyyu
+License: MIT
+Project-URL: Homepage, https://github.com/SybilGambleyyu/cashapply
+Project-URL: Repository, https://github.com/SybilGambleyyu/cashapply
+Project-URL: Issues, https://github.com/SybilGambleyyu/cashapply/issues
+Keywords: accounting,accounts-receivable,cash-application,reconciliation,invoice-matching,remittance,open-item,bookkeeping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rapidfuzz>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# cashapply
+
+**Deterministic cash application for accounts receivable.**
+
+Match bank payments and remittance lines to open invoices — with a confidence score and a plain-English reason for every match. No black-box model: every suggestion is auditable.
+
+Also includes **bank ↔ book (GL) reconciliation** for classic statement matching.
+
+```bash
+pip install cashapply
+
+cashapply apply -p payments.csv -i invoices.csv -o matches.csv
+cashapply reconcile -b bank.csv -g book.csv -o pairs.csv
+```
+
+## Why this exists
+
+AR clerks and controllers still burn hours every week on cash application:
+
+1. A payment hits the bank for `$1,650.00`
+2. The memo says something like `paying both open invoices` or `INV-1004`
+3. Someone hunts through the open AR aging to find which invoice(s) it covers
+
+Enterprise tools (HighRadius, BlackLine, Versapay, …) automate this — at enterprise prices. Lightweight open-source matching engines you can drop into a script, a notebook, or a small firm’s workflow are scarce.
+
+**cashapply** is that engine:
+
+| Need | What cashapply does |
+|------|---------------------|
+| Memo says `INV-1001` | Reference extraction → high-confidence apply |
+| One payment covers two invoices | Subset-sum multi-invoice match |
+| Partial payment on account | Partial apply with customer-name check |
+| Bank line vs GL line | Two-sided ledger reconciliation |
+| Auditor asks “why?” | Every match has `reasons[]` and a score |
+
+It is **not** a full ERP, lockbox OCR product, or ML remittance reader. It takes clean structured inputs (CSV / Python objects) and returns scored matches you can post or review.
+
+## Install
+
+```bash
+pip install cashapply
+```
+
+Requires Python 3.10+.
+
+## Quick start (CLI)
+
+### Cash application
+
+**invoices.csv**
+
+```csv
+id,amount,customer,invoice_date,due_date,reference
+INV-1001,1500.00,Acme Corporation,2024-05-01,2024-05-31,PO-7781
+INV-1002,275.50,Acme Corporation,2024-05-15,2024-06-14,
+INV-1004,1200.00,Initech LLC,2024-06-10,2024-07-10,
+INV-1005,450.00,Initech LLC,2024-06-12,2024-07-12,
+```
+
+**payments.csv**
+
+```csv
+id,amount,date,memo,payer
+P-01,1500.00,2024-05-28,ACH BILL PAY INV-1001,Acme Corporation
+P-04,1650.00,2024-07-15,paying both open invoices,Initech LLC
+```
+
+```bash
+cashapply apply -p payments.csv -i invoices.csv -o matches.csv --json result.json
+```
+
+Example summary:
+
+```
+=== Cash application summary ===
+Payments:     2
+Invoices:     4
+Matches:      2  (auto-apply ≥0.85: 2)
+...
+[AUTO] pay P-01 → INV-1001  $1500.00  conf=0.97  (reference_full)
+       • memo reference 'INV-1001' (known_id) → invoice INV-1001
+[AUTO] pay P-04 → INV-1004, INV-1005  $1650.00  conf=0.93  (multi_invoice)
+       • multi-invoice: 1650.00 = sum of ['INV-1004', 'INV-1005'] (...)
+```
+
+### Bank ↔ book reconciliation
+
+```bash
+cashapply reconcile -b bank.csv -g gl.csv -o pairs.csv
+```
+
+## Python API
+
+```python
+from decimal import Decimal
+from cashapply import Invoice, Payment, MatchConfig, match_payments
+
+invoices = [
+    Invoice(id="INV-1001", amount=Decimal("1500.00"), customer="Acme Corporation"),
+    Invoice(id="INV-1002", amount=Decimal("275.50"), customer="Acme Corporation"),
+]
+payments = [
+    Payment(id="P-01", amount=Decimal("1500.00"), memo="ACH INV-1001", payer="Acme Corp"),
+]
+
+result = match_payments(payments, invoices)
+
+for m in result.high_confidence(0.85):
+    print(m.payment_id, "→", m.invoice_ids, m.confidence, m.reasons)
+
+# Full audit payload
+print(result.to_dict())
+```
+
+### Bank / GL reconciliation
+
+```python
+from cashapply.reconcile import LedgerLine, reconcile_ledgers
+from datetime import date
+from decimal import Decimal
+
+bank = [LedgerLine("b1", Decimal("100"), date(2024, 5, 1), "ACME DEP")]
+book = [LedgerLine("g1", Decimal("100"), date(2024, 5, 1), "Acme deposit")]
+result = reconcile_ledgers(bank, book)
+```
+
+## How matching works
+
+Matches are tried in order; each invoice is claimed at most once per run:
+
+1. **Reference** — invoice numbers / PO / refs extracted from the payment memo (and exact known-id scan)
+2. **Exact amount** — open balance equals payment; boosted by customer-name and date proximity; penalized when ambiguous
+3. **Multi-invoice** — payment equals the sum of a small set of open invoices (same customer preferred)
+4. **Partial** — payment is less than one larger invoice, only with reasonable customer-name agreement
+5. **Name + amount band** — strong name match with short-pay / near amount
+
+Confidence is a number in `[0, 1]`. Default rule of thumb:
+
+- **≥ 0.85** — safe to auto-post (still keep the reason trail)
+- **0.40–0.85** — queue for human review
+- **< 0.40** — not reported (stays unmatched)
+
+Tune with `MatchConfig`:
+
+```python
+cfg = MatchConfig(
+    amount_tolerance=Decimal("0.05"),
+    date_window_days=60,
+    allow_partial=True,
+    max_invoices_per_payment=5,
+    auto_apply_threshold=0.90,
+    min_report_confidence=0.50,
+)
+result = match_payments(payments, invoices, cfg)
+```
+
+## CSV columns
+
+Flexible headers — any of these work:
+
+| Role | Accepted column names |
+|------|------------------------|
+| Invoice id | `id`, `invoice_id`, `invoice`, `invoice_number`, `number` |
+| Amount | `amount`, `open_amount`, `balance`, `total` |
+| Customer | `customer`, `customer_name`, `name`, `client` |
+| Payment id | `id`, `payment_id`, `txn_id`, `transaction_id` |
+| Memo | `memo`, `description`, `narrative`, `reference`, `remittance` |
+| Payer | `payer`, `customer`, `name`, `payor` |
+
+## Examples
+
+This repo ships runnable samples:
+
+```bash
+git clone https://github.com/SybilGambleyyu/cashapply
+cd cashapply
+pip install -e .
+cashapply apply -p examples/payments.csv -i examples/invoices.csv
+cashapply reconcile -b examples/bank.csv -g examples/book.csv
+```
+
+## What this is not
+
+- Not OCR for PDF lockbox images (feed it structured data)
+- Not a full AR suite (credit memos, deductions workflows, ERP posting adapters — bring your own)
+- Not a neural net: accuracy comes from rules, fuzzy names, and combinatorial matching you can explain
+
+If you need PDF remittance capture, pair cashapply with your existing extraction step and pass the resulting tables in.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+MIT — use it in internal tools, products, and client work.

cashapply-0.1.0/README.md

@@ -0,0 +1,200 @@
+# cashapply
+
+**Deterministic cash application for accounts receivable.**
+
+Match bank payments and remittance lines to open invoices — with a confidence score and a plain-English reason for every match. No black-box model: every suggestion is auditable.
+
+Also includes **bank ↔ book (GL) reconciliation** for classic statement matching.
+
+```bash
+pip install cashapply
+
+cashapply apply -p payments.csv -i invoices.csv -o matches.csv
+cashapply reconcile -b bank.csv -g book.csv -o pairs.csv
+```
+
+## Why this exists
+
+AR clerks and controllers still burn hours every week on cash application:
+
+1. A payment hits the bank for `$1,650.00`
+2. The memo says something like `paying both open invoices` or `INV-1004`
+3. Someone hunts through the open AR aging to find which invoice(s) it covers
+
+Enterprise tools (HighRadius, BlackLine, Versapay, …) automate this — at enterprise prices. Lightweight open-source matching engines you can drop into a script, a notebook, or a small firm’s workflow are scarce.
+
+**cashapply** is that engine:
+
+| Need | What cashapply does |
+|------|---------------------|
+| Memo says `INV-1001` | Reference extraction → high-confidence apply |
+| One payment covers two invoices | Subset-sum multi-invoice match |
+| Partial payment on account | Partial apply with customer-name check |
+| Bank line vs GL line | Two-sided ledger reconciliation |
+| Auditor asks “why?” | Every match has `reasons[]` and a score |
+
+It is **not** a full ERP, lockbox OCR product, or ML remittance reader. It takes clean structured inputs (CSV / Python objects) and returns scored matches you can post or review.
+
+## Install
+
+```bash
+pip install cashapply
+```
+
+Requires Python 3.10+.
+
+## Quick start (CLI)
+
+### Cash application
+
+**invoices.csv**
+
+```csv
+id,amount,customer,invoice_date,due_date,reference
+INV-1001,1500.00,Acme Corporation,2024-05-01,2024-05-31,PO-7781
+INV-1002,275.50,Acme Corporation,2024-05-15,2024-06-14,
+INV-1004,1200.00,Initech LLC,2024-06-10,2024-07-10,
+INV-1005,450.00,Initech LLC,2024-06-12,2024-07-12,
+```
+
+**payments.csv**
+
+```csv
+id,amount,date,memo,payer
+P-01,1500.00,2024-05-28,ACH BILL PAY INV-1001,Acme Corporation
+P-04,1650.00,2024-07-15,paying both open invoices,Initech LLC
+```
+
+```bash
+cashapply apply -p payments.csv -i invoices.csv -o matches.csv --json result.json
+```
+
+Example summary:
+
+```
+=== Cash application summary ===
+Payments:     2
+Invoices:     4
+Matches:      2  (auto-apply ≥0.85: 2)
+...
+[AUTO] pay P-01 → INV-1001  $1500.00  conf=0.97  (reference_full)
+       • memo reference 'INV-1001' (known_id) → invoice INV-1001
+[AUTO] pay P-04 → INV-1004, INV-1005  $1650.00  conf=0.93  (multi_invoice)
+       • multi-invoice: 1650.00 = sum of ['INV-1004', 'INV-1005'] (...)
+```
+
+### Bank ↔ book reconciliation
+
+```bash
+cashapply reconcile -b bank.csv -g gl.csv -o pairs.csv
+```
+
+## Python API
+
+```python
+from decimal import Decimal
+from cashapply import Invoice, Payment, MatchConfig, match_payments
+
+invoices = [
+    Invoice(id="INV-1001", amount=Decimal("1500.00"), customer="Acme Corporation"),
+    Invoice(id="INV-1002", amount=Decimal("275.50"), customer="Acme Corporation"),
+]
+payments = [
+    Payment(id="P-01", amount=Decimal("1500.00"), memo="ACH INV-1001", payer="Acme Corp"),
+]
+
+result = match_payments(payments, invoices)
+
+for m in result.high_confidence(0.85):
+    print(m.payment_id, "→", m.invoice_ids, m.confidence, m.reasons)
+
+# Full audit payload
+print(result.to_dict())
+```
+
+### Bank / GL reconciliation
+
+```python
+from cashapply.reconcile import LedgerLine, reconcile_ledgers
+from datetime import date
+from decimal import Decimal
+
+bank = [LedgerLine("b1", Decimal("100"), date(2024, 5, 1), "ACME DEP")]
+book = [LedgerLine("g1", Decimal("100"), date(2024, 5, 1), "Acme deposit")]
+result = reconcile_ledgers(bank, book)
+```
+
+## How matching works
+
+Matches are tried in order; each invoice is claimed at most once per run:
+
+1. **Reference** — invoice numbers / PO / refs extracted from the payment memo (and exact known-id scan)
+2. **Exact amount** — open balance equals payment; boosted by customer-name and date proximity; penalized when ambiguous
+3. **Multi-invoice** — payment equals the sum of a small set of open invoices (same customer preferred)
+4. **Partial** — payment is less than one larger invoice, only with reasonable customer-name agreement
+5. **Name + amount band** — strong name match with short-pay / near amount
+
+Confidence is a number in `[0, 1]`. Default rule of thumb:
+
+- **≥ 0.85** — safe to auto-post (still keep the reason trail)
+- **0.40–0.85** — queue for human review
+- **< 0.40** — not reported (stays unmatched)
+
+Tune with `MatchConfig`:
+
+```python
+cfg = MatchConfig(
+    amount_tolerance=Decimal("0.05"),
+    date_window_days=60,
+    allow_partial=True,
+    max_invoices_per_payment=5,
+    auto_apply_threshold=0.90,
+    min_report_confidence=0.50,
+)
+result = match_payments(payments, invoices, cfg)
+```
+
+## CSV columns
+
+Flexible headers — any of these work:
+
+| Role | Accepted column names |
+|------|------------------------|
+| Invoice id | `id`, `invoice_id`, `invoice`, `invoice_number`, `number` |
+| Amount | `amount`, `open_amount`, `balance`, `total` |
+| Customer | `customer`, `customer_name`, `name`, `client` |
+| Payment id | `id`, `payment_id`, `txn_id`, `transaction_id` |
+| Memo | `memo`, `description`, `narrative`, `reference`, `remittance` |
+| Payer | `payer`, `customer`, `name`, `payor` |
+
+## Examples
+
+This repo ships runnable samples:
+
+```bash
+git clone https://github.com/SybilGambleyyu/cashapply
+cd cashapply
+pip install -e .
+cashapply apply -p examples/payments.csv -i examples/invoices.csv
+cashapply reconcile -b examples/bank.csv -g examples/book.csv
+```
+
+## What this is not
+
+- Not OCR for PDF lockbox images (feed it structured data)
+- Not a full AR suite (credit memos, deductions workflows, ERP posting adapters — bring your own)
+- Not a neural net: accuracy comes from rules, fuzzy names, and combinatorial matching you can explain
+
+If you need PDF remittance capture, pair cashapply with your existing extraction step and pass the resulting tables in.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+MIT — use it in internal tools, products, and client work.

cashapply-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cashapply"
+version = "0.1.0"
+description = "Deterministic cash application: match bank payments to open invoices with an auditable trail"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "SybilGambleyyu" },
+]
+keywords = [
+    "accounting",
+    "accounts-receivable",
+    "cash-application",
+    "reconciliation",
+    "invoice-matching",
+    "remittance",
+    "open-item",
+    "bookkeeping",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "rapidfuzz>=3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "build", "twine"]
+
+[project.scripts]
+cashapply = "cashapply.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/SybilGambleyyu/cashapply"
+Repository = "https://github.com/SybilGambleyyu/cashapply"
+Issues = "https://github.com/SybilGambleyyu/cashapply/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

cashapply-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cashapply-0.1.0/src/cashapply/__init__.py

@@ -0,0 +1,23 @@
+"""
+cashapply — deterministic cash application and open-item matching.
+
+Match bank payments (or remittance lines) to open invoices with scored,
+auditable reasons. No ML black boxes: every match explains itself.
+"""
+
+from cashapply.engine import MatchConfig, match_payments
+from cashapply.models import Invoice, Match, MatchResult, Payment
+from cashapply.reconcile import ReconcileConfig, reconcile_ledgers
+
+__version__ = "0.1.0"
+__all__ = [
+    "Invoice",
+    "Payment",
+    "Match",
+    "MatchResult",
+    "MatchConfig",
+    "match_payments",
+    "ReconcileConfig",
+    "reconcile_ledgers",
+    "__version__",
+]