ADR-001: Ghostfolio AI Agent - Portfolio Analysis Tool

Status: Proposed Date: 2026-02-23 Context: First MVP tool for Ghostfolio AI agent. Need to enable portfolio analysis queries with verified calculations.

Options Considered

Option A: Extend Existing PortfolioService ✅ (CHOSEN)

Description: Use Ghostfolio's existing PortfolioService.getPortfolio() and PortfolioCalculator
Pros:
- Ships fastest (2-4 hours vs 1-2 days)
- Battle-tested math (TWR, ROI, MWR)
- No new dependencies
- Matches PRESEARCH decision
Cons:
- Limited to existing calculations
- Can't customize output format easily

Option B: Build New Calculation Engine ❌ (REJECTED)

Description: Create new portfolio calculation logic from scratch
Pros: Full control over calculations
Cons:
- 1-2 days implementation
- High risk of math errors
- Hard to verify against existing data
- Reason: Reimplementing finance math is unnecessary risk

Option C: Third-Party Finance API ❌ (REJECTED)

Description: Use external portfolio analysis API (e.g., Yahoo Finance, Alpha Vantage)
Pros: Offloads calculation complexity
Cons:
- Rate limits
- API costs
- Data privacy concerns
- Reason: Ghostfolio already has this data; redundant call

Decision

Extend PortfolioService with portfolio analysis tool using existing calculation engines.

Trade-offs / Consequences

Positive:
- Ships in 4 hours (MVP on track)
- Verified calculations (matches Ghostfolio UI)
- Zero API costs for data layer
Negative:
- Can't easily add custom metrics
- Tied to Ghostfolio's calculation logic

What Would Change Our Mind

Existing PortfolioService math fails verification checks
Performance issues with large portfolios (>1000 holdings)
Requirements need custom metrics not in Ghostfolio

Tests: apps/api/src/app/endpoints/ai/ai.service.spec.ts
Evals: evals/mvp-dataset.ts (cases: portfolio-1, portfolio-2, portfolio-3)
PRESEARCH: Section 3 (Tool Plan)
Supersedes: None (first ADR)

2.1 KiB Raw Blame History