Goals¶
Create, track, and project financial goals.
create_goal¶
Create a financial goal with specified strategy and targets.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
string | required | Goal name (1-200 characters) |
goal_type |
string | required | Goal type (e.g., 'retirement', 'emergency_fund', 'education', 'home_purchase') |
strategy |
string | required | Funding strategy (e.g., 'fixed_contribution', 'fill_to_target', 'percentage_income') |
importance |
float | required | Success probability target (0.50-0.99, e.g., 0.90 = 90% confidence) |
target_amount_cents |
int | null | Target amount in cents (required for fill_to_target and minimum_balance strategies) |
target_date |
string | null | Target date in YYYY-MM-DD format (optional) |
target_date_flexibility |
string | null | Date flexibility: 'firm', 'flexible', or 'very_flexible' (optional) |
current_balance_cents |
int | 0 |
Current savings toward this goal in cents |
contribution_amount_cents |
int | null | Fixed monthly contribution in cents (required for fixed_contribution strategy) |
contribution_percentage |
float | null | Contribution as % of income (required for percentage_income strategy, e.g., 0.15 = 15%) |
months_expenses |
int | null | Number of months of expenses to save (for emergency_fund goals) |
status |
string | "active" |
Goal status: 'active', 'paused', 'completed', 'abandoned', or 'pending' |
tax_advantaged |
bool | false |
Prefer tax-advantaged accounts for this goal |
notes |
string | null | Additional notes about the goal |
Returns the created goal as JSON including auto-generated ID and validation results.
get_goal_progress¶
Calculate current progress toward a goal.
| Parameter | Type | Default | Description |
|---|---|---|---|
goal_json |
object | required | Goal as JSON dictionary |
Returns progress percentage, remaining amount, and completion status.
project_goal_progress¶
Project goal progress forward with compound growth.
| Parameter | Type | Default | Description |
|---|---|---|---|
goal_json |
object | required | Goal as JSON dictionary |
annual_return_rate |
float | 0.07 |
Expected annual return rate (e.g., 0.07 = 7%) |
months_ahead |
int | 12 |
Number of months to project forward |
Returns: goal_id, goal_name, current_balance_cents, current_balance_dollars, projection_date, months_ahead, annual_return_rate, projected_balance_cents, projected_balance_dollars, and projected_progress_percentage, and more.
required_monthly_cashflow¶
Calculate the monthly contribution needed to reach a goal.
| Parameter | Type | Default | Description |
|---|---|---|---|
target_amount_cents |
int | required | Target goal amount in cents |
time_horizon_months |
int | required | Number of months until target date |
initial_balance_cents |
int | 0 |
Current savings toward goal in cents |
annual_return_rate |
float | 0.07 |
Expected annual return rate (e.g., 0.07 = 7%) |
inflation |
float | 0.0 |
Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, the target is assumed to be in today's dollars and is inflated to the target date's nominal value before solving. |
Returns: target_amount_cents, target_amount_dollars, initial_balance_cents, initial_balance_dollars, time_horizon_months, annual_return_rate, inflation, inflation_adjusted_target_cents, inflation_adjusted_target_dollars, and cashflow_cents, and more.