================================================================================
                           FinSim
          AI-Powered Investment Simulation & Education Platform
================================================================================


WHAT IS FINSIM?
───────────────────────────────────────────────────────────────────────

FinSim is a full-stack web application that teaches people how to make
smarter investment decisions — using real market data, artificial
intelligence, and interactive simulations.

Think of it as a personal investment training ground: you can chat with
an AI advisor, test your knowledge with scenario-based quizzes, predict
stock movements with a multi-agent AI engine, and even ask "what if I
had invested in Tesla 5 years ago?" and get the real math.

The platform is built for students, aspiring investors, and anyone who
wants to understand how financial markets work — without risking real
money.


CORE FEATURES
───────────────────────────────────────────────────────────────────────

1. USER AUTHENTICATION & DASHBOARD
   - Secure login/registration system
   - Personal dashboard showing quiz scores, accuracy stats, and
     recent performance
   - Tracks your learning progress over time

2. AI INVESTMENT ADVISOR (Chat)
   - A conversational AI chatbot powered by Groq's LLaMA 3.3 (70B)
   - Has access to live market data (real stock prices via yfinance)
     and web search (SerpAPI) for current news
   - Can answer questions about stocks, bonds, ETFs, portfolio
     strategy, and financial concepts
   - Can generate practice MCQ scenarios on demand

3. SCENARIO GENERATOR (Z-Score Pipeline)
   - Fetches 5 years of real historical stock prices from Yahoo Finance
   - Uses statistical analysis (Z-Scores via Polars) to detect
     significant market events and anomalies
   - Feeds those events into an AI model that generates realistic
     investment scenario questions with 4 multiple-choice answers
   - Each scenario includes a best answer with rationale and 3 wrong
     answers with explanations for why they're wrong
   - All scenarios are stored in a MySQL database

4. PRACTICE MCQ QUIZ SYSTEM
   - Timed quizzes with real-world investment scenarios
   - Configurable: choose number of questions and difficulty
   - Instant feedback after each answer with detailed explanations
   - Scores are tracked and contribute to your dashboard stats

5. LEADERBOARD
   - Competitive ranking across all users
   - Shows total score, quizzes taken, and average performance
   - Encourages engagement through friendly competition

6. AKINATOR 2.0 — Multi-Agent Investment Prediction Engine
   This is the flagship feature. A sophisticated AI system built with
   LangGraph (a graph-based AI orchestration framework) that runs
   9 interconnected processing nodes:

   - ROUTER: Classifies user queries and determines the processing path
   - WHAT-IF ENGINE: Analyzes hypothetical past investments using real
     historical data ("What if I invested $10K in Apple 3 years ago?")
   - ANALYST HUB: A ReAct agent that runs 5 expert tools in parallel:
       * Market Data Analyst (live prices, PE ratios, returns)
       * News & Sentiment Analyst (current headlines and market mood)
       * Risk Assessment Analyst (volatility, Sharpe ratio, drawdown)
       * Portfolio Strategy Advisor (allocation recommendations)
       * NewsAPI Headlines (dedicated news fetching)
   - NEWS SENTIMENT SCORER: Calculates a sentiment score (0-100) from
     real headlines using keyword-based analysis
   - CONFIDENCE SCORER: Rates the prediction's reliability (0-95%)
     based on data completeness and source alignment
   - SELF-CORRECTION (CRITIQUE): Reviews the prediction against the
     news sentiment — if the AI says "buy" but the news is bearish,
     it flags the contradiction with a correction note
   - JIT EDUCATION: Scans the response for financial jargon (P/E Ratio,
     Volatility, Sharpe Ratio, etc.) and provides plain-English
     definitions so beginners can learn as they read
   - INVESTMENT MEMO: Compiles the entire analysis into a professional
     summary document
   - FORMAT RESPONSE: Assembles everything into the final output

   Additionally, Akinator 2.0 features a "Panel Discussion Mode" where
   10 distinct investor personas (risk manager, quant, aggressive trader,
   value investor, macro economist, technical analyst, institutional
   banker, crypto enthusiast, behavioral psychologist, ESG advocate)
   debate the investment using real data before making a consensus
   recommendation.


TECHNOLOGY STACK
───────────────────────────────────────────────────────────────────────

Backend:
  - Python 3.12
  - FastAPI (web framework and REST API)
  - LangGraph (graph-based AI workflow orchestration)
  - LangChain (LLM integration and tool calling)
  - Groq API with LLaMA 3.3 70B Versatile (large language model)
  - yfinance (real-time and historical stock market data)
  - SerpAPI (live web search and news)
  - Polars (high-performance data processing, written in Rust)
  - MySQL (remote database for scenario storage)
  - bcrypt (password hashing)

Frontend:
  - Vanilla HTML, CSS, JavaScript (no frameworks)
  - marked.js (markdown rendering in chat)
  - Responsive dark-mode UI with glassmorphism design
  - Mobile-friendly with sidebar navigation

Infrastructure:
  - UV package manager (reproducible Python environments)
  - CapRover (remote MySQL hosting)


HOW IT ALL CONNECTS
───────────────────────────────────────────────────────────────────────

                    ┌─────────────────────┐
                    │    User Browser     │
                    │  (HTML/CSS/JS UI)   │
                    └────────┬────────────┘
                             │ HTTP
                             ▼
                    ┌─────────────────────┐
                    │   FastAPI Server    │
                    │      (app.py)       │
                    └────────┬────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
          ▼                  ▼                  ▼
   ┌─────────────┐  ┌──────────────┐  ┌──────────────┐
   │  AI Advisor  │  │  Akinator    │  │  Scenario    │
   │ (chat_agent) │  │  2.0 Graph   │  │  Generator   │
   │  ReAct Agent │  │  (9 nodes)   │  │  (Z-Scores)  │
   └──────┬──────┘  └──────┬───────┘  └──────┬───────┘
          │                │                  │
          ▼                ▼                  ▼
   ┌─────────────────────────────────────────────────┐
   │              External Services                   │
   │  Groq LLM  |  yfinance  |  SerpAPI  |  MySQL   │
   └─────────────────────────────────────────────────┘


WHAT MAKES THIS PROJECT SPECIAL
───────────────────────────────────────────────────────────────────────

1. Real Data, Not Simulations
   Unlike most educational tools that use fake numbers, FinSim pulls
   live stock prices, real news headlines, and actual historical data.
   Every prediction and scenario is grounded in reality.

2. Multi-Agent AI Architecture
   The Akinator 2.0 doesn't just call one AI model — it orchestrates
   multiple specialized "agents" (market analyst, risk assessor, news
   scanner, strategy advisor) that each gather different data, then
   synthesizes their findings into a unified recommendation.

3. Self-Correcting AI
   The system reviews its own predictions against current news
   sentiment. If there's a contradiction, it flags it automatically.
   This teaches users that even AI predictions need critical thinking.

4. Learning While Using
   The JIT Education system detects financial jargon in AI responses
   and explains terms in plain English. Users learn new financial
   vocabulary naturally as they interact with the system.

5. Graph-Based AI Orchestration
   Built with LangGraph, the Akinator uses a directed graph where
   data flows through 9 processing nodes with conditional branching.
   This is the same architecture used by production AI systems at
   companies like Google and OpenAI.

6. Full-Stack, Production-Quality
   User authentication, database persistence, responsive mobile UI,
   leaderboards, error handling, rate limit management — this isn't
   a prototype, it's a complete application.


================================================================================
  Built with Python, FastAPI, LangGraph, LangChain, Groq AI, and love.
================================================================================
