How lelekhoa1812/studybuddy works
Project Type & Purpose
• EdSummariser (StudyBuddy) is a modular, full-stack Retrieval-Augmented Generation (RAG) application built in Python with FastAPI. Its primary function is to ingest user documents (PDF/DOCX), index them via embeddings, and answer user queries by retrieving context and composing answers via LLMs, while maintaining per‐user memory.
Top-Level Components
A. FastAPI App (app.py + routes/)
• Central orchestration, HTTP interface
• Routes grouped by function: auth, projects, upload, data, chat, report, health
B. Ingestion Subsystem (utils/ingestion + helpers/pages)
• PDF/DOCX parser → image extraction → optional BLIP captioning
• Chunker (cards) → embedder (sentence-transformers) → storage in vector DB
C. RAG Store & Vector Search (utils/rag + MongoDB)
• Embeddings pipeline
• Storage backend: Mongo Atlas (with Atlas Vector Search) or local cosine index
D. Retrieval & Relevance Classification (routes/chat + utils/api/rotator/router)
• Filename detection → NVIDIA relevance classifier → restrict vector queries
• Retry logic & summary fallbacks
E. Memory System (memo/)
• LRU per-user memory summaries
• Components: context, conversation, history, sessions, planning, retrieval
F. Reasoning & LLM Integration (utils/api + utils/service)
• Key rotation (NVIDIA_API_1..5 / GEMINI_* ) via api/rotator/router
• Summarizer, PDF report generator in service/
G. Data Storage & Config
• MongoDB document store + vector index
• Config via environment (MONGO_URI, vector index flags, model overrides)
Data-Flow Workflow (detailed backend focus)
1) Upload Endpoint (/upload)
→ app.py calls ingestion orchestrator
→ utils/ingestion/parser.py extracts pages
→ helpers/pages.py merges images + captions (BLIP via utils/api)
→ ingestion/chunker.py splits into cards
→ rag/embeddings.py computes embeddings
→ rag/rag.py stores vectors + metadata in MongoDB
2) Chat Endpoint (/chat)
→ routes/chats.py receives question + user context
→ memo/session.py loads recent-memory summaries
→ namer.py detects filenames in query
→ utils/api/router.py calls NVIDIA classifier for per-file relevance
→ rag/rag.py performs vector search with restricted file list
• on zero hits → retry phases → fallback to file-level summaries
→ Compose prompt: context + retrieved chunks + memory + question
→ utils/api/router.py dispatch to LLM (Gemini/NVIDIA) with key rotation
→ routes/chats.py returns answer + sources + relevant_files
→ memo/history.py + memo/conversation.py update memory
3) Report Generation (/report)
→ routes/reports.py applies Gemini CoT filter via utils/service/summarizer.py
→ utils/service/pdf.py renders PDF
Architectural Patterns & Design Principles
• Modular Monolith: separate concerns into directories (routes, utils, memo, helpers)
• Pipeline Architecture for ingestion & retrieval
• Layered approach:
1) HTTP Layer (FastAPI routes)
2) Orchestration Layer (app.py, helpers/setup.py)
3) Domain Services (utils/ingestion, utils/rag, utils/service)
4) Data Layer (MongoDB + vector index)
• External Service Integration: BLIP for captions, NVIDIA for classification, LLM endpoints