# Financial Debt Optimizer 1.1.1
[](https://pypi.org/project/financial-debt-optimizer/)
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://www.python.org/downloads/)
[](https://financial-debt-optimizer.readthedocs.io/en/latest/?badge=latest)
A comprehensive Python tool for analyzing and optimizing debt repayment strategies to help you become debt-free faster while minimizing interest costs.
## 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
### 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)
```bash
pip install financial-debt-optimizer
```
### Requirements
- Python 3.8 or higher
- Dependencies are automatically installed with the package
### Install from Source
```bash
git clone https://github.com/bryankemp/financial-debt-optimizer.git
cd financial-debt-optimizer
pip install -e .
```
### Development Installation
```bash
git clone https://github.com/bryankemp/financial-debt-optimizer.git
cd financial-debt-optimizer
pip install -e .[dev]
```
## Quick Start
### 1. Generate an Excel Template
```bash
debt-optimizer generate-template my-debt-data.xlsx
```
### 2. 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
### 3. Run Analysis
```bash
debt-optimizer analyze --input my-debt-data.xlsx --output debt-analysis.xlsx
```
### 4. 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
### Basic Analysis
```bash
# Analyze debts with default settings (minimize interest)
debt-optimizer analyze -i my-debts.xlsx -o results.xlsx
```
### Advanced Options
```bash
# Compare all strategies with extra monthly payment
debt-optimizer analyze \
--input my-debts.xlsx \
--output comprehensive-analysis.xlsx \
--goal minimize_interest \
--extra-payment 500 \
--compare-strategies
```
### 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
```python
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](CONTRIBUTING.md) for guidelines.
### Development Setup
```bash
git clone https://github.com/bryankemp/financial-debt-optimizer.git
cd financial-debt-optimizer
pip install -e .[dev]
```
### Running Tests
```bash
pip install -e .[test]
pytest
```
## License
This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
## Documentation
📖 **[Complete Documentation](https://financial-debt-optimizer.readthedocs.io/)**
- **[Installation Guide](https://financial-debt-optimizer.readthedocs.io/en/latest/installation.html)** - Detailed installation instructions
- **[Quick Start](https://financial-debt-optimizer.readthedocs.io/en/latest/quickstart.html)** - Get started in minutes
- **[User Guide](https://financial-debt-optimizer.readthedocs.io/en/latest/user_guide.html)** - Comprehensive usage documentation
- **[Examples](https://financial-debt-optimizer.readthedocs.io/en/latest/examples.html)** - Real-world use cases and scenarios
- **[API Reference](https://financial-debt-optimizer.readthedocs.io/en/latest/modules.html)** - Complete API documentation
- **[FAQ](https://financial-debt-optimizer.readthedocs.io/en/latest/faq.html)** - Frequently asked questions
## Support
- **📖 Documentation**: [https://financial-debt-optimizer.readthedocs.io/](https://financial-debt-optimizer.readthedocs.io/)
- **🐛 Issues**: [GitHub Issues](https://github.com/bryankemp/financial-debt-optimizer/issues)
- **💬 Discussions**: [GitHub Discussions](https://github.com/bryankemp/financial-debt-optimizer/discussions)
- **📧 Email**: bryan@kempville.com
## Changelog
See [CHANGELOG.md](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 (bryan@kempville.com)
**Version**: 1.0.0
**License**: BSD 3-Clause
Raw data
{
"_id": null,
"home_page": "https://github.com/bryankemp/financial-debt-optimizer",
"name": "financial-debt-optimizer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "debt optimization finance calculator repayment strategy",
"author": "Bryan Kemp",
"author_email": "bryan@kempville.com",
"download_url": "https://files.pythonhosted.org/packages/c3/f6/84c66a20ab1f097609ba327939a648012d478f998597592dcfd5c3cbae9e/financial_debt_optimizer-1.1.1.tar.gz",
"platform": null,
"description": "# Financial Debt Optimizer 1.1.1\n\n[](https://pypi.org/project/financial-debt-optimizer/)\n[](https://opensource.org/licenses/BSD-3-Clause)\n[](https://www.python.org/downloads/)\n[](https://financial-debt-optimizer.readthedocs.io/en/latest/?badge=latest)\n\nA comprehensive Python tool for analyzing and optimizing debt repayment strategies to help you become debt-free faster while minimizing interest costs.\n\n## Features\n\n### Core Optimization Strategies\n- **Debt Avalanche**: Minimize total interest paid by targeting highest interest rates first\n- **Debt Snowball**: Build momentum by paying off smallest balances first\n- **Hybrid Strategy**: Balance psychological wins with mathematical optimization\n- **Custom Strategy**: Define your own debt prioritization order\n\n### Advanced Financial Modeling\n- **Future Income Integration**: Account for raises, bonuses, and additional income sources\n- **Recurring Expense Management**: Track monthly, bi-weekly, quarterly, and annual expenses\n- **Extra Payment Allocation**: Optimize how extra funds are distributed across debts\n- **Cash Flow Analysis**: Monitor monthly financial health and surplus calculations\n\n### Comprehensive Reporting\n- **Excel Integration**: Generate detailed spreadsheet reports with multiple worksheets\n- **Visual Charts**: 6+ interactive charts showing debt progression, payment breakdowns, and cash flow\n- **Monthly Summaries**: Track income, expenses, payments, and extra funds by month\n- **Decision Logging**: Audit trail of optimization decisions and rationale\n- **Strategy Comparisons**: Side-by-side analysis of different repayment approaches\n\n### Professional Excel Output\n- **Payment Schedule**: Detailed chronological payment plan\n- **Monthly Summary**: Income, expenses, and payment tracking\n- **Debt Progression**: Individual debt balance evolution\n- **Strategy Comparison**: Performance metrics across different approaches\n- **Charts & Visualizations**: Professional charts and graphs\n- **Decision Log**: Detailed rationale for optimization choices\n\n## Installation\n\n### PyPI Installation (Recommended)\n```bash\npip install financial-debt-optimizer\n```\n\n### Requirements\n- Python 3.8 or higher\n- Dependencies are automatically installed with the package\n\n### Install from Source\n```bash\ngit clone https://github.com/bryankemp/financial-debt-optimizer.git\ncd financial-debt-optimizer\npip install -e .\n```\n\n### Development Installation\n```bash\ngit clone https://github.com/bryankemp/financial-debt-optimizer.git\ncd financial-debt-optimizer\npip install -e .[dev]\n```\n\n## Quick Start\n\n### 1. Generate an Excel Template\n```bash\ndebt-optimizer generate-template my-debt-data.xlsx\n```\n\n### 2. Fill in Your Data\nOpen `my-debt-data.xlsx` and fill in:\n- **Debts**: Name, balance, minimum payment, interest rate, due date\n- **Income**: Sources, amounts, frequency (bi-weekly, monthly, etc.)\n- **Recurring Expenses**: Monthly bills, subscriptions, etc.\n- **Future Income**: Bonuses, raises, additional income streams\n- **Settings**: Bank balance, optimization preferences\n\n### 3. Run Analysis\n```bash\ndebt-optimizer analyze --input my-debt-data.xlsx --output debt-analysis.xlsx\n```\n\n### 4. Review Results\nOpen `debt-analysis.xlsx` to see:\n- Optimized payment strategy\n- Month-by-month payment schedule\n- Visual charts and progress tracking\n- Interest savings and time to debt freedom\n\n## Usage Examples\n\n### Basic Analysis\n```bash\n# Analyze debts with default settings (minimize interest)\ndebt-optimizer analyze -i my-debts.xlsx -o results.xlsx\n```\n\n### Advanced Options\n```bash\n# Compare all strategies with extra monthly payment\ndebt-optimizer analyze \\\n --input my-debts.xlsx \\\n --output comprehensive-analysis.xlsx \\\n --goal minimize_interest \\\n --extra-payment 500 \\\n --compare-strategies\n```\n\n### Available Goals\n- `minimize_interest`: Pay least total interest (default)\n- `minimize_time`: Become debt-free fastest\n- `maximize_cashflow`: Optimize monthly cash flow\n\n## Excel Template Structure\n\n### Debts Sheet\n| Name | Balance | Min Payment | Interest Rate | Due Date |\n|------|---------|-------------|---------------|----------|\n| Credit Card 1 | 5000.00 | 150.00 | 18.99 | 15 |\n| Student Loan | 25000.00 | 300.00 | 5.50 | 1 |\n\n### Income Sheet\n| Source | Amount | Frequency | Start Date |\n|--------|--------|-----------|------------|\n| Salary | 2500.00 | bi-weekly | 2024-01-01 |\n\n### Recurring Expenses Sheet\n| Description | Amount | Frequency | Due Date | Start Date |\n|-------------|--------|-----------|----------|------------|\n| Rent | 1200.00 | monthly | 1 | 2024-01-01 |\n\n### Future Income Sheet\n| Description | Amount | Start Date | Frequency | End Date |\n|-------------|--------|------------|-----------|----------|\n| Bonus | 5000.00 | 2024-12-15 | once | |\n| Raise | 200.00 | 2024-07-01 | bi-weekly | |\n\n## Output Analysis\n\n### Key Metrics\n- **Total Interest Saved**: Compared to minimum payments only\n- **Time to Debt Freedom**: Months until all debts are paid\n- **Monthly Cash Flow**: Available funds after payments and expenses\n- **Strategy Efficiency**: Comparison across different approaches\n\n### Charts Included\n1. **Individual Debt Progression**: Track each debt balance over time\n2. **Payment Breakdown**: Principal vs interest by month\n3. **Total Debt Reduction**: Overall debt elimination progress\n4. **Cash Flow Analysis**: Income vs expenses vs payments\n5. **Debt Payoff Timeline**: Order and timing of debt elimination\n6. **Extra Funds Utilization**: Efficiency of extra payment allocation\n\n## API Usage\n\n```python\nfrom src.excel_io.excel_reader import ExcelReader\nfrom src.core.debt_optimizer import DebtOptimizer, OptimizationGoal\nfrom src.excel_io.excel_writer import ExcelReportWriter\n\n# Load data\nreader = ExcelReader(\"my-debts.xlsx\")\ndebts, income, expenses, future_income, future_expenses, settings = reader.read_all_data()\n\n# Initialize optimizer\noptimizer = DebtOptimizer(debts, income, expenses, future_income, future_expenses, settings)\n\n# Run optimization\nresult = optimizer.optimize_debt_strategy(\n goal=OptimizationGoal.MINIMIZE_INTEREST,\n extra_payment=500.0\n)\n\n# Generate report\nwriter = ExcelReportWriter(\"analysis.xlsx\")\ndebt_summary = optimizer.generate_debt_summary()\nwriter.create_comprehensive_report(result, debt_summary)\n```\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n```bash\ngit clone https://github.com/bryankemp/financial-debt-optimizer.git\ncd financial-debt-optimizer\npip install -e .[dev]\n```\n\n### Running Tests\n```bash\npip install -e .[test]\npytest\n```\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.\n\n## Documentation\n\n\ud83d\udcd6 **[Complete Documentation](https://financial-debt-optimizer.readthedocs.io/)**\n\n- **[Installation Guide](https://financial-debt-optimizer.readthedocs.io/en/latest/installation.html)** - Detailed installation instructions\n- **[Quick Start](https://financial-debt-optimizer.readthedocs.io/en/latest/quickstart.html)** - Get started in minutes\n- **[User Guide](https://financial-debt-optimizer.readthedocs.io/en/latest/user_guide.html)** - Comprehensive usage documentation\n- **[Examples](https://financial-debt-optimizer.readthedocs.io/en/latest/examples.html)** - Real-world use cases and scenarios\n- **[API Reference](https://financial-debt-optimizer.readthedocs.io/en/latest/modules.html)** - Complete API documentation\n- **[FAQ](https://financial-debt-optimizer.readthedocs.io/en/latest/faq.html)** - Frequently asked questions\n\n## Support\n\n- **\ud83d\udcd6 Documentation**: [https://financial-debt-optimizer.readthedocs.io/](https://financial-debt-optimizer.readthedocs.io/)\n- **\ud83d\udc1b Issues**: [GitHub Issues](https://github.com/bryankemp/financial-debt-optimizer/issues)\n- **\ud83d\udcac Discussions**: [GitHub Discussions](https://github.com/bryankemp/financial-debt-optimizer/discussions)\n- **\ud83d\udce7 Email**: bryan@kempville.com\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and changes.\n\n## Disclaimer\n\nThis 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.\n\n---\n\n**Author**: Bryan Kemp (bryan@kempville.com) \n**Version**: 1.0.0 \n**License**: BSD 3-Clause\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive tool for analyzing and optimizing debt repayment strategies",
"version": "1.1.1",
"project_urls": {
"Bug Reports": "https://github.com/bryankemp/financial-debt-optimizer/issues",
"Documentation": "https://github.com/bryankemp/financial-debt-optimizer#readme",
"Homepage": "https://github.com/bryankemp/financial-debt-optimizer",
"Source": "https://github.com/bryankemp/financial-debt-optimizer"
},
"split_keywords": [
"debt",
"optimization",
"finance",
"calculator",
"repayment",
"strategy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e608124587db89ae469a06e712c000dd94603c89488ad5513bdbbc3e9571b2d0",
"md5": "613b08988c3dc76f5295d9b098057746",
"sha256": "c595c05fe7653be1be2b9be7416baf23687fa3d02e42de9f140a617867c7db20"
},
"downloads": -1,
"filename": "financial_debt_optimizer-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "613b08988c3dc76f5295d9b098057746",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 54483,
"upload_time": "2025-10-14T02:51:53",
"upload_time_iso_8601": "2025-10-14T02:51:53.086810Z",
"url": "https://files.pythonhosted.org/packages/e6/08/124587db89ae469a06e712c000dd94603c89488ad5513bdbbc3e9571b2d0/financial_debt_optimizer-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c3f684c66a20ab1f097609ba327939a648012d478f998597592dcfd5c3cbae9e",
"md5": "13494bacc79e3a47fc4fe5b01aa8dc01",
"sha256": "620e8b46f5352e3f37f77018626eec0cc28b76be910b7f858d2b9f03229a23ab"
},
"downloads": -1,
"filename": "financial_debt_optimizer-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "13494bacc79e3a47fc4fe5b01aa8dc01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 56326,
"upload_time": "2025-10-14T02:51:54",
"upload_time_iso_8601": "2025-10-14T02:51:54.507114Z",
"url": "https://files.pythonhosted.org/packages/c3/f6/84c66a20ab1f097609ba327939a648012d478f998597592dcfd5c3cbae9e/financial_debt_optimizer-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 02:51:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bryankemp",
"github_project": "financial-debt-optimizer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pandas",
"specs": [
[
">=",
"1.5.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "xlsxwriter",
"specs": [
[
">=",
"3.0.3"
]
]
},
{
"name": "openpyxl",
"specs": [
[
">=",
"3.0.7"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.4.0"
]
]
}
],
"lcname": "financial-debt-optimizer"
}
JSON
