bankstract 0.2.0__tar.gz

bankstract-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+.venv/
+venv/
+env/
+.python-version
+.env
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Fixture privacy — never commit unredacted statements.
+# Drop real PDFs into tests/<bank>/fixtures/_local/ for dev only.
+tests/**/fixtures/_local/
+tests/**/fixtures/*real*.pdf
+tests/**/fixtures/*unredacted*.pdf
+tests/**/fixtures/*raw*.pdf

bankstract-0.2.0/LICENSE

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

bankstract-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: bankstract
+Version: 0.2.0
+Summary: Convert Nigerian bank PDF statements into structured CSV.
+Project-URL: Homepage, https://github.com/logickoder/bankstract
+Project-URL: Issues, https://github.com/logickoder/bankstract/issues
+Author: Jeffery Orazulike
+License: MIT License
+        
+        Copyright (c) 2026 Jeffery Orazulike
+        
+        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.
+License-File: LICENSE
+Keywords: bank,csv,nigeria,pdf,statement
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pymupdf>=1.27.2
+Provides-Extra: camelot
+Requires-Dist: camelot-py[cv]>=0.11; extra == 'camelot'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: ocr
+Requires-Dist: pillow>=10.0; extra == 'ocr'
+Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
+Description-Content-Type: text/markdown
+
+# bankstract
+
+Convert Nigerian bank PDF statements into structured CSV. Plugin architecture — one parser per bank.
+
+```bash
+pip install bankstract
+
+bankstract palmpay statement.pdf -o out.csv
+bankstract auto unknown.pdf -o out.csv
+bankstract list
+```
+
+## Status
+
+| Bank       | Status        |
+| ---------- | ------------- |
+| PalmPay    | v0.1 — alpha  |
+| First Bank | v0.1 — alpha  |
+
+## Install
+
+```bash
+pip install bankstract
+```
+
+Optional extras:
+
+```bash
+pip install "bankstract[ocr]"      # pytesseract for scanned PDFs
+pip install "bankstract[camelot]"  # camelot lattice fallback
+```
+
+## Develop
+
+Project uses [uv](https://docs.astral.sh/uv/) for dependency + venv management.
+
+```bash
+uv sync --all-extras       # create .venv, install deps + extras from uv.lock
+uv run pre-commit install  # one-time: enable the pre-commit hook
+uv run pytest              # run tests
+uv run ruff check src tests
+uv run pyright src tests   # strict type check (see CLAUDE.md directive 8)
+uv run bankstract list     # invoke CLI
+```
+
+Add a dependency with `uv add <pkg>` (dev: `uv add --dev <pkg>`). Commit `uv.lock`.
+
+The pre-commit hook runs `ruff check`, `ruff format --check`, `pyright` (strict), and `pytest` before every commit. Bypass only in genuine emergencies with `git commit --no-verify`; the same checks run again in CI.
+
+### Releasing
+
+CI publishes to PyPI automatically on push to `main` via `.github/workflows/publish.yml`. The workflow runs the full gate (ruff + pyright + pytest), and if the current `pyproject.toml` version already exists on PyPI it auto-bumps the minor component and commits the bump before publishing. PyPI auth uses OIDC trusted publishing — no token in repo or CI secrets.
+
+To prepare a release locally:
+
+```bash
+scripts/bump-version.sh                 # patch bump
+scripts/bump-version.sh minor           # 0.2.x -> 0.3.0
+scripts/bump-version.sh major           # 0.x.x -> 1.0.0
+scripts/bump-version.sh 0.3.0           # exact set
+uv build                                # dist/*.whl + dist/*.tar.gz
+uv publish dist/*                       # only if not using the GH workflow; needs --token or UV_PUBLISH_TOKEN
+```
+
+Trusted-publisher setup (one-time, owner only): create a publisher at <https://pypi.org/manage/account/publishing/> with workflow `publish.yml`, repo `logickoder/bankstract`.
+
+## Usage
+
+```bash
+bankstract <bank> <pdf> -o <csv>           # explicit parser
+bankstract auto <pdf> -o <csv>             # auto-detect via Parser.detect()
+bankstract list                            # show registered parsers
+```
+
+Unparseable blocks are written to a `.log` sidecar next to the output CSV.
+
+## Reconciliation invariant
+
+Two complementary checks; the CLI picks whichever applies per bank.
+
+- **Row-wise** (banks that print a running balance): `prev.balance ± debit/credit == curr.balance`. Mismatch raises `ReconciliationError` with the row index.
+- **Totals-based** (banks like PalmPay that omit a balance column): the parser reads `Total Money In` / `Total Money Out` from the statement header and the CLI asserts that the sum of parsed credits/debits equals those totals.
+
+Both modes exist to catch silently-dropped rows — the failure mode of naive PDF parsers.
+
+## Contributing a bank parser
+
+1. Copy `src/bankstract/parsers/palmpay.py` to `src/bankstract/parsers/<bank>.py`.
+2. Implement `detect()` and `parse() -> ParseResult` from `parsers/base.py`. Populate `total_credit` / `total_debit` if the statement only ships header totals.
+3. Add a `Redactor` subclass under `src/bankstract/redactors/<bank>.py` for the fixture pipeline.
+4. Drop the raw statement at `tests/<bank>/fixtures/_local/` (gitignored), then `uv run bankstract redact <bank> <raw> tests/<bank>/fixtures/sample.pdf` to produce the committable fixture.
+5. Add tests under `tests/<bank>/test_parser.py` and `tests/<bank>/test_redactor.py`.
+
+CI runs `ruff` + `pyright` (strict) + `pytest`. All three must pass clean. Reconciliation invariant must hold on every fixture.
+
+Fixture PDFs must be redacted: account numbers, names, addresses, transaction IDs scrubbed. Never commit unredacted statements.
+
+## License
+
+MIT. Author: [logickoder](https://github.com/logickoder).

bankstract-0.2.0/PRD.md

@@ -0,0 +1,184 @@
+# bankstract — PRD
+
+**Status:** concept · v0.1 target
+**License:** MIT
+**Stack:** Python 3.11+
+
+---
+
+## What
+
+Public Python CLI + library that converts Nigerian bank PDF statements into structured CSV. Plugin architecture — one parser module per bank.
+
+```bash
+bankstract palmpay statement.pdf -o out.csv
+bankstract auto unknown.pdf -o out.csv          # auto-detect bank
+bankstract fbn scanned.pdf -o out.csv --ocr     # force OCR
+bankstract list                                 # show registered parsers
+```
+
+## Why
+
+Every Nigerian dev solves this once, badly, in private. Banks export PDFs; tools like BudgetBakers, YNAB, Notion, Google Sheets want CSV. Manual entry costs more than the visibility is worth, so trackers go stale.
+
+bankstract closes that gap with one clean tool, one plugin contract, and community-driven bank coverage.
+
+## Scope
+
+| Version | Coverage                                                                         |
+| ------- | -------------------------------------------------------------------------------- |
+| v0.1    | PalmPay only. CLI + plugin contract + reconciliation + tests + CI. PyPI release. |
+| v0.2    | First Bank parser + OCR fallback for scanned statements.                         |
+| v0.3+   | GTB, Kuda, Opay, Stanbic, Wise, Bamboo, Risevest — community PRs.                |
+
+**Out of scope:** category inference, ML-based parsing, GUI, pushing data into third-party trackers (those belong in downstream tools).
+
+## Architecture
+
+### Stack rationale
+
+- **Python** over Node — `pdfplumber` and `camelot-py` are best-in-class table extractors; `pytesseract` is the cleanest OCR binding. Node alternatives are weaker on table extract and slower on OCR.
+- **pdfplumber primary, camelot fallback** — pdfplumber for text-PDF table extract; camelot lattice mode for messy ruled tables; pytesseract only when the text layer is absent (scanned PDFs).
+- **pymupdf for true redaction** — `apply_redactions()` rewrites the PDF content stream rather than visually overlaying, so fixture PDFs contain no recoverable PII.
+- **pydantic schema** — runtime validation + clean JSON Schema export for downstream tools.
+- **click CLI** — standard, autocomplete-friendly, low boilerplate.
+
+### Plugin contract
+
+Every bank is a parser module implementing the `Parser` ABC.
+
+```python
+class Parser(ABC):
+    bank: str  # module-level identifier (e.g. "palmpay", "fbn")
+
+    @abstractmethod
+    def detect(self, pdf_path: Path) -> bool:
+        """Return True if this parser handles the given PDF (header/logo/text-marker match)."""
+
+    @abstractmethod
+    def parse(self, pdf_path: Path) -> ParseResult:
+        """Extract transactions and header totals. Raise ParseError on format mismatch."""
+```
+
+Parsers live in `src/bankstract/parsers/<bank>.py` and self-register via import side-effect in `parsers/__init__.py`. A parallel `Redactor` plugin tree under `src/bankstract/redactors/<bank>.py` produces committable fixtures from raw statements.
+
+### Transaction + ParseResult schema
+
+```python
+class Transaction(BaseModel):
+    date: date
+    narration: str
+    debit: Decimal = Decimal("0")
+    credit: Decimal = Decimal("0")
+    balance: Decimal | None = None   # None when the statement omits a running balance
+    reference: str | None = None     # bank transaction ID
+    currency: str = "NGN"
+
+
+@dataclass
+class ParseResult:
+    transactions: list[Transaction]
+    total_credit: Decimal | None = None   # from statement header
+    total_debit: Decimal | None = None
+    format_version: str | None = None
+```
+
+Amounts are stored as `Decimal` (not float — financial precision). The Naira sign is stripped before parsing.
+
+### Reconciliation invariant
+
+Two complementary checks:
+
+- **Row-wise** (`reconcile()`): `prev.balance ± debit/credit == curr.balance`. Used when the statement carries a per-row running balance. Mismatch raises `ReconciliationError` with the row index.
+- **Totals-based** (`verify_totals()`): sum of parsed credits/debits equals header `Total Money In` / `Total Money Out`. Used when the statement omits a running balance (e.g. PalmPay). Parsers MUST populate `ParseResult.total_credit/total_debit` in that case, otherwise reconciliation is skipped silently — a directive 2 violation.
+
+Both modes catch silently-dropped rows, which is the failure mode of every naive PDF parser.
+
+### Failure handling
+
+- **Unparseable blocks** go to a `.log` sidecar file. Never silently dropped.
+- **Format-version drift** — each parser logs a detected `format_version` at run start. Parse errors include the detected version, so issue reports are actionable.
+
+### Repo layout
+
+```
+bankstract/
+├── pyproject.toml             hatchling backend, ruff + pytest + pyright config
+├── pyrightconfig.json         IDE-side mirror of [tool.pyright]
+├── uv.lock                    uv-managed lockfile
+├── README.md
+├── PRD.md
+├── LICENSE                    MIT
+├── src/
+│   └── bankstract/            standard src-layout package
+│       ├── cli.py
+│       ├── schema.py          Transaction + ParseResult + errors
+│       ├── reconcile.py       reconcile() + verify_totals()
+│       ├── _layout.py         Word dataclass + classify + Y-grouping (shared)
+│       ├── _pymupdf.py        typed facade over pymupdf
+│       ├── _pdfplumber.py     typed facade over pdfplumber
+│       ├── writers/csv.py
+│       ├── parsers/
+│       │   ├── __init__.py    registry (import side-effect)
+│       │   ├── base.py        Parser ABC
+│       │   ├── palmpay.py
+│       │   └── fbn.py
+│       └── redactors/
+│           ├── __init__.py    registry (import side-effect)
+│           ├── base.py        Redactor ABC + RedactReport (template-method)
+│           ├── _shared.py     shared redact primitives
+│           ├── palmpay.py
+│           └── fbn.py
+├── tests/
+│   ├── test_reconcile.py      bank-agnostic
+│   └── <bank>/                one folder per bank
+│       ├── test_parser.py
+│       ├── test_redactor.py
+│       └── fixtures/
+│           ├── sample.pdf     redacted sample (committed)
+│           └── _local/        gitignored: raw statements for dev
+└── .github/workflows/ci.yml   uv + ruff + pyright + pytest
+```
+
+## CLI surface
+
+```bash
+bankstract <bank> <pdf> -o <csv>           # explicit parser
+bankstract auto <pdf> -o <csv>             # detect via Parser.detect()
+bankstract <bank> <pdf> -o <csv> --ocr     # force OCR path
+bankstract list                            # show registered parsers + status
+```
+
+## Risks
+
+| Risk                                                                         | Mitigation                                                                                                 |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Statement format drift — banks rev PDFs annually.                            | Per-parser `format_version` detection + log on parse error. Per-bank fixture suite in tests.               |
+| OCR accuracy on scanned statements — ₦ / N confusion, comma-separator drift. | Post-OCR regex normalization. Reconciliation invariant catches arithmetic errors before they ship.         |
+| Charset edge cases — `₦` decodes differently across PDF producers.           | Strip currency symbols and store as `Decimal`.                                                             |
+| Fixture privacy — sample PDFs contain PII.                                   | All fixtures must be anonymized: account numbers, names, addresses scrubbed. Never commit unredacted PDFs. |
+
+## Roadmap
+
+- [ ] `pyproject.toml` + Parser ABC + Transaction schema + csv writer + reconciliation
+- [ ] PalmPay parser + 1 anonymized fixture + test
+- [ ] CLI wrapper + auto-detect
+- [ ] README + LICENSE + CI
+- [ ] **v0.1.0** — PyPI release, PalmPay only, FBN marked in progress
+- [ ] First Bank parser + OCR fallback → **v0.2.0**
+- [ ] Open issues for next 5 banks; invite contributors
+
+## Contributing
+
+Add a bank in four steps:
+
+1. Copy `src/bankstract/parsers/palmpay.py` to `src/bankstract/parsers/<your_bank>.py` and implement `detect()` + `parse() -> ParseResult`.
+2. Copy `src/bankstract/redactors/palmpay.py` to `src/bankstract/redactors/<your_bank>.py` for the fixture pipeline.
+3. Drop the raw statement in `tests/<your_bank>/fixtures/_local/` (gitignored), run `uv run bankstract redact <your_bank> <raw> tests/<your_bank>/fixtures/sample.pdf`, eyeball the output, commit the redacted sample.
+4. Add tests in `tests/<your_bank>/test_parser.py` and `tests/<your_bank>/test_redactor.py`.
+
+CI runs `ruff` + `pyright` (strict) + `pytest`. All three must pass. Reconciliation invariant must hold on every fixture.
+
+## License
+
+MIT. See `LICENSE`.

bankstract-0.2.0/README.md

@@ -0,0 +1,100 @@
+# bankstract
+
+Convert Nigerian bank PDF statements into structured CSV. Plugin architecture — one parser per bank.
+
+```bash
+pip install bankstract
+
+bankstract palmpay statement.pdf -o out.csv
+bankstract auto unknown.pdf -o out.csv
+bankstract list
+```
+
+## Status
+
+| Bank       | Status        |
+| ---------- | ------------- |
+| PalmPay    | v0.1 — alpha  |
+| First Bank | v0.1 — alpha  |
+
+## Install
+
+```bash
+pip install bankstract
+```
+
+Optional extras:
+
+```bash
+pip install "bankstract[ocr]"      # pytesseract for scanned PDFs
+pip install "bankstract[camelot]"  # camelot lattice fallback
+```
+
+## Develop
+
+Project uses [uv](https://docs.astral.sh/uv/) for dependency + venv management.
+
+```bash
+uv sync --all-extras       # create .venv, install deps + extras from uv.lock
+uv run pre-commit install  # one-time: enable the pre-commit hook
+uv run pytest              # run tests
+uv run ruff check src tests
+uv run pyright src tests   # strict type check (see CLAUDE.md directive 8)
+uv run bankstract list     # invoke CLI
+```
+
+Add a dependency with `uv add <pkg>` (dev: `uv add --dev <pkg>`). Commit `uv.lock`.
+
+The pre-commit hook runs `ruff check`, `ruff format --check`, `pyright` (strict), and `pytest` before every commit. Bypass only in genuine emergencies with `git commit --no-verify`; the same checks run again in CI.
+
+### Releasing
+
+CI publishes to PyPI automatically on push to `main` via `.github/workflows/publish.yml`. The workflow runs the full gate (ruff + pyright + pytest), and if the current `pyproject.toml` version already exists on PyPI it auto-bumps the minor component and commits the bump before publishing. PyPI auth uses OIDC trusted publishing — no token in repo or CI secrets.
+
+To prepare a release locally:
+
+```bash
+scripts/bump-version.sh                 # patch bump
+scripts/bump-version.sh minor           # 0.2.x -> 0.3.0
+scripts/bump-version.sh major           # 0.x.x -> 1.0.0
+scripts/bump-version.sh 0.3.0           # exact set
+uv build                                # dist/*.whl + dist/*.tar.gz
+uv publish dist/*                       # only if not using the GH workflow; needs --token or UV_PUBLISH_TOKEN
+```
+
+Trusted-publisher setup (one-time, owner only): create a publisher at <https://pypi.org/manage/account/publishing/> with workflow `publish.yml`, repo `logickoder/bankstract`.
+
+## Usage
+
+```bash
+bankstract <bank> <pdf> -o <csv>           # explicit parser
+bankstract auto <pdf> -o <csv>             # auto-detect via Parser.detect()
+bankstract list                            # show registered parsers
+```
+
+Unparseable blocks are written to a `.log` sidecar next to the output CSV.
+
+## Reconciliation invariant
+
+Two complementary checks; the CLI picks whichever applies per bank.
+
+- **Row-wise** (banks that print a running balance): `prev.balance ± debit/credit == curr.balance`. Mismatch raises `ReconciliationError` with the row index.
+- **Totals-based** (banks like PalmPay that omit a balance column): the parser reads `Total Money In` / `Total Money Out` from the statement header and the CLI asserts that the sum of parsed credits/debits equals those totals.
+
+Both modes exist to catch silently-dropped rows — the failure mode of naive PDF parsers.
+
+## Contributing a bank parser
+
+1. Copy `src/bankstract/parsers/palmpay.py` to `src/bankstract/parsers/<bank>.py`.
+2. Implement `detect()` and `parse() -> ParseResult` from `parsers/base.py`. Populate `total_credit` / `total_debit` if the statement only ships header totals.
+3. Add a `Redactor` subclass under `src/bankstract/redactors/<bank>.py` for the fixture pipeline.
+4. Drop the raw statement at `tests/<bank>/fixtures/_local/` (gitignored), then `uv run bankstract redact <bank> <raw> tests/<bank>/fixtures/sample.pdf` to produce the committable fixture.
+5. Add tests under `tests/<bank>/test_parser.py` and `tests/<bank>/test_redactor.py`.
+
+CI runs `ruff` + `pyright` (strict) + `pytest`. All three must pass clean. Reconciliation invariant must hold on every fixture.
+
+Fixture PDFs must be redacted: account numbers, names, addresses, transaction IDs scrubbed. Never commit unredacted statements.
+
+## License
+
+MIT. Author: [logickoder](https://github.com/logickoder).

bankstract-0.2.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bankstract"
+version = "0.2.0"
+description = "Convert Nigerian bank PDF statements into structured CSV."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "Jeffery Orazulike" }]
+keywords = ["pdf", "csv", "bank", "statement", "nigeria"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "click>=8.1",
+    "pdfplumber>=0.11",
+    "pydantic>=2.6",
+    "pymupdf>=1.27.2",
+]
+
+[project.optional-dependencies]
+ocr = ["pytesseract>=0.3.10", "Pillow>=10.0"]
+camelot = ["camelot-py[cv]>=0.11"]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.5",
+    "build>=1.0",
+]
+
+[project.scripts]
+bankstract = "bankstract.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/logickoder/bankstract"
+Issues = "https://github.com/logickoder/bankstract/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bankstract"]
+
+[tool.hatch.build.targets.sdist]
+# Fixture PDFs in tests/ are dev-only redacted samples; exclude from the
+# published sdist to keep the upload lean.
+include = ["src", "README.md", "LICENSE", "PRD.md", "pyproject.toml", "uv.lock"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W", "N"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.0",
+    "pyright>=1.1.410",
+]

bankstract-0.2.0/src/bankstract/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

bankstract-0.2.0/src/bankstract/_layout.py

@@ -0,0 +1,91 @@
+"""
+Shared PDF-layout primitives used by both the parser and redactor stacks.
+
+A `Word` is the canonical typed token. pymupdf returns word tuples; pdfplumber
+returns dicts. Both are converted to `Word` at the boundary so downstream code
+stays strictly typed.
+
+`classify` and `group_by_baseline` are intentionally bank-agnostic — they
+operate on shapes, not vocabulary. Bank-specific dictionaries
+(NARRATION_PHRASES, HEADER_LABELS, etc.) live with their consuming module.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Literal
+
+TokenKind = Literal["blank", "date", "time", "ampm", "amount", "alnum", "text"]
+
+DATE_TOK = re.compile(r"(?:\d{2}/\d{2}/\d{4}|\d{2}-[A-Za-z]{3}-\d{4})")
+TIME_TOK = re.compile(r"\d{2}:\d{2}:\d{2}")
+AMOUNT_TOK = re.compile(r"[+-]?\d[\d,]*\.\d{2}")
+NAIRA_TOK = re.compile(r"₦\d[\d,]*\.\d{2}")
+TXID_TOK = re.compile(r"[A-Za-z0-9_]{6,}")
+
+
+@dataclass(frozen=True, slots=True)
+class Word:
+    text: str
+    x0: float
+    top: float
+    x1: float
+    bottom: float
+
+
+def classify(text: str) -> TokenKind:
+    if not text:
+        return "blank"
+    if DATE_TOK.fullmatch(text):
+        return "date"
+    if TIME_TOK.fullmatch(text):
+        return "time"
+    if text in ("AM", "PM"):
+        return "ampm"
+    if AMOUNT_TOK.fullmatch(text) or NAIRA_TOK.fullmatch(text):
+        return "amount"
+    if TXID_TOK.fullmatch(text) and any(c.isdigit() for c in text):
+        return "alnum"
+    return "text"
+
+
+def group_by_baseline(words: list[Word], tol: float) -> list[list[Word]]:
+    """Group words sharing a visual baseline. PalmPay and similar layouts
+    place a row's date / narration / txid columns at slightly offset
+    y-coordinates (txid often sits ~4 pt above the date baseline), so the
+    `top` value drifts WITHIN a single visual row. We compare each candidate
+    word against the LAST appended word's top, not the first — otherwise a
+    row whose first word is at the high edge of the drift will split off
+    the tokens at the low edge."""
+    rows: list[list[Word]] = []
+    for w in sorted(words, key=lambda x: (round(x.top / tol) * tol, x.x0)):
+        if rows and abs(rows[-1][-1].top - w.top) <= tol:
+            rows[-1].append(w)
+        else:
+            rows.append([w])
+    for row in rows:
+        row.sort(key=lambda x: x.x0)
+    return rows
+
+
+def from_pymupdf_words(raw: Any) -> list[Word]:
+    """Adapt pymupdf's (x0, y0, x1, y1, text, block, line, word_no) tuples."""
+    return [
+        Word(text=str(w[4]), x0=float(w[0]), top=float(w[1]), x1=float(w[2]), bottom=float(w[3]))
+        for w in raw
+    ]
+
+
+def from_pdfplumber_words(raw: Any) -> list[Word]:
+    """Adapt pdfplumber's word dicts."""
+    return [
+        Word(
+            text=str(w["text"]),
+            x0=float(w["x0"]),
+            top=float(w["top"]),
+            x1=float(w["x1"]),
+            bottom=float(w["bottom"]),
+        )
+        for w in raw
+    ]

bankstract-0.2.0/src/bankstract/_pdfplumber.py

@@ -0,0 +1,23 @@
+"""
+Typed facade over pdfplumber.
+
+Same rationale as _pymupdf: restrict the untyped third-party surface to one
+file so the rest of the codebase stays clean under pyright/Pylance strict.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+import pdfplumber as _pdfplumber  # type: ignore[import-untyped]
+
+
+@contextmanager
+def open_doc(path: Path) -> Any:
+    pdf = _pdfplumber.open(str(path))
+    try:
+        yield pdf
+    finally:
+        pdf.close()