mirror of https://github.com/ghostfolio/ghostfolio
Priyanka Punukollu
1 month ago
1 changed files with 212 additions and 0 deletions
@ -0,0 +1,212 @@ |
|||||
|
# AgentForge Bounty — $500 Submission |
||||
|
|
||||
|
## The Customer |
||||
|
|
||||
|
Tech professionals anywhere in the world evaluating a job offer, relocation, |
||||
|
or first home purchase. Specifically: someone with investments in Ghostfolio |
||||
|
who wants to know: |
||||
|
|
||||
|
- "Is this job offer in Seattle/London/Tokyo actually a real raise after cost of living?" |
||||
|
- "Can my portfolio fund a down payment? Where can I afford?" |
||||
|
- "What is my total net worth including my home equity?" |
||||
|
|
||||
|
**The pain:** "I have money in the market. I got a $180k offer in Seattle. |
||||
|
I don't know if I can afford to move, whether I can buy a house, or if the |
||||
|
raise is even real." |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## The Features |
||||
|
|
||||
|
### 1. Portfolio → Down Payment Bridge |
||||
|
|
||||
|
Reads the user's live Ghostfolio portfolio and calculates exactly which housing |
||||
|
markets they can afford at 20% down with monthly payment estimates and rent vs |
||||
|
buy comparison. Works for Austin (real MLS data) and any city worldwide |
||||
|
(Teleport API). |
||||
|
|
||||
|
### 2. Job Offer Affordability Calculator |
||||
|
|
||||
|
Takes any salary offer and destination city anywhere in the world, adjusts for |
||||
|
cost of living, and tells the user whether it is a real raise in purchasing |
||||
|
power terms. Covers 200+ cities via Teleport API + real Austin MLS data. |
||||
|
Handles state income tax comparison automatically. |
||||
|
|
||||
|
### 3. Property Tracker — Full CRUD |
||||
|
|
||||
|
Users log owned properties, track equity, monitor appreciation. Agent supports |
||||
|
create, read, update, and delete via natural language. Stored in SQLite — |
||||
|
persists across sessions. Soft-delete preserves audit trail. |
||||
|
|
||||
|
### 4. Unified Net Worth View |
||||
|
|
||||
|
Agent combines live investment portfolio + real estate equity into one complete |
||||
|
financial picture in a single conversation turn. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## The Data Sources |
||||
|
|
||||
|
### ACTRIS / Unlock MLS — January 2026 (Austin TX) |
||||
|
|
||||
|
- 7 counties: City of Austin, Travis County, Williamson County, Hays County, |
||||
|
Bastrop County, Caldwell County, Austin-Round Rock-San Marcos MSA |
||||
|
- Provided by the developer — a licensed Austin real estate agent (ACTRIS member) |
||||
|
- Fields: ListPrice, DaysOnMarket, MonthsOfInventory, MedianRentMonthly, |
||||
|
CloseToListRatio, PendingSalesYoY, ClosedSalesYoY, AffordabilityScore |
||||
|
- Schema follows RESO Web API naming — live API swap requires zero refactoring |
||||
|
- Footer appended to every Texas response: |
||||
|
`📊 Source: ACTRIS/Unlock MLS · January 2026 · Verified by licensed Austin real estate agent` |
||||
|
|
||||
|
**Key January 2026 figures:** |
||||
|
|
||||
|
| Market | Median Price | DOM | Months Inventory | Rent/mo | |
||||
|
| ----------------- | ------------ | --- | ---------------- | ------- | |
||||
|
| City of Austin | $522,500 | 82 | 3.9 | $2,100 | |
||||
|
| Travis County | $445,000 | 87 | 3.9 | $2,100 | |
||||
|
| Austin MSA | $400,495 | 89 | 4.0 | $2,000 | |
||||
|
| Williamson County | $403,500 | 92 | 3.5 | $1,995 | |
||||
|
| Hays County | $344,500 | 86 | 4.4 | $1,937 | |
||||
|
| Bastrop County | $335,970 | 109 | 5.8 | $1,860 | |
||||
|
| Caldwell County | $237,491 | 73 | 8.4 | $1,750 | |
||||
|
|
||||
|
### Teleport API (global — 200+ cities, free, no auth) |
||||
|
|
||||
|
- Endpoint: `api.teleport.org` |
||||
|
- Covers: cost of living, housing costs, quality of life scores for cities |
||||
|
worldwide including US, Europe, Asia, Australia, Canada, Latin America |
||||
|
- Functions: `search_city_slug()` + `get_city_housing_data()` |
||||
|
- Returns normalized schema compatible with Austin ACTRIS data structure |
||||
|
- Fallback: hardcoded data for 23 major cities if API unavailable |
||||
|
- Used by wealth_bridge for COL-adjusted salary calculations |
||||
|
|
||||
|
### Ghostfolio Portfolio API |
||||
|
|
||||
|
- Live portfolio holdings, total value, performance metrics |
||||
|
- Connected via bearer token auth (per-user, passed from Angular frontend) |
||||
|
- Used to calculate real purchasing power for down payment analysis |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## The Impact |
||||
|
|
||||
|
A user asks one question: |
||||
|
|
||||
|
> "I have a job offer in Tokyo for $200k. I currently make $120k in Austin. |
||||
|
> Is it worth it, and could I ever afford to buy there?" |
||||
|
|
||||
|
The agent: |
||||
|
|
||||
|
1. Reads their live $94k portfolio from Ghostfolio |
||||
|
2. Fetches Tokyo cost of living + housing from Teleport API |
||||
|
3. Calculates real purchasing power of Tokyo offer vs Austin salary |
||||
|
4. Shows down payment power across Austin vs Tokyo markets |
||||
|
5. Returns clear recommendation in plain English |
||||
|
|
||||
|
This is not possible in any other portfolio app. It requires live portfolio data |
||||
|
|
||||
|
- real MLS data + global city data in the same agent with shared context across |
||||
|
turns. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Suggestion Chips (UI) |
||||
|
|
||||
|
Three rows of suggestion chips, visible before first message: |
||||
|
|
||||
|
**Row 1 — Portfolio (always shown):** |
||||
|
|
||||
|
- 📈 My portfolio performance |
||||
|
- ⚠️ Any concentration risk? |
||||
|
- 💰 Estimate my taxes |
||||
|
|
||||
|
**Row 2 — Real Estate (when `enableRealEstate=true`):** |
||||
|
|
||||
|
- 🏠 Austin under $500k |
||||
|
- 📊 Austin vs Denver |
||||
|
- 🏘️ SF snapshot |
||||
|
|
||||
|
**Row 3 — Wealth Bridge (when `enableRealEstate=true`):** |
||||
|
|
||||
|
- 💰 Can my portfolio buy a house? |
||||
|
- ✈️ Is my job offer a real raise? |
||||
|
- 🌍 Cost of living in Tokyo |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Tool Architecture |
||||
|
|
||||
|
``` |
||||
|
wealth_bridge.py |
||||
|
├── calculate_down_payment_power(portfolio_value, cities) |
||||
|
│ → 7 Austin markets (ACTRIS) or any cities (Teleport) |
||||
|
│ → can_afford_full / conservative / safe + monthly payment |
||||
|
│ → rent vs buy comparison + break-even years |
||||
|
├── calculate_job_offer_affordability(salaries, cities) |
||||
|
│ → COL-adjusted purchasing power for any two cities worldwide |
||||
|
│ → state income tax comparison |
||||
|
│ → verdict + breakeven salary needed |
||||
|
└── get_portfolio_real_estate_summary() |
||||
|
→ reads live Ghostfolio portfolio + runs down payment calc |
||||
|
|
||||
|
property_tracker.py |
||||
|
├── add_property(address, prices, mortgage) |
||||
|
├── get_properties() / list_properties() |
||||
|
├── update_property(id, new_values) |
||||
|
├── remove_property(id) ← soft delete |
||||
|
└── get_total_net_worth(portfolio_value) |
||||
|
|
||||
|
real_estate.py (Austin — real ACTRIS MLS data) |
||||
|
├── search_listings(query, filters) |
||||
|
├── get_neighborhood_snapshot(location) |
||||
|
├── compare_neighborhoods(city_a, city_b) |
||||
|
└── get_listing_details(listing_id) |
||||
|
|
||||
|
teleport_api.py (global — 200+ cities) |
||||
|
├── search_city_slug(city_name) ← resolves to Teleport slug |
||||
|
└── get_city_housing_data(city_name) |
||||
|
→ live Teleport API → normalized schema → fallback if down |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Evals & Verification |
||||
|
|
||||
|
- **89 passing tests total** (81 existing + 8 new wealth bridge tests) |
||||
|
- 8 wealth bridge specific tests: |
||||
|
- Down payment power at $94k portfolio |
||||
|
- Small portfolio cannot afford safe down payment |
||||
|
- Seattle $180k offer is NOT a real raise vs Austin $120k |
||||
|
- SF $250k offer IS a real raise vs Austin $80k |
||||
|
- Global city (London) comparison returns all required fields |
||||
|
- Full property CRUD cycle (CREATE → READ → UPDATE → DELETE) |
||||
|
- Net worth combines portfolio + real estate equity correctly |
||||
|
- Teleport fallback works when API unavailable |
||||
|
- LangSmith tracing active at smith.langchain.com |
||||
|
- `/real-estate/log` observability endpoint |
||||
|
- Structured error codes on all tool failures (`REAL_ESTATE_PROVIDER_UNAVAILABLE`, |
||||
|
`PROPERTY_TRACKER_NOT_FOUND`, `PROPERTY_TRACKER_INVALID_INPUT`, etc.) |
||||
|
- All tools registered in LangGraph with conversation history maintained |
||||
|
- Feature flag: `ENABLE_REAL_ESTATE=true` activates all real estate + wealth bridge features |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## New Files Added in This Submission |
||||
|
|
||||
|
| File | Purpose | |
||||
|
| ----------------------------------- | -------------------------------------------------- | |
||||
|
| `agent/tools/teleport_api.py` | Global city COL + housing data (200+ cities) | |
||||
|
| `agent/tools/wealth_bridge.py` | Down payment power + job offer COL calculator | |
||||
|
| `agent/evals/test_wealth_bridge.py` | 8 new tests for wealth bridge features | |
||||
|
| `agent/data/` | SQLite database directory for property persistence | |
||||
|
| `BOUNTY.md` | This file | |
||||
|
|
||||
|
## Modified Files |
||||
|
|
||||
|
| File | Change | |
||||
|
| ---------------------------------------- | -------------------------------------------------------- | |
||||
|
| `agent/tools/real_estate.py` | Expose real ACTRIS data_source in responses + TX footer | |
||||
|
| `agent/tools/property_tracker.py` | Full SQLite CRUD + update_property + get_total_net_worth | |
||||
|
| `agent/graph.py` | Wealth bridge routes + property update/remove routes | |
||||
|
| `apps/client/.../ai-chat.component.html` | Row 3 wealth bridge suggestion chips | |
||||
|
| `apps/client/.../ai-chat.component.scss` | Amber gold chip styling for Row 3 | |
||||
Loading…
Reference in new issue