financial-debt-optimizer 2.0.0

A comprehensive tool for analyzing and optimizing debt repayment strategies

Financial Debt Optimizer 2.0.0

A comprehensive Python tool for analyzing and optimizing debt repayment strategies to help you become debt-free faster while minimizing interest costs.

✨ What's New in Version 2.0

• 🔄 Quicken Integration: Directly sync balances from Quicken databases
• ⚙️ Configuration System: YAML-based config files with sensible defaults
• 🎯 Smart Balance Updates: Only updates when balances actually change
• 📊 Fixed Surplus Calculations: Accurate monthly cash flow including all expenses
• 🚀 Unified CLI: All features accessible through single command interface

Features

Core Optimization Strategies

• Debt Avalanche: Minimize total interest paid by targeting highest interest rates first
• Debt Snowball: Build momentum by paying off smallest balances first
• Hybrid Strategy: Balance psychological wins with mathematical optimization
• Custom Strategy: Define your own debt prioritization order

Advanced Financial Modeling

• Future Income Integration: Account for raises, bonuses, and additional income sources
• Recurring Expense Management: Track monthly, bi-weekly, quarterly, and annual expenses
• Extra Payment Allocation: Optimize how extra funds are distributed across debts
• Cash Flow Analysis: Monitor monthly financial health and surplus calculations
• Quicken Database Sync: Automatically update balances from Quicken SQLite databases
• Fuzzy Matching: Intelligent account name matching with configurable thresholds

Comprehensive Reporting

• Excel Integration: Generate detailed spreadsheet reports with multiple worksheets
• Visual Charts: 6+ interactive charts showing debt progression, payment breakdowns, and cash flow
• Monthly Summaries: Track income, expenses, payments, and extra funds by month
• Decision Logging: Audit trail of optimization decisions and rationale
• Strategy Comparisons: Side-by-side analysis of different repayment approaches

Professional Excel Output

• Payment Schedule: Detailed chronological payment plan
• Monthly Summary: Income, expenses, and payment tracking
• Debt Progression: Individual debt balance evolution
• Strategy Comparison: Performance metrics across different approaches
• Charts & Visualizations: Professional charts and graphs
• Decision Log: Detailed rationale for optimization choices

Installation

PyPI Installation (Recommended)

pip install financial-debt-optimizer

With Quicken Integration Support

pip install financial-debt-optimizer[balance]

Requirements

• Python 3.8 or higher
• Dependencies are automatically installed with the package
• Optional: rapidfuzz or thefuzz for balance update fuzzy matching

Install from Source

git clone https://github.com/bryankemp/financial-debt-optimizer.git
cd financial-debt-optimizer
pip install -e .

Development Installation

git clone https://github.com/bryankemp/financial-debt-optimizer.git
cd financial-debt-optimizer
pip install -e .[dev]

Quick Start

1. Create Configuration (One-time Setup)

debt-optimizer config init

This creates ~/.debt-optimizer/config.yaml with default settings. Edit it to set:

• Input/output file paths
• Quicken database location
• Optimization preferences
• Balance update settings

2. Generate an Excel Template

debt-optimizer generate-template my-debt-data.xlsx

3. Fill in Your Data

Open my-debt-data.xlsx and fill in:

• Debts: Name, balance, minimum payment, interest rate, due date
• Income: Sources, amounts, frequency (bi-weekly, monthly, etc.)
• Recurring Expenses: Monthly bills, subscriptions, etc.
• Future Income: Bonuses, raises, additional income streams
• Settings: Bank balance, optimization preferences

4. Update Balances from Quicken (Optional)

debt-optimizer update-balances --db ~/Documents/MyQuicken.quicken/data --xlsx my-debt-data.xlsx

Or update automatically during analysis with the -u flag.

5. Run Analysis

debt-optimizer analyze -u --input my-debt-data.xlsx --output debt-analysis.xlsx

The -u flag automatically updates balances from Quicken before analyzing.

6. Review Results

Open debt-analysis.xlsx to see:

• Optimized payment strategy
• Month-by-month payment schedule
• Visual charts and progress tracking
• Interest savings and time to debt freedom

Usage Examples

Configuration Management

# Create configuration file
debt-optimizer config init

# View current settings
debt-optimizer config show

# Get specific setting
debt-optimizer config get input_file

# Set value
debt-optimizer config set extra_payment 500.0

Balance Updates

# Update balances using config defaults
debt-optimizer update-balances

# Update with custom paths
debt-optimizer update-balances \
    --db ~/Documents/MyQuicken.quicken/data \
    --xlsx my-debts.xlsx \
    --threshold 85

# Skip backup creation
debt-optimizer update-balances --no-backup

Basic Analysis

# Analyze using config defaults
debt-optimizer analyze

# Analyze with balance update
debt-optimizer analyze -u

# Override config defaults
debt-optimizer analyze -i my-debts.xlsx -o results.xlsx

Advanced Analysis

# Full workflow: update balances, compare all strategies
debt-optimizer analyze -u \
    --input my-debts.xlsx \
    --output comprehensive-analysis.xlsx \
    --goal minimize_interest \
    --extra-payment 500 \
    --compare-strategies

# Generate simple one-sheet report
debt-optimizer analyze -u --simple-report

Available Goals

• minimize_interest: Pay least total interest (default)
• minimize_time: Become debt-free fastest
• maximize_cashflow: Optimize monthly cash flow

Excel Template Structure

Debts Sheet

Name	Balance	Min Payment	Interest Rate	Due Date
Credit Card 1	5000.00	150.00	18.99	15
Student Loan	25000.00	300.00	5.50	1

Income Sheet

Source	Amount	Frequency	Start Date
Salary	2500.00	bi-weekly	2024-01-01

Recurring Expenses Sheet

Description	Amount	Frequency	Due Date	Start Date
Rent	1200.00	monthly	1	2024-01-01

Future Income Sheet

Description	Amount	Start Date	Frequency	End Date
Bonus	5000.00	2024-12-15	once
Raise	200.00	2024-07-01	bi-weekly

Output Analysis

Key Metrics

• Total Interest Saved: Compared to minimum payments only
• Time to Debt Freedom: Months until all debts are paid
• Monthly Cash Flow: Available funds after payments and expenses
• Strategy Efficiency: Comparison across different approaches

Charts Included

1. Individual Debt Progression: Track each debt balance over time
2. Payment Breakdown: Principal vs interest by month
3. Total Debt Reduction: Overall debt elimination progress
4. Cash Flow Analysis: Income vs expenses vs payments
5. Debt Payoff Timeline: Order and timing of debt elimination
6. Extra Funds Utilization: Efficiency of extra payment allocation

API Usage

from src.excel_io.excel_reader import ExcelReader
from src.core.debt_optimizer import DebtOptimizer, OptimizationGoal
from src.excel_io.excel_writer import ExcelReportWriter

# Load data
reader = ExcelReader("my-debts.xlsx")
debts, income, expenses, future_income, future_expenses, settings = reader.read_all_data()

# Initialize optimizer
optimizer = DebtOptimizer(debts, income, expenses, future_income, future_expenses, settings)

# Run optimization
result = optimizer.optimize_debt_strategy(
    goal=OptimizationGoal.MINIMIZE_INTEREST,
    extra_payment=500.0
)

# Generate report
writer = ExcelReportWriter("analysis.xlsx")
debt_summary = optimizer.generate_debt_summary()
writer.create_comprehensive_report(result, debt_summary)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/bryankemp/financial-debt-optimizer.git
cd financial-debt-optimizer
pip install -e .[dev]

Running Tests

pip install -e .[test]
pytest

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Documentation

📖 Complete Documentation

• Installation Guide - Detailed installation instructions
• Quick Start - Get started in minutes
• User Guide - Comprehensive usage documentation
• Examples - Real-world use cases and scenarios
• API Reference - Complete API documentation
• FAQ - Frequently asked questions

Support

• 📖 Documentation: https://financial-debt-optimizer.readthedocs.io/
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [e-mail]

Changelog

See CHANGELOG.md for version history and changes.

Disclaimer

This tool is for educational and informational purposes only. It does not constitute financial advice. Always consult with qualified financial professionals for personalized guidance on debt management and financial planning.

---

Author: Bryan Kemp ([e-mail])
Version: 2.0.0
License: BSD 3-Clause