debt_optimizer.core.debt_optimizer module

Module documentation for debt_optimizer.py.

This module is part of the Financial Debt Optimizer project.

class debt_optimizer.core.debt_optimizer.OptimizationGoal(value)

Bases: Enum

Available optimization goals.

MINIMIZE_INTEREST = 'minimize_interest'

MINIMIZE_TIME = 'minimize_time'

MAXIMIZE_CASHFLOW = 'maximize_cashflow'

class debt_optimizer.core.debt_optimizer.PaymentStrategy(value)

Bases: Enum

Available payment strategies.

AVALANCHE = 'debt_avalanche'

SNOWBALL = 'debt_snowball'

HYBRID = 'hybrid'

CUSTOM = 'custom'

class debt_optimizer.core.debt_optimizer.DecisionLogEntry(timestamp, month, decision_type, description, rationale, impact, data_snapshot)

Bases: object

Individual decision log entry tracking priority changes and rationale.

Parameters:

• timestamp (datetime)

• month (int)

• decision_type (str)

• description (str)

• rationale (str)

• impact (str)

• data_snapshot (Dict[str, Any])

timestamp: datetime

month: int

decision_type: str

description: str

rationale: str

impact: str

data_snapshot: Dict[str, Any]

__init__(timestamp, month, decision_type, description, rationale, impact, data_snapshot)

Parameters:

• timestamp (datetime)

• month (int)

• decision_type (str)

• description (str)

• rationale (str)

• impact (str)

• data_snapshot (Dict[str, Any])

Return type:

None

class debt_optimizer.core.debt_optimizer.MonthlyExtraFunds(month, date, total_income, required_minimums, recurring_expenses, available_extra, allocated_extra, remaining_extra, allocation_decisions)

Bases: object

Track extra funds available and their allocation for each month.

Parameters:

• month (int)

• date (date)

• total_income (float)

• required_minimums (float)

• recurring_expenses (float)

• available_extra (float)

• allocated_extra (float)

• remaining_extra (float)

• allocation_decisions (List[Dict[str, Any]])

month: int

date: date

total_income: float

required_minimums: float

recurring_expenses: float

available_extra: float

allocated_extra: float

remaining_extra: float

allocation_decisions: List[Dict[str, Any]]

__init__(month, date, total_income, required_minimums, recurring_expenses, available_extra, allocated_extra, remaining_extra, allocation_decisions)

Parameters:

• month (int)

• date (date)

• total_income (float)

• required_minimums (float)

• recurring_expenses (float)

• available_extra (float)

• allocated_extra (float)

• remaining_extra (float)

• allocation_decisions (List[Dict[str, Any]])

Return type:

None

class debt_optimizer.core.debt_optimizer.OptimizationResult(strategy, goal, total_interest_paid, total_months_to_freedom, monthly_cash_flow_improvement, payment_schedule, monthly_summary, debt_progression, savings_vs_minimum, decision_log, monthly_extra_funds)

Bases: object

Results from debt optimization analysis.

Parameters:

• strategy (str)

• goal (str)

• total_interest_paid (float)

• total_months_to_freedom (int)

• monthly_cash_flow_improvement (float)

• payment_schedule (pandas.DataFrame)

• monthly_summary (pandas.DataFrame)

• debt_progression (pandas.DataFrame)

• savings_vs_minimum (Dict[str, float])

• decision_log (List[DecisionLogEntry])

• monthly_extra_funds (List[MonthlyExtraFunds])

strategy: str

goal: str

total_interest_paid: float

total_months_to_freedom: int

monthly_cash_flow_improvement: float

payment_schedule: DataFrame

monthly_summary: DataFrame

debt_progression: DataFrame

savings_vs_minimum: Dict[str, float]

decision_log: List[DecisionLogEntry]

monthly_extra_funds: List[MonthlyExtraFunds]

__init__(strategy, goal, total_interest_paid, total_months_to_freedom, monthly_cash_flow_improvement, payment_schedule, monthly_summary, debt_progression, savings_vs_minimum, decision_log, monthly_extra_funds)

Parameters:

• strategy (str)

• goal (str)

• total_interest_paid (float)

• total_months_to_freedom (int)

• monthly_cash_flow_improvement (float)

• payment_schedule (pandas.DataFrame)

• monthly_summary (pandas.DataFrame)

• debt_progression (pandas.DataFrame)

• savings_vs_minimum (Dict[str, float])

• decision_log (List[DecisionLogEntry])

• monthly_extra_funds (List[MonthlyExtraFunds])

Return type:

None

class debt_optimizer.core.debt_optimizer.DebtPaymentPlan(debt_name, current_balance, monthly_payment, months_to_payoff, total_interest, payoff_order)

Bases: object

Individual debt payment plan.

Parameters:

• debt_name (str)

• current_balance (float)

• monthly_payment (float)

• months_to_payoff (int)

• total_interest (float)

• payoff_order (int)

debt_name: str

current_balance: float

monthly_payment: float

months_to_payoff: int

total_interest: float

payoff_order: int

__init__(debt_name, current_balance, monthly_payment, months_to_payoff, total_interest, payoff_order)

Parameters:

• debt_name (str)

• current_balance (float)

• monthly_payment (float)

• months_to_payoff (int)

• total_interest (float)

• payoff_order (int)

Return type:

None

debt_optimizer.core.debt_optimizer.compute_min_payment_reserves(now, cash_on_hand, incomes, obligations)

Calculate minimum payment reserves needed to cover all obligations.

This function ensures that every minimum payment due on or before its due date is fully covered by the sum of: - Current cash on hand - Plus incomes that arrive on or before each obligation’s due date - Minus reserves already committed to obligations with earlier due dates

Parameters:

• now (date) – Current date for which to calculate reserves

• cash_on_hand (Decimal) – Current available cash (as Decimal)

• incomes (List[Dict[str, Any]]) – List of future income events, each with ‘date’ and ‘amount’ keys

• obligations (List[Dict[str, Any]]) – List of minimum payment obligations, each with ‘debt_name’, ‘due_date’, and ‘min_amount’ keys

Return type:

Tuple[Decimal, Dict[str, Decimal]]

Returns:

Tuple of (total_required_reserve, per_obligation_reserve_map) - total_required_reserve: Total amount that must be reserved - per_obligation_reserve_map: Dict mapping debt_name to reserve amount

Policy:

• Incomes on the same day as the obligation due date are counted as available

• Obligations are processed in chronological order by due date

• Only the shortfall (if any) is reserved for each obligation

Example

For the November 2025 scenario: - now = 2025-11-11, cash_on_hand = 1523.75 - incomes = [{date: 2025-11-12, amount: 590}, {date: 2025-11-21, amount: 1492.37}] - obligations = [{debt_name: “Prime Visa”, due_date: 2025-11-19, min_amount: 805}] - Result: total_reserve = 215.00 (805 - 590), per_obligation = {“Prime Visa”: 215}

class debt_optimizer.core.debt_optimizer.DebtOptimizer(debts, income_sources, recurring_expenses=None, future_income=None, future_expenses=None, settings=None)

Bases: object

Main debt optimization engine.

Parameters:

• debts (List[Debt])

• income_sources (List[Income])

• recurring_expenses (List[RecurringExpense] | None)

• future_income (List[FutureIncome] | None)

• future_expenses (List | None)

• settings (Dict[str, Any] | None)

__init__(debts, income_sources, recurring_expenses=None, future_income=None, future_expenses=None, settings=None)

Initialize the debt optimizer with debts, income, expenses, and future income.

Parameters:

• debts (List[Debt])

• income_sources (List[Income])

• recurring_expenses (List[RecurringExpense] | None)

• future_income (List[FutureIncome] | None)

• future_expenses (List | None)

• settings (Dict[str, Any] | None)

calculate_available_extra_payment(additional_extra=0.0)

Calculate available extra payment amount.

Return type:

float

Parameters:

additional_extra (float)

log_decision(decision_type, description, rationale, impact, data_snapshot=None)

Log a decision for audit trail and learning purposes.

Return type:

None

Parameters:

• decision_type (str)

• description (str)

• rationale (str)

• impact (str)

• data_snapshot (Dict[str, Any] | None)

track_monthly_extra_funds(month, date_val, total_income, required_minimums, recurring_expenses, available_extra, allocated_extra, allocation_decisions)

Track extra funds and their allocation for each month.

Return type:

None

Parameters:

• month (int)

• date_val (date)

• total_income (float)

• required_minimums (float)

• recurring_expenses (float)

• available_extra (float)

• allocated_extra (float)

• allocation_decisions (List[Dict[str, Any]])

optimize_debt_strategy(goal=OptimizationGoal.MINIMIZE_INTEREST, extra_payment=0.0)

Find the optimal debt repayment strategy based on the specified goal.

Return type:

OptimizationResult

Parameters:

• goal (OptimizationGoal)

• extra_payment (float)

compare_strategies(extra_payment=0.0)

Compare all available strategies side by side.

Return type:

DataFrame

Parameters:

extra_payment (float)

generate_debt_summary()

Generate comprehensive summary of current debt situation.

Return type:

Dict[str, Any]