Natural Language Goal Parsing

const prompt = `You are a financial goal parser. Given a user's natural language financial goal, extract structured parameters.

User's goal: "${goal}"

Extract the following (use null if not determinable):

1. goal_type: One of:
   - "retirement" (retiring, stop working, financial independence)
   - "major_purchase" (house, car, boat, etc.)
   - "emergency_fund" (rainy day, safety net, 6 months expenses)
   - "debt_payoff" (pay off loans, become debt free)
   - "travel" (vacation, trip, sabbatical)
   - "education" (college, degree, certification)
   - "investment" (grow wealth, portfolio target)
   - "custom" (anything else)

2. target_amount: Number in USD. If vague:
   - "comfortable retirement" → 1000000
   - "house down payment" → 60000
   - "emergency fund" → 15000 (estimate)
   - "pay off debt" → null (will be filled from data)
   - IMPORTANT: Flag as unrealistic if target seems way too low for the goal type (e.g., $3 for a car)

3. timeline_months: Number of months. If vague:
   - "in a few years" → 36
   - "by retirement" → use 65 - 30 = 35 years = 420 months
   - "soon" → 12
   - "long term" → 120

4. constraints: Array of any constraints mentioned (empty array if none)

5. needsClarification: Boolean. Set to true if:
   - Target amount is unrealistically low for the goal type
   - Timeline is missing for a time-sensitive goal
   - Goal description is too vague to estimate amounts

6. clarifyingQuestions: If needsClarification is true, provide questions. Otherwise null.

Respond in JSON only, no explanation.

const result = await this.model.generateContent(prompt)
const response = result.response
const text = response.text()

// Extract JSON from the response (handle markdown code blocks)
let jsonStr = text
const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/)
if (jsonMatch) {
  jsonStr = jsonMatch[1].trim()
}

const parsed = JSON.parse(jsonStr) as ParsedGoal

{
  "goalType": "retirement",
  "targetAmount": 1000000,
  "timelineMonths": 180,
  "constraints": [],
  "needsClarification": false,
  "clarifyingQuestions": null
}

prompt = f"""
You are a financial advisor. Parse the following savings goal and extract:
1. Type of goal (retirement, house, emergency_fund, vacation, college, car, custom)
2. Target amount in USD
3. Timeline in months
4. Whether the goal description contains enough information to parse (realistic and clear)

User context:
- Monthly income: ${monthly_income:,.0f}
- Risk tolerance: {risk_tolerance}
- Goal description: "{goal_text}"

Important: If the goal seems unrealistic or lacks critical information, flag it and provide clarifying questions needed.

Respond as JSON with these fields:
{{
    "goal_type": "string",
    "target_amount": number (USD) or null if unclear,
    "timeline_months": number or null if unclear,
    "description": "string describing the goal",
    "confidence": number (0-1, how confident are you in this parsing),
    "needs_clarification": boolean,
    "clarifying_questions": ["string"] or []
}}
"""

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful financial planning assistant. Always respond with valid JSON."},
        {"role": "user", "content": prompt}
    ],
    temperature=0.3,
    max_tokens=300
)

def parse_goal_with_templates(
    goal_text: str,
    monthly_income: float,
    current_age: int = 30
) -> ParsedGoal:
    goal_lower = goal_text.lower()
    
    # Try to match against known templates
    for goal_type, template in GOAL_TEMPLATES.items():
        if goal_type in goal_lower:
            target = template['multiplier'](monthly_income)
            timeline = template['default_years'] * 12

            import re
            # Extract years if specified
            years_match = re.search(r'(\d+)\s*years?', goal_lower)
            if years_match:
                timeline = int(years_match.group(1)) * 12

            goal = ParsedGoal(
                goal_type=goal_type,
                target_amount=round(target, 2),
                timeline_months=timeline,
                description=template['description'],
                confidence=0.7,
                source="template"
            )

            return _validate_goal_output(goal, monthly_income)

GOAL_TEMPLATES = {
    "retirement": {
        "description": "Retirement planning",
        "multiplier": lambda monthly_income: monthly_income * 12 * 25,  # 25x annual salary
        "default_years": 35
    },
    "house": {
        "description": "House down payment",
        "multiplier": lambda _: 100000,  # 20% down on $500k house
        "default_years": 5
    },
    "emergency_fund": {
        "description": "Emergency fund (6 months)",
        "multiplier": lambda monthly_income: monthly_income * 6,
        "default_years": 1
    },
    "vacation": {
        "description": "Vacation/travel",
        "multiplier": lambda _: 10000,
        "default_years": 2
    },
    "college": {
        "description": "College fund",
        "multiplier": lambda _: 100000,
        "default_years": 18
    },
    "car": {
        "description": "New car",
        "multiplier": lambda _: 30000,
        "default_years": 3
    }
}

def _validate_goal_output(goal: ParsedGoal, monthly_income: float) -> ParsedGoal:
    """Clamp clearly bad outputs (e.g., $60 retirement goals)."""
    min_target_by_type = {
        "retirement": monthly_income * 12 * 15,  # at least 15x annual
        "house": 20000,
        "emergency_fund": monthly_income * 3,
    }

    min_target = min_target_by_type.get(goal.goal_type, 5000)
    if goal.target_amount < min_target:
        goal.target_amount = round(min_target, 2)
        goal.description += " (auto-corrected unrealistic target)"
        goal.confidence = min(goal.confidence, 0.6)

    # Ensure timeline is at least 12 months
    if goal.timeline_months < 12:
        goal.timeline_months = 12
        goal.description += " (min 12 months enforced)"

    return goal

def _normalize_retirement_timeline(goal_text: str, current_age: int, default_years: int) -> int:
    """Derive retirement timeline in months. Handles phrases like 'retire by 60'."""
    import re

    # Look for "by 60" or "by age 60"
    by_age_match = re.search(r"by\s+age?\s*(\d{2})", goal_text.lower())
    if by_age_match:
        retire_age = int(by_age_match.group(1))
        years_left = max(retire_age - current_age, 1)
        return years_left * 12

    # Look for "in 15 years"
    years_match = re.search(r"(\d+)\s*years?", goal_text.lower())
    if years_match:
        return max(int(years_match.group(1)), 1) * 12

    return default_years * 12

// Ensure clarifying questions exist if needed
if (parsed.needsClarification && !parsed.clarifyingQuestions) {
  parsed.clarifyingQuestions = [
    'Please provide more specific details about your goal amount and timeline.'
  ]
}

if (extractedAmount !== null && extractedAmount < 100) {
  if (goalType === 'major_purchase' || goalType === 'retirement') {
    needsClarification = true
    clarifyingQuestions = [
      `The amount $${extractedAmount} seems very low for a ${goalType}. Did you mean $${extractedAmount * 1000}?`,
      'Could you clarify the exact amount you need?'
    ]
  }
}

class GeminiGoalConversation {
  async processUserInput(
    userMessage: string,
    conversationHistory: ConversationMessage[]
  ): Promise<GoalConversationResponse> {
    const systemPrompt = `You are Drift, a friendly financial goal assistant.

RULES:
1. Be conversational and warm - like a smart friend who's good with money
2. Keep responses SHORT (1-2 sentences max)
3. Ask ONE clarifying question at a time if needed
4. Extract: goal type, target amount, timeline

WHEN YOU HAVE ALL THREE (amount, timeline, goal type):
- Confirm what you understood
- End your response with [GOAL_COMPLETE] on its own line
- Include a JSON block with the parsed goal
`

    const result = await this.model.generateContent(fullPrompt)
    const responseText = result.response.text().trim()

    // Check if goal is complete
    const isComplete = responseText.includes('[GOAL_COMPLETE]')

    // Extract parsed goal if complete
    if (isComplete) {
      const jsonMatch = responseText.match(/```json\s*([\s\S]*?)```/)
      if (jsonMatch) {
        parsedGoal = JSON.parse(jsonMatch[1].trim())
      }
    }

    return { response: cleanResponse, isComplete, parsedGoal }
  }
}

User: "I want to save for a house"
Drift: "Nice! How much are you thinking for the down payment?"

User: "Like 50 thousand"
Drift: "Got it, $50K for a house down payment. What's your timeline - when are you hoping to buy?"

User: "Maybe 3 years"
Drift: "Perfect - $50,000 for a house down payment in 3 years. Let's see what your odds look like!
[GOAL_COMPLETE]
```json
{"targetAmount": 50000, "timelineMonths": 36, "goalType": "major_purchase"}

## Income Estimation from Transactions

When parsing goals, Drift can estimate income from deposit patterns (goal_parser.py:318-379):

```python
def extract_salary_from_deposits(
    deposits_by_account: Dict[str, list],
    purchases_data: Optional[Dict[str, list]] = None,
    return_details: bool = False
) -> Tuple[float, Optional[Dict[str, Any]]]:
    # Collect all deposits
    all_deposits = []
    for account_id, deposits in deposits_by_account.items():
        for deposit in deposits:
            amount = deposit.get('amount', 0)
            if amount > 0:
                all_deposits.append({
                    'amount': amount,
                    'date': deposit.get('date', ''),
                    'description': deposit.get('description', '')
                })
    
    # Look for large recurring deposits (likely salary)
    amounts = [d['amount'] for d in all_deposits]
    q75 = np.percentile(amounts, 75)
    large_deposits = [a for a in amounts if a >= q75]
    
    if large_deposits:
        salary = np.mean(large_deposits)
    else:
        salary = np.median(amounts)
    
    return round(salary, 2)

private get model(): GenerativeModel | null {
  if (this._model === null && process.env.GEMINI_API_KEY) {
    const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY)
    this._model = genAI.getGenerativeModel({ model: 'gemini-2.0-flash' })
  }
  return this._model
}

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful financial planning assistant. Always respond with valid JSON."},
        {"role": "user", "content": prompt}
    ],
    temperature=0.3,
    max_tokens=300
)