README.md

📚 Study Buddy — AI Knowledge Base

Upload your PDFs, notes, and articles — then chat with them, quiz yourself, and challenge your assumptions with Devil's Advocate mode.

Built for the Gemini API Hackathon using Gemini 2.5 Flash Lite + LangGraph + ChromaDB + FastAPI + DaisyUI.

---

✨ Features

Feature	Description
📄 PDF Ingestion	Upload any PDF — parsed, chunked, and embedded instantly
🔗 URL Scraping	Paste any article URL — scraped and stored in your knowledge base
📝 Paste Notes	Drop raw text directly with a custom label
💬 Normal Mode	Conversational Q&A sourced exclusively from YOUR notes
🎯 Quiz Mode	AI generates multiple-choice questions to test your knowledge
😈 Devil's Advocate	AI argues the OPPOSITE of your notes — challenges your thinking
📄 Export Chat as PDF	Download your full conversation as a formatted PDF report
🌙 Dark / Light Mode	Toggle themes with smooth transitions
⌨️ Keyboard Shortcuts	Full keyboard navigation for power users
🧠 Source Attribution	Every answer shows exactly which document it came from
💾 Persistent Storage	ChromaDB survives restarts — your brain stays intact

---

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl + K	Focus chat input
Ctrl + N	New chat
Ctrl + Q	Toggle Quiz mode
Ctrl + D	Toggle Devil's Advocate mode
Ctrl + E	Export chat as PDF
Ctrl + T	Toggle dark/light theme
Ctrl + ?	Show shortcuts panel
Esc	Close shortcuts panel

---

🚀 Quick Start

1. Navigate to the project

cd study-buddy

2. Create a virtual environment

python -m venv venv

# Windows
venv\Scripts\activate

# Mac/Linux
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Add your Gemini API key

copy .env.example .env
# Open .env and paste your GEMINI_API_KEY

Get a free key at: https://aistudio.google.com/app/apikey

5. Run the app

uvicorn api:app --reload --port 8000

Open http://localhost:8000 in your browser.

---

📁 Project Structure

study-buddy/
├── index.html        # Frontend UI (DaisyUI + animated canvas)
├── api.py            # FastAPI backend (REST endpoints)
├── graph.py          # LangGraph agent (retrieve → answer)
├── ingest.py         # Chunking + embedding pipeline
├── retriever.py      # Semantic search via ChromaDB
├── vectorstore.py    # ChromaDB client setup
├── requirements.txt  # Python dependencies
├── .env.example      # API key template
└── brain_db/         # Auto-created: persistent local vector database

---

🧩 How It Works

User uploads PDF / URL / Note
          ↓
    Parse raw text
          ↓
    Chunk into 200-word pieces (20-word overlap)
          ↓
    Embed via sentence-transformers (local, free)
          ↓
    Store in ChromaDB (persistent)
          ↓
User asks a question
          ↓
    Embed query locally
          ↓
    Cosine similarity → top 2 chunks retrieved
          ↓
    LangGraph passes context + mode to Gemini 2.5 Flash Lite
          ↓
    Answer generated with source attribution

---

🎭 Modes Explained

💬 Normal Mode

Standard RAG — answers come only from your uploaded documents. Nothing is hallucinated.

🎯 Quiz Mode (Ctrl+Q)

AI generates a multiple-choice question from your notes. Click an answer to get instant feedback with explanation. Great for exam prep.

😈 Devil's Advocate (Ctrl+D)

AI takes the opposite position of what your notes say. Forces you to defend your knowledge and think critically. The hardest — and most valuable — study mode.

---

🛠️ API Endpoints

Method	Endpoint	Description
POST	/ingest/pdf	Upload and embed a PDF
POST	/ingest/url	Scrape and embed a URL
POST	/ingest/text	Embed raw text with a label
POST	/ask	Ask a question (supports mode + system_prompt)
GET	/	Serve the frontend

---

🔧 Tech Stack

Layer	Technology
Generation	Gemini 2.5 Flash Lite (Google AI Studio)
Embeddings	sentence-transformers/all-MiniLM-L6-v2 (local)
Vector DB	ChromaDB (persistent local storage)
Agent	LangGraph (stateful retrieve → answer graph)
Backend	FastAPI + Uvicorn
Frontend	Vanilla HTML + DaisyUI + Tailwind CSS
Animations	CSS keyframes + Canvas particles
PDF Export	jsPDF (client-side)