How fuwad13/physics-chatbot works
Project Overview & Main Purpose
• This project is a full-stack chatbot focused on answering questions from Class 9-10 NCTB Physics textbooks.
• It employs a Retrieval-Augmented Generation (RAG) approach: first retrieving relevant physics documents from a vector database (Chroma) using embedding models, and then running locally hosted LLM models (via Ollama) to generate answers.
And Label Core Components
a. Frontend:
• Component: Chat User Interface
• File Reference: src/frontend/chat_ui.py (with initialization in src/frontend/__init__.py)
• Role: Presents the chat interface to end-users, collects user queries, and displays answers.
b. Backend:
• General Entry Point: main.py and config.py at the root for overall configuration.
• LLM and RAG Workflow:
• Located in src/backend/LLM where you see:
• The "chroma server" folder – this constitutes the vector database setup. The multiple subdirectories (identified by UUIDs) house binary files (data_level0.bin, header.bin, length.bin, link_lists.bin) that represent stored vectors and index metadata.
• The "llm-api" folder – likely a service endpoint or script (main.py inside it) that wraps around the LLM execution.
• The "data" folder under src/backend/LLM contains scripts for data ingestion (e.g., data_population.py) and reference QnA (reference_qna.py) as well as a reference PDF file.
c. Vector Database:
• Component: Chroma Server
• File/Folder Reference: src/backend/LLM/chroma server containing binary files and a chroma.sqlite3 file (which may store metadata or be used for persistence).
• Role: Stores document embeddings generated from physics content. It is crucial for retrieving relevant snippets when processing queries.
d. External LLM and Embeddings Service:
• Component: LLM Host (Ollama)
• Role: Provides locally hosted LLM models (like llama3.2, gemma2, mistral) used in combination with embedding models (e.g., all-MiniLM-L6-v2, nomic-embed-text) to process retrieval and generation.
• External services form part of the RAG pipeline and are indirectly referenced by the backend logic.
e. Testing and Evaluation:
• Component: Automated Testing Suite
• File/Folder Reference: testing/ (includes automated_testing.py, dataset curation scripts, and JSON datasets)
• Role: Validates system functionality, ensuring correct data flow and response generation.
Component Interactions and Data Flow
• User Interface (src/frontend) initiates a chat session by sending a query.
• The gateway (main.py at the root and within src/backend) receives this query and splits the workflow:
• It forwards the query to the vector database (Chroma Server) to retrieve relevant document snippets via embedding models.
• The retrieved context is sent, along with the original query, to the LLM API (in src/backend/LLM/llm-api) which interacts with the locally hosted LLMs (via Ollama) to generate the answer.
• Request from Frontend to Backend.
• Retrieval request from Backend to Chroma vector store.
• Processing step that involves external LLM models for answer generation.
• Response flow from Backend back to Frontend.
Architectural Patterns and Design Principles
• RAG Workflow: Clearly design the pipeline that decouples document retrieval from natural language generation.
• Modularity: Separate components for UI, backend processing, database interactions (chroma server), and LLM interfacing.
• Extensibility: Highlight the modular directory structure that enables additions like new embedding models, further API endpoints (e.g., in llm-api), or testing modules.