finforge 1.0.0__tar.gz

finforge-1.0.0/LICENSE

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

finforge-1.0.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+include setup.py
+recursive-include finforge *.py
+global-exclude __pycache__
+global-exclude *.py[cod]

finforge-1.0.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: finforge
+Version: 1.0.0
+Summary: Synthetic financial transaction data generation with persona-driven behavior simulation.
+Author: FinForge contributors
+Maintainer: FinForge maintainers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/finforge/finforge
+Project-URL: Repository, https://github.com/finforge/finforge
+Project-URL: Issues, https://github.com/finforge/finforge/issues
+Project-URL: Documentation, https://github.com/finforge/finforge#readme
+Project-URL: Changelog, https://github.com/finforge/finforge/blob/main/CHANGELOG.md
+Keywords: synthetic-data,finance,transactions,simulation,testing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: faker>=24.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-dateutil>=2.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# FinForge v1.0
+
+FinForge is a synthetic financial transaction data generation framework for developers, QA teams, and analytics engineers who need realistic transaction datasets without using production customer records.
+
+Unlike basic fake data libraries, FinForge focuses on behavioral simulation: persona-driven users, persistent financial identities, recurring cash flows, spending memory, merchant loyalty, monthly stress cycles, chronological balance updates, and deterministic reproducibility for testing and benchmarking.
+
+## Why FinForge v1.0 Is Different
+
+FinForge v1.0 simulates persistent financial lives instead of generating isolated fake rows.
+
+- Persistent user identity: each user carries a stable spending style, merchant loyalty profile, night activity score, and savings tendency.
+- Temporal financial rhythm: salaries, transfers, bills, and subscriptions follow a repeatable monthly cadence.
+- Realistic behavioral adaptation: low-balance users pull back discretionary spending, while stronger spenders show more weekend and late-night activity.
+- Reproducible synthetic data: the same seed and config produce the same dataset, which makes FinForge practical for testing and benchmarking.
+
+## Problem Statement
+
+Financial applications often need transaction histories that are:
+
+- realistic enough to exercise business logic
+- reproducible enough for automated testing
+- structured enough for analytics experiments
+- safe enough to share across teams
+
+Most generic fake data tools generate isolated rows. Real financial systems need temporally consistent histories where balances evolve over time, transactions follow plausible cadence, and spending patterns reflect customer behavior.
+
+FinForge addresses that gap.
+
+## Features
+
+- Synthetic user generation with configurable personas
+- Persona-driven transaction generation with persistent user habits
+- Persistent user identity traits such as spending style, merchant loyalty, and commute pattern
+- Chronologically ordered event simulation
+- Deterministic seed support for reproducible datasets
+- Realistic recurring events like salary, rent, and subscriptions
+- Merchant/category consistency with merchant affinity reuse
+- Weekend vs weekday spending behavior
+- Balance-aware suppression of discretionary spending
+- Spending memory and overspend suppression
+- Dedicated subscription engine with once-per-month recurrence
+- Explicit overdraft metadata and configurable negative-balance handling
+- Month-end spending compression and salary-cycle effects
+- Clustered daily transaction bursts that feel session-like
+- Spending-style frequency calibration for `minimalist`, `budget_conscious`, `lifestyle_spender`, and `impulsive_student`
+- Running balance tracking
+- Pandas DataFrame output
+- CSV export utilities
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or install dependencies manually:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Quickstart
+
+```python
+from finforge import DatasetGenerator
+
+dataset = (
+    DatasetGenerator(seed=42)
+    .with_users(100)
+    .with_persona("salaried")
+    .for_months(6)
+    .generate()
+)
+
+print(dataset.head())
+```
+
+Export to CSV:
+
+```python
+from finforge import DatasetGenerator
+
+generator = (
+    DatasetGenerator(seed=42)
+    .with_users(25)
+    .with_persona("student")
+    .for_months(3)
+)
+
+dataset = generator.generate()
+generator.export_csv("student_transactions.csv")
+```
+
+The public API remains fluent and backward-compatible:
+
+```python
+from finforge import DatasetGenerator
+
+dataset = (
+    DatasetGenerator(seed=101)
+    .with_users(3)
+    .with_persona("student")
+    .for_months(2)
+    .generate()
+)
+
+dataset.to_csv("transactionsBehaviour.csv", index=False)
+```
+
+Overdraft controls are configurable without changing the public API shape:
+
+```python
+dataset = (
+    DatasetGenerator(seed=7)
+    .with_users(10)
+    .with_persona("student")
+    .for_months(2)
+    .prevent_negative_balance(True)
+    .with_overdraft(0.0)
+    .generate()
+)
+```
+
+## Architecture Overview
+
+FinForge is organized into small, composable modules:
+
+- `finforge.core`: shared models, enums, constants, and configuration
+- `finforge.personas`: persona definitions and behavioral profiles
+- `finforge.generators`: user generation, scheduling, and transaction generation
+- `finforge.merchants`: category-safe merchant catalog
+- `finforge.utils`: randomness, dates, and balance helpers
+- `finforge.exporters`: output adapters such as CSV
+- `finforge.dataset`: fluent public API surface
+
+The v1.0 architecture keeps future local-model extensions possible while keeping all LLM-related functionality out of the runtime path for now.
+
+Behavioral simulation components live under `finforge.behavior`:
+
+- `identity.py`: long-lived user behavioral identities
+- `merchant_affinity.py`: persistent merchant preferences and reuse weights
+- `adaptive_spending.py`: liquidity and overspend-aware daily spending controls
+- `subscriptions.py`: dedicated subscription assignment and stable monthly pricing
+- `overdraft.py`: explicit negative-balance policy decisions
+- `budgeting.py`: rolling budget memory and spending pressure
+- `lifecycle.py`: monthly cashflow rhythm and student irregular inflows
+- `sessions.py`: grouped temporal spending sessions
+
+## Example Output
+
+Example generated schema:
+
+| transaction_id | user_id | timestamp | merchant | category | amount | spending_style | is_subscription | recurrence_type | balance_state | session_id |
+| --- | --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- |
+| txn_000001 | user_000001 | 2026-01-01 09:14:00 | Acme Payroll | income | 5840.00 | budget_conscious | False | income | normal |  |
+| txn_000002 | user_000001 | 2026-01-03 10:05:00 | Green Residency | housing | -1450.00 | budget_conscious | False | bill | normal |  |
+| txn_000003 | user_000001 | 2026-01-05 20:11:00 | Netflix | subscription | -649.00 | budget_conscious | True | subscription | normal |  |
+
+Typical generated behavior now includes:
+
+- recurring salary and bill cadence near the beginning of each month
+- subscriptions generated only by the recurring engine, never by random entertainment spending
+- exactly one subscription row per assigned merchant per simulated month
+- repeated use of a user’s preferred merchants
+- persistent user styles such as `budget_conscious`, `lifestyle_spender`, and `impulsive_student`
+- stronger commute and coffee activity on weekdays
+- more entertainment and food delivery on weekends
+- student late-night activity and irregular top-up inflows
+- smaller discretionary tickets when balances run low
+- behavioral pullback after recent overspending
+- overdrafts either prevented or explicitly marked with `is_overdraft` and `overdraft_amount`
+- clustered bursts such as `Uber -> Coffee -> Lunch`
+
+## Metadata Columns
+
+Generated transaction rows include behavioral metadata that is useful for testing and downstream modeling:
+
+- `persona`
+- `spending_style`
+- `savings_tendency`
+- `merchant_loyalty`
+- `impulse_buying_score`
+- `lifestyle_score`
+- `night_activity_score`
+- `is_recurring`
+- `is_subscription`
+- `is_discretionary`
+- `recurrence_type`
+- `session_id`
+- `day_type`
+- `balance_state`
+- `is_overdraft`
+- `overdraft_amount`
+
+## Testing Guarantees
+
+The v1.0 test suite verifies:
+
+- balance integrity on every row
+- chronological ordering per user
+- seed reproducibility
+- subscription recurrence and amount stability
+- low-balance discretionary suppression
+- reasonable session-linked rates
+- merchant-category consistency
+- required behavioral metadata columns
+- explicit overdraft marking whenever balances go negative
+
+## Roadmap
+
+- Additional personas for freelancers, retirees, and small business owners
+- More nuanced cash flow events and seasonal behavior
+- Local Ollama-backed narrative and explanation modules
+- Richer export formats and scenario presets
+- Extended validation and benchmarking datasets
+
+## Contributing
+
+Contributions are welcome. Good first contributions include:
+
+- new persona modules
+- expanded merchant catalogs
+- improved temporal rules
+- additional exporters
+- stronger test coverage
+
+To contribute:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for behavior changes
+4. Run `pytest`
+5. Open a pull request with a clear description of the use case
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

finforge-1.0.0/README.md

@@ -0,0 +1,244 @@
+# FinForge v1.0
+
+FinForge is a synthetic financial transaction data generation framework for developers, QA teams, and analytics engineers who need realistic transaction datasets without using production customer records.
+
+Unlike basic fake data libraries, FinForge focuses on behavioral simulation: persona-driven users, persistent financial identities, recurring cash flows, spending memory, merchant loyalty, monthly stress cycles, chronological balance updates, and deterministic reproducibility for testing and benchmarking.
+
+## Why FinForge v1.0 Is Different
+
+FinForge v1.0 simulates persistent financial lives instead of generating isolated fake rows.
+
+- Persistent user identity: each user carries a stable spending style, merchant loyalty profile, night activity score, and savings tendency.
+- Temporal financial rhythm: salaries, transfers, bills, and subscriptions follow a repeatable monthly cadence.
+- Realistic behavioral adaptation: low-balance users pull back discretionary spending, while stronger spenders show more weekend and late-night activity.
+- Reproducible synthetic data: the same seed and config produce the same dataset, which makes FinForge practical for testing and benchmarking.
+
+## Problem Statement
+
+Financial applications often need transaction histories that are:
+
+- realistic enough to exercise business logic
+- reproducible enough for automated testing
+- structured enough for analytics experiments
+- safe enough to share across teams
+
+Most generic fake data tools generate isolated rows. Real financial systems need temporally consistent histories where balances evolve over time, transactions follow plausible cadence, and spending patterns reflect customer behavior.
+
+FinForge addresses that gap.
+
+## Features
+
+- Synthetic user generation with configurable personas
+- Persona-driven transaction generation with persistent user habits
+- Persistent user identity traits such as spending style, merchant loyalty, and commute pattern
+- Chronologically ordered event simulation
+- Deterministic seed support for reproducible datasets
+- Realistic recurring events like salary, rent, and subscriptions
+- Merchant/category consistency with merchant affinity reuse
+- Weekend vs weekday spending behavior
+- Balance-aware suppression of discretionary spending
+- Spending memory and overspend suppression
+- Dedicated subscription engine with once-per-month recurrence
+- Explicit overdraft metadata and configurable negative-balance handling
+- Month-end spending compression and salary-cycle effects
+- Clustered daily transaction bursts that feel session-like
+- Spending-style frequency calibration for `minimalist`, `budget_conscious`, `lifestyle_spender`, and `impulsive_student`
+- Running balance tracking
+- Pandas DataFrame output
+- CSV export utilities
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or install dependencies manually:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Quickstart
+
+```python
+from finforge import DatasetGenerator
+
+dataset = (
+    DatasetGenerator(seed=42)
+    .with_users(100)
+    .with_persona("salaried")
+    .for_months(6)
+    .generate()
+)
+
+print(dataset.head())
+```
+
+Export to CSV:
+
+```python
+from finforge import DatasetGenerator
+
+generator = (
+    DatasetGenerator(seed=42)
+    .with_users(25)
+    .with_persona("student")
+    .for_months(3)
+)
+
+dataset = generator.generate()
+generator.export_csv("student_transactions.csv")
+```
+
+The public API remains fluent and backward-compatible:
+
+```python
+from finforge import DatasetGenerator
+
+dataset = (
+    DatasetGenerator(seed=101)
+    .with_users(3)
+    .with_persona("student")
+    .for_months(2)
+    .generate()
+)
+
+dataset.to_csv("transactionsBehaviour.csv", index=False)
+```
+
+Overdraft controls are configurable without changing the public API shape:
+
+```python
+dataset = (
+    DatasetGenerator(seed=7)
+    .with_users(10)
+    .with_persona("student")
+    .for_months(2)
+    .prevent_negative_balance(True)
+    .with_overdraft(0.0)
+    .generate()
+)
+```
+
+## Architecture Overview
+
+FinForge is organized into small, composable modules:
+
+- `finforge.core`: shared models, enums, constants, and configuration
+- `finforge.personas`: persona definitions and behavioral profiles
+- `finforge.generators`: user generation, scheduling, and transaction generation
+- `finforge.merchants`: category-safe merchant catalog
+- `finforge.utils`: randomness, dates, and balance helpers
+- `finforge.exporters`: output adapters such as CSV
+- `finforge.dataset`: fluent public API surface
+
+The v1.0 architecture keeps future local-model extensions possible while keeping all LLM-related functionality out of the runtime path for now.
+
+Behavioral simulation components live under `finforge.behavior`:
+
+- `identity.py`: long-lived user behavioral identities
+- `merchant_affinity.py`: persistent merchant preferences and reuse weights
+- `adaptive_spending.py`: liquidity and overspend-aware daily spending controls
+- `subscriptions.py`: dedicated subscription assignment and stable monthly pricing
+- `overdraft.py`: explicit negative-balance policy decisions
+- `budgeting.py`: rolling budget memory and spending pressure
+- `lifecycle.py`: monthly cashflow rhythm and student irregular inflows
+- `sessions.py`: grouped temporal spending sessions
+
+## Example Output
+
+Example generated schema:
+
+| transaction_id | user_id | timestamp | merchant | category | amount | spending_style | is_subscription | recurrence_type | balance_state | session_id |
+| --- | --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- |
+| txn_000001 | user_000001 | 2026-01-01 09:14:00 | Acme Payroll | income | 5840.00 | budget_conscious | False | income | normal |  |
+| txn_000002 | user_000001 | 2026-01-03 10:05:00 | Green Residency | housing | -1450.00 | budget_conscious | False | bill | normal |  |
+| txn_000003 | user_000001 | 2026-01-05 20:11:00 | Netflix | subscription | -649.00 | budget_conscious | True | subscription | normal |  |
+
+Typical generated behavior now includes:
+
+- recurring salary and bill cadence near the beginning of each month
+- subscriptions generated only by the recurring engine, never by random entertainment spending
+- exactly one subscription row per assigned merchant per simulated month
+- repeated use of a user’s preferred merchants
+- persistent user styles such as `budget_conscious`, `lifestyle_spender`, and `impulsive_student`
+- stronger commute and coffee activity on weekdays
+- more entertainment and food delivery on weekends
+- student late-night activity and irregular top-up inflows
+- smaller discretionary tickets when balances run low
+- behavioral pullback after recent overspending
+- overdrafts either prevented or explicitly marked with `is_overdraft` and `overdraft_amount`
+- clustered bursts such as `Uber -> Coffee -> Lunch`
+
+## Metadata Columns
+
+Generated transaction rows include behavioral metadata that is useful for testing and downstream modeling:
+
+- `persona`
+- `spending_style`
+- `savings_tendency`
+- `merchant_loyalty`
+- `impulse_buying_score`
+- `lifestyle_score`
+- `night_activity_score`
+- `is_recurring`
+- `is_subscription`
+- `is_discretionary`
+- `recurrence_type`
+- `session_id`
+- `day_type`
+- `balance_state`
+- `is_overdraft`
+- `overdraft_amount`
+
+## Testing Guarantees
+
+The v1.0 test suite verifies:
+
+- balance integrity on every row
+- chronological ordering per user
+- seed reproducibility
+- subscription recurrence and amount stability
+- low-balance discretionary suppression
+- reasonable session-linked rates
+- merchant-category consistency
+- required behavioral metadata columns
+- explicit overdraft marking whenever balances go negative
+
+## Roadmap
+
+- Additional personas for freelancers, retirees, and small business owners
+- More nuanced cash flow events and seasonal behavior
+- Local Ollama-backed narrative and explanation modules
+- Richer export formats and scenario presets
+- Extended validation and benchmarking datasets
+
+## Contributing
+
+Contributions are welcome. Good first contributions include:
+
+- new persona modules
+- expanded merchant catalogs
+- improved temporal rules
+- additional exporters
+- stronger test coverage
+
+To contribute:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for behavior changes
+4. Run `pytest`
+5. Open a pull request with a clear description of the use case
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

finforge-1.0.0/finforge/__init__.py

@@ -0,0 +1,5 @@
+"""Public package exports for FinForge."""
+
+from finforge.dataset import DatasetGenerator
+
+__all__ = ["DatasetGenerator"]

finforge-1.0.0/finforge/behavior/__init__.py

@@ -0,0 +1 @@
+"""Behavioral simulation components for FinForge."""

finforge-1.0.0/finforge/behavior/adaptive_spending.py

@@ -0,0 +1,129 @@
+"""Adaptive spending adjustments based on balance, budget, and lifecycle."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from finforge.behavior.budgeting import BudgetingEngine, UserBudgetState
+from finforge.core.models import User
+from finforge.personas.base import SpendingProfile
+
+
+@dataclass(frozen=True)
+class AdaptiveSpendingSignal:
+    """Per-day spending signal derived from balance and memory."""
+
+    state: str
+    frequency_multiplier: float
+    amount_multiplier: float
+    category_multipliers: dict[str, float]
+    amount_multipliers: dict[str, float]
+    overspend_pressure: float
+    lifecycle_phase: str
+    max_discretionary_transactions: int | None
+
+
+class AdaptiveSpendingEngine:
+    """Combines balance, month phase, and recent spend memory."""
+
+    def __init__(self, budgeting_engine: BudgetingEngine) -> None:
+        self.budgeting_engine = budgeting_engine
+
+    def assess(
+        self,
+        user: User,
+        state: UserBudgetState,
+        day_of_month: int,
+        days_in_month: int,
+        spending_profile: SpendingProfile,
+    ) -> AdaptiveSpendingSignal:
+        """Compute day-level adaptive spending controls."""
+        phase = self._phase(day_of_month, days_in_month)
+        overspend = self.budgeting_engine.overspend_pressure(state)
+        low_threshold, high_threshold = self._thresholds(user)
+        category_multipliers = {category: 1.0 for category in user.category_affinities}
+        amount_multipliers = {category: 1.0 for category in user.category_affinities}
+
+        for category, affinity in user.category_affinities.items():
+            category_multipliers[category] *= affinity
+
+        if phase == "early":
+            category_multipliers["shopping"] = category_multipliers.get("shopping", 1.0) * (1.05 + user.impulse_buying_score * 0.18)
+            category_multipliers["entertainment"] = category_multipliers.get("entertainment", 1.0) * (1.03 + user.entertainment_preference * 0.15)
+        elif phase == "late":
+            for category, multiplier in spending_profile.month_end_category_multipliers.items():
+                category_multipliers[category] = category_multipliers.get(category, 1.0) * multiplier
+
+        if state.balance <= low_threshold:
+            low_balance_multipliers = {
+                "entertainment": 0.10,
+                "shopping": 0.15,
+                "food": 0.40,
+                "coffee": 0.50,
+                "travel": 0.80,
+                "groceries": 1.20,
+            }
+            low_balance_amount_multipliers = {
+                "entertainment": 0.50,
+                "shopping": 0.50,
+                "food": 0.65,
+                "coffee": 0.75,
+                "travel": 0.90,
+                "groceries": 1.00,
+            }
+            for category, multiplier in low_balance_multipliers.items():
+                category_multipliers[category] = category_multipliers.get(category, 1.0) * multiplier
+            for category, multiplier in low_balance_amount_multipliers.items():
+                amount_multipliers[category] = amount_multipliers.get(category, 1.0) * multiplier
+            signal_state = "low"
+            frequency_multiplier = 0.26 if user.persona.value == "student" else 0.34
+            amount_multiplier = 0.46
+            max_discretionary_transactions = 1 if user.persona.value == "student" else 2
+        elif state.balance >= high_threshold:
+            for category, multiplier in spending_profile.high_balance_category_multipliers.items():
+                category_multipliers[category] = category_multipliers.get(category, 1.0) * multiplier
+            signal_state = "high"
+            frequency_multiplier = 1.10
+            amount_multiplier = 1.08
+            max_discretionary_transactions = None
+        else:
+            signal_state = "normal"
+            frequency_multiplier = 1.0
+            amount_multiplier = 1.0
+            max_discretionary_transactions = None
+
+        if overspend > 1.0:
+            pressure_discount = min((overspend - 1.0) * 0.35, 0.4)
+            frequency_multiplier *= 1.0 - pressure_discount
+            amount_multiplier *= 1.0 - pressure_discount * 0.8
+            category_multipliers["shopping"] = category_multipliers.get("shopping", 1.0) * 0.45
+            category_multipliers["entertainment"] = category_multipliers.get("entertainment", 1.0) * 0.55
+            category_multipliers["food"] = category_multipliers.get("food", 1.0) * 0.78
+            amount_multipliers["shopping"] = amount_multipliers.get("shopping", 1.0) * 0.7
+            amount_multipliers["entertainment"] = amount_multipliers.get("entertainment", 1.0) * 0.75
+            amount_multipliers["food"] = amount_multipliers.get("food", 1.0) * 0.85
+
+        return AdaptiveSpendingSignal(
+            state=signal_state,
+            frequency_multiplier=round(frequency_multiplier, 3),
+            amount_multiplier=round(amount_multiplier, 3),
+            category_multipliers={key: round(value, 3) for key, value in category_multipliers.items()},
+            amount_multipliers={key: round(value, 3) for key, value in amount_multipliers.items()},
+            overspend_pressure=round(overspend, 3),
+            lifecycle_phase=phase,
+            max_discretionary_transactions=max_discretionary_transactions,
+        )
+
+    def _phase(self, day_of_month: int, days_in_month: int) -> str:
+        """Map a day in month into a lifecycle phase."""
+        if day_of_month <= 7:
+            return "early"
+        if day_of_month >= max(days_in_month - 5, 25):
+            return "late"
+        return "mid"
+
+    def _thresholds(self, user: User) -> tuple[float, float]:
+        """Return persona-level low and high balance thresholds."""
+        if user.persona.value == "student":
+            return 500.0, 5000.0
+        return 5000.0, 50000.0