Initial commit — MCQ Generator with T5 + NER + WordNet

.gitignore

@@ -0,0 +1,25 @@
+# Virtual environment
+myenv/
+venv/
+env/
+
+# Model files (too large for GitHub)
+models/
+*.bin
+*.pt
+*.safetensors
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# HuggingFace cache
+.cache/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Jupyter checkpoints
+.ipynb_checkpoints/

__init__.py

@@ -0,0 +1 @@
+# Makes src/ a Python package

app/__init__.py

@@ -0,0 +1 @@
+# Makes app/ a Python package

app/components.py

@@ -0,0 +1,115 @@
+# ─────────────────────────────────────────────
+#  app/components.py
+#  Reusable Streamlit UI building blocks.
+#  Keeps main.py clean and focused on flow logic.
+# ─────────────────────────────────────────────
+
+import streamlit as st
+from src.mcq_builder import MCQ
+
+
+def render_question_card(mcq: MCQ, index: int) -> str | None:
+    """
+    Render a question with labelled radio button options.
+    Returns the selected option label ("A"/"B"/"C"/"D") or None.
+    """
+    st.markdown(f"### Q{index + 1}. {mcq.question}")
+
+    # Build labelled options: ["A. Paris", "B. London", ...]
+    labelled_options = [f"{chr(65+i)}. {opt}" for i, opt in enumerate(mcq.options)]
+
+    # Restore previous selection if user came back to this question
+    prev_index = st.session_state.user_answers[index]
+    default    = prev_index if prev_index >= 0 else 0
+
+    selected = st.radio(
+        label     = "Select your answer:",
+        options   = labelled_options,
+        index     = default,
+        key       = f"q_{index}",
+        label_visibility = "collapsed",
+    )
+
+    # Return just the letter ("A", "B", etc.)
+    return selected[0] if selected else None
+
+
+def render_result_card(result: dict, question_num: int):
+    """
+    Render a single question's result with colour coding.
+    Green = correct, Red = wrong.
+    """
+    is_correct = result["is_correct"]
+    icon       = "✅" if is_correct else "❌"
+    color      = "#d4edda" if is_correct else "#f8d7da"
+    border     = "#28a745" if is_correct else "#dc3545"
+
+    with st.container():
+        st.markdown(
+            f"""
+            <div style="
+                background-color: {color};
+                border-left: 4px solid {border};
+                padding: 12px 16px;
+                border-radius: 6px;
+                margin-bottom: 12px;
+            ">
+                <b>{icon} Q{question_num}: {result['question']}</b>
+            </div>
+            """,
+            unsafe_allow_html=True,
+        )
+
+        col1, col2 = st.columns(2)
+        with col1:
+            st.write(f"**Your answer:** {result['your_answer']}")
+        with col2:
+            if not is_correct:
+                st.write(f"**Correct answer:** {result['correct_answer']}")
+            else:
+                st.write("**Correct!**")
+
+        with st.expander("See explanation"):
+            st.info(result["explanation"])
+
+
+def render_score_summary(result: dict):
+    """
+    Render the score banner at the top of the results screen.
+    """
+    score      = result["score"]
+    total      = result["total"]
+    percentage = result["percentage"]
+    feedback   = result["feedback"]
+
+    # Choose colour based on score
+    if percentage >= 80:
+        color = "#d4edda"; border = "#28a745"
+    elif percentage >= 60:
+        color = "#fff3cd"; border = "#ffc107"
+    else:
+        color = "#f8d7da"; border = "#dc3545"
+
+    st.markdown(
+        f"""
+        <div style="
+            background-color: {color};
+            border: 2px solid {border};
+            border-radius: 10px;
+            padding: 20px 24px;
+            text-align: center;
+        ">
+            <h2 style="margin:0">{score} / {total}</h2>
+            <h4 style="margin:4px 0">{percentage}%</h4>
+            <p style="margin:0; color: #555">{feedback}</p>
+        </div>
+        """,
+        unsafe_allow_html=True,
+    )
+
+    # Metric columns for quick glance
+    st.markdown("<br>", unsafe_allow_html=True)
+    c1, c2, c3 = st.columns(3)
+    c1.metric("Correct",   score)
+    c2.metric("Wrong",     total - score)
+    c3.metric("Score",     f"{percentage}%")

app/main.py

@@ -0,0 +1,239 @@
+# ─────────────────────────────────────────────
+#  app/main.py
+#  Streamlit UI — the full interactive quiz app.
+#
+#  Run with:  streamlit run app/main.py
+#
+#  Three screens:
+#    1. INPUT   → user pastes a passage, picks # of questions
+#    2. QUIZ    → one question at a time with radio buttons
+#    3. RESULTS → score + per-question feedback
+# ─────────────────────────────────────────────
+
+import streamlit as st
+import sys, os
+
+# Make sure we can import from project root
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from config import APP_TITLE, APP_ICON, MAX_QUESTIONS
+from src.mcq_builder import build_quiz
+from src.evaluator   import score_quiz
+from app.components  import render_question_card, render_result_card, render_score_summary
+
+
+# ─────────────────────────────────────────────
+#  PAGE CONFIG — must be first Streamlit call
+# ─────────────────────────────────────────────
+
+st.set_page_config(
+    page_title = APP_TITLE,
+    page_icon  = APP_ICON,
+    layout     = "centered",
+)
+
+
+# ─────────────────────────────────────────────
+#  SESSION STATE INITIALISATION
+#  st.session_state persists values across reruns.
+#  Think of it as the app's memory.
+# ─────────────────────────────────────────────
+
+def init_state():
+    defaults = {
+        "screen"       : "input",   # "input" | "quiz" | "results"
+        "mcqs"         : [],        # list of MCQ objects
+        "current_q"    : 0,         # index of current question
+        "user_answers" : [],        # user's selected option indices
+        "quiz_result"  : None,      # scored result dict
+    }
+    for key, val in defaults.items():
+        if key not in st.session_state:
+            st.session_state[key] = val
+
+init_state()
+
+
+# ─────────────────────────────────────────────
+#  HELPER: reset to start a new quiz
+# ─────────────────────────────────────────────
+
+def reset():
+    st.session_state.screen       = "input"
+    st.session_state.mcqs         = []
+    st.session_state.current_q    = 0
+    st.session_state.user_answers = []
+    st.session_state.quiz_result  = None
+
+
+# ─────────────────────────────────────────────
+#  SCREEN 1: INPUT
+#  User pastes a passage and hits "Generate Quiz"
+# ─────────────────────────────────────────────
+
+def screen_input():
+    st.title(f"{APP_ICON} {APP_TITLE}")
+    st.write("Paste any text passage below to automatically generate a quiz from it.")
+
+    st.info(
+        "**For best results**, use factual passages containing: "
+        "**people names, places, dates, organisations, or events.**  \n"
+        "Try: history, science, geography, biographies.  \n"
+        "Avoid opinion or purely descriptive text — they lack named facts."
+    )
+
+    st.markdown("---")
+
+    passage = st.text_area(
+        label       = "Your passage",
+        placeholder = "Paste a paragraph or article here...",
+        height      = 250,
+        help        = "Minimum ~5 sentences recommended for best results.",
+    )
+
+    num_questions = st.slider(
+        label   = "Number of questions",
+        min_value = 3,
+        max_value = MAX_QUESTIONS,
+        value     = 5,
+        step      = 1,
+    )
+
+    st.markdown("---")
+
+    if st.button("Generate Quiz", type="primary", use_container_width=True):
+        if not passage or len(passage.split()) < 30:
+            st.warning("Please paste a longer passage (at least ~30 words).")
+            return
+
+        with st.spinner("Generating questions... this may take 30–60 seconds on first run."):
+            try:
+                mcqs = build_quiz(passage, num_questions=num_questions)
+            except Exception as e:
+                st.error(f"Something went wrong: {e}")
+                return
+
+        if not mcqs:
+            st.error("Could not generate questions from this passage. Try a different text.")
+            return
+
+        # Store in session and move to quiz screen
+        st.session_state.mcqs         = mcqs
+        st.session_state.user_answers = [-1] * len(mcqs)  # -1 = unanswered
+        st.session_state.current_q    = 0
+        st.session_state.screen       = "quiz"
+        st.rerun()
+
+
+# ─────────────────────────────────────────────
+#  SCREEN 2: QUIZ
+#  One question at a time, with navigation.
+# ─────────────────────────────────────────────
+
+def screen_quiz():
+    mcqs      = st.session_state.mcqs
+    current   = st.session_state.current_q
+    total     = len(mcqs)
+    mcq       = mcqs[current]
+
+    # Progress bar
+    st.progress((current) / total, text=f"Question {current+1} of {total}")
+    st.markdown("---")
+
+    # Render the question card (defined in components.py)
+    selected_label = render_question_card(mcq, current)
+
+    st.markdown("---")
+
+    col1, col2, col3 = st.columns([1, 2, 1])
+
+    # Previous button
+    with col1:
+        if current > 0:
+            if st.button("← Previous"):
+                st.session_state.current_q -= 1
+                st.rerun()
+
+    # Next / Submit button
+    with col3:
+        # Convert selected label (A/B/C/D) back to index
+        if selected_label:
+            selected_index = ord(selected_label) - ord("A")
+            st.session_state.user_answers[current] = selected_index
+
+        if current < total - 1:
+            if st.button("Next →", type="primary"):
+                if selected_label is None:
+                    st.warning("Please select an answer before continuing.")
+                else:
+                    st.session_state.current_q += 1
+                    st.rerun()
+        else:
+            # Last question — show Submit button
+            if st.button("Submit Quiz", type="primary"):
+                if selected_label is None:
+                    st.warning("Please select an answer before submitting.")
+                else:
+                    # Score the quiz
+                    result = score_quiz(
+                        st.session_state.mcqs,
+                        st.session_state.user_answers
+                    )
+                    st.session_state.quiz_result = result
+                    st.session_state.screen      = "results"
+                    st.rerun()
+
+    # Show quit option
+    with col2:
+        if st.button("Quit Quiz", help="Return to the input screen"):
+            reset()
+            st.rerun()
+
+
+# ─────────────────────────────────────────────
+#  SCREEN 3: RESULTS
+#  Score summary + per-question breakdown
+# ─────────────────────────────────────────────
+
+def screen_results():
+    result = st.session_state.quiz_result
+
+    st.title("Quiz Complete!")
+    st.markdown("---")
+
+    # Score summary banner
+    render_score_summary(result)
+
+    st.markdown("---")
+    st.subheader("Question-by-question breakdown")
+
+    # Per-question result cards
+    for i, r in enumerate(result["results"]):
+        render_result_card(r, i + 1)
+
+    st.markdown("---")
+
+    col1, col2 = st.columns(2)
+    with col1:
+        if st.button("Try Another Passage", use_container_width=True):
+            reset()
+            st.rerun()
+    with col2:
+        if st.button("Retake Same Quiz", type="primary", use_container_width=True):
+            # Reset answers but keep the same MCQs
+            st.session_state.user_answers = [-1] * len(st.session_state.mcqs)
+            st.session_state.current_q    = 0
+            st.session_state.screen       = "quiz"
+            st.rerun()
+
+
+# ─────────────────────────────────────────────
+#  ROUTER — picks which screen to show
+# ─────────────────────────────────────────────
+
+if st.session_state.screen == "input":
+    screen_input()
+elif st.session_state.screen == "quiz":
+    screen_quiz()
+elif st.session_state.screen == "results":
+    screen_results()

config.py

@@ -0,0 +1,42 @@
+# ─────────────────────────────────────────────
+#  config.py  –  Central settings for MCQ Generator
+#  Change values here to tune the whole project.
+# ─────────────────────────────────────────────
+
+# ── Model settings ──────────────────────────
+# T5 model fine-tuned on SQuAD for question generation
+# "highlight" format: answer is wrapped in <hl> tags in the input
+QG_MODEL_NAME = "valhalla/t5-small-qg-hl"
+
+# spaCy English model for NLP preprocessing
+SPACY_MODEL = "en_core_web_sm"
+
+# ── Pipeline settings ───────────────────────
+# How many top-ranked sentences to pick questions from
+TOP_SENTENCES = 7
+
+# Maximum number of MCQs to generate from one passage
+MAX_QUESTIONS = 10
+
+# Minimum sentence length (in words) to be considered for a question
+MIN_SENTENCE_LENGTH = 8
+
+# Number of wrong options (distractors) per question
+NUM_DISTRACTORS = 3
+
+# ── Distractor generation strategy ──────────
+# Order of strategies tried. First one that returns enough distractors wins.
+# Options: "wordnet", "sense2vec", "ner"
+DISTRACTOR_STRATEGIES = ["wordnet", "ner", "sense2vec"]
+
+# ── Paths ────────────────────────────────────
+# Path to GloVe vectors file (download separately if using sense2vec)
+# Download: https://nlp.stanford.edu/projects/glove/
+GLOVE_PATH = "models/glove.6B.100d.txt"
+
+# Path to sample passages for testing
+SAMPLE_DATA_PATH = "data/sample_passages.json"
+
+# ── UI settings ──────────────────────────────
+APP_TITLE = "MCQ Generator"
+APP_ICON  = "📝"

data/sample_passages.json

@@ -0,0 +1,27 @@
+[
+  {
+    "id": 1,
+    "topic": "ISRO",
+    "text": "The Indian Space Research Organisation (ISRO) was founded in 1969 by Vikram Sarabhai. It is headquartered in Bengaluru, Karnataka. ISRO developed India's first satellite, Aryabhata, which was launched in 1975. The Chandrayaan-1 mission in 2008 discovered water molecules on the Moon. In 2023, Chandrayaan-3 successfully landed near the lunar south pole, making India the fourth country to achieve a Moon landing. The Mars Orbiter Mission, also called Mangalyaan, was launched in 2013 and made India the first Asian country to reach Martian orbit."
+  },
+  {
+    "id": 2,
+    "topic": "Photosynthesis",
+    "text": "Photosynthesis is a process used by plants and other organisms to convert light energy into chemical energy stored in glucose. It takes place primarily in the chloroplasts of plant cells, which contain a green pigment called chlorophyll. The overall equation for photosynthesis is: carbon dioxide plus water, in the presence of light, produces glucose and oxygen. Photosynthesis has two main stages: the light-dependent reactions and the Calvin cycle. The light-dependent reactions occur in the thylakoid membranes, while the Calvin cycle takes place in the stroma."
+  },
+  {
+    "id": 3,
+    "topic": "Mahatma Gandhi",
+    "text": "Mahatma Gandhi was born on October 2, 1869, in Porbandar, Gujarat, India. He studied law in London and later worked as a lawyer in South Africa, where he first developed his method of nonviolent resistance called Satyagraha. Returning to India in 1915, Gandhi became a leading figure in the Indian independence movement against British rule. He led major campaigns such as the Non-Cooperation Movement in 1920 and the Salt March in 1930. Gandhi was assassinated on January 30, 1948, by Nathuram Godse. He is widely regarded as the Father of the Nation in India."
+  },
+  {
+    "id": 4,
+    "topic": "Artificial Intelligence",
+    "text": "Artificial intelligence is the simulation of human intelligence processes by computer systems. Machine learning is a subset of AI that enables systems to learn from data without being explicitly programmed. Deep learning, a subset of machine learning, uses neural networks with many layers to analyse patterns in data. Natural language processing allows computers to understand and generate human language. AI applications include image recognition, speech recognition, autonomous vehicles, and medical diagnosis. The term artificial intelligence was coined by John McCarthy in 1956 at the Dartmouth Conference."
+  },
+  {
+    "id": 5,
+    "topic": "Water Cycle",
+    "text": "The water cycle, also known as the hydrological cycle, describes the continuous movement of water on, above, and below the Earth's surface. The main processes involved are evaporation, condensation, precipitation, and collection. Evaporation occurs when water from oceans, lakes, and rivers is heated by the sun and turns into water vapour. This vapour rises into the atmosphere and cools, forming clouds through condensation. When clouds become heavy enough, water falls back to Earth as precipitation in the form of rain, snow, or hail. The water then collects in oceans, rivers, and groundwater, and the cycle begins again."
+  }
+]

requirements.txt

@@ -0,0 +1,23 @@
+# MCQ Generator — Python dependencies
+# Install with: pip install -r requirements.txt
+
+# ── Core NLP ──────────────────────────────────
+spacy==3.7.4
+nltk==3.8.1
+
+# ── Transformers (T5 for question generation) ─
+transformers==4.38.2
+torch==2.2.1          # CPU version — change to torch==2.2.1+cu118 for GPU
+
+# ── Word Embeddings ───────────────────────────
+gensim==4.3.2         # Word2Vec / GloVe loading
+
+# ── ML utilities ─────────────────────────────
+scikit-learn==1.4.1.post1   # TF-IDF vectorizer
+numpy==1.26.4
+
+# ── UI ────────────────────────────────────────
+streamlit==1.33.0
+
+# ── Utilities ─────────────────────────────────
+pandas==2.2.1         # Useful for data inspection in notebooks

src/distractor_generator.py

@@ -0,0 +1,154 @@
+# ─────────────────────────────────────────────
+#  src/distractor_generator.py  (v3)
+#  Distractors MUST be the same entity type
+#  as the correct answer.
+#  e.g. answer=PERSON → distractors are PERSONs
+#       answer=DATE   → distractors are DATEs
+# ─────────────────────────────────────────────
+
+import random
+import sys, os
+
+import nltk
+from nltk.corpus import wordnet
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config import NUM_DISTRACTORS
+
+nltk.download('wordnet', quiet=True)
+nltk.download('omw-1.4', quiet=True)
+
+
+def get_same_label_distractors(answer: str, answer_label: str,
+                                all_entities: list, n: int) -> list:
+    """
+    Find entities from the passage that have the SAME NER label as the answer.
+    This ensures distractors are always the same type as the answer.
+
+    all_entities is a list of {"text": str, "label": str} dicts.
+    """
+    distractors = []
+    seen = {answer.lower()}
+
+    # First pass: exact same label
+    for ent in all_entities:
+        if ent["label"] == answer_label and ent["text"].lower() not in seen:
+            distractors.append(ent["text"])
+            seen.add(ent["text"].lower())
+
+    return distractors[:n]
+
+
+def get_wordnet_distractors(answer: str, n: int) -> list:
+    """WordNet hyponym siblings — same semantic category."""
+    answer_key  = answer.lower().replace(" ", "_")
+    distractors = set()
+
+    synsets = wordnet.synsets(answer_key)
+    if not synsets:
+        for word in answer.split():
+            synsets += wordnet.synsets(word.lower())
+
+    for synset in synsets[:5]:
+        for hypernym in synset.hypernyms():
+            for hyponym in hypernym.hyponyms():
+                for lemma in hyponym.lemma_names():
+                    word = lemma.replace("_", " ")
+                    if word.lower() == answer.lower():
+                        continue
+                    if len(word) > 1:
+                        distractors.add(word.title() if answer[0].isupper() else word)
+        if len(distractors) >= n * 3:
+            break
+
+    result = list(distractors)
+    random.shuffle(result)
+    return result[:n]
+
+
+def get_distractors(answer: str, all_entities: list,
+                     passage_doc=None, n: int = NUM_DISTRACTORS) -> list:
+    """
+    Main distractor function.
+    Strategy:
+      1. Same-label entities from the passage  (best — contextual + same type)
+      2. WordNet siblings                       (good for common nouns)
+      3. Cross-label entities from passage      (last resort, still real words)
+    Never mixes types if same-label gives enough results.
+    """
+    collected = []
+    seen      = {answer.lower()}
+
+    def add(candidates):
+        for c in candidates:
+            if isinstance(c, dict):
+                text = c["text"]
+            else:
+                text = c
+            if text.lower() not in seen and text.lower() != answer.lower():
+                seen.add(text.lower())
+                collected.append(text)
+
+    # Find the answer's NER label from the entity list
+    answer_label = ""
+    for ent in all_entities:
+        if ent["text"].lower() == answer.lower():
+            answer_label = ent["label"]
+            break
+    # Fuzzy match if exact not found
+    if not answer_label:
+        for ent in all_entities:
+            if answer.lower() in ent["text"].lower():
+                answer_label = ent["label"]
+                break
+
+    # Strategy 1: same label from passage
+    add(get_same_label_distractors(answer, answer_label, all_entities, n * 2))
+
+    # Strategy 2: WordNet
+    if len(collected) < n:
+        add(get_wordnet_distractors(answer, n * 2))
+
+    # Strategy 3: any other passage entity (cross-label fallback)
+    if len(collected) < n:
+        add(all_entities)   # add() handles dedup
+
+    # Only if still short, add generic placeholders
+    placeholders = ["None of the above", "Cannot be determined", "All of the above"]
+    for p in placeholders:
+        if len(collected) >= n:
+            break
+        if p not in collected:
+            collected.append(p)
+
+    return collected[:n]
+
+
+if __name__ == "__main__":
+    # Simulate entity list from preprocessor
+    entities = [
+        {"text": "ISRO",            "label": "ORG"},
+        {"text": "NASA",            "label": "ORG"},
+        {"text": "ESA",             "label": "ORG"},
+        {"text": "Vikram Sarabhai", "label": "PERSON"},
+        {"text": "Vince McMahon",   "label": "PERSON"},
+        {"text": "John Cena",       "label": "PERSON"},
+        {"text": "1969",            "label": "DATE"},
+        {"text": "1975",            "label": "DATE"},
+        {"text": "2008",            "label": "DATE"},
+        {"text": "India",           "label": "GPE"},
+        {"text": "United States",   "label": "GPE"},
+        {"text": "China",           "label": "GPE"},
+    ]
+
+    tests = [
+        ("Vikram Sarabhai", "PERSON"),
+        ("1969",            "DATE"),
+        ("India",           "GPE"),
+        ("ISRO",            "ORG"),
+    ]
+
+    print("=== DISTRACTOR TEST ===\n")
+    for answer, label in tests:
+        d = get_distractors(answer, entities)
+        print(f"  Answer ({label:8s}): {answer:20s} → {d}")

src/evaluator.py

@@ -0,0 +1,132 @@
+# ─────────────────────────────────────────────
+#  src/evaluator.py
+#  Checks user answers and computes scores.
+#  Simple but important — this is what makes
+#  the project interactive and demo-worthy.
+# ─────────────────────────────────────────────
+
+from src.mcq_builder import MCQ
+
+
+# ─────────────────────────────────────────────
+#  CHECK A SINGLE ANSWER
+# ─────────────────────────────────────────────
+
+def check_answer(mcq: MCQ, user_choice: int) -> bool:
+    """
+    Check if the user's selected option index is correct.
+    
+    Parameters:
+        mcq         : the MCQ object
+        user_choice : index 0-3 that the user selected
+    
+    Returns: True if correct, False otherwise
+    """
+    return user_choice == mcq.correct_index
+
+
+# ─────────────────────────────────────────────
+#  SCORE A FULL QUIZ
+# ─────────────────────────────────────────────
+
+def score_quiz(mcqs: list[MCQ], user_answers: list[int]) -> dict:
+    """
+    Score all questions and return a detailed results dict.
+    
+    Parameters:
+        mcqs         : list of MCQ objects (the quiz)
+        user_answers : list of int indices (user's selections, one per MCQ)
+    
+    Returns:
+        {
+          "score"      : 7,           ← number correct
+          "total"      : 10,          ← total questions
+          "percentage" : 70.0,
+          "results"    : [            ← per-question details
+            {
+              "question"      : "In what year was ISRO founded?",
+              "your_answer"   : "1975",
+              "correct_answer": "1969",
+              "is_correct"    : False,
+              "explanation"   : "ISRO was founded in 1969 by Vikram Sarabhai.",
+            },
+            ...
+          ]
+        }
+    """
+    score   = 0
+    results = []
+
+    for i, (mcq, user_choice) in enumerate(zip(mcqs, user_answers)):
+        is_correct = check_answer(mcq, user_choice)
+        if is_correct:
+            score += 1
+
+        results.append({
+            "question"       : mcq.question,
+            "your_answer"    : mcq.options[user_choice] if 0 <= user_choice < len(mcq.options) else "No answer",
+            "correct_answer" : mcq.correct_answer,
+            "is_correct"     : is_correct,
+            "explanation"    : mcq.explanation,
+            "all_options"    : mcq.options,
+            "correct_index"  : mcq.correct_index,
+            "user_index"     : user_choice,
+        })
+
+    total      = len(mcqs)
+    percentage = round((score / total) * 100, 1) if total > 0 else 0.0
+
+    # Provide a feedback message based on score
+    if percentage >= 80:
+        feedback = "Excellent! You have a strong understanding of this passage."
+    elif percentage >= 60:
+        feedback = "Good effort! Review the explanations for questions you missed."
+    elif percentage >= 40:
+        feedback = "Fair attempt. Try re-reading the passage and retaking the quiz."
+    else:
+        feedback = "Keep practising! The explanations below will help you understand."
+
+    return {
+        "score"      : score,
+        "total"      : total,
+        "percentage" : percentage,
+        "feedback"   : feedback,
+        "results"    : results,
+    }
+
+
+# ─────────────────────────────────────────────
+#  QUICK TEST
+#  python src/evaluator.py
+# ─────────────────────────────────────────────
+
+if __name__ == "__main__":
+    # Simulate 3 MCQs without running the full pipeline
+    fake_mcqs = [
+        MCQ("What year was ISRO founded?",
+            ["1969", "1975", "1947", "1985"], 0, "1969",
+            "ISRO was founded in 1969 by Vikram Sarabhai."),
+        MCQ("Who founded ISRO?",
+            ["Kalam", "Vikram Sarabhai", "Nehru", "Dhawan"], 1, "Vikram Sarabhai",
+            "ISRO was founded in 1969 by Vikram Sarabhai."),
+        MCQ("What did Chandrayaan-1 discover?",
+            ["Oxygen", "Iron", "Water molecules", "Helium"], 2, "Water molecules",
+            "Chandrayaan-1 discovered water molecules on the Moon."),
+    ]
+
+    # Simulate user answers: Q1 correct, Q2 wrong, Q3 correct
+    user_answers = [0, 0, 2]
+
+    result = score_quiz(fake_mcqs, user_answers)
+
+    print("=== QUIZ RESULTS ===")
+    print(f"Score: {result['score']} / {result['total']} ({result['percentage']}%)")
+    print(f"Feedback: {result['feedback']}\n")
+    for i, r in enumerate(result['results'], 1):
+        status = "CORRECT" if r['is_correct'] else "WRONG"
+        print(f"Q{i} [{status}] {r['question']}")
+        print(f"     Your answer   : {r['your_answer']}")
+        if not r['is_correct']:
+            print(f"     Correct answer: {r['correct_answer']}")
+        print(f"     Explanation   : {r['explanation'][:80]}...")
+        print()

src/mcq_builder.py

@@ -0,0 +1,222 @@
+# ─────────────────────────────────────────────
+#  src/mcq_builder.py  (v4)
+#  Added strict MCQ quality validation.
+# ─────────────────────────────────────────────
+
+import random
+from dataclasses import dataclass
+import sys, os
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config import NUM_DISTRACTORS, MAX_QUESTIONS
+
+from src.preprocessor         import preprocess
+from src.question_generator   import generate_questions
+from src.distractor_generator import get_distractors
+
+
+@dataclass
+class MCQ:
+    question       : str
+    options        : list
+    correct_index  : int
+    correct_answer : str
+    explanation    : str
+
+    def display(self):
+        print(f"\nQ: {self.question}")
+        for i, opt in enumerate(self.options):
+            marker = " ✓" if i == self.correct_index else ""
+            print(f"   {chr(65+i)}. {opt}{marker}")
+        print(f"   Explanation: {self.explanation[:100]}...")
+
+
+def are_too_similar(a: str, b: str) -> bool:
+    """
+    Check if two option strings are too similar to coexist in the same MCQ.
+    Handles cases like "WWE" vs "World Wrestling Entertainment",
+    or "ISRO" vs "Indian Space Research Organisation".
+    """
+    a_lower = a.lower().strip()
+    b_lower = b.lower().strip()
+
+    # Exact match
+    if a_lower == b_lower:
+        return True
+
+    # One is a substring of the other (e.g. "WWE" in "WWE Championship")
+    if a_lower in b_lower or b_lower in a_lower:
+        return True
+
+    # Check word overlap ratio — if 60%+ words overlap, too similar
+    words_a = set(a_lower.split())
+    words_b = set(b_lower.split())
+    if not words_a or not words_b:
+        return False
+    overlap = len(words_a & words_b)
+    smaller = min(len(words_a), len(words_b))
+    if smaller > 0 and overlap / smaller >= 0.6:
+        return True
+
+    return False
+
+
+def deduplicate_options(answer: str, distractors: list) -> list:
+    """
+    Remove distractors that are too similar to each other or to the answer.
+    Returns a clean list of unique distractors.
+    """
+    clean = []
+    for d in distractors:
+        # Skip if too similar to the correct answer
+        if are_too_similar(d, answer):
+            continue
+        # Skip if too similar to an already-accepted distractor
+        if any(are_too_similar(d, accepted) for accepted in clean):
+            continue
+        clean.append(d)
+    return clean
+
+
+def is_valid_mcq(question: str, answer: str, options: list) -> tuple:
+    """
+    Final quality gate before an MCQ is accepted.
+    Returns (is_valid: bool, reason: str).
+    """
+    # Answer must appear in options exactly once
+    answer_count = sum(1 for o in options if o.lower().strip() == answer.lower().strip())
+    if answer_count != 1:
+        return False, f"Answer appears {answer_count} times in options"
+
+    # Must have exactly 4 options
+    if len(options) != 4:
+        return False, f"Only {len(options)} options"
+
+    # No two options should be too similar
+    for i in range(len(options)):
+        for j in range(i + 1, len(options)):
+            if are_too_similar(options[i], options[j]):
+                return False, f"Options too similar: '{options[i]}' vs '{options[j]}'"
+
+    # Generic placeholder options are a last resort — skip if more than 1
+    generic = {"None of the above", "Cannot be determined",
+               "All of the above", "Information not provided"}
+    generic_count = sum(1 for o in options if o in generic)
+    if generic_count > 1:
+        return False, "Too many generic placeholder options"
+
+    # Question should not just be asking "What is X?" where X is the answer
+    q_lower = question.lower()
+    a_lower = answer.lower()
+    if a_lower in q_lower:
+        return False, "Answer already present in question"
+
+    return True, "OK"
+
+
+def build_mcq(question: str, answer: str, distractors: list, explanation: str):
+    """Build and validate one MCQ. Returns MCQ or None if quality check fails."""
+
+    # Deduplicate distractors against each other and the answer
+    clean_distractors = deduplicate_options(answer, distractors)
+
+    if len(clean_distractors) < 1:
+        return None
+
+    # Pad to 3 if needed (after dedup we might have fewer)
+    placeholders = ["None of the above", "Cannot be determined", "All of the above"]
+    for p in placeholders:
+        if len(clean_distractors) >= NUM_DISTRACTORS:
+            break
+        if p not in clean_distractors:
+            clean_distractors.append(p)
+
+    options = [answer] + clean_distractors[:NUM_DISTRACTORS]
+    random.shuffle(options)
+    correct_index = options.index(answer)
+
+    # Run quality gate
+    valid, reason = is_valid_mcq(question, answer, options)
+    if not valid:
+        print(f"  [QC] Rejected MCQ — {reason}: Q='{question[:50]}'")
+        return None
+
+    return MCQ(
+        question       = question,
+        options        = options,
+        correct_index  = correct_index,
+        correct_answer = answer,
+        explanation    = explanation,
+    )
+
+
+def build_quiz(passage: str, num_questions: int = MAX_QUESTIONS) -> list:
+    print(f"\n[Pipeline] Starting for passage ({len(passage)} chars)...")
+
+    print("[Pipeline] Step 1/3: Preprocessing...")
+    prep             = preprocess(passage)
+    sentence_answers = prep["sentence_answers"]
+    all_entities     = prep["entities"]
+
+    if not sentence_answers:
+        print("[Pipeline] No suitable sentences found.")
+        return []
+
+    print("[Pipeline] Step 2/3: Generating questions...")
+    qa_pairs = generate_questions(sentence_answers)
+
+    if not qa_pairs:
+        print("[Pipeline] No questions generated.")
+        return []
+
+    print(f"[Pipeline] {len(qa_pairs)} candidate question(s) generated.")
+
+    print("[Pipeline] Step 3/3: Building and validating MCQs...")
+    mcqs = []
+
+    for qa in qa_pairs:
+        if len(mcqs) >= num_questions:
+            break
+
+        distractors = get_distractors(
+            answer       = qa["answer"],
+            all_entities = all_entities,
+        )
+
+        mcq = build_mcq(
+            question    = qa["question"],
+            answer      = qa["answer"],
+            distractors = distractors,
+            explanation = qa["sentence"],
+        )
+
+        if mcq is not None:
+            mcqs.append(mcq)
+
+    print(f"[Pipeline] Done. {len(mcqs)} valid MCQ(s) built.")
+
+    if len(mcqs) == 0:
+        print("\n[Pipeline] NOTICE: Could not build valid MCQs from this passage.")
+        print("  This usually means the passage lacks specific named facts.")
+        print("  Try a factual passage with: people names, places, dates, organisations.")
+
+    return mcqs
+
+
+if __name__ == "__main__":
+    # Test with ISRO passage (factual — should work well)
+    passage = """
+    The Indian Space Research Organisation (ISRO) was founded in 1969 by Vikram Sarabhai.
+    It is headquartered in Bengaluru, Karnataka. ISRO developed India's first satellite,
+    Aryabhata, which was launched in 1975. The Chandrayaan-1 mission in 2008 discovered
+    water molecules on the Moon. In 2023, Chandrayaan-3 successfully landed near the
+    lunar south pole, making India the fourth country to achieve a Moon landing.
+    The Mars Orbiter Mission, also called Mangalyaan, was launched in 2013 and made
+    India the first Asian country to reach Martian orbit.
+    """
+
+    mcqs = build_quiz(passage, num_questions=5)
+    print("\n========== GENERATED QUIZ ==========")
+    for i, mcq in enumerate(mcqs, 1):
+        print(f"\n--- Question {i} ---")
+        mcq.display()

src/preprocessor.py

@@ -0,0 +1,165 @@
+# ─────────────────────────────────────────────
+#  src/preprocessor.py  (v3)
+# ─────────────────────────────────────────────
+
+import re
+import spacy
+from sklearn.feature_extraction.text import TfidfVectorizer
+import numpy as np
+import sys, os
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config import SPACY_MODEL, TOP_SENTENCES, MIN_SENTENCE_LENGTH
+
+try:
+    nlp = spacy.load(SPACY_MODEL)
+except OSError:
+    print(f"[ERROR] Run: python -m spacy download {SPACY_MODEL}")
+    raise
+
+# Only these NER labels make meaningful quiz answers
+GOOD_NER_LABELS = {
+    "PERSON", "ORG", "GPE", "LOC",
+    "DATE", "EVENT", "WORK_OF_ART",
+    "NORP", "FAC", "PRODUCT",
+}
+
+# Hard blacklist — never use these as answers
+BLACKLIST = {
+    "annual", "various", "many", "several", "some", "other",
+    "new", "old", "big", "large", "small", "high", "low",
+    "one", "two", "three", "four", "five", "first", "second",
+    "today", "yesterday", "now", "then", "later", "also",
+    "he", "she", "it", "they", "we", "i", "the", "a", "an",
+    "moon", "sun", "earth",
+    "india", "america", "china", "russia", "england", "world",  # too broad
+    "isro", "nasa", "wwe", "un", "who",  # abbreviations make circular Qs
+}
+
+# Prefer answers with these labels — they make the clearest questions
+HIGH_PRIORITY_LABELS = {"PERSON", "ORG", "GPE", "LOC", "EVENT", "WORK_OF_ART", "FAC", "PRODUCT"}
+
+
+def extract_sentences(text: str) -> list:
+    doc = nlp(text)
+    sentences = []
+    for sent in doc.sents:
+        clean = sent.text.strip()
+        word_count = len([t for t in sent if not t.is_space and not t.is_punct])
+        if word_count >= MIN_SENTENCE_LENGTH:
+            sentences.append(clean)
+    return sentences
+
+
+def rank_sentences(sentences: list, top_n: int = TOP_SENTENCES) -> list:
+    if len(sentences) <= top_n:
+        return sentences
+    vectorizer   = TfidfVectorizer(stop_words='english')
+    tfidf_matrix = vectorizer.fit_transform(sentences)
+    scores       = np.array(tfidf_matrix.sum(axis=1)).flatten()
+    top_indices  = sorted(np.argsort(scores)[::-1][:top_n])
+    return [sentences[i] for i in top_indices]
+
+
+def is_good_answer(text: str, label: str) -> bool:
+    t = text.strip()
+
+    if len(t) < 2:
+        return False
+
+    # Reject blacklisted words (case-insensitive)
+    if t.lower() in BLACKLIST:
+        return False
+
+    # Must be an allowed NER label
+    if label not in GOOD_NER_LABELS:
+        return False
+
+    # Single lowercase word with no capitals = probably not a proper noun
+    if len(t.split()) == 1 and t[0].islower() and not t.isdigit():
+        return False
+
+    # Reject very long phrases (>5 words) — hard to use as MCQ answers
+    if len(t.split()) > 5:
+        return False
+
+    return True
+
+
+def extract_answer_candidates(sentence: str) -> list:
+    """
+    Extract answer candidates from a sentence.
+    Returns high-priority entities first, then dates/others.
+    Only ONE answer per sentence is ultimately used (the best one).
+    """
+    doc = nlp(sentence)
+
+    high = []   # PERSON, ORG, GPE, etc.
+    low  = []   # DATE, QUANTITY, etc.
+    seen = set()
+
+    for ent in doc.ents:
+        text  = ent.text.strip()
+        label = ent.label_
+
+        if not is_good_answer(text, label):
+            continue
+        if text.lower() in seen:
+            continue
+
+        seen.add(text.lower())
+
+        if label in HIGH_PRIORITY_LABELS:
+            high.append(text)
+        else:
+            low.append(text)
+
+    # Return high-priority first, then dates/quantities
+    return high + low
+
+
+def preprocess(text: str) -> dict:
+    text             = re.sub(r'\s+', ' ', text).strip()
+    all_sentences    = extract_sentences(text)
+    top_sentences    = rank_sentences(all_sentences)
+    sentence_answers = {}
+
+    for sent in top_sentences:
+        candidates = extract_answer_candidates(sent)
+        if candidates:
+            sentence_answers[sent] = candidates
+
+    doc          = nlp(text)
+    # Store entities WITH their labels for the distractor generator
+    all_entities = []
+    seen = set()
+    for ent in doc.ents:
+        if is_good_answer(ent.text.strip(), ent.label_) and ent.text.lower() not in seen:
+            seen.add(ent.text.lower())
+            all_entities.append({"text": ent.text.strip(), "label": ent.label_})
+
+    return {
+        "all_sentences"    : all_sentences,
+        "top_sentences"    : top_sentences,
+        "sentence_answers" : sentence_answers,
+        "entities"         : all_entities,   # now list of {"text":..,"label":..}
+    }
+
+
+if __name__ == "__main__":
+    sample = """
+    The Indian Space Research Organisation (ISRO) was founded in 1969 by Vikram Sarabhai.
+    ISRO developed India's first satellite, Aryabhata, which was launched in 1975.
+    The Chandrayaan-1 mission in 2008 discovered water molecules on the Moon.
+    In 2023, Chandrayaan-3 successfully landed near the lunar south pole, making India
+    the fourth country to achieve a Moon landing.
+    The Mars Orbiter Mission, also called Mangalyaan, was launched in 2013.
+    """
+    result = preprocess(sample)
+    print("=== SENTENCE → CANDIDATES ===")
+    for sent, ans in result['sentence_answers'].items():
+        print(f"  Source : {sent[:75]}")
+        print(f"  Answers: {ans}\n")
+    print("=== ALL ENTITIES (for distractors) ===")
+    for e in result['entities']:
+        print(f"  {e['label']:15s} {e['text']}")

src/question_generator.py

@@ -0,0 +1,180 @@
+# ─────────────────────────────────────────────
+#  src/question_generator.py  (v4)
+#  Key fix: validate that the generated question
+#  actually targets the intended answer.
+#  Also filters circular questions like
+#  "What is the name of X?" when answer IS X.
+# ─────────────────────────────────────────────
+
+from transformers import pipeline
+import re
+import sys, os
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config import QG_MODEL_NAME, MAX_QUESTIONS
+
+print(f"[INFO] Loading QG model: {QG_MODEL_NAME} ...")
+import warnings
+warnings.filterwarnings("ignore")   # suppress HuggingFace FutureWarnings
+
+try:
+    qg_pipeline = pipeline(
+        "text2text-generation",
+        model     = QG_MODEL_NAME,
+        tokenizer = QG_MODEL_NAME,
+    )
+    print("[INFO] Model loaded.")
+except Exception as e:
+    print(f"[ERROR] {e}")
+    raise
+
+
+def highlight_answer(sentence: str, answer: str) -> str:
+    """Wrap answer with <hl> tags for the T5 model."""
+    pattern = re.compile(re.escape(answer), re.IGNORECASE)
+    result  = pattern.sub(f"<hl> {answer} <hl>", sentence, count=1)
+    return result
+
+
+def answer_is_addressable(question: str, answer: str) -> bool:
+    """
+    Check that the question is actually ASKING FOR the answer.
+    
+    Rejects:
+    - Circular: answer text appears in the question
+      e.g. Q: "What is the name of ISRO?" A: "The Indian Space Research Organisation"
+           (ISRO is an abbreviation of the answer — circular)
+    - Too vague: question is only 4 words or fewer
+    - No question word
+    - Answer is a substring of the question
+    """
+    q = question.strip()
+    a = answer.strip()
+
+    # Must end with ?
+    if not q.endswith("?"):
+        return False
+
+    # Must have a question word
+    q_lower = q.lower()
+    if not any(q_lower.startswith(w) for w in
+               ["what", "who", "when", "where", "which", "how", "why"]):
+        return False
+
+    # Must be at least 5 words
+    if len(q.split()) < 5:
+        return False
+
+    # Answer must NOT appear verbatim in the question
+    if a.lower() in q_lower:
+        return False
+
+    # Check abbreviation trap: if any word in the question is an abbreviation
+    # of the answer (e.g. "ISRO" in question, answer is "Indian Space Research...")
+    answer_words = [w.lower() for w in a.split() if len(w) > 1]
+    abbrev = "".join(w[0] for w in answer_words if w.isalpha())
+    if len(abbrev) >= 2 and abbrev.lower() in q_lower:
+        return False
+
+    # Reject questions asking about name/abbreviation — usually circular
+    circular_patterns = [
+        r"what (is|was|were) the (full |official )?name",
+        r"what (does|did) .{1,10} stand for",
+        r"what (is|was) the abbreviation",
+        r"what (is|was) .{1,15} also (known|called)",
+    ]
+    for pat in circular_patterns:
+        if re.search(pat, q_lower):
+            return False
+
+    return True
+
+
+def generate_question(sentence: str, answer: str) -> str | None:
+    """
+    Generate a question for a (sentence, answer) pair.
+    Returns the best valid question string, or None.
+    """
+    highlighted = highlight_answer(sentence, answer)
+    input_text  = f"generate question: {highlighted}"
+
+    try:
+        outputs = qg_pipeline(
+            input_text,
+            max_new_tokens       = 64,
+            num_beams            = 5,
+            num_return_sequences = 3,
+            early_stopping       = True,
+        )
+    except Exception as e:
+        print(f"  [QG] Generation error: {e}")
+        return None
+
+    for output in outputs:
+        q = output["generated_text"].strip()
+        if not q.endswith("?"):
+            q += "?"
+        if answer_is_addressable(q, answer):
+            return q
+
+    return None
+
+
+def generate_questions(sentence_answers: dict) -> list:
+    """
+    For each (sentence → answer candidates), generate one good question.
+    Tries each answer candidate in priority order until one works.
+    """
+    results = []
+
+    for sentence, candidates in sentence_answers.items():
+        if len(results) >= MAX_QUESTIONS:
+            break
+
+        generated = False
+        for answer in candidates:
+            if len(answer.strip()) < 2:
+                continue
+
+            question = generate_question(sentence, answer)
+
+            if question:
+                print(f"  [QG] ✓ Q: {question}")
+                print(f"         A: {answer}")
+                results.append({
+                    "question" : question,
+                    "answer"   : answer,
+                    "sentence" : sentence,
+                })
+                generated = True
+                break
+            else:
+                print(f"  [QG] ✗ Rejected for answer '{answer}'")
+
+        if not generated:
+            print(f"  [QG] — No valid question for: '{sentence[:60]}'")
+
+    return results
+
+
+if __name__ == "__main__":
+    tests = [
+        # Good cases — specific named answers
+        ("ISRO was founded in 1969 by Vikram Sarabhai.", "Vikram Sarabhai"),
+        ("Aryabhata was India's first satellite, launched in 1975.", "Aryabhata"),
+        ("The Chandrayaan-1 mission in 2008 discovered water on the Moon.", "2008"),
+        ("Chandrayaan-3 landed near the lunar south pole in 2023.", "Chandrayaan-3"),
+        ("The Taj Mahal was built by Shah Jahan in 1632 in Agra.", "Shah Jahan"),
+        # Bad cases — should all be rejected
+        ("The Indian Space Research Organisation (ISRO) was founded in 1969.", "The Indian Space Research Organisation"),
+        ("ISRO developed India's first satellite.", "India"),
+    ]
+
+    print("\n=== QUESTION GENERATION TEST ===\n")
+    for sentence, answer in tests:
+        q = generate_question(sentence, answer)
+        status = "✓" if q else "✗ (rejected)"
+        print(f"  [{status}]")
+        print(f"    Sentence: {sentence}")
+        print(f"    Answer  : {answer}")
+        print(f"    Question: {q}\n")