Moodle Student Tracker

The Moodle Student Tracker is an innovative solution that leverages a chat-based teaching approach to enhance academic success. This tool indexes course materials, lectures, grades, and attendance from Moodle, providing real-time insights through an easy-to-use Telegram interface. Utilizing the latest in Retrieval-Augmented Generation (RAG) technology, this bot streamlines learning and supports students in navigating their educational resources effectively.

Features

• Chat-first Learning: Students can select a course and ask questions, receiving pedagogical responses based on materials.
• Hybrid RAG Technology: Combines FAISS (semantic search) and BM25 (keyword search) using Reciprocal Rank Fusion for optimal results.
• Teaching/Guidance Modes: When adequate materials are available, the bot teaches; if not, it redirects students to relevant topics.
• Multi-Course Support: Allows users to choose their active courses easily.
• Moodle Synchronization: Automatically fetches and indexes materials via the Moodle API.
• Admin Document Upload: Supports PDF, DOCX, and PPTX uploads directly through Telegram for indexing.
• Multi-provider LLM Routing: Routes tasks to the appropriate models (Gemini, OpenAI, GLM) based on context.
• Conversation Memory: Retains recent messages to maintain context in conversations.
• Rate Limiting: Implements user-based request limitations for better performance.
• Health Checks: Supports an HTTP /health endpoint to monitor uptime and active users.
• Deployment Flexibility: Facilitates Docker and systemd deployment options.

Architecture

The bot follows a layered architecture design, ensuring clear separation of concerns:

                          Telegram API
                              |
                       bot/main.py
                       (Application wiring)
                              |
               +--------------+--------------+
               |                             |
      bot/handlers/                   bot/middleware/
      commands.py                     auth.py
      messages.py                     error_handler.py
               |
      bot/services/
      rag_service.py ---------> core/vector_store.py  (FAISS + BM25)
      llm_service.py ---------> core/llm_engine.py    (Multi-provider LLM)
      user_service.py            core/llm_providers.py  (Adapter pattern)
      document_service.py        core/moodle_client.py  (Moodle REST API)
      topic_cache.py             core/sync_engine.py    (Material pipeline)
      conversation_memory.py     core/document_processor.py (PDF/DOCX/PPTX)

Message Flow

The interaction process delineated below illustrates how user messages are processed:

User Message
    |
    v
[Rate Limit Check] ---x---> "You are sending messages too quickly"
    |
    v
[Active Course Check] ---x---> "Please select a course: /courses"
    |
    v
[Load Conversation History]
    |
    v
[Hybrid RAG Search]
  FAISS (semantic) + BM25 (keyword)
  --> Reciprocal Rank Fusion (k=60)
  --> Adaptive threshold: max(top_score * 0.60, 0.20)
    |
    v
[Is there sufficient material?]
   (chunk count >= RAG_MIN_CHUNKS
   and similarity >= RAG_SIMILARITY_THRESHOLD)
   /              \
  Yes            No
  |                 |
  v                 v
Teaching          Guidance
Mode              Mode
  |                 |
  v                 v
LLM: produces      LLM: recommends current topics
context-based pedagogical
responses            + example questions
  |                 |
  +--------+--------+
           |
           v
  [Save to conversation history]
           |
           v
  [Send to Telegram with Markdown]

Interactive Modes

• Teaching Mode: When adequate resources are available, the bot generates pedagogical answers while maintaining the professor's terminology. It labels source files in brackets like [file.pdf]. It avoids generating misleading content by clearly stating when information is not available.

  

• Guidance Mode: If resources are insufficient, the bot redirects students without technical details, offering suggestions for existing topics.

Screenshots

Teaching Mode	Material Selection

Lessons Explained with RAG	Upcoming Exams

Attendance Information	Grades

Quick Start

1. Clone the project:

   git clone https://github.com/onurcangnc/Moodle_Student_Tracker.git
   cd Moodle_Student_Tracker
   

2. Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # Linux/Mac
   # venv\Scripts\activate  # Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   # or
   make install
   

4. Configure the .env file:

   cp .env.example .env
   

5. Run the application:

   python -m bot.main
   # or
   make run
   

Technology Stack

The project employs a robust technology stack including Python, semantic and keyword search capabilities, as well as multi-provider LLM models, ensuring a seamless and efficient experience for users while interacting with their Moodle materials.