🎓 Study Buddy AI

An agentic AI application that acts as your personal study assistant. Upload your syllabus, chat with AI agents, get personalized study plans, and track your progress.

---

✨ Features

• 📄 Syllabus Upload & Parsing — Upload PDF syllabi, auto-extract topics, index for semantic search
• 💬 Agentic Chat — Multi-agent system with intelligent routing (Planner, Assignment Helper, Memory)
• 📅 Study Plan Generator — AI-powered personalized study schedules with weighted topic distribution
• 📊 Attendance Tracker — Track class attendance, get percentage warnings, AI-powered advice
• 🧠 Conversation Memory — RAG-based context retrieval across chat sessions

---

🏗️ Architecture

User → Streamlit UI → FastAPI Backend
                          │
                    ┌──────┴──────┐
                    │ Orchestrator │ (routes to correct agent)
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        PlannerAgent  AssignmentAgent  MemoryAgent
              │            │            │
              └────────────┼────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
           ChromaDB     SQLite       Redis
          (vectors)   (structured)  (cache)

---

🛠️ Tech Stack

Technology	Purpose	Why
Python 3.11+	Core language	Industry standard for AI
FastAPI	Backend API	Async-first, auto API docs
Streamlit	Frontend UI	Python-native, rapid iteration
SQLite	Primary database	Zero-config, SQL practice
ChromaDB	Vector database	Local RAG, zero API cost
Redis	Cache + queue	Industry-standard (optional, falls back to memory)
Groq API	LLM inference	Ultra-fast inference with Llama 3.3 70B

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Git
• Groq API key (get one free)
• Redis (optional — app works without it)

Installation

# 1. Clone repository
git clone https://github.com/yourusername/study-buddy.git
cd study-buddy

# 2. Create virtual environment
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate    # macOS/Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
copy .env.example .env
# Edit .env and add your GROQ_API_KEY

# 5. Start FastAPI backend (Terminal 1)
uvicorn api.main:app --reload --port 8000

# 6. Start Streamlit frontend (Terminal 2)
streamlit run app.py

# 7. Open http://localhost:8501

Quick Test

# Run all tests
pytest tests/ -v

# Test PDF parsing
python -c "from api.services.pdf_parser import parse_pdf; print('Parser OK')"

# Test vector store
python -c "from api.services.vector_store import VectorStore; s = VectorStore(); print(f'VectorStore OK: {s.get_document_count()} docs')"

---

📁 Project Structure

study-buddy/
├── app.py                          ← Streamlit UI (main frontend)
├── api/
│   ├── main.py                     ← FastAPI app entry point
│   ├── routes/
│   │   ├── chat.py                 ← POST /chat/message
│   │   ├── documents.py            ← POST /documents/upload
│   │   ├── planner.py              ← POST /planner/generate
│   │   └── attendance.py           ← GET/POST /attendance
│   ├── agents/
│   │   ├── base_agent.py           ← Abstract base class
│   │   ├── orchestrator.py         ← Routes to correct agent
│   │   ├── planner_agent.py        ← Study schedule generator
│   │   ├── assignment_agent.py     ← Homework helper
│   │   └── memory_agent.py         ← Past conversation retrieval
│   ├── services/
│   │   ├── llm_service.py          ← Groq API wrapper
│   │   ├── pdf_parser.py           ← PDF text extraction
│   │   ├── vector_store.py         ← ChromaDB operations
│   │   ├── cache_service.py        ← Redis + in-memory cache
│   │   ├── study_planner.py        ← Scheduling algorithm
│   │   └── embeddings.py           ← Embedding abstraction
│   ├── models/
│   │   ├── database.py             ← SQLite/SQLAlchemy setup
│   │   ├── user.py                 ← User model
│   │   ├── subject.py              ← Subject model
│   │   ├── study_plan.py           ← Study plan model
│   │   └── attendance.py           ← Attendance model
│   └── core/
│       ├── config.py               ← Environment config
│       └── dependencies.py         ← FastAPI DI
├── data/
│   ├── uploads/                    ← Uploaded PDFs
│   └── chroma/                     ← Vector DB storage
├── tests/
│   ├── test_agents.py
│   ├── test_pdf_parser.py
│   └── test_vector_store.py
├── requirements.txt
├── .env.example
└── .gitignore

---

🔑 Environment Variables

# Required
GROQ_API_KEY=gsk_xxxxx            # Get from console.groq.com

# Optional (has defaults)
GROQ_MODEL=llama-3.3-70b-versatile
GROQ_FAST_MODEL=llama-3.1-8b-instant
DATABASE_URL=sqlite:///./data/study_buddy.db
REDIS_HOST=localhost
REDIS_PORT=6379
CHROMA_PATH=./data/chroma
DEBUG=True

---

📖 API Documentation

Once the backend is running, visit http://localhost:8000/docs for interactive Swagger documentation.

Key Endpoints

Method	Endpoint	Description
POST	/chat/message	Send message to agentic chat system
POST	/documents/upload	Upload and index a syllabus PDF
GET	/documents/list	List all uploaded documents
POST	/planner/generate	Generate a study plan
GET	/planner/{user_id}	Get all plans for a user
POST	/attendance/mark	Mark class attendance
GET	/attendance/{user_id}/{subject_id}	Get attendance stats

---

🧪 Testing

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_pdf_parser.py -v

# Run with coverage
pytest tests/ -v --cov=api

---

🚀 Deployment

Streamlit Cloud (Frontend)

1. Push to GitHub
2. Go to share.streamlit.io
3. Connect your repo
4. Add GROQ_API_KEY in Streamlit secrets

Railway (Backend)

1. Push to GitHub
2. Connect to railway.app
3. Add environment variables
4. Update API_URL in app.py

---

📈 Future Improvements

• Quiz Generator Agent
• Google Calendar integration
• Spaced repetition (SM-2 algorithm)
• Collaborative study groups
• Mobile-responsive React frontend
• Multi-user authentication (OAuth2)

---

Built with ❤️ using FastAPI • Streamlit • SQLite • ChromaDB • Redis • Groq API (Llama 3.3 70B)