Brilliant Muslim Arabic Lesson Recall

An interactive, AI-powered recall trainer built for learners of the Bayyinah Institute Dream curriculum. Type what you remember, let the app retrieve the relevant material, and get instant formative feedback.

Table of Contents

• Overview

• Stack

• Features

• Live Demo

• Getting Started

  • Clone the Repository
  • Install Dependencies
  • Environment Variables
  • Run Locally
  • Run Tests

• Architecture

• Contributing

• License

Overview

Brilliant Muslim’s Arabic Lesson Evaluator helps students shift from passive review to active recall. It embeds the Dream textbook as searchable vectors, evaluates free-text answers with large language models, and delivers color-coded feedback so you know exactly what to fix next.

Stack

Layer	Tech & Services
LLM / Eval	OpenAI GPT-4o · Gemini 2.5 Pro
Retrieval	FAISS vector store + LangChain RAG
Frontend	Streamlit
Hosting	Streamlit Community Cloud (demo)

Features

1. Lesson Browser – Flip through textbook units inside the app.

2. Active Recall Input – Type everything you remember; no multiple-choice crutches.

3. RAG Retrieval – Relevant textbook passages surface automatically.

4. AI Scoring – Your answer is graded on accuracy and completeness.

5. Granular Feedback

   • ✅ Correct points
   • ❌ Misunderstandings
   • ⚠️ Missed concepts
   • 💡 Actionable advice

Live Demo

Try it now → https://brilliant-muslim-ai-recall.streamlit.app/

Getting Started

Clone the Repository

git clone https://github.com/aatif-dawawala/arabic-lesson-eval.git
cd arabic-lesson-eval

Install Dependencies

pip install -r requirements.txt

Environment Variables

Create a .env or .streamlit/secrets.toml file:

OPENAI_API_KEY   = "your-openai-key"
GEMINI_API_KEY   = "your-gemini-key"

Run Locally

streamlit run streamlit_app.py

The app will open at http://localhost:8501.

Run Tests

pytest

Architecture

┌──────────────┐
│  Streamlit   │  ←– UI
└──────┬───────┘
       │ user prompt
┌──────▼─────────┐
│ LangChain RAG  │  ←– chunking & similarity search
└──────┬─────────┘
       │ relevant docs
┌──────▼─────────┐
│   LLM Scorer   │  ←– model
└──────┬─────────┘
       │ feedback JSON
┌──────▼─────────┐
│  Streamlit UI  │  ←– highlights & scores
└────────────────┘

Contributing

Pull requests are welcome—help us empower Arabic learners worldwide! Please follow the conventional commit style and open an issue first if you plan a large change.

License

This project is released under the MIT License – see LICENSE for details.

---

© 2025 Brilliant Muslim. By using this software you agree to our Privacy Policy.