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.
Files changed (60) hide show
  1. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/PKG-INFO +6 -5
  2. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/README.md +5 -4
  3. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/__init__.py +15 -1
  4. bankstatementparser-0.0.25/bankstatementparser/analytics/__init__.py +50 -0
  5. bankstatementparser-0.0.25/bankstatementparser/analytics/cash_flow.py +247 -0
  6. bankstatementparser-0.0.25/bankstatementparser/analytics/common.py +104 -0
  7. bankstatementparser-0.0.25/bankstatementparser/analytics/models.py +155 -0
  8. bankstatementparser-0.0.25/bankstatementparser/analytics/patterns.py +291 -0
  9. bankstatementparser-0.0.25/bankstatementparser/api.py +263 -0
  10. bankstatementparser-0.0.25/bankstatementparser/api_limits.py +226 -0
  11. bankstatementparser-0.0.25/bankstatementparser/api_worker.py +150 -0
  12. bankstatementparser-0.0.25/bankstatementparser/telemetry.py +177 -0
  13. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/pyproject.toml +2 -2
  14. bankstatementparser-0.0.24/bankstatementparser/analytics.py +0 -691
  15. bankstatementparser-0.0.24/bankstatementparser/api.py +0 -583
  16. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/LICENSE +0 -0
  17. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/LICENSE-APACHE +0 -0
  18. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/LICENSE-MIT +0 -0
  19. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/_amounts.py +0 -0
  20. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/_llm_common.py +0 -0
  21. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/additional_parsers.py +0 -0
  22. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/bank_statement_parsers.py +0 -0
  23. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/base_parser.py +0 -0
  24. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/camt_parser.py +0 -0
  25. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/cli.py +0 -0
  26. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/__init__.py +0 -0
  27. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/account_mapper.py +0 -0
  28. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/categorizer.py +0 -0
  29. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/exceptions.py +0 -0
  30. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/export/__init__.py +0 -0
  31. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/export/ledger.py +0 -0
  32. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/export/parquet.py +0 -0
  33. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/field86_parser.py +0 -0
  34. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/forensics.py +0 -0
  35. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/__init__.py +0 -0
  36. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/evaluation.py +0 -0
  37. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/llm_extractor.py +0 -0
  38. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/ollama_direct.py +0 -0
  39. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/orchestrator.py +0 -0
  40. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/pdf_text.py +0 -0
  41. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/prompts.py +0 -0
  42. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/scanner.py +0 -0
  43. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/verification.py +0 -0
  44. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/vision.py +0 -0
  45. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/input_validator.py +0 -0
  46. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/pain001_parser.py +0 -0
  47. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parallel.py +0 -0
  48. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/__init__.py +0 -0
  49. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/common.py +0 -0
  50. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/csv_parser.py +0 -0
  51. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/mt940.py +0 -0
  52. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/parsers/ofx.py +0 -0
  53. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/plugins.py +0 -0
  54. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/privacy.py +0 -0
  55. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/py.typed +0 -0
  56. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/reconciliation.py +0 -0
  57. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/record_types.py +0 -0
  58. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/transaction_deduplicator.py +0 -0
  59. {bankstatementparser-0.0.24 → bankstatementparser-0.0.25}/bankstatementparser/transaction_models.py +0 -0
  60. {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.24
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.24" alt="PyPI" /></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.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** | 1014 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
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 (44 modules)
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/ 1014 tests (unit, integration, property-based, security, hybrid mocks)
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.24" alt="PyPI" /></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.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** | 1014 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
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 (44 modules)
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/ 1014 tests (unit, integration, property-based, security, hybrid mocks)
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.24"
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
+ }