Metadata-Version: 2.4
Name: financial-compass
Version: 0.1.0
Summary: A privacy-first financial contingency planner: know how long you can survive, what your options are, and what your plan should be.
Project-URL: Homepage, https://github.com/rameezrz25/financial-compass
Project-URL: Repository, https://github.com/rameezrz25/financial-compass
Project-URL: Issues, https://github.com/rameezrz25/financial-compass/issues
Project-URL: Changelog, https://github.com/rameezrz25/financial-compass/blob/main/CHANGELOG.md
Author: Financial Compass Contributors
License: MIT
License-File: LICENSE
Keywords: budgeting,finance,financial-planning,layoff,personal-finance,runway
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pandas-stubs; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# Financial Compass

**Know where you stand. Know your options. Plan your next move.**

Financial Compass is a privacy-first, local-first CLI that answers one question calmly and
factually:

> *If my income stops tomorrow, how long can I survive, what are my options, and what should
> my plan be?*

It never predicts when you'll find a job, never gives personalized investment/tax/legal advice,
and never classifies your investments as halal/haram. It just does the arithmetic, clearly, on
your own machine.

## Why

Most "financial planning" tools are either sales funnels for investment products or vague
budgeting apps that don't answer the actual question people have during a layoff or income
scare: *how long do I have, and what are my real options?* Financial Compass is a calculator,
not an advisor — it separates **facts** (your transactions, balances, debts) from
**assumptions** (job search length, spending cuts) and **scenarios** (what-if projections), so
you always know which is which.

## Principles

- **Local-first.** Your financial data never leaves your machine. No bank credentials, ever.
- **No mandatory cloud or AI APIs.** Everything runs offline.
- **Facts vs. assumptions vs. scenarios, always labeled.** Nothing is presented as certain that
  isn't.
- **No job-search-duration predictions.** You choose the horizon; the tool just does the math.
- **No personalized investment, tax, or legal advice.** And no automatic halal/haram
  classification of your holdings.
- **Calm, factual, scenario-based — never fear-driven.**

## Install

```bash
pip install financial-compass
```

Requires Python 3.11+.

## Try it in one command

```bash
pip install financial-compass
financial-compass demo
```

This runs the entire workflow against bundled, made-up synthetic data — no setup,
no real financial data touched — and opens the generated HTML report.

## Quick start (with your own data)

```bash
# 1. Create a local workspace and fill in your assets/liabilities/income facts
financial-compass init
$EDITOR .financial-compass/facts.yaml

# 2. Import a bank statement (CSV or XLSX exported from your bank)
financial-compass import statement.csv

# 3. See categorized spending and burn rates
financial-compass analyze

# 4. Simulate income stopping tomorrow
financial-compass simulate --months 12

# 5. See the salary thresholds that matter
financial-compass salary

# 6. Get a calm, month-by-month action plan
financial-compass plan

# 7. Generate a full offline HTML dashboard
financial-compass report --html
```

Try it immediately with the bundled synthetic example data:

```bash
financial-compass init --workspace demo-workspace --force
cp examples/facts.yaml demo-workspace/facts.yaml
financial-compass import examples/sample_statement.csv --workspace demo-workspace
financial-compass report --html --workspace demo-workspace --output demo-report.html
```

## What it does

1. **Bank statement analysis** — imports CSV/XLSX, categorizes transactions with local
   keyword rules, detects recurring income/expenses, and calculates actual / essential /
   reduced / survival monthly burn.
2. **Assets** — cash, FDs, mutual funds, Indian/US stocks, RSUs (vested/unvested), EPF, PPF,
   NPS, gold, property — classified as immediate / accessible / long-term liquidity.
3. **Liabilities** — home/car/personal/education loans, credit cards, and their EMIs.
4. **Layoff simulation** — assumes income stops tomorrow, includes notice pay, severance,
   leave encashment, and pending bonus, and projects month-by-month asset drawdown for
   3/6/9/12/18/24-month horizons.
5. **Job planning** — simulates a new job starting after N months at a chosen salary, and
   computes four thresholds: survival, minimum sustainable, recovery, and target salary.
6. **Action plan** — a calm, practical month-by-month plan (Month 0, 1-3, 3-6, 6-9, 9-12, 12+)
   with concrete options to extend runway at each stage.
7. **What-if scenarios** — lower spending, temporary income, different job-search durations,
   different new-job salaries, all compared side by side.
8. **HTML report** — a single self-contained offline dashboard covering net worth, liquid
   assets, spending, runway, scenarios, salary thresholds, the action plan, and every
   assumption used to produce them.

## Python API

```python
from financial_compass import storage
from financial_compass.core.spending import calculate_burn_rates
from financial_compass.core.simulation import simulate_layoff

profile = storage.load_profile()
transactions = storage.load_transactions()
burn = calculate_burn_rates(transactions)
result = simulate_layoff(profile, burn.survival, months=12)
print(result.runway_months)
```

## Data & privacy

- All data lives in a local workspace directory (`.financial-compass/` by default) as plain
  YAML/JSON files you can read, edit, back up, or delete yourself.
- No bank credentials are ever requested — you export a statement file from your bank and
  point the tool at it.
- No network calls are made by any core command.

## Development

```bash
git clone https://github.com/rameezrz25/financial-compass
cd financial-compass
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

ruff check .
mypy .
pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for more.

## License

MIT — see [LICENSE](LICENSE).
