Upload 7 files

.env.example

@@ -0,0 +1,9 @@
+# OpenAI API Key
+OPENAI_API_KEY=your_openai_api_key_here
+
+# App Configuration
+DETERMINISTIC_TEMPERATURE=0.1
+TOOL_MAX_RETRIES=2
+MAX_FILE_SIZE_MB=500
+MAX_PDF_PAGES=2000
+PDF_EXTRACTION_TIMEOUT=200

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+architecture.pdf filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,44 @@
----
-title: SMART TUTOR
-emoji: 🐢
-colorFrom: blue
-colorTo: red
-sdk: gradio
-sdk_version: 6.5.1
-app_file: app.py
-pinned: false
-short_description: SmartTutor AI is a multi-agent system built with CrewAI
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧠 SmartTutor AI
+
+SmartTutor AI is an intelligent educational assistant built with **CrewAI** and **Gradio**. It helps users summarize documents, generate quizzes, and get detailed explanations for their mistakes.
+
+## ✨ Features
+
+- **Document Summarization**: Get concise summaries from PDF or Text files.
+- **Quiz Generation**: Automatically create multiple-choice quizzes based on document content.
+- **Intelligent Grading**: Submit quiz answers and get detailed explanations for errors.
+- **Quick Actions**: One-click shortcuts for common tasks.
+- **Persistent Storage**: Quizzes are saved locally to `quizzes_db.json`.
+
+## 🛠️ Setup
+
+### 1. Requirements
+Ensure you have Python 3.9+ installed.
+
+### 2. Installation
+Install the dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+### 3. Environment Variables
+1. Create a `.env` file from the example:
+   ```bash
+   cp .env.example .env
+   ```
+2. Open `.env` and add your `OPENAI_API_KEY`.
+
+## 🚀 Usage
+
+Run the application:
+```bash
+python app.py
+```
+The interface will be available at `http://localhost:7860`.
+
+## 📁 Project Structure
+
+- `app.py`: Main application and UI.
+- `quizzes_db.json`: Local storage for generated quizzes.
+- `requirements.txt`: Python dependencies.
+- `.env`: Secret configuration (not included in version control).

app.py

@@ -0,0 +1,978 @@
+import gradio as gr
+import os
+import sys
+import json
+import re
+
+# Ensure the current directory is in the path
+current_dir = os.path.dirname(os.path.abspath(__file__))
+sys.path.append(current_dir)
+
+from smart_tutor_core import crew
+
+# ----------------------------------------------------------------------
+# Helper: Parse Output
+# ----------------------------------------------------------------------
+
+
+def parse_agent_output(raw_output: str):
+    """
+    Tries to parse JSON from the raw string output.
+    Returns (data_dict, is_json).
+    """
+    data = None
+    try:
+        data = json.loads(raw_output)
+        return data, True
+    except json.JSONDecodeError:
+        # Try finding JSON block
+        match = re.search(r"(\{.*\})", raw_output, re.DOTALL)
+        if match:
+            try:
+                data = json.loads(match.group(1))
+                return data, True
+            except:
+                pass
+    return raw_output, False
+
+
+def clean_text(text: str) -> str:
+    """
+    Aggressively removes markdown formatting to ensure clean text display.
+    Removes: **bold**, __bold__, *italic*, _italic_, `code`
+    """
+    if not text:
+        return ""
+    text = str(text)
+    # Remove bold/italic markers
+    text = re.sub(r"\*\*|__|`", "", text)
+    text = re.sub(r"^\s*\*\s+", "", text)  # Remove leading list asterisks if any
+    return text.strip()
+
+
+# ----------------------------------------------------------------------
+# Helper: Format Text Output for Display
+# ----------------------------------------------------------------------
+
+
+def format_text_output(raw_text):
+    """
+    Converts raw agent text (markdown-ish) into
+    beautifully styled HTML inside a summary-box.
+    """
+    if not raw_text:
+        return ""
+    text = str(raw_text).strip()
+
+    # Convert markdown headings to HTML
+    text = re.sub(r"^### (.+)$", r"<h3>\1</h3>", text, flags=re.MULTILINE)
+    text = re.sub(r"^## (.+)$", r"<h2>\1</h2>", text, flags=re.MULTILINE)
+    text = re.sub(r"^# (.+)$", r"<h2>\1</h2>", text, flags=re.MULTILINE)
+
+    # Convert **bold** to <strong>
+    text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", text)
+
+    # Convert bullet lists (- item or * item)
+    lines = text.split("\n")
+    result = []
+    in_list = False
+
+    for line in lines:
+        stripped = line.strip()
+        is_bullet = (
+            stripped.startswith("- ")
+            or stripped.startswith("* ")
+            or re.match(r"^\d+\.\s", stripped)
+        )
+
+        if is_bullet:
+            if not in_list:
+                tag = "ul"  # Always use bullets as requested
+                result.append(f"<{tag}>")
+                in_list = tag
+            # Remove both -/* and 1. from the start of the line
+            content = re.sub(r"^[-*]\s+|^\d+\.\s+", "", stripped)
+            result.append(f"<li>{content}</li>")
+        else:
+            if in_list:
+                result.append(f"</{in_list}>")
+                in_list = False
+            if stripped.startswith("<h"):
+                result.append(stripped)
+            elif stripped:
+                result.append(f"<p>{stripped}</p>")
+
+    if in_list:
+        result.append(f"</{in_list}>")
+
+    html = "\n".join(result)
+    return f"<div class='summary-box'>{html}</div>"
+
+
+# ----------------------------------------------------------------------
+# Logic: Run Agent
+# ----------------------------------------------------------------------
+
+
+def run_agent(file, user_text):
+    if not user_text and not file:
+        return (
+            gr.update(
+                visible=True,
+                value="<div class='error-box'>⚠️ Please enter a request or upload a file.</div>",
+            ),
+            gr.update(visible=False),  # Quiz Group
+            None,  # State
+        )
+
+    full_request = user_text
+
+    # Check if user wants a quiz but didn't upload a file (common error)
+    if "quiz" in user_text.lower() and not file:
+        return (
+            gr.update(
+                visible=True,
+                value="<div class='error-box'>⚠️ To generate a quiz, please upload a document first.</div>",
+            ),
+            gr.update(visible=False),
+            None,
+        )
+
+    if file:
+        # file is a filepath string because type='filepath'
+        full_request = f"""USER REQUEST: {user_text}
+
+IMPORTANT: The file to process is located at this EXACT path:
+{file}
+
+You MUST use this exact path when calling tools (process_file, store_quiz, etc.)."""
+
+    # SYSTEM PROMPT INJECTION to force JSON format from the agent
+    system_instruction = "\n\n(SYSTEM NOTE: If generating a quiz, you MUST call the store_quiz tool and return its VALID JSON output including 'quiz_id'. Do NOT return just the questions text.)"
+
+    try:
+        inputs = {"user_request": full_request + system_instruction}
+        result = crew.kickoff(inputs=inputs)
+        raw_output = str(result)
+
+        print(f"\n{'='*60}")
+        print(f"[DEBUG] raw_output (first 500 chars):")
+        print(raw_output[:500])
+        print(f"{'='*60}")
+
+        data, is_json = parse_agent_output(raw_output)
+
+        print(f"[DEBUG] is_json={is_json}")
+        if is_json:
+            print(
+                f"[DEBUG] keys={list(data.keys()) if isinstance(data, dict) else 'not a dict'}"
+            )
+            if isinstance(data, dict) and "questions" in data:
+                print(f"[DEBUG] num questions={len(data['questions'])}")
+
+        # Case 1: Quiz Output (Success)
+        if is_json and "questions" in data:
+            # We accept it even if quiz_id is missing, but grading might fail.
+            return (
+                gr.update(visible=False),  # Hide Summary
+                gr.update(visible=True),  # Show Quiz
+                data,  # Store Data
+            )
+
+        # Case 2: Grade Result (Standard JSON from grade_quiz) - Handled nicely
+        if is_json and "score" in data:
+            markdown = format_grade_result(data)
+            return (
+                gr.update(visible=True, value=markdown),
+                gr.update(visible=False),
+                None,
+            )
+
+        # Case 3: Normal Text / Summary / Explanation
+        html_content = format_text_output(raw_output)
+        return (
+            gr.update(visible=True, value=html_content),
+            gr.update(visible=False),
+            None,
+        )
+
+    except Exception as e:
+        error_msg = f"<div class='error-box'>❌ Error: {str(e)}</div>"
+        return (
+            gr.update(visible=True, value=error_msg),
+            gr.update(visible=False),
+            None,
+        )
+
+
+# ----------------------------------------------------------------------
+# Logic: Quiz Render & Grading
+# ----------------------------------------------------------------------
+
+
+def render_quiz(quiz_data):
+    """
+    Renders the quiz questions dynamically.
+    Returns updates for: [Radios x10] + [Feedbacks x10] + [CheckBtn] (Total 21)
+    """
+    updates = []
+
+    if not quiz_data:
+        # Hide everything
+        return [gr.update(visible=False)] * 21
+
+    questions = quiz_data.get("questions", [])
+
+    # 1. Update Radios (10 slots)
+    for i in range(10):
+        if i < len(questions):
+            q = questions[i]
+            q_txt = clean_text(q.get("question", "Question text missing"))
+            question_text = f"{i+1}. {q_txt}"
+
+            # Ensure options are a dict and sorted
+            raw_options = q.get("options", {})
+            if not isinstance(raw_options, dict):
+                # Fallback if options came as a list or string
+                raw_options = {"A": "Error loading options"}
+
+            # Sort by key A, B, C, D...
+            # We strictly enforce the "Key. Value" format
+            choices = []
+            for key in sorted(raw_options.keys()):
+                val = clean_text(raw_options[key])
+                choices.append(f"{key}. {val}")
+
+            updates.append(
+                gr.update(
+                    visible=True,
+                    label=question_text,
+                    choices=choices,
+                    value=None,
+                    interactive=True,
+                )
+            )
+        else:
+            updates.append(gr.update(visible=False, choices=[], value=None))
+
+    # 2. Update Feedbacks (10 slots) - Hide them initially
+    for i in range(10):
+        updates.append(gr.update(visible=False, value=""))
+
+    # 3. Show Grid/Check Button
+    updates.append(gr.update(visible=True))
+
+    return updates
+
+
+def grade_quiz_ui(quiz_data, *args):
+    """
+    Collects answers, calls agent (or tool), and returns graded results designed for UI.
+    Input args: [Radio1_Val, Radio2_Val, ..., Radio10_Val] (Length 10)
+    Output: [Radios x10] + [Feedbacks x10] + [ResultMsg] (Total 21)
+    """
+    # args tuple contains the values of the 10 radios
+    answers_list = args[0:10]
+
+    updates = []
+
+    # Validation
+    if not quiz_data or "quiz_id" not in quiz_data:
+        # Fallback if ID is missing
+        error_updates = [gr.update()] * 10 + [gr.update()] * 10
+        error_updates.append(
+            gr.update(
+                visible=True,
+                value="<div class='error-box'>⚠️ Error: Quiz ID not found. Cannot grade this quiz.</div>",
+            )
+        )
+        return error_updates
+
+    quiz_id = quiz_data["quiz_id"]
+
+    # Construct answer map {"1": "A", ...}
+    user_answers = {}
+    for i, ans in enumerate(answers_list):
+        if ans:
+            # ans is like "A. Option Text" -> extract "A"
+            selected_opt = ans.split(".")[0]
+            # Use qid from data if available, else i+1
+            qid = str(i + 1)
+            # Try to match qid from quiz_data if possible
+            if i < len(quiz_data.get("questions", [])):
+                q = quiz_data["questions"][i]
+                qid = str(q.get("qid", i + 1))
+
+            user_answers[qid] = selected_opt
+
+    # Construct the JSON for the agent
+    answers_json = json.dumps(user_answers)
+    grading_request = f"Grade quiz {quiz_id} with answers {answers_json}\n(SYSTEM: Return valid JSON matching GradeQuizResult schema.)"
+
+    try:
+        inputs = {"user_request": grading_request}
+        result = crew.kickoff(inputs=inputs)
+        raw_output = str(result)
+        data, is_json = parse_agent_output(raw_output)
+
+        if is_json and "score" in data:
+            return format_grade_result_interactive(data, answers_list)
+        else:
+            # Fallback error in result box
+            error_updates = [gr.update()] * 10 + [gr.update()] * 10
+            error_updates.append(
+                gr.update(
+                    visible=True,
+                    value=f"<div class='error-box'>Error parsing grading result: {raw_output}</div>",
+                )
+            )
+            return error_updates
+
+    except Exception as e:
+        error_updates = [gr.update()] * 10 + [gr.update()] * 10
+        error_updates.append(
+            gr.update(
+                visible=True, value=f"<div class='error-box'>Error: {str(e)}</div>"
+            )
+        )
+        return error_updates
+
+
+def format_grade_result_interactive(data, user_answers_list):
+    """
+    Updates the UI with colors and correctness.
+    Returns 21 updates.
+    """
+    details = data.get("details", [])
+    # Map details by QID or index for safety
+    details_map = {}
+    for det in details:
+        details_map[str(det.get("qid"))] = det
+
+    radio_updates = []
+    feedback_updates = []
+
+    # Iterate 10 slots
+    for i in range(10):
+        # Find corresponding detail
+        # We assume strict ordering i=0 -> Q1
+        # But let's try to be smart with QID if possible
+        qid = (
+            str(data.get("details", [])[i].get("qid"))
+            if i < len(data.get("details", []))
+            else str(i + 1)
+        )
+        det = details_map.get(qid)
+
+        if det:
+            # Clean feedback text
+            correct_raw = det.get("correct_answer", "?")
+            correct = clean_text(correct_raw)
+
+            explanation_raw = det.get("explanation", "")
+            explanation = clean_text(explanation_raw)
+
+            is_correct = det.get("is_correct", False)
+
+            # 1. Lock Radio
+            radio_updates.append(gr.update(interactive=False))
+
+            # 2. Show Feedback Box
+            css_class = (
+                "feedback-box-correct" if is_correct else "feedback-box-incorrect"
+            )
+
+            # Title
+            title_text = "Correct Answer!" if is_correct else "Incorrect Answer."
+            title_icon = "✅" if is_correct else "❌"
+
+            html_content = f"""
+            <div class='{css_class}'>
+                <div class='feedback-header'>
+                    <span class='feedback-icon'>{title_icon}</span>
+                    <span class='feedback-title'>{title_text}</span>
+                </div>
+                <div class='feedback-body'>
+                    <div class='feedback-correct-answer'><strong>Correct Answer:</strong> {correct}</div>
+                    {'<div class="feedback-explanation"><strong>Explanation:</strong> ' + explanation + '</div>' if explanation else ''}
+                </div>
+            </div>
+            """
+
+            feedback_updates.append(gr.update(visible=True, value=html_content))
+        else:
+            # No detail (maybe question didn't exist)
+            radio_updates.append(gr.update(visible=False))
+            feedback_updates.append(gr.update(visible=False))
+
+    # 3. Final Score Msg
+    percentage = data.get("percentage", 0)
+    emoji = "🏆" if percentage >= 80 else "📊"
+
+    # Create a nice result card
+    score_html = f"""
+    <div class='result-card'>
+        <div class='result-header'>{emoji} Quiz Completed!</div>
+        <div class='result-score'>Your Score: {data.get('score')} / {data.get('total')}</div>
+        <div class='result-percentage'>({percentage}%)</div>
+    </div>
+    """
+
+    return (
+        radio_updates + feedback_updates + [gr.update(visible=True, value=score_html)]
+    )
+
+
+def format_grade_result(data):
+    """Standard markdown formatter for standalone grade result"""
+    score = data.get("percentage", 0)
+    emoji = "🎉" if score > 70 else "📚"
+    md = f"# {emoji} Score: {data.get('score')}/{data.get('total')}\n\n"
+    for cx in data.get("details", []):
+        md += f"- **Q{cx['qid']}**: {cx['is_correct'] and '✅' or '❌'} (Correct: {cx.get('correct_answer')})\n"
+    return md
+
+
+# ----------------------------------------------------------------------
+# CSS Styling
+# ----------------------------------------------------------------------
+
+custom_css = """
+@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&display=swap');
+
+body {
+    font-family: 'Poppins', sans-serif !important;
+    background: #f8fafc; /* Lighter background */
+    color: #334155;
+    font-weight: 400; /* Regular weight by default */
+}
+
+.gradio-container {
+    max-width: 900px !important;
+    margin: 40px auto !important;
+    background: #ffffff;
+    border-radius: 24px;
+    box-shadow: 0 20px 40px -10px rgba(0,0,0,0.1);
+    padding: 0 !important;
+    overflow: hidden;
+    border: 1px solid rgba(255,255,255,0.8);
+}
+
+/* ================= HEADER ================= */
+.header-box {
+    background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%);
+    color: white;
+    padding: 60px 40px;
+    text-align: center;
+    position: relative;
+    overflow: hidden;
+    margin-bottom: 30px;
+}
+
+.header-box::before {
+    content: '';
+    position: absolute;
+    top: -50%;
+    left: -50%;
+    width: 200%;
+    height: 200%;
+    background: radial-gradient(circle, rgba(255,255,255,0.1) 0%, transparent 60%);
+    animation: rotate 20s linear infinite;
+}
+
+.header-box h1 {
+    color: white !important;
+    margin: 0;
+    font-size: 3em !important;
+    font-weight: 700;
+    letter-spacing: -1px;
+    text-shadow: 0 4px 10px rgba(0,0,0,0.2);
+    position: relative;
+    z-index: 1;
+}
+
+.header-box p {
+    color: #e0e7ff !important;
+    font-size: 1.25em !important;
+    margin-top: 15px;
+    font-weight: 300;
+    position: relative;
+    z-index: 1;
+}
+
+@keyframes rotate {
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); }
+}
+
+/* ================= INPUT PANEL ================= */
+.gradio-row {
+    gap: 30px !important;
+    padding: 0 40px 40px 40px;
+}
+
+/* Logic to remove padding from internal rows if needed, simplified here */
+
+/* Buttons */
+button.primary {
+    background: linear-gradient(90deg, #4f46e5 0%, #6366f1 100%) !important;
+    border: none !important;
+    color: white !important;
+    font-weight: 600 !important;
+    padding: 12px 24px !important;
+    border-radius: 12px !important;
+    box-shadow: 0 4px 15px rgba(79, 70, 229, 0.4) !important;
+    transition: all 0.3s ease !important;
+}
+
+button.primary:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 8px 25px rgba(79, 70, 229, 0.5) !important;
+}
+
+button.secondary {
+    background: #f3f4f6 !important;
+    color: #4b5563 !important;
+    border: 1px solid #e5e7eb !important;
+    border-radius: 12px !important;
+}
+
+button.secondary:hover {
+    background: #e5e7eb !important;
+}
+
+/* ================= QUIZ CARDS ================= */
+.quiz-question {
+    background: #ffffff;
+    border-radius: 16px;
+    padding: 25px;
+    margin-bottom: 30px !important;
+    border: 1px solid #e5e7eb;
+    box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.03), 0 4px 6px -2px rgba(0, 0, 0, 0.02);
+    transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.quiz-question:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.05), 0 10px 10px -5px rgba(0, 0, 0, 0.02);
+}
+
+.quiz-question span { /* Label/Title */
+    font-size: 1.15em !important;
+    font-weight: 600 !important;
+    color: #111827;
+    margin-bottom: 20px;
+    display: block;
+    line-height: 1.5;
+}
+
+/* Options Wrapper (The Radio Group) */
+.quiz-question .wrap {
+    display: flex !important;
+    flex-direction: column !important;
+    gap: 12px !important;
+}
+
+/* Individual Option Label */
+.quiz-question .wrap label {
+    display: flex !important;
+    align-items: center !important;
+    background: #f9fafb;
+    border: 2px solid #e5e7eb !important; /* Thick border */
+    padding: 15px 20px !important;
+    border-radius: 12px !important;
+    cursor: pointer;
+    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+    font-size: 1.05em;
+    color: #4b5563;
+}
+
+.quiz-question .wrap label:hover {
+    background: #f3f4f6;
+    border-color: #6366f1 !important;
+    color: #4f46e5;
+}
+
+.quiz-question .wrap label.selected {
+    background: #eef2ff !important;
+    border-color: #4f46e5 !important;
+    color: #4338ca !important;
+    font-weight: 600;
+    box-shadow: 0 4px 6px -1px rgba(79, 70, 229, 0.1);
+}
+
+/* Hide default circle if possible, or style it. 
+   Gradio's radio inputs are tricky to hide fully without breaking accessibility, 
+   but we can style the container enough. */
+
+/* ================= RESULTS & FEEDBACK ================= */
+
+/* Success/Error Cards */
+.feedback-box-correct, .feedback-box-incorrect {
+    margin-top: 20px;
+    padding: 20px;
+    border-radius: 12px;
+    animation: popIn 0.4s cubic-bezier(0.175, 0.885, 0.32, 1.275);
+    position: relative;
+    overflow: hidden;
+}
+
+.feedback-box-correct {
+    background: linear-gradient(135deg, #ecfdf5 0%, #d1fae5 100%);
+    border: 1px solid #10b981;
+    color: #065f46;
+}
+
+.feedback-box-incorrect {
+    background: linear-gradient(135deg, #fef2f2 0%, #fee2e2 100%);
+    border: 1px solid #ef4444;
+    color: #991b1b;
+}
+
+.feedback-header {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    margin-bottom: 12px;
+    font-size: 1.2em;
+    font-weight: 700;
+}
+
+.feedback-icon {
+    font-size: 1.4em;
+    background: rgba(255,255,255,0.5);
+    border-radius: 50%;
+    width: 32px;
+    height: 32px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    box-shadow: 0 2px 4px rgba(0,0,0,0.05);
+}
+
+.feedback-body {
+    background: rgba(255,255,255,0.4);
+    padding: 15px;
+    border-radius: 8px;
+    font-size: 1em;
+    line-height: 1.6;
+}
+
+.feedback-correct-answer {
+    font-weight: 600;
+    margin-bottom: 8px;
+    color: #064e3b; /* darker green */
+}
+.feedback-box-incorrect .feedback-correct-answer {
+    color: #7f1d1d; /* darker red */
+}
+
+/* Summary / Explanation Box */
+.summary-box {
+    background: linear-gradient(135deg, #ffffff 0%, #f8faff 100%);
+    border-radius: 20px;
+    padding: 35px 40px;
+    border: 1px solid #e0e7ff;
+    box-shadow: 0 8px 30px rgba(79, 70, 229, 0.06);
+    font-size: 1.05em;
+    line-height: 1.9;
+    color: #374151;
+    position: relative;
+    overflow: hidden;
+}
+
+.summary-box::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    height: 4px;
+    background: linear-gradient(90deg, #4f46e5, #7c3aed, #a78bfa);
+}
+
+.summary-box h2 {
+    font-size: 1.4em;
+    font-weight: 700;
+    color: #312e81;
+    margin: 0 0 18px 0;
+    padding-bottom: 12px;
+    border-bottom: 2px solid #e0e7ff;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+
+.summary-box h3 {
+    font-size: 1.15em;
+    font-weight: 600;
+    color: #4338ca;
+    margin: 20px 0 10px 0;
+}
+
+.summary-box p {
+    margin: 0 0 14px 0;
+    text-align: justify;
+}
+
+.summary-box ul, .summary-box ol {
+    margin: 10px 0 16px 0;
+    padding-left: 24px;
+}
+
+.summary-box li {
+    margin-bottom: 8px;
+    position: relative;
+}
+
+.summary-box strong {
+    color: #312e81;
+    font-weight: 600;
+}
+
+.summary-box .summary-footer {
+    margin-top: 20px;
+    padding-top: 14px;
+    border-top: 1px solid #e0e7ff;
+    font-size: 0.85em;
+    color: #9ca3af;
+    text-align: left;
+}
+
+/* Example Buttons */
+#examples-container {
+    margin: 15px 0;
+    padding: 10px;
+    background: #f3f4f6;
+    border-radius: 12px;
+}
+
+.example-btn {
+    background: #ffffff !important;
+    border: 1px solid #e5e7eb !important;
+    color: #6366f1 !important; /* Indigo text */
+    font-size: 0.85em !important;
+    padding: 2px 10px !important;
+    border-radius: 20px !important; /* Pill shape */
+    transition: all 0.2s ease !important;
+    font-weight: 500 !important;
+    box-shadow: 0 1px 2px rgba(0,0,0,0.05) !important;
+}
+
+.example-btn:hover {
+    background: #f5f7ff !important;
+    border-color: #6366f1 !important;
+    transform: translateY(-1px);
+    box-shadow: 0 4px 6px -1px rgba(99, 102, 241, 0.1) !important;
+}
+
+/* Result Card */
+.result-card {
+    background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%);
+    border-radius: 20px;
+    padding: 40px;
+    text-align: center;
+    color: white;
+    box-shadow: 0 20px 25px -5px rgba(79, 70, 229, 0.3);
+    margin-top: 40px;
+    animation: slideUp 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.result-header {
+    font-size: 2em;
+    font-weight: 800;
+    margin-bottom: 15px;
+    text-shadow: 0 2px 4px rgba(0,0,0,0.1);
+}
+
+.result-score {
+    font-size: 3.5em;
+    font-weight: 800;
+    margin: 10px 0;
+    background: -webkit-linear-gradient(#ffffff, #e0e7ff);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+}
+
+.result-percentage {
+    font-size: 1.5em;
+    opacity: 0.9;
+    font-weight: 500;
+}
+
+/* Keyframes */
+@keyframes popIn {
+    from { opacity: 0; transform: scale(0.95) translateY(-5px); }
+    to { opacity: 1; transform: scale(1) translateY(0); }
+}
+
+@keyframes slideUp {
+    from { opacity: 0; transform: translateY(40px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+/* Hide Gradio Footer */
+footer { display: none !important; }
+.gradio-container .prose.footer-content { display: none !important; }
+"""
+
+# ----------------------------------------------------------------------
+# Main App
+# ----------------------------------------------------------------------
+
+with gr.Blocks(css=custom_css, title="SmartTutor AI") as demo:
+
+    # State
+    quiz_state = gr.State()
+
+    with gr.Column(elem_classes="header-box"):
+        gr.HTML(
+            """
+        <div style='color: white;'>
+            <h1 style='color: white; font-size: 3em; margin: 0;'>🧠 SmartTutor AI</h1>
+            <p style='color: #e0e7ff; font-size: 1.25em;'>Your intelligent companion for learning and assessment</p>
+        </div>
+        """
+        )
+
+    with gr.Row():
+        # Left Panel: Controls
+        with gr.Column(scale=1, variant="panel"):
+            file_input = gr.File(
+                label="📄 Upload Document", file_types=[".pdf", ".txt"], type="filepath"
+            )
+            user_input = gr.Textbox(
+                label="✍️ Request",
+                placeholder="e.g. 'Summarize this' or 'Create a quiz'",
+                lines=3,
+            )
+
+            # Quick Examples
+            with gr.Column(elem_id="examples-container"):
+                gr.Markdown("✨ **Quick Actions:**")
+                with gr.Row():
+                    ex_summarize = gr.Button(
+                        "📝 Summary (3 lines)", size="sm", elem_classes="example-btn"
+                    )
+                    ex_quiz = gr.Button(
+                        "🧪 3 Questions", size="sm", elem_classes="example-btn"
+                    )
+                with gr.Row():
+                    ex_explain = gr.Button(
+                        "💡 Main Concepts", size="sm", elem_classes="example-btn"
+                    )
+
+            with gr.Row():
+                submit_btn = gr.Button("🚀 Run", variant="primary")
+                clear_btn = gr.Button("🧹 Clear")
+
+        # Right Panel: Results
+        with gr.Column(scale=2):
+
+            # 1. Summary / Text Output
+            summary_output = gr.HTML(visible=True)
+
+            # 2. Quiz Group (Hidden initially)
+            with gr.Group(visible=False) as quiz_group:
+                gr.Markdown("## 📝 Quiz Time")
+                gr.Markdown("Select the correct answer for each question.")
+
+                # Create 10 Questions + Feedback slots
+                q_radios = []
+                q_feedbacks = []
+
+                for i in range(10):
+                    # Radio
+                    r = gr.Radio(
+                        label=f"Question {i+1}",
+                        visible=False,
+                        elem_classes="quiz-question",
+                    )
+                    q_radios.append(r)
+
+                    # Feedback (Markdown/HTML)
+                    fb = gr.HTML(visible=False)
+                    q_feedbacks.append(fb)
+
+                check_btn = gr.Button(
+                    "✅ Check Answers", variant="primary", visible=False
+                )
+
+                # Final Result Message
+                quiz_result_msg = gr.Markdown(visible=False)
+
+    # ------------------------------------------------------------------
+    # Events
+    # ------------------------------------------------------------------
+
+    # 1. Run Agent
+    # Returns: [Summary, QuizGroup, QuizState]
+    submit_btn.click(
+        fn=run_agent,
+        inputs=[file_input, user_input],
+        outputs=[summary_output, quiz_group, quiz_state],
+    ).success(
+        # On success, update the quiz UI components (21 items)
+        fn=render_quiz,
+        inputs=[quiz_state],
+        outputs=q_radios + q_feedbacks + [check_btn],
+    )
+
+    # Example Buttons Handling
+    # These will ONLY fill the text box. User must click 'Run' manually.
+
+    ex_summarize.click(
+        fn=lambda: "Summarize this document strictly in exactly 3 lines.",
+        outputs=[user_input],
+    )
+
+    ex_quiz.click(
+        fn=lambda: "Generate a quiz with exactly 3 multiple-choice questions.",
+        outputs=[user_input],
+    )
+
+    ex_explain.click(
+        fn=lambda: "Explain the 5 most important core concepts in this document clearly.",
+        outputs=[user_input],
+    )
+
+    # 2. Check Answers
+    # Inputs: State + 10 Radios
+    # Outputs: 10 Radios (Lock) + 10 Feedbacks (Show) + ResultMsg
+    check_btn.click(
+        fn=grade_quiz_ui,
+        inputs=[quiz_state] + q_radios,
+        outputs=q_radios + q_feedbacks + [quiz_result_msg],
+    )
+
+    # 3. Clear
+    def reset_ui():
+        # Reset everything to default
+        updates = [
+            gr.update(value=None, interactive=True, visible=False)
+        ] * 10  # Radios
+        fb_updates = [gr.update(value="", visible=False)] * 10  # Feedbacks
+        return (
+            None,
+            "",  # Inputs
+            gr.update(value="", visible=True),  # Summary
+            gr.update(visible=False),  # Quiz Group
+            None,  # State
+            *updates,
+            *fb_updates,  # Radios + Feedbacks
+            gr.update(visible=False),  # CheckBtn
+            gr.update(visible=False),  # ResultMsg
+        )
+
+    clear_btn.click(
+        fn=reset_ui,
+        inputs=[],
+        outputs=[file_input, user_input, summary_output, quiz_group, quiz_state]
+        + q_radios
+        + q_feedbacks
+        + [check_btn, quiz_result_msg],
+    )
+
+if __name__ == "__main__":
+    print("Starting SmartTutor AI...")
+    demo.launch(share=False)

architecture.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:979be7256d4949702bc8e598e555162c4c29ef5b22df58fb386963bf8ef745fe
+size 173342

quizzes_db.json

@@ -0,0 +1,253 @@
+{
+  "bc0a0de5-7257-4648-991f-dc148c41c4e2": {
+    "file_path": "C:\\Users\\Yaz00\\AppData\\Local\\Temp\\gradio\\cbb1f0b598874cdd2d33694a480d4a837fc795b1ef2c35bf341accce66d00612\\AISA 3 2.pdf",
+    "questions": [
+      {
+        "qid": "1",
+        "question": "What does AISA stand for?",
+        "options": {
+          "A": "Agentic Intelligence Systems Architecture",
+          "B": "Agentic AI Systems Architecture",
+          "C": "Autonomous Intelligent Systems Architecture",
+          "D": "Advanced Intelligent Systems Architecture"
+        },
+        "correct": "B",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "2",
+        "question": "What is a key feature of agentic AI systems according to the document?",
+        "options": {
+          "A": "Autonomous reasoning",
+          "B": "Limited interaction",
+          "C": "Static planning",
+          "D": "Manual reasoning"
+        },
+        "correct": "A",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "3",
+        "question": "What does the AISA framework aim to provide?",
+        "options": {
+          "A": "A fragmented approach to AI development",
+          "B": "A focus on ad hoc development",
+          "C": "A single-layered AI architecture",
+          "D": "A unified architectural framework for agentic AI systems"
+        },
+        "correct": "D",
+        "explanation": "",
+        "supporting_context": ""
+      }
+    ]
+  },
+  "ee196ded-ed87-45d9-90d7-3a82ca14808e": {
+    "file_path": "C:\\Users\\Yaz00\\AppData\\Local\\Temp\\gradio\\cbb1f0b598874cdd2d33694a480d4a837fc795b1ef2c35bf341accce66d00612\\AISA 3 2.pdf",
+    "questions": [
+      {
+        "qid": "1",
+        "question": "What does AISA stand for?",
+        "options": {
+          "A": "Advanced Intelligent Systems Architecture",
+          "B": "Artificial Intelligence Systems Architecture",
+          "C": "Autonomous Intelligent Systems Architecture",
+          "D": "Agentic AI Systems Architecture"
+        },
+        "correct": "D",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "2",
+        "question": "What is one of the main focuses of the AISA framework?",
+        "options": {
+          "A": "Simplifying AI models",
+          "B": "Reducing AI costs",
+          "C": "Integration of reasoning and infrastructure",
+          "D": "Fragmented development of AI systems"
+        },
+        "correct": "C",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "3",
+        "question": "When was the AISA paper published?",
+        "options": {
+          "A": "December 31, 2025",
+          "B": "January 1, 2025",
+          "C": "January 6, 2026",
+          "D": "February 1, 2026"
+        },
+        "correct": "C",
+        "explanation": "",
+        "supporting_context": ""
+      }
+    ]
+  },
+  "3a62fe3b-63ba-46a0-a0c4-09d261e70551": {
+    "file_path": "C:\\Users\\Yaz00\\AppData\\Local\\Temp\\gradio\\cbb1f0b598874cdd2d33694a480d4a837fc795b1ef2c35bf341accce66d00612\\AISA 3 2.pdf",
+    "questions": [
+      {
+        "qid": "1",
+        "question": "What does AISA stand for?",
+        "options": {
+          "A": "Agentic Intelligent Systems Architecture",
+          "B": "Advanced Intelligent Systems Architecture",
+          "C": "Autonomous Intelligent Systems Architecture",
+          "D": "Agentic AI Systems Architecture"
+        },
+        "correct": "D",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "2",
+        "question": "What is one of the main focuses of the AISA framework?",
+        "options": {
+          "A": "Limited interaction with environments",
+          "B": "Fragmented development of AI systems",
+          "C": "Ethical oversight and governance",
+          "D": "Simplified tool execution"
+        },
+        "correct": "C",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "3",
+        "question": "What does the AISA framework aim to unify?",
+        "options": {
+          "A": "Cognitive agent design and tool execution",
+          "B": "Hardware and software integration",
+          "C": "Data collection and analysis",
+          "D": "User interface design and user experience"
+        },
+        "correct": "A",
+        "explanation": "",
+        "supporting_context": ""
+      }
+    ]
+  },
+  "f652d60d-12fe-4641-95ba-219b6a24fd2b": {
+    "file_path": "C:\\Users\\Yaz00\\AppData\\Local\\Temp\\gradio\\cbb1f0b598874cdd2d33694a480d4a837fc795b1ef2c35bf341accce66d00612\\AISA 3 2.pdf",
+    "questions": [
+      {
+        "qid": "1",
+        "question": "What does AISA stand for?",
+        "options": {
+          "A": "Agentic AI Systems Architecture",
+          "B": "Agentic Intelligent Systems Architecture",
+          "C": "Autonomous Intelligent Systems Architecture",
+          "D": "Advanced Intelligent Systems Architecture"
+        },
+        "correct": "C",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "2",
+        "question": "What is one of the main focuses of the AISA framework?",
+        "options": {
+          "A": "Simplified tool execution",
+          "B": "Fragmented development of AI systems",
+          "C": "Ethical oversight and governance",
+          "D": "Limited interaction with environments"
+        },
+        "correct": "B",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "3",
+        "question": "What does the AISA framework aim to unify?",
+        "options": {
+          "A": "Hardware and software integration",
+          "B": "Cognitive agent design and tool execution",
+          "C": "Data collection and analysis",
+          "D": "User interface design and user experience"
+        },
+        "correct": "B",
+        "explanation": "",
+        "supporting_context": ""
+      }
+    ]
+  },
+  "d39aeec6-d084-4188-b079-ec74771cb31f": {
+    "file_path": "C:\\Users\\Yaz00\\AppData\\Local\\Temp\\gradio\\cbb1f0b598874cdd2d33694a480d4a837fc795b1ef2c35bf341accce66d00612\\AISA 3 2.pdf",
+    "questions": [
+      {
+        "qid": "1",
+        "question": "What is the primary focus of the AISA architecture?",
+        "options": {
+          "A": "Multi-agent systems",
+          "B": "Single-agent systems",
+          "C": "Data analysis",
+          "D": "Network security"
+        },
+        "correct": "A",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "2",
+        "question": "Which layer ensures alignment with human and institutional values in the AISA architecture?",
+        "options": {
+          "A": "Agentic Infrastructure Layer",
+          "B": "Cognitive Agent Layer",
+          "C": "Evaluation & Feedback Layer",
+          "D": "LLM Foundation Layer"
+        },
+        "correct": "C",
+        "explanation": "",
+        "supporting_context": ""
+      }
+    ]
+  },
+  "4dd3612d-9e7e-489a-8ba2-f53f9f6320d3": {
+    "file_path": "C:\\Users\\Yaz00\\AppData\\Local\\Temp\\gradio\\cbb1f0b598874cdd2d33694a480d4a837fc795b1ef2c35bf341accce66d00612\\AISA 3 2.pdf",
+    "questions": [
+      {
+        "qid": "1",
+        "question": "What does AISA stand for?",
+        "options": {
+          "A": "Autonomous Intelligent Systems Architecture",
+          "B": "Advanced Intelligent Systems Architecture",
+          "C": "Agentic Intelligent Systems Architecture",
+          "D": "Agentic AI Systems Architecture"
+        },
+        "correct": "D",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "2",
+        "question": "What is one of the main focuses of the AISA framework?",
+        "options": {
+          "A": "Simplified tool execution",
+          "B": "Ethical oversight and governance",
+          "C": "Fragmented development of AI systems",
+          "D": "Reducing AI capabilities"
+        },
+        "correct": "B",
+        "explanation": "",
+        "supporting_context": ""
+      },
+      {
+        "qid": "3",
+        "question": "When was the AISA framework introduced?",
+        "options": {
+          "A": "December 31, 2025",
+          "B": "February 1, 2026",
+          "C": "January 1, 2025",
+          "D": "January 6, 2026"
+        },
+        "correct": "D",
+        "explanation": "",
+        "supporting_context": ""
+      }
+    ]
+  }
+}

requirements.txt

@@ -0,0 +1,5 @@
+crewai>=0.1.0
+gradio>=4.0.0
+python-dotenv>=1.0.0
+pymupdf>=1.23.0
+pydantic>=2.0.0

smart_tutor_core.py

@@ -0,0 +1,677 @@
+import os, json, re, random
+import uuid
+import time
+import logging
+from typing import Literal, List, Dict, Any, Optional
+
+from pydantic import BaseModel, Field, ValidationError
+from crewai import Agent, Task, Crew, Process
+from crewai.tools import tool
+from crewai.llm import LLM
+
+import dotenv
+
+dotenv.load_dotenv(
+    r"C:\Users\Yaz00\OneDrive\سطح المكتب\Agent AI - Tuwaiq\week 5\Homework 1\api_key.env"
+)
+
+# ============================================================
+# Guardrails: logging, retries, deterministic config
+# ============================================================
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)s | %(message)s",
+)
+logger = logging.getLogger("smart_tutor_guardrails")
+
+DETERMINISTIC_TEMPERATURE = float(os.getenv("DETERMINISTIC_TEMPERATURE", "0.1"))
+TOOL_MAX_RETRIES = int(os.getenv("TOOL_MAX_RETRIES", "2"))
+
+# ============================================================
+# Guardrails: rate limits / timeouts / policies
+# ============================================================
+
+MAX_FILE_SIZE_MB = int(os.getenv("MAX_FILE_SIZE_MB", "500"))
+MAX_PDF_PAGES = int(os.getenv("MAX_PDF_PAGES", "2000"))
+PDF_EXTRACTION_TIMEOUT = float(os.getenv("PDF_EXTRACTION_TIMEOUT", "200"))  # seconds
+
+ALLOWED_TOOLS = {"process_file", "store_quiz", "grade_quiz"}
+
+PROMPT_INJECTION_PATTERNS = [
+    "ignore previous instructions",
+    "ignore all previous instructions",
+    "system:",
+    "assistant:",
+    "developer:",
+    "act as",
+    "you must",
+    "follow these instructions",
+    "override",
+]
+
+# ============================================================
+# Helpers
+# ============================================================
+
+
+def clean_text(text: str) -> str:
+    text = text.replace("\x00", " ")
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def detect_prompt_injection(text: str) -> bool:
+    lower = text.lower()
+    return any(p in lower for p in PROMPT_INJECTION_PATTERNS)
+
+
+def chunk_text(text: str, max_chars: int = 1200, overlap: int = 150) -> List[str]:
+    text = clean_text(text)
+    if not text:
+        return []
+    chunks = []
+    start = 0
+    n = len(text)
+    while start < n:
+        end = min(start + max_chars, n)
+        part = text[start:end].strip()
+        if part:
+            chunks.append(part)
+        if end == n:
+            break
+        start = max(0, end - overlap)
+    return chunks
+
+
+def keyword_retrieve(chunks: List[str], query: str, top_k: int) -> List[str]:
+    q_terms = [w for w in re.findall(r"\w+", query.lower()) if len(w) > 2]
+
+    def score(c: str) -> int:
+        c_l = c.lower()
+        return sum(1 for t in q_terms if t in c_l)
+
+    ranked = sorted(chunks, key=score, reverse=True)
+    return [c for c in ranked[:top_k] if c]
+
+
+# ============================================================
+# File extraction with limits + timeout
+# ============================================================
+
+
+def extract_text(file_path: str) -> str:
+    if os.path.getsize(file_path) > MAX_FILE_SIZE_MB * 1024 * 1024:
+        raise ValueError(f"File too large (> {MAX_FILE_SIZE_MB} MB)")
+
+    ext = os.path.splitext(file_path)[1].lower()
+
+    if ext == ".txt":
+        with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+            return f.read()
+
+    if ext == ".pdf":
+        import fitz  # PyMuPDF
+
+        start_time = time.time()
+        doc = fitz.open(file_path)
+
+        if len(doc) > MAX_PDF_PAGES:
+            raise ValueError(f"PDF exceeds max page limit ({MAX_PDF_PAGES})")
+
+        parts = []
+        for i in range(len(doc)):
+            if time.time() - start_time > PDF_EXTRACTION_TIMEOUT:
+                raise TimeoutError("PDF extraction timeout")
+            t = doc.load_page(i).get_text("text") or ""
+            t = clean_text(t)
+            if t:
+                parts.append(t)
+        return "\n\n".join(parts).strip()
+
+    raise ValueError("Unsupported file type (PDF/TXT only).")
+
+
+# ============================================================
+# Schemas (Structured Inputs / Outputs)
+# ============================================================
+
+
+class ProcessArgs(BaseModel):
+    file_path: str = Field(..., description="Local path to PDF/TXT")
+    query: str = Field(..., description="User question or instruction")
+    mode: Literal["summarize", "quiz", "explain"] = Field(..., description="Task type")
+    top_k: int = Field(6, ge=1, le=15, description="How many chunks to use as context")
+
+
+class QuizQuestion(BaseModel):
+    qid: str
+    question: str
+    options: Dict[Literal["A", "B", "C", "D"], str]
+    correct: Literal["A", "B", "C", "D"]
+    explanation: str = ""
+    supporting_context: str = ""
+
+
+class StoreQuizArgs(BaseModel):
+    file_path: str = Field(
+        ..., description="The absolute file path of the document used"
+    )
+    questions: List[QuizQuestion]
+
+
+class GradeQuizArgs(BaseModel):
+    quiz_id: str
+    answers: Dict[str, Literal["A", "B", "C", "D"]]
+
+
+class ToolError(BaseModel):
+    error: str
+    details: Optional[Any] = None
+
+
+class ProcessFileResult(BaseModel):
+    mode: str
+    query: str
+    context_chunks: List[str]
+    stats: Dict[str, Any]
+
+
+class StoreQuizResult(BaseModel):
+    quiz_id: str
+    questions: List[Dict[str, Any]]  # masked questions
+
+
+class GradeQuizResult(BaseModel):
+    quiz_id: str
+    score: int
+    total: int
+    percentage: float
+    file_path: Optional[str] = None
+    details: List[Dict[str, Any]]
+
+
+# ============================================================
+# Memory/State with Persistence
+# ============================================================
+
+QUIZ_FILE = "quizzes_db.json"
+
+
+def load_quizzes():
+    if os.path.exists(QUIZ_FILE):
+        try:
+            with open(QUIZ_FILE, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except:
+            return {}
+    return {}
+
+
+def save_quizzes(data):
+    try:
+        with open(QUIZ_FILE, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+    except Exception as e:
+        logger.error(f"Failed to save quizzes: {e}")
+
+
+QUIZ_STORE: Dict[str, Dict[str, Any]] = load_quizzes()
+
+
+# ============================================================
+# Tool wrapper: retries + logs + redaction
+# ============================================================
+
+
+def _redact(obj: Any) -> Any:
+    """Redact secrets + quiz answer key in logs."""
+    try:
+        if isinstance(obj, dict):
+            out = {}
+            for k, v in obj.items():
+                lk = str(k).lower()
+                if lk in {"openai_api_key", "api_key", "authorization", "x-api-key"}:
+                    out[k] = "***"
+                elif lk == "correct":
+                    out[k] = "***"
+                else:
+                    out[k] = _redact(v)
+            return out
+        if isinstance(obj, list):
+            return [_redact(x) for x in obj]
+        if isinstance(obj, str):
+            key = os.getenv("OPENAI_API_KEY") or ""
+            if key and key in obj:
+                return obj.replace(key, "***")
+            return obj
+        return obj
+    except Exception:
+        return "<redacted>"
+
+
+def safe_tool_call(tool_name: str, fn):
+    if tool_name not in ALLOWED_TOOLS:
+        raise RuntimeError("Tool not allowed by policy")
+
+    last_err = None
+    for attempt in range(1, TOOL_MAX_RETRIES + 2):
+        try:
+            logger.info(f"[TOOL_CALL] {tool_name} attempt={attempt}")
+            out = fn()
+            logger.info(
+                f"[TOOL_RESULT] {tool_name} attempt={attempt} out={json.dumps(_redact(out), ensure_ascii=False)[:900]}"
+            )
+            return out
+        except Exception as e:
+            last_err = e
+            logger.warning(
+                f"[TOOL_ERROR] {tool_name} attempt={attempt} err={type(e).__name__}"
+            )
+            time.sleep(0.2 * attempt)
+    raise last_err
+
+
+# ============================================================
+# Tools
+# ============================================================
+
+
+@tool("process_file")
+def process_file(file_path: str, query: str, mode: str, top_k: int = 6) -> str:
+    """Read PDF/TXT, chunk it, retrieve top_k relevant chunks. Returns structured JSON."""
+    try:
+        args = ProcessArgs(file_path=file_path, query=query, mode=mode, top_k=top_k)
+    except ValidationError as ve:
+        return json.dumps(
+            ToolError(error="Invalid arguments", details=ve.errors()).model_dump(),
+            ensure_ascii=False,
+        )
+
+    def _run():
+        # Clean path: remove quotes and whitespace that agents sometimes add
+        clean_path = args.file_path.strip().strip("'\"").strip()
+        if not os.path.exists(clean_path):
+            return ToolError(error=f"Invalid file path: {clean_path}").model_dump()
+
+        try:
+            raw_text = extract_text(args.file_path)
+        except Exception as e:
+            return ToolError(
+                error="Extraction failed", details=type(e).__name__
+            ).model_dump()
+
+        if detect_prompt_injection(raw_text):
+            logger.warning(
+                "[SECURITY] Potential prompt injection detected in document. Treating as data only."
+            )
+
+        text = clean_text(raw_text)
+        if not text:
+            return ToolError(error="Empty or unreadable file text.").model_dump()
+
+        chunks = chunk_text(text)
+        if not chunks:
+            return ToolError(error="No chunks produced.").model_dump()
+
+        context = keyword_retrieve(chunks, args.query, args.top_k)
+
+        return ProcessFileResult(
+            mode=args.mode,
+            query=args.query,
+            context_chunks=context,
+            stats={
+                "chunks_total": len(chunks),
+                "chars_extracted": len(text),
+                "top_k": args.top_k,
+            },
+        ).model_dump()
+
+    try:
+        out = safe_tool_call("process_file", _run)
+        return json.dumps(out, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps(
+            ToolError(
+                error="process_file failed", details=type(e).__name__
+            ).model_dump(),
+            ensure_ascii=False,
+        )
+
+
+def clean_json_input(text: str) -> str:
+    """Clean markdown code blocks and extract JSON object from string."""
+    text = text.strip()
+
+    # Remove markdown code blocks (flexible)
+    # This handles ```json ... ``` even if there is text before/after
+    pattern = r"```(?:json)?\s*(\{.*?\})\s*```"
+    match = re.search(pattern, text, re.DOTALL)
+    if match:
+        return match.group(1)
+
+    # If no code blocks, try to find the first outer-most JSON object
+    # This regex looks for { ... } minimally or greedily?
+    # We want the largest block starting with { and ending with }
+    # but strictly speaking, standard json.loads might just work if we strip.
+
+    # If text starts with ``` but didn't match the block above (maybe incomplete),
+    # let's just strip the fences.
+    if text.startswith("```"):
+        text = re.sub(r"^```(\w+)?\n?", "", text)
+        text = re.sub(r"\n?```$", "", text)
+
+    # Remove single backticks
+    if text.startswith("`") and text.endswith("`"):
+        text = text.strip("`")
+
+    return text.strip()
+
+
+@tool("store_quiz")
+def store_quiz(quiz_package_json: str) -> str:
+    """Store quiz with hidden answers; return masked quiz (no correct answers)."""
+
+    def _run():
+        try:
+            cleaned_json = clean_json_input(quiz_package_json)
+            # First try: direct parse
+            pkg_raw = json.loads(cleaned_json)
+        except json.JSONDecodeError:
+            # Second try: liberal regex search for { ... }
+            # Use dotall and greedy to capture nested objects
+            match = re.search(r"(\{.*\})", quiz_package_json, re.DOTALL)
+            if match:
+                try:
+                    pkg_raw = json.loads(match.group(1))
+                except json.JSONDecodeError as e:
+                    return ToolError(
+                        error=f"quiz_package_json is not valid JSON. Parse error: {str(e)}",
+                        details=f"Input fragment: {quiz_package_json[:200]}...",
+                    ).model_dump()
+            else:
+                return ToolError(
+                    error="quiz_package_json is not valid JSON (no braces found)",
+                    details=f"Input fragment: {quiz_package_json[:200]}...",
+                ).model_dump()
+
+        try:
+            pkg = StoreQuizArgs(**pkg_raw)
+        except ValidationError as ve:
+            return ToolError(
+                error="Invalid quiz_package_json", details=ve.errors()
+            ).model_dump()
+
+        quiz_id = str(uuid.uuid4())
+
+        # Randomize options for each question
+        final_questions = []
+        for q in pkg.questions:
+            # q is a QuizQuestion object
+            original_options = q.options  # dict e.g. {"A": "...", "B": "..."}
+            original_correct_key = q.correct  # "A"
+            correct_text = original_options[original_correct_key]
+
+            # Extract texts
+            option_texts = list(original_options.values())
+            random.shuffle(option_texts)
+
+            # Re-map to A, B, C, D
+            new_options = {}
+            new_correct_key = ""
+            keys = ["A", "B", "C", "D"]
+
+            # Handle cases with fewer than 4 options just in case
+            for i, text in enumerate(option_texts):
+                if i < len(keys):
+                    key = keys[i]
+                    new_options[key] = text
+                    if text == correct_text:
+                        new_correct_key = key
+
+            # Update the question object (create a copy/dict)
+            q_dump = q.model_dump()
+            q_dump["options"] = new_options
+            q_dump["correct"] = new_correct_key
+            final_questions.append(q_dump)
+
+        QUIZ_STORE[quiz_id] = {
+            "file_path": pkg.file_path,
+            "questions": final_questions,
+        }
+        save_quizzes(QUIZ_STORE)
+
+        masked = [
+            {"qid": q["qid"], "question": q["question"], "options": q["options"]}
+            for q in final_questions
+        ]
+        return StoreQuizResult(quiz_id=quiz_id, questions=masked).model_dump()
+
+    try:
+        out = safe_tool_call("store_quiz", _run)
+        return json.dumps(out, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps(
+            ToolError(error="store_quiz failed", details=type(e).__name__).model_dump(),
+            ensure_ascii=False,
+        )
+
+
+@tool("grade_quiz")
+def grade_quiz(quiz_id: str, answers_json: str) -> str:
+    """Grade quiz answers by quiz_id and answers_json. Returns score + details as structured JSON.
+    Also returns 'file_path' and 'question' text for further processing."""
+
+    def _run():
+        if quiz_id not in QUIZ_STORE:
+            return ToolError(error="Unknown quiz_id.").model_dump()
+
+        try:
+            cleaned_json = clean_json_input(answers_json)
+            submitted_raw = json.loads(cleaned_json)
+        except json.JSONDecodeError:
+            # Fallback
+            match = re.search(r"(\{.*\})", answers_json, re.DOTALL)
+            if match:
+                try:
+                    submitted_raw = json.loads(match.group(1))
+                except:
+                    return ToolError(
+                        error="answers_json is not valid JSON"
+                    ).model_dump()
+            else:
+                return ToolError(error="answers_json is not valid JSON").model_dump()
+
+        try:
+            args = GradeQuizArgs(quiz_id=quiz_id, answers=submitted_raw)
+        except ValidationError as ve:
+            return ToolError(
+                error="Invalid answers_json", details=ve.errors()
+            ).model_dump()
+
+        stored_data = QUIZ_STORE[args.quiz_id]
+        questions = stored_data["questions"]
+        file_path = stored_data.get("file_path")
+
+        total = len(questions)
+        score = 0
+        details = []
+
+        for q in questions:
+            qid = q["qid"]
+            correct = q["correct"]
+            question_text = q.get("question", "")
+
+            your = (args.answers.get(qid) or "").strip().upper()
+            is_correct = your == correct
+            score += 1 if is_correct else 0
+
+            details.append(
+                {
+                    "qid": qid,
+                    "question": question_text,  # Added for Agent context
+                    "is_correct": is_correct,
+                    "your_answer": your,
+                    "correct_answer": correct,  # NOTE: returned to tutor; OK for feedback
+                    "explanation": q.get("explanation", "") or "",
+                    "supporting_context": q.get("supporting_context", "") or "",
+                }
+            )
+
+        percentage = round((score / total) * 100, 2) if total else 0.0
+
+        return GradeQuizResult(
+            quiz_id=args.quiz_id,
+            score=score,
+            total=total,
+            percentage=percentage,
+            file_path=file_path,
+            details=details,
+        ).model_dump()
+
+    try:
+        out = safe_tool_call("grade_quiz", _run)
+        return json.dumps(out, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps(
+            ToolError(error="grade_quiz failed", details=type(e).__name__).model_dump(),
+            ensure_ascii=False,
+        )
+
+
+# ============================================================
+# CrewAI setup
+# ============================================================
+
+llm = LLM(
+    model="gpt-4o-mini",
+    api_key=os.getenv("OPENAI_API_KEY"),
+    temperature=DETERMINISTIC_TEMPERATURE,
+)
+
+manager = Agent(
+    role="Manager (Router)",
+    goal=(
+        "Route user request to the correct specialist co-worker."
+        " Pass ALL user constraints (line count, "
+        "paragraph count, language, etc.) to the specialist."
+    ),
+    backstory=(
+        "You are a routing agent. You HAVE specialist co-workers: "
+        "Summarizer, Quiz Maker, and Tutor. "
+        "Your ONLY job is to delegate the task to the right co-worker "
+        "using your delegation tool. "
+        "NEVER answer the user yourself. NEVER use internal knowledge. "
+        "Always forward the FULL user request including any constraints."
+    ),
+    allow_delegation=True,
+    llm=llm,
+    verbose=True,
+)
+
+summarizer = Agent(
+    role="Summarizer",
+    goal=(
+        "Produce a summary grounded strictly in "
+        "context_chunks from process_file. STRICTLY "
+        "follow any user constraints on length, "
+        "number of lines, paragraphs, or format."
+    ),
+    backstory=(
+        "Call process_file(mode=summarize) first. "
+        "Summarize ONLY from context_chunks. "
+        "If the user specifies constraints like "
+        "'3 lines', '2 paragraphs', 'short', or "
+        "'detailed', you MUST follow them exactly. "
+        "Use bullet points (- or *) for lists instead of numbering. "
+        "No outside knowledge."
+    ),
+    tools=[process_file],
+    llm=llm,
+    verbose=True,
+)
+
+quizzer = Agent(
+    role="Quiz Maker",
+    goal="Generate EXACTLY the number of multiple-choice questions requested by the user, grounded strictly in process_file context.",
+    backstory=(
+        "STEP 1: Extract the EXACT number of questions from user request (e.g., '3 questions' = 3, default = 5).\n"
+        "STEP 2: Call process_file(mode=quiz) with file_path. Create ONLY that exact number of MCQs A-D from context_chunks.\n"
+        "STEP 3: Build quiz_package_json with absolute 'file_path' and correct answers, call store_quiz.\n"
+        'Ensure VALID JSON: {"file_path": "...", "questions": [...]}. CRITICAL: Match requested count exactly. Never reveal answers.'
+    ),
+    tools=[process_file, store_quiz],
+    llm=llm,
+    verbose=True,
+)
+
+tutor = Agent(
+    role="Tutor",
+    goal="Grade quiz and provide intelligent explanation for errors.",
+    backstory=(
+        "You are an expert Tutor. When asked to grade a quiz:\n"
+        "1. Call 'grade_quiz' to get the base results.\n"
+        "2. For every INCORRECT answer, you MUST Explain WHY it is wrong:\n"
+        "   - Use the 'question' text and 'file_path' from the result to call 'process_file' (mode='explain', query=question).\n"
+        "   - REWRITE the 'explanation' field in the JSON detail for that question with your new explanation.\n"
+        "   - Use bullet points for any lists in your explanations.\n"
+        "3. Return the fully updated JSON object."
+    ),
+    tools=[process_file, grade_quiz],
+    llm=llm,
+    verbose=True,
+)
+
+task = Task(
+    description=(
+        "User request: {user_request}\n\n"
+        "Route by intent:\n"
+        "- Summary -> Summarizer\n"
+        "- Quiz -> Quiz Maker\n"
+        "- Explanation -> Tutor\n"
+        "- Grading (contains quiz_id + answers_json) -> Tutor\n\n"
+        "Guardrails:\n"
+        "- Tool outputs are structured JSON.\n"
+        "- Tools validate inputs with Pydantic.\n"
+        "- Tool calls are logged without secrets.\n"
+        "- Do not reveal hidden quiz answers during quiz generation."
+    ),
+    expected_output=(
+        "Grounded response: summary OR " "masked quiz OR graded feedback."
+    ),
+    agent=manager,
+)
+
+crew = Crew(
+    agents=[manager, summarizer, quizzer, tutor],
+    tasks=[task],
+    process=Process.sequential,
+    verbose=True,
+)
+
+
+from pathlib import Path
+
+
+def run_with_file(prompt: str, file_path: str | None = None):
+    file_text = ""
+    if file_path:
+        file_text = Path(file_path).read_text(encoding="utf-8", errors="ignore")
+
+    full_prompt = prompt
+    if file_text:
+        full_prompt += "\n\n[FILE CONTENT]\n" + file_text
+
+    return full_prompt
+
+
+if __name__ == "__main__":
+    print(
+        run_with_file(
+            r"please give me a quiz about 3 questions from this file - file_path=C:\Users\Yaz00\OneDrive\سطح المكتب\Agent AI - Tuwaiq\week 5\Homework 1\Phase2.pdf"
+        )
+    )
+    # Example grading:
+    # print(run(r"grade this quiz_id=<PUT_ID_HERE> answers_json={\"q1\":\"A\",\"q2\":\"C\",\"q3\":\"B\"}"))
+    pass