How khairu-aqsara/moodle-blocks_terusrag works
Project Type and Purpose
• This is a Moodle block plugin named “Terus RAG” that implements Retrieval-Augmented Generation (RAG) to allow users to query course content via large language models.
• It indexes course descriptions, summaries, and other content into a vector store (Moodle DB by default) and uses BM25 + cosine similarity for retrieval.
File Structure
• Top-level plugin files:
• block_terusrag.php (entry point)
• version.php, settings.php, lang/, templates/, styles.css, edit_form.php (Moodle block scaffolding)
• classes/ – core PHP classes:
• provider_interface.php – defines LLM provider abstraction
• gemini.php, openai.php, ollama.php – provider implementations
• bm25.php – ranking algorithm
• llm.php – shared vector operations
• task/datainitializer.php – scheduled task for indexing
• db/ – Moodle database schema and upgrade/install scripts
• amd/ – front-end JavaScript (raginterface.js) for interactive UI
• tests/ – PHPUnit tests for provider integrations
• utils/ – stopwords list
Review README Insights
• Explains integrations with three AI providers and their embedding pathways.
• Describes daily scheduled tasks and manual CLI execution.
Main Components
a. Content Layer
– Moodle Course Content (descriptions, summaries, activities)
– Content Extractor & Text Chunker (PHP task)
b. Embedding Layer
– AI Provider Adapter (interface + implementations)
– Embedding Models (Gemini, OpenAI, Ollama)
– Vector Storage (Moodle DB by default; optional ChromaDB/Supabase)
c. Query Layer
– UI Input (block rails + AMD JS)
– Query Processor & Embedding Generation
– Vector Search (BM25 + cosine similarity)
d. Response Layer
– Context Assembly
– AI Provider Chat API Calls
– Response Formatter & UI Display
Relationships and Data Flows
• From User Query → Front-end JS → Query Processor → Embedding Adapter → Vector Search → Retrieved Chunks → Context Assembly → AI Provider Chat API → Formatter → UI.
• Scheduled task flows separately from real-time query flows.
Architectural Patterns
• Layered architecture (four layers as above).
• Adapter pattern for AI providers (provider_interface + implementations).
• Hybrid retrieval pattern (BM25 + vector similarity).
• Plugin structure following Moodle block conventions.
Technologies, Frameworks, Libraries
• PHP 7.4+, Moodle 4.1+ plugin APIs
• JavaScript AMD module (raginterface.js)
• PHPUnit for testing
• External AI APIs: Gemini, OpenAI, Ollama
Final Advice
• Be very detailed: break down the scheduled task into sub-steps (scan, chunk, embed, store).
• Adapter Pattern for AI providers: one interface feeding multiple provider implementations.
• Hybrid ranking: BM25 + vector similarity as parallel retrieval paths merging into candidate selection.
• Don’t over-complicate: keep four main layers, then expand each into logical subcomponents.