ledgerlens 0.1.2__tar.gz

ledgerlens-0.1.2/LICENSE

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

ledgerlens-0.1.2/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: ledgerlens
+Version: 0.1.2
+Summary: Forensic accounting analytics for Python: Benford's Law (Nigrini), journal entry testing, and Beneish / Altman / Piotroski scores.
+Author: Yu Zonglin (Sam Yu)
+License: MIT
+Project-URL: Homepage, https://github.com/yuzonglinsam/ledgerlens
+Project-URL: Issues, https://github.com/yuzonglinsam/ledgerlens/issues
+Keywords: audit,forensic accounting,benford,journal entry testing,fraud detection,beneish,altman,piotroski,data analytics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: scipy>=1.7
+Requires-Dist: openpyxl>=3.0
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.0; extra == "excel"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.4; extra == "plot"
+Provides-Extra: reference
+Requires-Dist: pyreadr>=0.4; extra == "reference"
+Provides-Extra: all
+Requires-Dist: openpyxl>=3.0; extra == "all"
+Requires-Dist: matplotlib>=3.4; extra == "all"
+Requires-Dist: pyreadr>=0.4; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: openpyxl>=3.0; extra == "dev"
+Requires-Dist: matplotlib>=3.4; extra == "dev"
+Dynamic: license-file
+
+# ledgerlens
+
+**Forensic accounting analytics for Python.** Run Nigrini-style Benford tests, 13
+explainable journal-entry procedures, Beneish / Altman / Piotroski financial screens,
+and export auditor-readable Excel workpapers. MIT licensed; Python 3.9–3.13.
+
+`ledgerlens` surfaces **red flags / reasons to investigate**. A flag is a sample-selection
+signal, never a finding that fraud occurred.
+
+## Installation
+
+```bash
+pip install .                         # from a cloned repository; includes Excel support
+pip install '.[dev]'                 # development, pytest, pytest-cov and ruff
+pip install '.[reference,plot]'      # optional R reference downloader and visualisations
+```
+
+Download the verified [v0.1.2 wheel and source distribution](https://github.com/yuzonglinsam/ledgerlens/releases/tag/v0.1.2). The package is not on PyPI yet;
+`pip install ledgerlens` will become available after PyPI Trusted Publishing is configured and the upload succeeds.
+
+## Benford's Law
+
+```python
+import ledgerlens as ll
+
+amounts = [119.20, 152.15, 203.00, 501.42, 509.10, 817.50]
+result = ll.benford(amounts, test="first_two", sign="positive", min_value=None)
+print(result.summary())
+print(result.table.head())
+print(result.suspects())
+
+# Other methods: first, second, first_three, last_two, summation_test,
+# number_duplication, second_order, mantissa_arc_test.
+```
+
+For meaningful conformity testing, use an appropriately sized population that spans
+several orders of magnitude. The library reports MAD, significance statistics, and
+record-level suspects, retaining source indexes.
+
+## Journal entry testing (JET01–JET13)
+
+```python
+from ledgerlens.datasets import synthetic_gl
+from ledgerlens.jet import JournalEntryTester
+
+gl, truth = synthetic_gl(n_entries=2000, seed=0)  # SYNTHETIC teaching data
+jet = JournalEntryTester(
+    gl, entry_id="entry_id", date="post_date", amount="amount",
+    account="account", description="description", user="user",
+    effective_date="effective_date", period_end="2025-12-31",
+)
+report = jet.run_all(threshold=50000, limits=[50000])
+print(report.summary().to_string(index=False))
+print(report.entry_risk_scores().head(10))
+print(report["JET09"].flagged[["entry_id", "description", "_reason"]].head())
+report.to_excel("jet_report.xlsx")
+```
+
+Input rows represent GL *lines*. Debit amounts are positive and credits negative;
+alternatively provide `debit="Debit"` and `credit="Credit"` instead of `amount=`.
+Only entry identifier, posting date and an amount representation are mandatory.
+Optional account, user and narrative columns enable more tests. The 13 rules cover
+imbalance, weekends/holidays, round values, large values, amounts just below approval
+limits, duplicates, cutoff, backdating, English/Chinese risk keywords, blanks, rare
+accounts, rare users/off-hours and Benford excess-digit spikes. `run_all()` retains
+skipped rules and their reasons. Each flagged row has its original index and `_reason`;
+the supplied DataFrame is unchanged. Risk score = number of distinct rules hit.
+
+The workbook has a linked **Summary**, sortable **Entry risk**, one tab per rule and a
+**Benford** tab with a native Excel bar chart when JET13 runs.
+
+## Financial scores
+
+Single-company input uses a `dict` or `pandas.Series` and returns a dataclass;
+company-year batches use a DataFrame and return a DataFrame. All numbers in these
+examples are *synthetic*.
+
+```python
+from ledgerlens import beneish_m, altman_z, piotroski_f
+
+altman_inputs = dict(
+    current_assets=40, current_liabilities=20, total_assets=100,
+    retained_earnings=10, ebit=10, total_liabilities=50,
+    market_cap=50, book_equity=50, sales=200,
+)
+print(altman_z(altman_inputs, model="public").summary())
+print(altman_z(altman_inputs, model="private").summary())
+print(altman_z(altman_inputs, model="non_manufacturing").summary())
+
+beneish_fields = dict(
+    receivables=(20, 10), sales=(200, 100), cogs=(100, 50),
+    current_assets=(60, 30), ppe=(60, 30), total_assets=(200, 100),
+    depreciation=(12, 6), sga=(20, 10), current_liabilities=(40, 20),
+    long_term_debt=(60, 30),
+)
+beneish_inputs = {f"{name}_{period}": value
+                  for name, pair in beneish_fields.items()
+                  for period, value in zip(("t", "prev"), pair)}
+beneish_inputs.update(net_income_t=20, cfo_t=10)
+print(beneish_m(beneish_inputs).summary())  # 8-variable M8 and 5-variable M5
+
+piotroski_inputs = dict(
+    net_income_t=15, net_income_prev=5, cfo_t=20, cfo_prev=2,
+    total_assets_t=100, total_assets_prev=100,
+    long_term_debt_t=10, long_term_debt_prev=20,
+    current_assets_t=60, current_assets_prev=40,
+    current_liabilities_t=20, current_liabilities_prev=20,
+    shares_outstanding_t=100, shares_outstanding_prev=100,
+    sales_t=200, sales_prev=100, cogs_t=80, cogs_prev=50,
+)
+print(piotroski_f(piotroski_inputs).summary())  # F-Score: 0–9
+```
+
+Input names and published coefficients are documented in
+[methodology](docs/methodology.md); ratios with zero denominators become NaN.
+
+## Command line
+
+```bash
+ledgerlens demo -o demo.xlsx
+ledgerlens benford payments.csv --column Amount --test first_two -o benford.xlsx
+ledgerlens jet general_ledger.csv --entry-id JE --date PostDate --amount Amt \
+  --account Account --description Description --user User --period-end 2025-12-31 \
+  --threshold 100000 --limits 50000,100000 -o audit.xlsx
+ledgerlens jet gl.xlsx --entry-id JE --date Date --debit Dr --credit Cr -o audit.xlsx
+ledgerlens score beneish company_years.csv -o beneish.csv
+ledgerlens score altman company_years.csv --model private -o altman.csv
+ledgerlens score piotroski company_years.csv -o fscore.csv
+```
+
+CSV, XLSX and Parquet inputs are supported (Parquet requires an installed pandas
+Parquet engine). Successful commands exit 0; expected input/usage errors exit 2.
+`ledgerlens demo` generates its own synthetic GL and never fetches client data.
+
+## Reproducible validation (2026-11-10)
+
+| Check | Independently measured result | Method |
+|---|---:|---|
+| CI matrix (3.9 / 3.11 / 3.13) | **39 passed, 1 skipped** on each version | GitHub Actions: lint + coverage |
+| Line coverage | **~95%** | Regression suite, including Excel and timezone edge cases |
+| Fresh installation | **PASS** | Isolated GitHub Actions venv; `pip install .` then `ledgerlens demo -o demo.xlsx` from /tmp; 16-sheet workbook |
+| Synthetic JET recall | **112/112 = 100.00%** | `synthetic_gl(2000, seed=0)`; matching `(entry_id, test_id)` pairs |
+| Clean-entry false-positive rate | **390/2000 = 19.50%** | Clean entries flagged by at least one rule |
+| Clean-entry-test false-positive rate | **390/26000 = 1.50%** | Clean `(entry_id, test_id)` pairs flagged |
+| 1,000,000 GL lines / 13 JET rules | **8.73 seconds** | Python 3.13.5, pandas 2.2.3; benchmarked separately in a local container |
+| R corporate-payment first-two MAD | **0.002336614** (matches 9 decimal places) | Independent GitHub Actions network run, 185,083 eligible observations |
+| R corporate-payment distortion factor | **−1.065467% (R)** vs **−1.064985% (corrected)** | Same public dataset, intentional denominator correction |
+
+The R reference test now runs in CI on `push`; locally it is opt-in using
+`LEDGERLENS_NETWORK=1 pytest -m network -q` after
+`pip install '.[reference]'`. Third-party `.rda` files are downloaded and
+cached at runtime, never bundled or committed.
+
+### Reproduced public case studies
+
+| Public reference dataset | Eligible observations | First-two MAD | Conformity |
+|---|---:|---:|---|
+| Corporate payments | 185,083 | 0.002336614 | Nonconformity |
+| Madoff *exposure amounts* | 198 | 0.006075249 | Nonconformity |
+| Sino-Forest published figures | 772 | 0.003463887 | Nonconformity |
+
+![Corporate payments Benford](docs/figures/corporate_payment-benford.png)
+![Madoff exposure Benford](docs/figures/madoff_returns-benford.png)
+![Sino-Forest Benford](docs/figures/sino_forest-benford.png)
+
+### Synthetic demonstration
+
+![Synthetic JET counts](docs/figures/synthetic-jet-counts.png)
+![Synthetic entry risk](docs/figures/synthetic-entry-risk.png)
+
+Reproduce case studies with `python examples/case_studies.py --public` (requires
+reference and plot extras). Generate the performance sample with
+`python examples/benchmark_jet.py --lines 1000000`. Interpret the synthetic
+false-positive rates as a controlled teaching example, not field precision.
+See [public and synthetic case studies](docs/case-studies.md),
+[methodology](docs/methodology.md), [performance](docs/performance.md), and
+[decisions](docs/decisions.md).
+
+## Development and release
+
+```bash
+python -m pytest -q
+python -m pytest --cov=ledgerlens --cov-fail-under=90 -q
+ruff check .
+python -m build
+```
+
+CI runs Python 3.9, 3.11 and 3.13, also checking fresh installation,
+benchmark reproducibility and external R references.
+The [GitHub v0.1.2 release](https://github.com/yuzonglinsam/ledgerlens/releases/tag/v0.1.2) includes a wheel and sdist.
+A [manual OIDC publishing workflow](docs/publishing.md) is ready for TestPyPI and PyPI; the repository owner must register the Trusted Publisher and explicitly initiate publication.
+
+## Disclaimer and licence
+
+These methods provide statistical indicators and audit sampling leads; conclusions
+require professional investigation, appropriate population selection, and corroborating
+evidence. Do not treat any output as an automated accusation of wrongdoing.
+MIT — see [LICENSE](LICENSE).

ledgerlens-0.1.2/README.md

@@ -0,0 +1,198 @@
+# ledgerlens
+
+**Forensic accounting analytics for Python.** Run Nigrini-style Benford tests, 13
+explainable journal-entry procedures, Beneish / Altman / Piotroski financial screens,
+and export auditor-readable Excel workpapers. MIT licensed; Python 3.9–3.13.
+
+`ledgerlens` surfaces **red flags / reasons to investigate**. A flag is a sample-selection
+signal, never a finding that fraud occurred.
+
+## Installation
+
+```bash
+pip install .                         # from a cloned repository; includes Excel support
+pip install '.[dev]'                 # development, pytest, pytest-cov and ruff
+pip install '.[reference,plot]'      # optional R reference downloader and visualisations
+```
+
+Download the verified [v0.1.2 wheel and source distribution](https://github.com/yuzonglinsam/ledgerlens/releases/tag/v0.1.2). The package is not on PyPI yet;
+`pip install ledgerlens` will become available after PyPI Trusted Publishing is configured and the upload succeeds.
+
+## Benford's Law
+
+```python
+import ledgerlens as ll
+
+amounts = [119.20, 152.15, 203.00, 501.42, 509.10, 817.50]
+result = ll.benford(amounts, test="first_two", sign="positive", min_value=None)
+print(result.summary())
+print(result.table.head())
+print(result.suspects())
+
+# Other methods: first, second, first_three, last_two, summation_test,
+# number_duplication, second_order, mantissa_arc_test.
+```
+
+For meaningful conformity testing, use an appropriately sized population that spans
+several orders of magnitude. The library reports MAD, significance statistics, and
+record-level suspects, retaining source indexes.
+
+## Journal entry testing (JET01–JET13)
+
+```python
+from ledgerlens.datasets import synthetic_gl
+from ledgerlens.jet import JournalEntryTester
+
+gl, truth = synthetic_gl(n_entries=2000, seed=0)  # SYNTHETIC teaching data
+jet = JournalEntryTester(
+    gl, entry_id="entry_id", date="post_date", amount="amount",
+    account="account", description="description", user="user",
+    effective_date="effective_date", period_end="2025-12-31",
+)
+report = jet.run_all(threshold=50000, limits=[50000])
+print(report.summary().to_string(index=False))
+print(report.entry_risk_scores().head(10))
+print(report["JET09"].flagged[["entry_id", "description", "_reason"]].head())
+report.to_excel("jet_report.xlsx")
+```
+
+Input rows represent GL *lines*. Debit amounts are positive and credits negative;
+alternatively provide `debit="Debit"` and `credit="Credit"` instead of `amount=`.
+Only entry identifier, posting date and an amount representation are mandatory.
+Optional account, user and narrative columns enable more tests. The 13 rules cover
+imbalance, weekends/holidays, round values, large values, amounts just below approval
+limits, duplicates, cutoff, backdating, English/Chinese risk keywords, blanks, rare
+accounts, rare users/off-hours and Benford excess-digit spikes. `run_all()` retains
+skipped rules and their reasons. Each flagged row has its original index and `_reason`;
+the supplied DataFrame is unchanged. Risk score = number of distinct rules hit.
+
+The workbook has a linked **Summary**, sortable **Entry risk**, one tab per rule and a
+**Benford** tab with a native Excel bar chart when JET13 runs.
+
+## Financial scores
+
+Single-company input uses a `dict` or `pandas.Series` and returns a dataclass;
+company-year batches use a DataFrame and return a DataFrame. All numbers in these
+examples are *synthetic*.
+
+```python
+from ledgerlens import beneish_m, altman_z, piotroski_f
+
+altman_inputs = dict(
+    current_assets=40, current_liabilities=20, total_assets=100,
+    retained_earnings=10, ebit=10, total_liabilities=50,
+    market_cap=50, book_equity=50, sales=200,
+)
+print(altman_z(altman_inputs, model="public").summary())
+print(altman_z(altman_inputs, model="private").summary())
+print(altman_z(altman_inputs, model="non_manufacturing").summary())
+
+beneish_fields = dict(
+    receivables=(20, 10), sales=(200, 100), cogs=(100, 50),
+    current_assets=(60, 30), ppe=(60, 30), total_assets=(200, 100),
+    depreciation=(12, 6), sga=(20, 10), current_liabilities=(40, 20),
+    long_term_debt=(60, 30),
+)
+beneish_inputs = {f"{name}_{period}": value
+                  for name, pair in beneish_fields.items()
+                  for period, value in zip(("t", "prev"), pair)}
+beneish_inputs.update(net_income_t=20, cfo_t=10)
+print(beneish_m(beneish_inputs).summary())  # 8-variable M8 and 5-variable M5
+
+piotroski_inputs = dict(
+    net_income_t=15, net_income_prev=5, cfo_t=20, cfo_prev=2,
+    total_assets_t=100, total_assets_prev=100,
+    long_term_debt_t=10, long_term_debt_prev=20,
+    current_assets_t=60, current_assets_prev=40,
+    current_liabilities_t=20, current_liabilities_prev=20,
+    shares_outstanding_t=100, shares_outstanding_prev=100,
+    sales_t=200, sales_prev=100, cogs_t=80, cogs_prev=50,
+)
+print(piotroski_f(piotroski_inputs).summary())  # F-Score: 0–9
+```
+
+Input names and published coefficients are documented in
+[methodology](docs/methodology.md); ratios with zero denominators become NaN.
+
+## Command line
+
+```bash
+ledgerlens demo -o demo.xlsx
+ledgerlens benford payments.csv --column Amount --test first_two -o benford.xlsx
+ledgerlens jet general_ledger.csv --entry-id JE --date PostDate --amount Amt \
+  --account Account --description Description --user User --period-end 2025-12-31 \
+  --threshold 100000 --limits 50000,100000 -o audit.xlsx
+ledgerlens jet gl.xlsx --entry-id JE --date Date --debit Dr --credit Cr -o audit.xlsx
+ledgerlens score beneish company_years.csv -o beneish.csv
+ledgerlens score altman company_years.csv --model private -o altman.csv
+ledgerlens score piotroski company_years.csv -o fscore.csv
+```
+
+CSV, XLSX and Parquet inputs are supported (Parquet requires an installed pandas
+Parquet engine). Successful commands exit 0; expected input/usage errors exit 2.
+`ledgerlens demo` generates its own synthetic GL and never fetches client data.
+
+## Reproducible validation (2026-11-10)
+
+| Check | Independently measured result | Method |
+|---|---:|---|
+| CI matrix (3.9 / 3.11 / 3.13) | **39 passed, 1 skipped** on each version | GitHub Actions: lint + coverage |
+| Line coverage | **~95%** | Regression suite, including Excel and timezone edge cases |
+| Fresh installation | **PASS** | Isolated GitHub Actions venv; `pip install .` then `ledgerlens demo -o demo.xlsx` from /tmp; 16-sheet workbook |
+| Synthetic JET recall | **112/112 = 100.00%** | `synthetic_gl(2000, seed=0)`; matching `(entry_id, test_id)` pairs |
+| Clean-entry false-positive rate | **390/2000 = 19.50%** | Clean entries flagged by at least one rule |
+| Clean-entry-test false-positive rate | **390/26000 = 1.50%** | Clean `(entry_id, test_id)` pairs flagged |
+| 1,000,000 GL lines / 13 JET rules | **8.73 seconds** | Python 3.13.5, pandas 2.2.3; benchmarked separately in a local container |
+| R corporate-payment first-two MAD | **0.002336614** (matches 9 decimal places) | Independent GitHub Actions network run, 185,083 eligible observations |
+| R corporate-payment distortion factor | **−1.065467% (R)** vs **−1.064985% (corrected)** | Same public dataset, intentional denominator correction |
+
+The R reference test now runs in CI on `push`; locally it is opt-in using
+`LEDGERLENS_NETWORK=1 pytest -m network -q` after
+`pip install '.[reference]'`. Third-party `.rda` files are downloaded and
+cached at runtime, never bundled or committed.
+
+### Reproduced public case studies
+
+| Public reference dataset | Eligible observations | First-two MAD | Conformity |
+|---|---:|---:|---|
+| Corporate payments | 185,083 | 0.002336614 | Nonconformity |
+| Madoff *exposure amounts* | 198 | 0.006075249 | Nonconformity |
+| Sino-Forest published figures | 772 | 0.003463887 | Nonconformity |
+
+![Corporate payments Benford](docs/figures/corporate_payment-benford.png)
+![Madoff exposure Benford](docs/figures/madoff_returns-benford.png)
+![Sino-Forest Benford](docs/figures/sino_forest-benford.png)
+
+### Synthetic demonstration
+
+![Synthetic JET counts](docs/figures/synthetic-jet-counts.png)
+![Synthetic entry risk](docs/figures/synthetic-entry-risk.png)
+
+Reproduce case studies with `python examples/case_studies.py --public` (requires
+reference and plot extras). Generate the performance sample with
+`python examples/benchmark_jet.py --lines 1000000`. Interpret the synthetic
+false-positive rates as a controlled teaching example, not field precision.
+See [public and synthetic case studies](docs/case-studies.md),
+[methodology](docs/methodology.md), [performance](docs/performance.md), and
+[decisions](docs/decisions.md).
+
+## Development and release
+
+```bash
+python -m pytest -q
+python -m pytest --cov=ledgerlens --cov-fail-under=90 -q
+ruff check .
+python -m build
+```
+
+CI runs Python 3.9, 3.11 and 3.13, also checking fresh installation,
+benchmark reproducibility and external R references.
+The [GitHub v0.1.2 release](https://github.com/yuzonglinsam/ledgerlens/releases/tag/v0.1.2) includes a wheel and sdist.
+A [manual OIDC publishing workflow](docs/publishing.md) is ready for TestPyPI and PyPI; the repository owner must register the Trusted Publisher and explicitly initiate publication.
+
+## Disclaimer and licence
+
+These methods provide statistical indicators and audit sampling leads; conclusions
+require professional investigation, appropriate population selection, and corroborating
+evidence. Do not treat any output as an automated accusation of wrongdoing.
+MIT — see [LICENSE](LICENSE).

ledgerlens-0.1.2/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ledgerlens"
+version = "0.1.2"
+description = "Forensic accounting analytics for Python: Benford's Law (Nigrini), journal entry testing, and Beneish / Altman / Piotroski scores."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Yu Zonglin (Sam Yu)" }]
+keywords = [
+    "audit", "forensic accounting", "benford", "journal entry testing",
+    "fraud detection", "beneish", "altman", "piotroski", "data analytics",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "numpy>=1.21",
+    "pandas>=1.3",
+    "scipy>=1.7",
+    "openpyxl>=3.0",
+]
+
+[project.optional-dependencies]
+excel = ["openpyxl>=3.0"]
+plot = ["matplotlib>=3.4"]
+reference = ["pyreadr>=0.4"]
+all = ["openpyxl>=3.0", "matplotlib>=3.4", "pyreadr>=0.4"]
+dev = ["pytest>=7", "pytest-cov>=4", "ruff>=0.6", "openpyxl>=3.0", "matplotlib>=3.4"]
+
+[project.scripts]
+ledgerlens = "ledgerlens.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/yuzonglinsam/ledgerlens"
+Issues = "https://github.com/yuzonglinsam/ledgerlens/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["network: tests that download public reference data at runtime"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]

ledgerlens-0.1.2/setup.cfg

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

ledgerlens-0.1.2/src/ledgerlens/__init__.py

@@ -0,0 +1,60 @@
+"""ledgerlens - forensic accounting analytics for Python.
+
+Three building blocks:
+
+* :mod:`ledgerlens.benford`  - Benford's Law digit tests following Nigrini (2012)
+* :mod:`ledgerlens.jet`      - journal entry tests for general-ledger data
+* :mod:`ledgerlens.scores`   - Beneish M-Score, Altman Z-Score, Piotroski F-Score
+
+Quick start::
+
+    import ledgerlens as ll
+
+    res = ll.benford(df["Amount"], test="first_two")
+    print(res.summary())
+
+    report = ll.JournalEntryTester(gl, entry_id="je_id", date="post_date",
+                                   amount="amount", account="account").run_all()
+    report.to_excel("jet_report.xlsx")
+"""
+
+from .benford import (
+    BenfordResult,
+    benford,
+    expected_distribution,
+    mantissa_arc_test,
+    number_duplication,
+    second_order,
+    summation_test,
+)
+from .jet import JETReport, JournalEntryTester, TestResult
+from .scores import (
+    AltmanResult,
+    BeneishResult,
+    PiotroskiResult,
+    altman_z,
+    beneish_m,
+    piotroski_f,
+)
+
+__version__ = "0.1.2"
+
+__all__ = [
+    "AltmanResult",
+    "BeneishResult",
+    "BenfordResult",
+    "JETReport",
+    "JournalEntryTester",
+    "PiotroskiResult",
+    "TestResult",
+    "altman_z",
+    "benford",
+    "beneish_m",
+    "expected_distribution",
+    "mantissa_arc_test",
+    "number_duplication",
+    "piotroski_f",
+    "second_order",
+    "summation_test",
+    "__version__",
+]

ledgerlens-0.1.2/src/ledgerlens/_utils.py

@@ -0,0 +1,90 @@
+"""Internal helpers shared across modules."""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+# Relative nudge used when extracting digits. Binary floating point cannot
+# represent most decimals exactly (0.29 / 0.1 == 2.8999999999999995), which
+# would make naive truncation report 28 instead of 29 as the first-two digits.
+# Accounting amounts rarely carry more than ~12 significant digits, so a
+# 1e-12 relative nudge fixes representation error without changing any value
+# a human would have typed.
+_EPS = 1e-12
+
+
+def clean_numeric(
+    data, sign: str = "positive"
+) -> Tuple[np.ndarray, pd.Index]:
+    """Return (positive magnitudes, original index) after the sign filter.
+
+    ``sign`` follows the usual Benford-software convention:
+
+    * ``"positive"`` - keep values > 0 (default; recommended by Nigrini)
+    * ``"negative"`` - keep values < 0, analysed as magnitudes
+    * ``"both"``     - keep every non-zero value, analysed as magnitudes
+    """
+    if isinstance(data, pd.DataFrame):
+        raise TypeError("Pass a single column (Series), not a DataFrame.")
+    s = data if isinstance(data, pd.Series) else pd.Series(np.asarray(data).ravel())
+    s = pd.to_numeric(s, errors="coerce").astype(float)
+    s = s[np.isfinite(s.to_numpy())]
+
+    if sign == "positive":
+        s = s[s > 0]
+    elif sign == "negative":
+        s = -s[s < 0]
+    elif sign == "both":
+        s = s[s != 0].abs()
+    else:
+        raise ValueError("sign must be 'positive', 'negative' or 'both'")
+    return s.to_numpy(dtype=float), s.index
+
+
+def leading_digits(x: np.ndarray, n: int) -> np.ndarray:
+    """First ``n`` significant digits of each positive value, as integers.
+
+    ``leading_digits([1234.5, 0.029], 2) -> [12, 29]``
+    """
+    x = np.asarray(x, dtype=float)
+    if x.size == 0:
+        return np.array([], dtype=np.int64)
+    if np.any(x <= 0):
+        raise ValueError("leading_digits expects strictly positive values")
+    e = np.floor(np.log10(x))
+    s = x / np.power(10.0, e)
+    # log10 can land a hair on the wrong side of an integer for exact powers.
+    hi = s >= 10
+    s[hi] /= 10
+    lo = s < 1
+    s[lo] *= 10
+    d = np.floor(s * 10 ** (n - 1) * (1 + _EPS)).astype(np.int64)
+    # 9.999999999999998 nudged to 10.000000000001 really means 10**(e+1).
+    d[d >= 10**n] = 10 ** (n - 1)
+    return d
+
+
+def last_two_digits(x: np.ndarray, decimals: int = 0) -> Tuple[np.ndarray, np.ndarray]:
+    """Last two digits of each value after scaling by ``10**decimals``.
+
+    Returns ``(digits, mask)`` where ``mask`` marks values whose scaled
+    integer is at least 10 (a one-digit number has no "last two digits").
+    """
+    scaled = np.rint(np.asarray(x, dtype=float) * 10**decimals)
+    mask = scaled >= 10
+    digits = np.mod(scaled[mask], 100).astype(np.int64)
+    return digits, mask
+
+
+def require_columns(df: pd.DataFrame, cols: dict) -> None:
+    missing = {k: v for k, v in cols.items() if v is not None and v not in df.columns}
+    if missing:
+        detail = ", ".join(f"{k}={v!r}" for k, v in missing.items())
+        raise KeyError(f"Column(s) not found in data: {detail}")
+
+
+def fmt_pct(x: Optional[float], digits: int = 1) -> str:
+    return "n/a" if x is None or not np.isfinite(x) else f"{x * 100:.{digits}f}%"