Adaptive Learning

Overview

The Financial Freedom Adventure features a sophisticated Adaptive Learning engine that allows the AI to evolve based on specific user behavior. Unlike static budgeting apps, the system utilizes a "Human-in-the-Loop" correction model where Professor Ledger (the AI Agent) learns from your manual corrections to improve future categorization accuracy and conversational context.

The Correction Loop

When the system miscategorizes an expense (e.g., labeling a medical bill as "Entertainment"), users can trigger a learning event through the UI.

Trigger: In the BudgetPlanner, click the correction icon on a transaction.
Input: Use the CorrectionModal to provide the correct category and an optional "Reason."
Persistence: The learningService saves this rule to the user's long-term memory.
Application: The next time a similar transaction is entered, the system overrides its default logic with the learned rule.

Example: Teaching the Agent

import { teachAgent } from './services/learningService';

// Teaching the system that 'The Batmobile' is a 'Transport' expense
teachAgent(
  "The Batmobile", 
  "Transport", 
  "This is my primary vehicle maintenance fund."
);

Smart Categorization (Prediction)

The system performs real-time lookups as users type descriptions. This is handled by the predictCategory function, which scans the learned rule database before falling back to generic AI suggestions.

Usage in Components

const handleDescriptionChange = (desc: string) => {
  setNewExpenseDesc(desc);
  
  // Attempt to predict category based on past corrections
  if (desc.length > 2) {
    const predicted = predictCategory(desc);
    if (predicted) {
      setNewExpenseCategory(predicted);
    }
  }
};

LLM Context Integration

Learned rules are not just used for UI shortcuts; they are injected into the Gemini AI prompt via the LEARNING_PROTOCOL. This ensures that Professor Ledger’s personality remains consistent with your past inputs.

Recognition: If you provide a correction, the AI is instructed to apologize and acknowledge the update (e.g., "My scanners were calibrated wrong! I have recorded that 'Starbucks' is actually 'Work Meeting' expense.").
Terminology: The AI adopts your specific nicknames for funds or categories, increasing immersion.

Learning API Reference

The learningService.ts provides the following core utilities:

`predictCategory(description: string): string | null`

Checks the learned rule database for a keyword match. Returns the corrected category string if found, otherwise returns null.

`teachAgent(transactionName: string, correctCategory: string, note: string)`

Creates a new LearningRule.

Keyword: The description is converted to lowercase for fuzzy matching.
Storage: Rules are persisted in localStorage under finmon_learning_rules.

`getAllRules(): LearningRule[]`

Retrieves the entire library of user-taught rules. This is primarily used by geminiService to provide context to the LLM.

Memory Protocol

Separate from categorization rules, the system tracks Long-Term Memories (Goals, Habits, and Preferences) via memoryService.ts.

When you mention a goal in chat (e.g., "I want to save for a house"), the AI generates a [[MEMORY:GOAL:Buying a house]] tag. This information is stored and later retrieved to build rapport, allowing Professor Ledger to say: "This saving habit will get you into that house you mentioned much faster!"