🧠 MindReader AI AI-POWERED PERSONALITY SCANNER Answer honestly. The AI will do the judging.

An AI-powered personality scanner that analyzes behavioral decisions using Google Gemini and delivers funny, roast-heavy psychological breakdowns.

What if an AI could read your personality... and roast you at the same time? 💀

---

✨ Features

• 🧠 AI Personality Analysis: Contextual pattern analysis powered by Google Gemini.
• 🎯 8 Behavioral Questions: Carefully crafted dilemmas exploring everyday reactions and cognitive quirks.
• 💀 Roast-Heavy Reports: Generates witty, sarcastic, and relatable personality archetypes.
• 📊 Personality Trait Scores: Evaluates metrics like Overthinking, Self-Awareness, Risk Taking, and Pretending IDC.
• 🎯 Confidence Score: AI-calculated confidence percentage for each scan.
• 🎨 Modern Desktop GUI: Polished dark-mode desktop app built with CustomTkinter.
• 💻 Interactive CLI: Classic rich terminal interface with styled prompts and formatted panels.
• 📄 Auto-Saved Reports: Timestamped .txt reports automatically organized in data/reports/.
• 🧩 Clean OOP Architecture: Modular design separating presentation, state management, and AI analysis.

---

🎨 GUI

MindReader AI features a dedicated desktop application with an electric purple and cyan dark-mode aesthetic.

GUI Workflow

Welcome Screen
      ↓
Answer 8 Questions
      ↓
AI Mind Scanning (Non-blocking)
      ↓
Personality Reveal (Structured Cards & Stats)
      ↓
Saved Report & OS File Launcher

Key Highlights

• Smooth Navigation: Interactive option cards with keyboard support (1-5, Enter).
• Non-Blocking AI Calls: Background daemon thread prevents the interface from freezing during Gemini API requests.
• Visual Stats & Badges: Progress indicators for brain metrics and punchline reveal cards.
• Resilient Parsing: Automatic fallback to raw output if response formatting varies.

---

💻 CLI

The original rich terminal experience is preserved as a separate runnable option.

python cli.py

(or via python main.py --cli)

• Styled terminal rules and question panels using Rich.
• Fast interactive command-line selection.
• Immediate terminal printout and automatic file saving.

---

🤖 How It Works

User Answers
      ↓
Question Manager
      ↓
Gemini AI
      ↓
Personality Analysis
      ↓
Personality Report
      ↓
Saved TXT Report

1. User input: The user selects answers across 8 behavioral scenarios.
2. Context building: QuestionManager gathers answers into structured question/answer pairs.
3. AI evaluation: PersonalityAnalyzer constructs a structured prompt and queries Gemini.
4. Presentation & Storage: ReportGenerator formats the output, displays it via GUI/CLI, and writes a timestamped record to data/reports/.

---

🧩 Project Structure

MindReader-AI/
│
├── main.py              # Main launcher (GUI by default, CLI with --cli)
├── cli.py               # Dedicated standalone CLI entry point
├── requirements.txt     # Project dependencies
├── api.env              # Local Gemini API key configuration (gitignored)
├── test_gui.py          # Automated test suite
├── README.md            # Documentation
│
├── src/                 # Core backend logic
│   ├── analyzer.py      # PersonalityAnalyzer (Gemini API client)
│   ├── questions.py     # 8 behavioral questions dataset
│   ├── report.py        # ReportGenerator (report saving & sanitization)
│   └── config.py        # Environment & API key loader
│
├── gui/                 # Desktop GUI layer (CustomTkinter)
│   ├── app.py           # Top-level window manager & controller
│   ├── theme.py         # Color tokens, fonts, and layout constants
│   ├── parser.py        # Resilient AI report parser with raw fallback
│   ├── components.py    # Reusable card frames, option cards & stat bars
│   └── views/           # Application views
│       ├── welcome_view.py   # Screen 1: Welcome landing
│       ├── question_view.py  # Screen 2: Question carousel
│       ├── scanning_view.py  # Screen 3: Threaded AI scanner
│       └── result_view.py    # Screen 4: Personality reveal & actions
│
└── data/
    └── reports/         # Output directory for saved .txt reports

---

🛠️ Tech Stack

• Language: Python 3.10+
• AI Engine: Google Gemini API (google-genai)
• Desktop GUI: CustomTkinter
• Terminal UI: Rich
• Configuration: python-dotenv

---

🚀 Installation

1. Clone the repository

git clone https://github.com/bilal-dev-0x/MindReader-AI.git
cd MindReader-AI

2. Create and activate a virtual environment

Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure API Key

Create a file named api.env in the root directory:

GEMINI_API_KEY=your_actual_gemini_api_key_here

Note: Never commit api.env to version control. It is ignored by .gitignore.

---

▶️ Run

🎨 Desktop GUI

python main.py

💻 Terminal CLI

python cli.py

---

📄 Example Result

🧠 MINDREADER AI
SCAN COMPLETE ✓

TYPE:
Professional Overthinker™

📊 BRAIN STATS
Overthinking: 92%
Self-Awareness: 40%
Risk Taking: 15%
Pretending IDC: 99%

🤖 AI SAYS:
You claim you hate drama, but your brain writes 5-season Netflix scripts about a 2-second glance from a stranger.

🚨 CAUGHT:
Re-reading an unanswered text 14 times while pretending to have zero social anxiety.

💀 FINAL VERDICT:
A high-functioning lunatic who wants to rule the world, but only if nobody looks directly at them.

CONFIDENCE: 97%

(Generated from live Gemini analysis based on user responses)

---

📁 Reports

Every completed scan generates a timestamped text report saved in:

data/reports/
└── <UserName>_<YYYY-MM-DD_HH-MM-SS>.txt

In the desktop GUI, click OPEN REPORT on the result screen to open the saved file directly in your default text editor.

---

🎯 Project Purpose

This project was built to explore practical Python design principles:

• Integrating real-world LLM APIs (google-genai).
• Clean separation of concerns between backend logic and UI layers.
• Building modern dark-themed desktop UIs with CustomTkinter.
• Practical Object-Oriented Programming (OOP) in Python.

Disclaimer: MindReader AI is an entertainment experiment. Its personality interpretations are playful, AI-generated observations and do not constitute psychological assessments or diagnostic tools.

---

🔮 Future Ideas

• Extended behavioral scenarios and custom question packs.
• Trait radar/spider chart visualizations in the GUI.
• Exporting reports to PDF and JSON formats.
• Historical session comparisons.

---

👨‍💻 Author

Bilal Aslam

Computer Science Student | Python Developer | AI Enthusiast

---

⭐ Final CTA

If you enjoyed MindReader AI, consider giving the repository a ⭐!