Gemini AI Service

The Gemini AI Service is the core intelligence engine of FinQuest AI, leveraging Google’s Gemini models to provide real-time financial coaching, automated budget analysis, and interactive pet personalities.

Configuration

To enable the AI features, you must provide a Google Gemini API key.

Obtain a key from the Google AI Studio.
Add the key to your .env.local file:
```
GEMINI_API_KEY=your_api_key_here
```

The service currently utilizes the gemini-3-flash-preview model for high-speed, low-latency responses suitable for chat and real-time analysis.

Core API Functions

The geminiService.ts exports several high-level functions used across the application.

`getBudgetAnalysis`

Analyzes a user's transaction history against their income to provide a financial health score and actionable recommendations.

Inputs:
- income: (number) The user's monthly net income.
- transactions: (Transaction[]) An array of expense and income objects.

Returns: Promise<BudgetAnalysis>

interface BudgetAnalysis {
  healthScore: number;      // 0-100 score
  summary: string;          // Natural language overview
  recommendations: string[]; // Array of improvement tips
  savingsPotential: number;  // Estimated monthly savings
}

`getTaxEstimate`

Provides a high-level estimation of tax liability based on basic user input.

Inputs: income (number), state (string), filingStatus (string).

Returns: Promise<TaxEstimate>

interface TaxEstimate {
  estimatedTax: number;
  effectiveRate: number;
  takeHomePay: number;
  bracket: string;
  tips: string[];
}

`getChatResponse`

The primary interface for conversational AI, handling both Professor Ledger and FinMon interactions.

Inputs:
- history: (ChatMessage[]) The previous messages in the thread.
- userPrompt: (string) The new message from the user.
- userLevel: (number) The trainer's current level (affects Professor persona).
- finMonState: (FinMonState, optional) The current state of the pet (affects FinMon persona).

AI Persona Engineering

The service uses dynamic prompt engineering to swap "personalities" based on the application state.

Professor Ledger

Professor Ledger acts as the financial mentor. His personality evolves as the user gains experience points (Levels):

FinMon Personalities

The pet's personality is determined by its Evolution Stage and Mood:

Stage 1 (Egg): Communicates via wiggles and simple sounds.
Stage 2 (Baby): Speaks in broken English, obsessed with "shinies."
Stage 3 (Teen): Uses slang, confident, and cool.
Stage 4 (Master): Wise, grand, and legendary.

Memory & Learning Protocols

The service implements two custom protocols to allow the AI to "remember" and "learn" without a traditional database:

1. Memory Protocol

The AI scans responses for a specific tag: [[MEMORY:CATEGORY:CONTENT]].

Internal Logic: If the user mentions a goal (e.g., "I want to buy a car"), the AI generates a tag.
Persistence: The memoryService extracts these tags and saves them to local storage.
Recall: Future prompts include a [MEMORY CONTEXT] block to help the AI build long-term rapport.

2. Learning Protocol

When a user corrects a categorization (e.g., "Starbucks isn't 'Housing', it's 'Food'"), the learningService stores a rule. This rule is then fed back into the Gemini prompt as [LEARNED RULES], ensuring the AI does not repeat the same mistake.

Safety and Resilience

Financial Disclaimer: Every prompt includes a safety instruction. If asked for illegal acts or specific investment advice, the AI is programmed to provide a standardized disclaimer: "I cannot provide specific financial advice. Please consult a certified professional."
Error Handling: If the Gemini API fails or returns malformed JSON, the service returns a "Safe Default" object to prevent the UI from crashing, accompanied by an in-character message (e.g., "My scanners are malfunctioning!").