bankstatementparser 0.0.24__tar.gz → 0.0.25__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/PKG-INFO +6 -5
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/README.md +5 -4
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/__init__.py +15 -1
- bankstatementparser-0.0.25/bankstatementparser/analytics/__init__.py +50 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/cash_flow.py +247 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/common.py +104 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/models.py +155 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/patterns.py +291 -0
- bankstatementparser-0.0.25/bankstatementparser/api.py +263 -0
- bankstatementparser-0.0.25/bankstatementparser/api_limits.py +226 -0
- bankstatementparser-0.0.25/bankstatementparser/api_worker.py +150 -0
- bankstatementparser-0.0.25/bankstatementparser/telemetry.py +177 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/pyproject.toml +2 -2
- bankstatementparser-0.0.24/bankstatementparser/analytics.py +0 -691
- bankstatementparser-0.0.24/bankstatementparser/api.py +0 -583
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/LICENSE +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/LICENSE-APACHE +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/LICENSE-MIT +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/_amounts.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/_llm_common.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/additional_parsers.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/bank_statement_parsers.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/base_parser.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/camt_parser.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/cli.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/__init__.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/account_mapper.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/categorizer.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/exceptions.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/export/__init__.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/export/ledger.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/export/parquet.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/field86_parser.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/forensics.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/__init__.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/evaluation.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/llm_extractor.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/ollama_direct.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/orchestrator.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/pdf_text.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/prompts.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/scanner.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/verification.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/vision.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/input_validator.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/pain001_parser.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parallel.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/__init__.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/common.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/csv_parser.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/mt940.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/ofx.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/plugins.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/privacy.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/py.typed +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/reconciliation.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/record_types.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/transaction_deduplicator.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/transaction_models.py +0 -0
- {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/zip_security.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: bankstatementparser
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.25
|
|
4
4
|
Summary: Parse bank statements (CAMT.053, PAIN.001, MT940, OFX, BAI2, CSV, and PDF) into unified Transactions with treasury analytics, 2-way reconciliation, PDF forensics, and ledger export.
|
|
5
5
|
License: Apache-2.0 OR MIT
|
|
6
6
|
License-File: LICENSE
|
|
@@ -64,7 +64,7 @@ Description-Content-Type: text/markdown
|
|
|
64
64
|
|
|
65
65
|
<p align="center">
|
|
66
66
|
<a href="https://github.com/sebastienrousseau/bankstatementparser/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/bankstatementparser/quality-gates.yml?style=for-the-badge&logo=github" alt="Build" /></a>
|
|
67
|
-
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.
|
|
67
|
+
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.25" alt="PyPI" /></a>
|
|
68
68
|
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/dm/bankstatementparser.svg?style=for-the-badge" alt="PyPI Downloads" /></a>
|
|
69
69
|
<a href="https://codecov.io/github/sebastienrousseau/bankstatementparser?branch=main"><img src="https://img.shields.io/codecov/c/github/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="Codecov" /></a>
|
|
70
70
|
<a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
|
|
@@ -390,7 +390,7 @@ for the full surface.
|
|
|
390
390
|
|---|---|
|
|
391
391
|
| **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
|
|
392
392
|
| **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
|
|
393
|
-
| **Tested** |
|
|
393
|
+
| **Tested** | 1023 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
|
|
394
394
|
|
|
395
395
|
---
|
|
396
396
|
|
|
@@ -750,7 +750,8 @@ cleanly — see each companion's README for runnable examples.
|
|
|
750
750
|
## Project Layout
|
|
751
751
|
|
|
752
752
|
```text
|
|
753
|
-
bankstatementparser/ Source code (
|
|
753
|
+
bankstatementparser/ Source code (51 modules)
|
|
754
|
+
bankstatementparser/analytics/ Financial metrics, cash flow, cadence & anomaly detection
|
|
754
755
|
bankstatementparser/parsers/ Modular statement parsers (CSV, MT940, OFX/QFX)
|
|
755
756
|
bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
|
|
756
757
|
bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
|
|
@@ -759,7 +760,7 @@ bankstatementparser/api.py REST API microservice (FastAPI)
|
|
|
759
760
|
docs/compliance/ ISO 13485 validation, risk register, traceability matrix
|
|
760
761
|
examples/ 14 deterministic + 9 hybrid runnable example scripts
|
|
761
762
|
scripts/ SBOM generation, checksums, signature verification
|
|
762
|
-
tests/
|
|
763
|
+
tests/ 1023 tests (unit, integration, property-based, security, hybrid mocks)
|
|
763
764
|
```
|
|
764
765
|
|
|
765
766
|
---
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
|
|
20
20
|
<p align="center">
|
|
21
21
|
<a href="https://github.com/sebastienrousseau/bankstatementparser/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/bankstatementparser/quality-gates.yml?style=for-the-badge&logo=github" alt="Build" /></a>
|
|
22
|
-
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.
|
|
22
|
+
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.25" alt="PyPI" /></a>
|
|
23
23
|
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/dm/bankstatementparser.svg?style=for-the-badge" alt="PyPI Downloads" /></a>
|
|
24
24
|
<a href="https://codecov.io/github/sebastienrousseau/bankstatementparser?branch=main"><img src="https://img.shields.io/codecov/c/github/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="Codecov" /></a>
|
|
25
25
|
<a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
|
|
@@ -345,7 +345,7 @@ for the full surface.
|
|
|
345
345
|
|---|---|
|
|
346
346
|
| **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
|
|
347
347
|
| **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
|
|
348
|
-
| **Tested** |
|
|
348
|
+
| **Tested** | 1023 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
|
|
349
349
|
|
|
350
350
|
---
|
|
351
351
|
|
|
@@ -705,7 +705,8 @@ cleanly — see each companion's README for runnable examples.
|
|
|
705
705
|
## Project Layout
|
|
706
706
|
|
|
707
707
|
```text
|
|
708
|
-
bankstatementparser/ Source code (
|
|
708
|
+
bankstatementparser/ Source code (51 modules)
|
|
709
|
+
bankstatementparser/analytics/ Financial metrics, cash flow, cadence & anomaly detection
|
|
709
710
|
bankstatementparser/parsers/ Modular statement parsers (CSV, MT940, OFX/QFX)
|
|
710
711
|
bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
|
|
711
712
|
bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
|
|
@@ -714,7 +715,7 @@ bankstatementparser/api.py REST API microservice (FastAPI)
|
|
|
714
715
|
docs/compliance/ ISO 13485 validation, risk register, traceability matrix
|
|
715
716
|
examples/ 14 deterministic + 9 hybrid runnable example scripts
|
|
716
717
|
scripts/ SBOM generation, checksums, signature verification
|
|
717
|
-
tests/
|
|
718
|
+
tests/ 1023 tests (unit, integration, property-based, security, hybrid mocks)
|
|
718
719
|
```
|
|
719
720
|
|
|
720
721
|
---
|
|
@@ -71,6 +71,14 @@ from .reconciliation import (
|
|
|
71
71
|
ReconciliationStatus,
|
|
72
72
|
reconcile_payments_and_statements,
|
|
73
73
|
)
|
|
74
|
+
from .telemetry import (
|
|
75
|
+
NullSpan,
|
|
76
|
+
is_telemetry_available,
|
|
77
|
+
trace_async_stream,
|
|
78
|
+
trace_span,
|
|
79
|
+
trace_stream,
|
|
80
|
+
traced,
|
|
81
|
+
)
|
|
74
82
|
from .transaction_deduplicator import (
|
|
75
83
|
DeduplicationResult,
|
|
76
84
|
Deduplicator,
|
|
@@ -91,7 +99,7 @@ from .zip_security import (
|
|
|
91
99
|
#: so the conformance gate can compare it statically against
|
|
92
100
|
#: pyproject.toml -- that comparison is the thing that catches drift, and
|
|
93
101
|
#: a runtime lookup would make the two trivially equal and check nothing.
|
|
94
|
-
__version__ = "0.0.
|
|
102
|
+
__version__ = "0.0.25"
|
|
95
103
|
|
|
96
104
|
__all__ = [
|
|
97
105
|
"AnalyticsReport",
|
|
@@ -115,6 +123,7 @@ __all__ = [
|
|
|
115
123
|
"InputValidator",
|
|
116
124
|
"MatchGroup",
|
|
117
125
|
"Mt940Parser",
|
|
126
|
+
"NullSpan",
|
|
118
127
|
"OfxParser",
|
|
119
128
|
"Pain001ParseError",
|
|
120
129
|
"Pain001Parser",
|
|
@@ -143,6 +152,7 @@ __all__ = [
|
|
|
143
152
|
"export_parquet",
|
|
144
153
|
"export_parquet_stream",
|
|
145
154
|
"inspect_pdf_forensics",
|
|
155
|
+
"is_telemetry_available",
|
|
146
156
|
"iter_files_parallel",
|
|
147
157
|
"iter_secure_statement_entries",
|
|
148
158
|
"iter_secure_xml_entries",
|
|
@@ -151,4 +161,8 @@ __all__ = [
|
|
|
151
161
|
"reconcile_payments_and_statements",
|
|
152
162
|
"register_loader",
|
|
153
163
|
"register_writer",
|
|
164
|
+
"trace_async_stream",
|
|
165
|
+
"trace_span",
|
|
166
|
+
"trace_stream",
|
|
167
|
+
"traced",
|
|
154
168
|
]
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0 OR MIT
|
|
2
|
+
# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
|
|
3
|
+
|
|
4
|
+
"""Treasury Cash-Flow Spreading, Cadence Detection, and Anomaly Engine."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from .cash_flow import (
|
|
9
|
+
compute_average_daily_balance,
|
|
10
|
+
compute_cash_flow_summary,
|
|
11
|
+
)
|
|
12
|
+
from .common import (
|
|
13
|
+
_amount_and_direction,
|
|
14
|
+
_calendar_months,
|
|
15
|
+
_extract_amount,
|
|
16
|
+
_extract_date,
|
|
17
|
+
_get_attr,
|
|
18
|
+
)
|
|
19
|
+
from .models import (
|
|
20
|
+
AnalyticsReport,
|
|
21
|
+
AnomalyFinding,
|
|
22
|
+
CashFlowMetrics,
|
|
23
|
+
DailyBalanceMetrics,
|
|
24
|
+
RecurringCadence,
|
|
25
|
+
RecurringPattern,
|
|
26
|
+
)
|
|
27
|
+
from .patterns import (
|
|
28
|
+
analyze_statement_transactions,
|
|
29
|
+
detect_anomalies_and_nsf,
|
|
30
|
+
detect_recurring_transactions,
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
__all__ = [
|
|
34
|
+
"AnalyticsReport",
|
|
35
|
+
"AnomalyFinding",
|
|
36
|
+
"CashFlowMetrics",
|
|
37
|
+
"DailyBalanceMetrics",
|
|
38
|
+
"RecurringCadence",
|
|
39
|
+
"RecurringPattern",
|
|
40
|
+
"_amount_and_direction",
|
|
41
|
+
"_calendar_months",
|
|
42
|
+
"_extract_amount",
|
|
43
|
+
"_extract_date",
|
|
44
|
+
"_get_attr",
|
|
45
|
+
"analyze_statement_transactions",
|
|
46
|
+
"compute_average_daily_balance",
|
|
47
|
+
"compute_cash_flow_summary",
|
|
48
|
+
"detect_anomalies_and_nsf",
|
|
49
|
+
"detect_recurring_transactions",
|
|
50
|
+
]
|
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0 OR MIT
|
|
2
|
+
# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
|
|
3
|
+
|
|
4
|
+
"""Cash-flow spreading and average daily balance computation."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from calendar import monthrange
|
|
9
|
+
from collections import defaultdict
|
|
10
|
+
from collections.abc import Iterable
|
|
11
|
+
from datetime import date
|
|
12
|
+
from decimal import Decimal
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
from .._amounts import iso_decimal
|
|
16
|
+
from .common import (
|
|
17
|
+
_amount_and_direction,
|
|
18
|
+
_calendar_months,
|
|
19
|
+
_extract_date,
|
|
20
|
+
_get_attr,
|
|
21
|
+
)
|
|
22
|
+
from .models import CashFlowMetrics, DailyBalanceMetrics
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _process_daily_balance_tx(
|
|
26
|
+
tx: Any,
|
|
27
|
+
currency: str,
|
|
28
|
+
account_id: str | None,
|
|
29
|
+
period_start: date,
|
|
30
|
+
period_end: date,
|
|
31
|
+
) -> tuple[Decimal, int]:
|
|
32
|
+
"""Validate transaction account/currency/date and return signed amount with days remaining."""
|
|
33
|
+
tx_currency = str(_get_attr(tx, "currency", default="UNKNOWN")).upper()
|
|
34
|
+
raw_account = _get_attr(tx, "account_id", default=None)
|
|
35
|
+
tx_account = str(raw_account) if raw_account is not None else None
|
|
36
|
+
if tx_currency != currency or tx_account != account_id:
|
|
37
|
+
raise ValueError("Daily balance requires one account and currency")
|
|
38
|
+
booked = _extract_date(_get_attr(tx, "booking_date", "date"))
|
|
39
|
+
if booked is None or not period_start <= booked <= period_end:
|
|
40
|
+
raise ValueError("Every booking date must fall within the period")
|
|
41
|
+
amount, credit = _amount_and_direction(tx)
|
|
42
|
+
signed = abs(amount) if credit else -abs(amount)
|
|
43
|
+
days_remaining = (period_end - booked).days + 1
|
|
44
|
+
return signed, days_remaining
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def compute_average_daily_balance(
|
|
48
|
+
transactions: Iterable[Any],
|
|
49
|
+
*,
|
|
50
|
+
opening_balance: Decimal,
|
|
51
|
+
period_start: date,
|
|
52
|
+
period_end: date,
|
|
53
|
+
currency: str,
|
|
54
|
+
account_id: str | None = None,
|
|
55
|
+
) -> DailyBalanceMetrics:
|
|
56
|
+
"""Average end-of-day balances, including days without transactions.
|
|
57
|
+
|
|
58
|
+
Opening balance is the balance immediately before the first day. Each
|
|
59
|
+
booking affects that day's closing balance through the inclusive end date.
|
|
60
|
+
The caller must supply the complete period and all its posted transactions.
|
|
61
|
+
Reject mixed accounts/currencies, missing dates and out-of-period rows;
|
|
62
|
+
never infer an opening balance from incomplete transaction history.
|
|
63
|
+
Runtime is linear in rows, without allocating one balance per day.
|
|
64
|
+
"""
|
|
65
|
+
if period_end < period_start:
|
|
66
|
+
raise ValueError("period_end must not precede period_start")
|
|
67
|
+
clean_currency = currency.strip().upper()
|
|
68
|
+
if not clean_currency or clean_currency == "UNKNOWN":
|
|
69
|
+
raise ValueError("An explicit currency is required")
|
|
70
|
+
opening = iso_decimal(str(opening_balance), context="opening balance")
|
|
71
|
+
days = (period_end - period_start).days + 1
|
|
72
|
+
weighted_balance = opening * days
|
|
73
|
+
closing = opening
|
|
74
|
+
for tx in transactions:
|
|
75
|
+
signed, days_remaining = _process_daily_balance_tx(
|
|
76
|
+
tx, clean_currency, account_id, period_start, period_end
|
|
77
|
+
)
|
|
78
|
+
closing += signed
|
|
79
|
+
weighted_balance += signed * days_remaining
|
|
80
|
+
return DailyBalanceMetrics(
|
|
81
|
+
account_id,
|
|
82
|
+
clean_currency,
|
|
83
|
+
period_start,
|
|
84
|
+
period_end,
|
|
85
|
+
opening,
|
|
86
|
+
closing,
|
|
87
|
+
weighted_balance / days,
|
|
88
|
+
days,
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _validate_period(
|
|
93
|
+
period_start: date | None, period_end: date | None
|
|
94
|
+
) -> None:
|
|
95
|
+
"""Validate consistency of start and end period parameters."""
|
|
96
|
+
if (period_start is None) != (period_end is None):
|
|
97
|
+
raise ValueError("Supply both period_start and period_end")
|
|
98
|
+
if (
|
|
99
|
+
period_start is not None
|
|
100
|
+
and period_end is not None
|
|
101
|
+
and period_end < period_start
|
|
102
|
+
):
|
|
103
|
+
raise ValueError("period_end must not precede period_start")
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _calculate_run_rates(
|
|
107
|
+
dates: list[date],
|
|
108
|
+
tx_count: int,
|
|
109
|
+
total_outflow: Decimal,
|
|
110
|
+
net_cash: Decimal,
|
|
111
|
+
period_start: date | None,
|
|
112
|
+
period_end: date | None,
|
|
113
|
+
) -> tuple[Decimal | None, Decimal | None]:
|
|
114
|
+
"""Calculate monthly burn rate and annual run rate if all dates are present."""
|
|
115
|
+
if len(dates) != tx_count:
|
|
116
|
+
return None, None
|
|
117
|
+
first, last = min(dates), max(dates)
|
|
118
|
+
start = period_start or first.replace(day=1)
|
|
119
|
+
end = period_end or last.replace(day=monthrange(last.year, last.month)[1])
|
|
120
|
+
months = _calendar_months(start, end)
|
|
121
|
+
burn_rate = total_outflow / months
|
|
122
|
+
projected_run_rate = net_cash / months * 12
|
|
123
|
+
return burn_rate, projected_run_rate
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
class _CurrencyAccumulator:
|
|
127
|
+
"""Accumulates cash flow figures and metrics for a single currency."""
|
|
128
|
+
|
|
129
|
+
def __init__(
|
|
130
|
+
self,
|
|
131
|
+
curr: str,
|
|
132
|
+
period_start: date | None,
|
|
133
|
+
period_end: date | None,
|
|
134
|
+
) -> None:
|
|
135
|
+
"""Initialize currency accumulator state."""
|
|
136
|
+
self.curr = curr
|
|
137
|
+
self.period_start = period_start
|
|
138
|
+
self.period_end = period_end
|
|
139
|
+
self.total_inflow = Decimal("0.00")
|
|
140
|
+
self.total_outflow = Decimal("0.00")
|
|
141
|
+
self.credit_count = 0
|
|
142
|
+
self.debit_count = 0
|
|
143
|
+
self.dates: list[date] = []
|
|
144
|
+
self.monthly_inflows: dict[str, Decimal] = defaultdict(
|
|
145
|
+
lambda: Decimal("0.00")
|
|
146
|
+
)
|
|
147
|
+
self.monthly_outflows: dict[str, Decimal] = defaultdict(
|
|
148
|
+
lambda: Decimal("0.00")
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
def process_tx(self, tx: Any) -> None:
|
|
152
|
+
"""Process a single transaction into currency aggregates."""
|
|
153
|
+
amt, is_credit = _amount_and_direction(tx)
|
|
154
|
+
abs_amt = abs(amt)
|
|
155
|
+
d = _extract_date(
|
|
156
|
+
_get_attr(tx, "booking_date", "value_date", "date", default=None)
|
|
157
|
+
)
|
|
158
|
+
m_key = d.strftime("%Y-%m") if d else "UNKNOWN"
|
|
159
|
+
if (
|
|
160
|
+
self.period_start is not None
|
|
161
|
+
and self.period_end is not None
|
|
162
|
+
and (d is None or not self.period_start <= d <= self.period_end)
|
|
163
|
+
):
|
|
164
|
+
raise ValueError("Every booking date must fall within the period")
|
|
165
|
+
if d is not None:
|
|
166
|
+
self.dates.append(d)
|
|
167
|
+
|
|
168
|
+
if is_credit:
|
|
169
|
+
self.total_inflow += abs_amt
|
|
170
|
+
self.credit_count += 1
|
|
171
|
+
self.monthly_inflows[m_key] += abs_amt
|
|
172
|
+
else:
|
|
173
|
+
self.total_outflow += abs_amt
|
|
174
|
+
self.debit_count += 1
|
|
175
|
+
self.monthly_outflows[m_key] += abs_amt
|
|
176
|
+
|
|
177
|
+
def build_metrics(self, tx_count: int) -> CashFlowMetrics:
|
|
178
|
+
"""Build finalized CashFlowMetrics from accumulated totals."""
|
|
179
|
+
net_cash = self.total_inflow - self.total_outflow
|
|
180
|
+
avg_in = (
|
|
181
|
+
self.total_inflow / Decimal(self.credit_count)
|
|
182
|
+
if self.credit_count > 0
|
|
183
|
+
else Decimal("0.00")
|
|
184
|
+
)
|
|
185
|
+
avg_out = (
|
|
186
|
+
self.total_outflow / Decimal(self.debit_count)
|
|
187
|
+
if self.debit_count > 0
|
|
188
|
+
else Decimal("0.00")
|
|
189
|
+
)
|
|
190
|
+
avg_amt = (
|
|
191
|
+
(self.total_inflow + self.total_outflow) / Decimal(tx_count)
|
|
192
|
+
if tx_count > 0
|
|
193
|
+
else Decimal("0.00")
|
|
194
|
+
)
|
|
195
|
+
|
|
196
|
+
burn_rate, projected_run_rate = _calculate_run_rates(
|
|
197
|
+
self.dates,
|
|
198
|
+
tx_count,
|
|
199
|
+
self.total_outflow,
|
|
200
|
+
net_cash,
|
|
201
|
+
self.period_start,
|
|
202
|
+
self.period_end,
|
|
203
|
+
)
|
|
204
|
+
|
|
205
|
+
return CashFlowMetrics(
|
|
206
|
+
currency=self.curr,
|
|
207
|
+
total_inflow=self.total_inflow,
|
|
208
|
+
total_outflow=self.total_outflow,
|
|
209
|
+
net_cash_flow=net_cash,
|
|
210
|
+
transaction_count=tx_count,
|
|
211
|
+
credit_count=self.credit_count,
|
|
212
|
+
debit_count=self.debit_count,
|
|
213
|
+
average_inflow=avg_in,
|
|
214
|
+
average_outflow=avg_out,
|
|
215
|
+
average_transaction_amount=avg_amt,
|
|
216
|
+
monthly_inflows={
|
|
217
|
+
k: str(v) for k, v in self.monthly_inflows.items()
|
|
218
|
+
},
|
|
219
|
+
monthly_outflows={
|
|
220
|
+
k: str(v) for k, v in self.monthly_outflows.items()
|
|
221
|
+
},
|
|
222
|
+
burn_rate_monthly=burn_rate,
|
|
223
|
+
projected_annual_run_rate=projected_run_rate,
|
|
224
|
+
)
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def compute_cash_flow_summary(
|
|
228
|
+
transactions: Iterable[Any],
|
|
229
|
+
*,
|
|
230
|
+
period_start: date | None = None,
|
|
231
|
+
period_end: date | None = None,
|
|
232
|
+
) -> dict[str, CashFlowMetrics]:
|
|
233
|
+
"""Calculate cash flow spreads, volume, and run rates grouped by currency."""
|
|
234
|
+
_validate_period(period_start, period_end)
|
|
235
|
+
groups: dict[str, list[Any]] = defaultdict(list)
|
|
236
|
+
for tx in transactions:
|
|
237
|
+
curr = _get_attr(tx, "currency", "curr", default="UNKNOWN")
|
|
238
|
+
groups[str(curr).upper()].append(tx)
|
|
239
|
+
|
|
240
|
+
results: dict[str, CashFlowMetrics] = {}
|
|
241
|
+
for curr, txs in groups.items():
|
|
242
|
+
accumulator = _CurrencyAccumulator(curr, period_start, period_end)
|
|
243
|
+
for tx in txs:
|
|
244
|
+
accumulator.process_tx(tx)
|
|
245
|
+
results[curr] = accumulator.build_metrics(len(txs))
|
|
246
|
+
|
|
247
|
+
return results
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0 OR MIT
|
|
2
|
+
# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
|
|
3
|
+
|
|
4
|
+
"""Common extraction and attribute resolution utilities for analytics."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from calendar import monthrange
|
|
9
|
+
from datetime import date, datetime
|
|
10
|
+
from decimal import Decimal
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
from .._amounts import iso_decimal
|
|
14
|
+
|
|
15
|
+
_ALIASES: dict[str, tuple[str, ...]] = {
|
|
16
|
+
"amount": ("Amount", "InstdAmt"),
|
|
17
|
+
"currency": ("Currency",),
|
|
18
|
+
"booking_date": ("BookgDt",),
|
|
19
|
+
"value_date": ("ValDt",),
|
|
20
|
+
"description": ("Description", "Reference", "RmtInf"),
|
|
21
|
+
"credit_debit": ("DrCr",),
|
|
22
|
+
"account_id": ("AccountId", "DbtrIBAN"),
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
_CREDIT_DIRECTIONS = frozenset(("CRDT", "CREDIT", "C", "CR"))
|
|
26
|
+
_DEBIT_DIRECTIONS = frozenset(("DBIT", "DEBIT", "D", "DR"))
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _extract_date(val: Any) -> date | None:
|
|
30
|
+
"""Parse arbitrary date object or string into a datetime.date."""
|
|
31
|
+
if isinstance(val, date) and not isinstance(val, datetime):
|
|
32
|
+
return val
|
|
33
|
+
if isinstance(val, datetime):
|
|
34
|
+
return val.date()
|
|
35
|
+
if isinstance(val, str):
|
|
36
|
+
val_clean = val.strip()[:10]
|
|
37
|
+
for fmt in ("%Y-%m-%d", "%d/%m/%Y", "%Y%m%d", "%d-%m-%Y"):
|
|
38
|
+
try:
|
|
39
|
+
return datetime.strptime(val_clean, fmt).date()
|
|
40
|
+
except ValueError:
|
|
41
|
+
continue
|
|
42
|
+
return None
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _extract_amount(val: Any) -> Decimal:
|
|
46
|
+
"""Convert amount attribute to Decimal."""
|
|
47
|
+
return iso_decimal(
|
|
48
|
+
str(val).strip().replace(",", ".").replace(" ", ""),
|
|
49
|
+
context="analytics amount",
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _get_dict_value(obj: dict[str, Any], key: str) -> Any:
|
|
54
|
+
"""Retrieve non-empty value from a dictionary by key."""
|
|
55
|
+
if key in obj and obj[key] not in (None, ""):
|
|
56
|
+
return obj[key]
|
|
57
|
+
return None
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _get_attr(obj: Any, *keys: str, default: Any = None) -> Any:
|
|
61
|
+
"""Retrieve attribute or dict key across Transaction or dict instances."""
|
|
62
|
+
expanded = [
|
|
63
|
+
alias for key in keys for alias in (key, *_ALIASES.get(key, ()))
|
|
64
|
+
]
|
|
65
|
+
for key in expanded:
|
|
66
|
+
if isinstance(obj, dict):
|
|
67
|
+
val = _get_dict_value(obj, key)
|
|
68
|
+
if val is not None:
|
|
69
|
+
return val
|
|
70
|
+
elif hasattr(obj, key):
|
|
71
|
+
val = getattr(obj, key)
|
|
72
|
+
if val is not None:
|
|
73
|
+
return val
|
|
74
|
+
return default
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _amount_and_direction(tx: Any) -> tuple[Decimal, bool]:
|
|
78
|
+
"""Resolve explicit bank direction before falling back to amount sign."""
|
|
79
|
+
amount = _extract_amount(_get_attr(tx, "amount", "amt", default=None))
|
|
80
|
+
direction = str(
|
|
81
|
+
_get_attr(tx, "credit_debit", "drcr", "type", default="")
|
|
82
|
+
).upper()
|
|
83
|
+
if direction in _CREDIT_DIRECTIONS:
|
|
84
|
+
return amount, True
|
|
85
|
+
if direction in _DEBIT_DIRECTIONS:
|
|
86
|
+
return amount, False
|
|
87
|
+
return amount, amount >= 0
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _calendar_months(start: date, end: date) -> Decimal:
|
|
91
|
+
"""Measure an inclusive period in calendar months, prorating edge months."""
|
|
92
|
+
cursor = start
|
|
93
|
+
months = Decimal(0)
|
|
94
|
+
while True:
|
|
95
|
+
last = date(
|
|
96
|
+
cursor.year, cursor.month, monthrange(cursor.year, cursor.month)[1]
|
|
97
|
+
)
|
|
98
|
+
stop = min(last, end)
|
|
99
|
+
months += Decimal((stop - cursor).days + 1) / last.day
|
|
100
|
+
if stop == end:
|
|
101
|
+
return months
|
|
102
|
+
cursor = date(
|
|
103
|
+
cursor.year + (cursor.month == 12), cursor.month % 12 + 1, 1
|
|
104
|
+
)
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0 OR MIT
|
|
2
|
+
# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
|
|
3
|
+
|
|
4
|
+
"""Data models for treasury analytics, cash flow, and anomaly detection."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from dataclasses import asdict, dataclass
|
|
9
|
+
from datetime import date
|
|
10
|
+
from decimal import Decimal
|
|
11
|
+
from enum import Enum
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class RecurringCadence(str, Enum):
|
|
16
|
+
"""Estimated repetition cadence for recurring transactions."""
|
|
17
|
+
|
|
18
|
+
DAILY = "DAILY"
|
|
19
|
+
WEEKLY = "WEEKLY"
|
|
20
|
+
BI_WEEKLY = "BI_WEEKLY"
|
|
21
|
+
MONTHLY = "MONTHLY"
|
|
22
|
+
QUARTERLY = "QUARTERLY"
|
|
23
|
+
ANNUAL = "ANNUAL"
|
|
24
|
+
IRREGULAR = "IRREGULAR"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@dataclass(frozen=True)
|
|
28
|
+
class CashFlowMetrics:
|
|
29
|
+
"""Cash flow spread metrics for a single currency or statement set."""
|
|
30
|
+
|
|
31
|
+
currency: str
|
|
32
|
+
total_inflow: Decimal
|
|
33
|
+
total_outflow: Decimal
|
|
34
|
+
net_cash_flow: Decimal
|
|
35
|
+
transaction_count: int
|
|
36
|
+
credit_count: int
|
|
37
|
+
debit_count: int
|
|
38
|
+
average_inflow: Decimal
|
|
39
|
+
average_outflow: Decimal
|
|
40
|
+
average_transaction_amount: Decimal
|
|
41
|
+
monthly_inflows: dict[str, str]
|
|
42
|
+
monthly_outflows: dict[str, str]
|
|
43
|
+
burn_rate_monthly: Decimal | None
|
|
44
|
+
projected_annual_run_rate: Decimal | None
|
|
45
|
+
|
|
46
|
+
def to_dict(self) -> dict[str, Any]:
|
|
47
|
+
"""Convert metrics to a clean serializable dictionary."""
|
|
48
|
+
data = asdict(self)
|
|
49
|
+
data["total_inflow"] = str(self.total_inflow)
|
|
50
|
+
data["total_outflow"] = str(self.total_outflow)
|
|
51
|
+
data["net_cash_flow"] = str(self.net_cash_flow)
|
|
52
|
+
data["average_inflow"] = str(self.average_inflow)
|
|
53
|
+
data["average_outflow"] = str(self.average_outflow)
|
|
54
|
+
data["average_transaction_amount"] = str(
|
|
55
|
+
self.average_transaction_amount
|
|
56
|
+
)
|
|
57
|
+
data["burn_rate_monthly"] = (
|
|
58
|
+
str(self.burn_rate_monthly)
|
|
59
|
+
if self.burn_rate_monthly is not None
|
|
60
|
+
else None
|
|
61
|
+
)
|
|
62
|
+
data["projected_annual_run_rate"] = (
|
|
63
|
+
str(self.projected_annual_run_rate)
|
|
64
|
+
if self.projected_annual_run_rate is not None
|
|
65
|
+
else None
|
|
66
|
+
)
|
|
67
|
+
return data
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@dataclass(frozen=True)
|
|
71
|
+
class DailyBalanceMetrics:
|
|
72
|
+
"""End-of-day balance average for one explicitly scoped inclusive period."""
|
|
73
|
+
|
|
74
|
+
account_id: str | None
|
|
75
|
+
currency: str
|
|
76
|
+
period_start: date
|
|
77
|
+
period_end: date
|
|
78
|
+
opening_balance: Decimal
|
|
79
|
+
closing_balance: Decimal
|
|
80
|
+
average_daily_balance: Decimal
|
|
81
|
+
day_count: int
|
|
82
|
+
|
|
83
|
+
def to_dict(self) -> dict[str, Any]:
|
|
84
|
+
"""Serialize dates and exact monetary values without float conversion."""
|
|
85
|
+
return {
|
|
86
|
+
key: str(value) if isinstance(value, (date, Decimal)) else value
|
|
87
|
+
for key, value in asdict(self).items()
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
@dataclass(frozen=True)
|
|
92
|
+
class RecurringPattern:
|
|
93
|
+
"""Detected recurring transaction pattern (e.g. payroll, subscription)."""
|
|
94
|
+
|
|
95
|
+
description: str
|
|
96
|
+
amount: Decimal
|
|
97
|
+
currency: str
|
|
98
|
+
is_income: bool
|
|
99
|
+
cadence: RecurringCadence
|
|
100
|
+
confidence: float
|
|
101
|
+
occurrence_count: int
|
|
102
|
+
transaction_dates: list[str]
|
|
103
|
+
sample_hashes: list[str]
|
|
104
|
+
account_id: str | None = None
|
|
105
|
+
|
|
106
|
+
def to_dict(self) -> dict[str, Any]:
|
|
107
|
+
"""Convert recurring pattern to dictionary."""
|
|
108
|
+
data = asdict(self)
|
|
109
|
+
data["amount"] = str(self.amount)
|
|
110
|
+
data["cadence"] = self.cadence.value
|
|
111
|
+
return data
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
@dataclass(frozen=True)
|
|
115
|
+
class AnomalyFinding:
|
|
116
|
+
"""Detected irregularity, fee spike, or NSF/overdraft transaction."""
|
|
117
|
+
|
|
118
|
+
finding_type: str
|
|
119
|
+
severity: str
|
|
120
|
+
description: str
|
|
121
|
+
amount: Decimal | None
|
|
122
|
+
currency: str | None
|
|
123
|
+
booking_date: str | None
|
|
124
|
+
transaction_hash: str | None
|
|
125
|
+
|
|
126
|
+
def to_dict(self) -> dict[str, Any]:
|
|
127
|
+
"""Convert anomaly finding to dictionary."""
|
|
128
|
+
data = asdict(self)
|
|
129
|
+
if self.amount is not None:
|
|
130
|
+
data["amount"] = str(self.amount)
|
|
131
|
+
return {k: v for k, v in data.items() if v is not None}
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
@dataclass(frozen=True)
|
|
135
|
+
class AnalyticsReport:
|
|
136
|
+
"""Comprehensive analytical summary for a batch of transactions."""
|
|
137
|
+
|
|
138
|
+
summary_by_currency: dict[str, CashFlowMetrics]
|
|
139
|
+
recurring_patterns: list[RecurringPattern]
|
|
140
|
+
anomalies: list[AnomalyFinding]
|
|
141
|
+
total_transactions_analyzed: int
|
|
142
|
+
|
|
143
|
+
def to_dict(self) -> dict[str, Any]:
|
|
144
|
+
"""Convert complete report to serializable dictionary."""
|
|
145
|
+
return {
|
|
146
|
+
"summary_by_currency": {
|
|
147
|
+
curr: m.to_dict()
|
|
148
|
+
for curr, m in self.summary_by_currency.items()
|
|
149
|
+
},
|
|
150
|
+
"recurring_patterns": [
|
|
151
|
+
p.to_dict() for p in self.recurring_patterns
|
|
152
|
+
],
|
|
153
|
+
"anomalies": [a.to_dict() for a in self.anomalies],
|
|
154
|
+
"total_transactions_analyzed": self.total_transactions_analyzed,
|
|
155
|
+
}
|