StudyMate AI is a full-stack educational study assistant combining a FastAPI backend with a React (Vite) frontend. It provides Socratic AI tutoring grounded in the Feynman technique, multimodal document question answering (PDFs and image notes), automated quiz generation with interactive scoring and DOCX export, and Google Classroom course and assignment synchronization.
- Web Application: https://study-mate-ai-study-bot.vercel.app
- Intuitive Concept Breakdown: Explanations follow an intuitive structure: Intuition → Simple Example → Technical Details → Common Pitfalls → Quick Check Questions.
- Computer Science & AI/ML Disambiguation: Defaults terminology to CS and software engineering domains (e.g., RAG, LLM, CNN, DP, OS, GC) unless otherwise specified.
- Streaming Responses: Real-time token streaming using Server-Sent Events (
/api/ask). - Code Highlighting & Copy: Automatic code block syntax highlighting powered by Prism with one-click copy.
- Voice Interactions: Web Speech API voice input and text-to-speech audio narration.
- Chat History & Export: Persists sessions to Firebase Firestore (when signed in) and exports conversations to CSV or Word DOCX.
- Document Ingestion: Drag-and-drop document upload (
/api/upload) supporting:- PDF Documents: Fast text and page extraction via
PyPDF2. - Images & Handwritten Notes: Visual transcription and equation extraction via NVIDIA NIM
meta/llama-3.2-90b-vision-instruct.
- PDF Documents: Fast text and page extraction via
- In-Memory Document Indexing: Fast document referencing, listing, and removal (
/api/documents).
- AI-Generated Quizzes: Generates customized multiple-choice questions from uploaded course materials or user-defined topics (
/api/generate-quiz). - Configurable Difficulty & Length: Select question counts (3 to 20) and difficulty levels (
easy,medium,hard). - Resilient Fallback Mode: Automated deterministic quiz generation fallback when external LLM endpoints are unreachable or unconfigured.
- Detailed Results & Reports: Interactive review of correct answers, explanations, and downloadable Word DOCX reports.
- OAuth 2.0 Integration: Connect Google Classroom to browse enrolled courses, coursework assignments, and announcements.
- Drive Import: Direct download and parsing of lecture PDFs from Google Drive into StudyMate memory.
- Post Quizzes as Assignments: Publish generated quizzes back to Google Classroom courses.
- Interactive Demo Mode: Built-in sandbox mode for exploring Classroom UI workflows without requiring live Google cloud credentials.
- Google Sign-In: Authenticate with Firebase Authentication.
- Firestore Synchronization: Secure user-scoped cloud storage of chat history with granular Firestore security rules.
| Layer | Technology | Details |
|---|---|---|
| Backend Framework | FastAPI (Python 3.10+) | Uvicorn ASGI server, Pydantic v2 validation |
| Frontend Framework | React 18 & Vite 5 | Tailwind CSS v4, Lucide / Material Symbols |
| AI / LLM Endpoints | NVIDIA NIM API | Llama 3.1 70B Instruct & Llama 3.2 90B Vision |
| PDF Extraction | PyPDF2 | Stream-based text and page extraction |
| Classroom Integration | Google APIs Client | Google Classroom API v1 & Google Drive API v3 |
| Auth & Cloud DB | Firebase SDK | Firebase Auth & Cloud Firestore |
| Document Export | docx & file-saver | Word (.docx) and CSV report generation |
| Production Server | Gunicorn | Uvicorn worker process manager (Procfile) |
├── .devcontainer/ # DevContainer definition for VS Code and GitHub Codespaces
│ └── devcontainer.json
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI (backend tests & frontend build)
├── backend/
│ ├── .env.example # Backend environment variable template
│ ├── __init__.py
│ ├── google_classroom.py # Google Classroom and Drive API connector
│ └── main.py # FastAPI routes, AI streaming, quiz engine
├── frontend/
│ ├── public/ # Static assets (favicons)
│ ├── src/
│ │ ├── components/
│ │ │ ├── ChatInterface.jsx # Streaming chat, markdown & code renderer
│ │ │ ├── DocumentList.jsx # Uploaded document manager
│ │ │ ├── FileUpload.jsx # Drag-and-drop file uploader
│ │ │ ├── GoogleClassroom.jsx # Classroom courses & assignment sync
│ │ │ └── QuizGenerator.jsx # Quiz generation and grading UI
│ │ ├── App.jsx # Main dashboard and tab router
│ │ ├── firebase.js # Firebase authentication & Firestore client
│ │ └── main.jsx # React DOM root entrypoint
│ ├── package.json # Frontend dependencies and build scripts
│ ├── tailwind.config.js # Tailwind CSS theme configuration
│ └── vite.config.js # Vite bundler configuration & API proxy
├── tests/
│ └── test_api.py # Automated API integration test suite
├── .env.example # Root environment configuration template
├── .gitignore # Git ignore rules for Python, Node, and secrets
├── app.py # Root ASGI execution entrypoint
├── LICENSE # MIT License
├── Procfile # Production web process definition (Gunicorn)
├── pytest.ini # Pytest configuration
├── requirements.txt # Python backend dependencies
└── README.md # Project documentation
- Python: 3.10 or higher
- Node.js: 18.0 or higher
- npm: 9.0 or higher
- NVIDIA NIM API Key: Free developer keys available at build.nvidia.com (optional for local fallback mode).
git clone https://github.com/nfsprogramming/studymate-ai-study-bot.git
cd studymate-ai-study-bot-
Create a virtual environment (optional but recommended):
python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate
-
Install Python dependencies:
pip install -r requirements.txt
-
Configure environment variables:
cp backend/.env.example backend/.env
Edit
backend/.envand add your NVIDIA API key:NVIDIA_API_KEY=nvapi-your-key-here NVIDIA_VISION_API_KEY=nvapi-your-vision-key-here
-
Start the FastAPI backend server:
python app.py
The backend API will start at
http://localhost:8000. Interactive API documentation is available athttp://localhost:8000/docs.
- Navigate to the
frontend/directory and install dependencies:cd frontend npm install - Start the Vite development server:
The user interface will be accessible at
npm run dev
http://localhost:3000.
| Variable | Description | Required | Default |
|---|---|---|---|
NVIDIA_API_KEY |
Primary API key for NVIDIA NIM LLM inference (meta/llama-3.1-70b-instruct) |
Recommended | None (activates fallback mode) |
NVIDIA_VISION_API_KEY |
Key for vision models (meta/llama-3.2-90b-vision-instruct) |
Optional | Falls back to NVIDIA_API_KEY |
GOOGLE_CREDENTIALS |
JSON string of Google OAuth 2.0 Web Client credentials | Optional | Read from backend/credentials.json |
GOOGLE_TOKEN |
JSON string of stored Google OAuth access/refresh token | Optional | Read from backend/token.pickle |
Run the automated test suite using pytest:
pytestCompile and type-check the frontend production bundle:
cd frontend
npm run buildThe repository includes a Procfile for platforms such as Render, Railway, or Heroku:
web: gunicorn -w 4 -k uvicorn.workers.UvicornWorker backend.main:appThe frontend includes frontend/vercel.json for single-page application routing. Point your Vercel project root to the frontend directory with build command npm run build and output directory dist.
- In-Memory Document Index: Uploaded documents are indexed in-memory per worker process; restarting the server clears uploaded documents.
- External AI Dependency: Streaming chat and vision image extraction rely on NVIDIA NIM API endpoints; an internet connection and valid API credentials are required for live LLM responses.
- Google Classroom Verification: Access to live Google Classroom courses requires a configured Google Cloud OAuth 2.0 Client ID with educational scopes enabled.
- Fork the repository.
- Create a feature branch (
git checkout -b feature/amazing-feature). - Commit your changes (
git commit -m 'Add amazing feature'). - Ensure tests pass (
pytestandnpm run build). - Push to the branch (
git push origin feature/amazing-feature). - Open a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.