Upload 3 files

README.md

@@ -3,21 +3,24 @@ title: Pathshala AI
 colorFrom: green
 colorTo: blue
 sdk: gradio
-sdk_version: 6.14.0
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
-license: mit
 ---
 
 # Pathshala AI
 
 Pathshala AI is a bilingual AI tutor demo for rural primary students in Nepal.
 
-The Gradio Space accepts a student question in English, Nepali, or romanized Nepali plus optional textbook context, then returns:
+The Gradio Space mirrors the local Streamlit/web app flow. It can accept a student
+question in English, Nepali, or romanized Nepali plus optional textbook context, then returns:
 
 - English explanation
 - Nepali explanation
 - 3 simple quiz questions
+- Retrieved textbook sources
+- Quiz grading when a backend is configured
+- Parent/teacher summary when a backend is configured
 
 ## Deploy To Hugging Face Spaces
 
@@ -45,7 +48,8 @@ git push
 ## Recommended Submission Mode
 
 For the easiest hackathon submission, deploy the Space without `BACKEND_URL`.
-It will use the built-in mock fallback, so judges can try it immediately.
+It will use the built-in demo fallback, so judges can try it immediately by pasting
+textbook context into the question tab.
 
 For the full RAG workflow, first deploy the FastAPI backend somewhere public, then set `BACKEND_URL` in the Space settings.
 
@@ -63,12 +67,20 @@ In Hugging Face Spaces, add it under:
 Space settings -> Variables and secrets -> New variable
 ```
 
-The app calls `POST /ask` and displays the backend response.
+The app calls:
+
+- `POST /upload-textbook` for PDF uploads
+- `POST /ask` for bilingual textbook-grounded answers
+- `POST /grade-quiz` for quiz grading
+- `GET /parent-summary/{student_id}` for the parent/teacher summary
+
+The `/ask` request sends both the student question and the optional textbook context.
+If a user types context in the Space, the backend can answer from that context even when no PDF has been uploaded.
 If the backend returns `normalized_question`, the Space shows the interpreted question above the English explanation.
 
 ## Mock Mode
 
-If `BACKEND_URL` is missing or the backend is unavailable, the Space uses a simple mock fallback so the demo remains easy to try.
+If `BACKEND_URL` is missing or the backend is unavailable, the Space uses a simple demo fallback so the demo remains easy to try. PDF upload, quiz grading, and parent summaries require the backend.
 
 Example question:
 
@@ -80,4 +92,4 @@ You can also try mixed romanized Nepali questions such as:
 
 ```text
 photosynthesis vaneko ke ho vana
-```
+```

app.py

@@ -8,7 +8,11 @@ import requests
 
 load_dotenv()
 
+APP_NAME = os.getenv("APP_NAME", "Pathshala AI")
 BACKEND_URL = os.getenv("BACKEND_URL", "").rstrip("/")
+UPLOAD_TIMEOUT_SECONDS = 900
+ASK_TIMEOUT_SECONDS = 180
+SHORT_TIMEOUT_SECONDS = 45
 EXAMPLE_QUESTION = "soil erosion vaneko ke ho"
 EXAMPLE_CONTEXT = (
     "Soil erosion is the removal of topsoil by wind, water, or other natural forces. "
@@ -16,8 +20,46 @@ EXAMPLE_CONTEXT = (
 )
 
 
-def ask_tutor(question: str, textbook_context: str) -> tuple[str, str, str]:
+def upload_textbook(pdf_path: str | None) -> str:
+    if not pdf_path:
+        return "Choose a PDF first."
+
+    if not BACKEND_URL:
+        return "Backend URL is not configured for this Space. Paste context below to use demo mode."
+
+    try:
+        with open(pdf_path, "rb") as pdf_file:
+            response = requests.post(
+                f"{BACKEND_URL}/upload-textbook",
+                files={"file": (os.path.basename(pdf_path), pdf_file, "application/pdf")},
+                timeout=UPLOAD_TIMEOUT_SECONDS,
+            )
+
+        if response.ok:
+            result = response.json()
+            extraction_method = result.get("extraction_method")
+            method_text = f" Text extraction: {extraction_method}." if extraction_method else ""
+            return (
+                f"Uploaded {result['filename']} with {result['page_count']} pages "
+                f"and {result['chunk_count']} chunks.{method_text}"
+            )
+
+        return _response_error(response, "Upload failed.")
+    except requests.Timeout:
+        return "Backend is still processing the PDF. Try a smaller PDF for the demo."
+    except requests.RequestException as exc:
+        return f"Could not reach backend: {exc}"
+    except OSError as exc:
+        return f"Could not read uploaded PDF: {exc}"
+
+
+def ask_tutor(
+    question: str,
+    student_id: str,
+    textbook_context: str,
+) -> tuple[str, str, str, str, str, dict[str, Any]]:
     question = question.strip()
+    student_id = (student_id or "hf-space-demo").strip()
     textbook_context = textbook_context.strip()
 
     if not question:
@@ -25,10 +67,13 @@ def ask_tutor(question: str, textbook_context: str) -> tuple[str, str, str]:
             "Please type a student question.",
             "कृपया विद्यार्थीको प्रश्न लेख्नुहोस्।",
             "1. Add a question first.\n2. Then try again.\n3. Use a textbook topic.",
+            "",
+            "Waiting for a question.",
+            {},
         )
 
     if BACKEND_URL:
-        backend_result = ask_backend(question)
+        backend_result = ask_backend(question, student_id, textbook_context)
 
         if backend_result and not is_insufficient_backend_result(backend_result):
             return backend_result
@@ -36,16 +81,25 @@ def ask_tutor(question: str, textbook_context: str) -> tuple[str, str, str]:
     return mock_response(question=question, textbook_context=textbook_context)
 
 
-def ask_backend(question: str) -> tuple[str, str, str] | None:
+def ask_backend(
+    question: str,
+    student_id: str,
+    textbook_context: str,
+) -> tuple[str, str, str, str, str, dict[str, Any]] | None:
+    payload: dict[str, Any] = {
+        "question": question,
+        "student_id": student_id,
+        "language_support": "English and Nepali",
+    }
+
+    if textbook_context:
+        payload["textbook_context"] = textbook_context
+
     try:
         response = requests.post(
             f"{BACKEND_URL}/ask",
-            json={
-                "question": question,
-                "student_id": "hf-space-demo",
-                "language_support": "English and Nepali",
-            },
-            timeout=60,
+            json=payload,
+            timeout=ASK_TIMEOUT_SECONDS,
         )
         response.raise_for_status()
         data = response.json()
@@ -54,26 +108,113 @@ def ask_backend(question: str) -> tuple[str, str, str] | None:
     except ValueError:
         return None
 
-    return format_backend_response(data)
+    return format_backend_response(data, student_id=student_id)
 
 
-def format_backend_response(data: dict[str, Any]) -> tuple[str, str, str]:
-    quiz_questions = data.get("quiz_questions", [])
-    english_answer = data.get("answer_english", "No English answer returned.")
+def format_backend_response(
+    data: dict[str, Any],
+    student_id: str,
+) -> tuple[str, str, str, str, str, dict[str, Any]]:
+    english_answer = str(data.get("answer_english", "No English answer returned."))
     normalized_question = str(data.get("normalized_question") or "").strip()
 
     if normalized_question:
         english_answer = f"Interpreted question: {normalized_question}\n\n{english_answer}"
 
+    quiz_questions = data.get("quiz_questions", [])
+    state = {
+        "quiz_id": data.get("quiz_id"),
+        "quiz_questions": quiz_questions,
+        "student_id": student_id,
+    }
+
     return (
         english_answer,
-        data.get("answer_nepali", "नेपाली उत्तर प��राप्त भएन।"),
+        str(data.get("answer_nepali", "नेपाली उत्तर प्राप्त भएन।")),
         format_quiz(quiz_questions),
+        format_sources(data.get("retrieved_sources", [])),
+        "Answered with the backend RAG workflow.",
+        state,
     )
 
 
-def is_insufficient_backend_result(result: tuple[str, str, str]) -> bool:
-    combined = " ".join(result).lower()
+def grade_quiz(
+    answer_1: str,
+    answer_2: str,
+    answer_3: str,
+    student_id: str,
+    quiz_state: dict[str, Any] | None,
+) -> str:
+    if not BACKEND_URL:
+        return "Quiz grading needs the backend. Demo mode can show questions but cannot grade them."
+
+    quiz_state = quiz_state or {}
+    quiz_id = quiz_state.get("quiz_id")
+
+    if not quiz_id:
+        return "Ask the tutor first so a quiz can be created."
+
+    try:
+        response = requests.post(
+            f"{BACKEND_URL}/grade-quiz",
+            json={
+                "student_id": (student_id or "hf-space-demo").strip(),
+                "quiz_id": quiz_id,
+                "answers": [answer_1, answer_2, answer_3],
+            },
+            timeout=SHORT_TIMEOUT_SECONDS,
+        )
+
+        if not response.ok:
+            return _response_error(response, "Quiz grading failed.")
+
+        return format_grade(response.json())
+    except requests.Timeout:
+        return "Quiz grading timed out. Please try again."
+    except requests.RequestException as exc:
+        return f"Could not reach backend: {exc}"
+    except ValueError:
+        return "Quiz grading returned an invalid response."
+
+
+def parent_summary(student_id: str) -> str:
+    if not BACKEND_URL:
+        return "Parent/teacher summary needs the backend."
+
+    student_id = (student_id or "hf-space-demo").strip()
+
+    try:
+        response = requests.get(
+            f"{BACKEND_URL}/parent-summary/{student_id}",
+            timeout=SHORT_TIMEOUT_SECONDS,
+        )
+
+        if not response.ok:
+            return _response_error(response, "Summary failed.")
+
+        summary = response.json()
+    except requests.Timeout:
+        return "Summary request timed out. Please try again."
+    except requests.RequestException as exc:
+        return f"Could not reach backend: {exc}"
+    except ValueError:
+        return "Summary returned an invalid response."
+
+    strengths = "\n".join(f"- {item}" for item in summary.get("strengths", []))
+    weak_topics = summary.get("weak_topics", [])
+    weak_topic_text = "\n".join(f"- {item}" for item in weak_topics) if weak_topics else "No weak topics recorded yet."
+
+    return (
+        f"Strengths\n{strengths}\n\n"
+        f"Weak topics\n{weak_topic_text}\n\n"
+        f"Suggested next practice\n{summary.get('suggested_next_practice', '')}\n\n"
+        f"Encouraging note\n{summary.get('encouraging_note', '')}\n\n"
+        f"Questions asked: {summary.get('questions_asked', 0)}"
+    )
+
+
+def is_insufficient_backend_result(result: tuple[str, str, str, str, str, dict[str, Any]]) -> bool:
+    combined = " ".join(str(item) for item in result[:5]).lower()
     markers = [
         "not have enough textbook context",
         "not enough textbook context",
@@ -84,33 +225,81 @@ def is_insufficient_backend_result(result: tuple[str, str, str]) -> bool:
     return any(marker in combined for marker in markers)
 
 
-def mock_response(question: str, textbook_context: str) -> tuple[str, str, str]:
+def mock_response(question: str, textbook_context: str) -> tuple[str, str, str, str, str, dict[str, Any]]:
     context = textbook_context or EXAMPLE_CONTEXT
-    simple_context = truncate(context, max_length=450)
     normalized_question = normalize_question_mock(question)
+    concept_answer = mock_english_explanation(normalized_question, context)
 
-    english = (
-        f"Interpreted question: {normalized_question}\n\n"
-        "Mock demo answer: I am using the textbook context only. "
-        f"A simple explanation is: {simple_context}"
-    )
-    nepali = (
-        "मक डेमो उत्तर: म पाठ्यपुस्तकको सन्दर्भ मात्र प्रयोग गर्दैछु। "
-        f"{mock_nepali_explanation(normalized_question)}"
+    english = f"Interpreted question: {normalized_question}\n\n{concept_answer}"
+    nepali = mock_nepali_explanation(normalized_question, context)
+    quiz_questions = mock_quiz_questions(normalized_question)
+
+    return (
+        english,
+        nepali,
+        format_quiz(quiz_questions),
+        format_sources(
+            [
+                {
+                    "score": 1.0,
+                    "text": context,
+                    "metadata": {"filename": "demo-context", "chunk_index": 0},
+                }
+            ]
+        ),
+        "Demo fallback is active. Configure BACKEND_URL in Space settings for PDF upload, RAG search, quiz grading, and parent summary.",
+        {"quiz_questions": quiz_questions},
     )
-    quiz = format_quiz(
-        [
-            "What is the main idea from the explanation?",
-            "Can you give one simple example?",
-            "Can you explain it in your own words?",
-        ]
+
+
+def mock_english_explanation(normalized_question: str, context: str) -> str:
+    text = f"{normalized_question} {context}".lower()
+
+    if "reflection" in text or "mirror" in text:
+        return (
+            "Reflection of light means light bounces back after hitting a surface. "
+            "A mirror reflects light in an orderly way, so we can see a clear image "
+            "of an object in it. Smooth, flat surfaces make clearer reflections, "
+            "while rough surfaces scatter light and do not show a clear image."
+        )
+
+    if "soil erosion" in text:
+        return (
+            "Soil erosion means the top fertile layer of soil is carried away by "
+            "water, wind, or other causes. It makes land less useful for growing "
+            "plants, so planting trees and grass helps protect the soil."
+        )
+
+    if "photosynthesis" in text:
+        return (
+            "Photosynthesis is the process by which green plants make their own food "
+            "using sunlight, water, and carbon dioxide. Chlorophyll in leaves helps "
+            "plants capture sunlight, and oxygen is released during the process."
+        )
+
+    if "fraction" in text:
+        return (
+            "A fraction shows a part of a whole. The top number tells how many parts "
+            "we have, and the bottom number tells how many equal parts the whole was "
+            "divided into."
+        )
+
+    return (
+        "Demo answer from the pasted textbook context: "
+        f"{truncate(context, max_length=450)}"
     )
 
-    return english, nepali, quiz
 
+def mock_nepali_explanation(normalized_question: str, context: str = "") -> str:
+    text = f"{normalized_question} {context}".lower()
 
-def mock_nepali_explanation(normalized_question: str) -> str:
-    text = normalized_question.lower()
+    if "reflection" in text or "mirror" in text:
+        return (
+            "प्रकाशको परावर्तन भनेको प्रकाश कुनै सतहमा ठोक्किएर फर्कनु हो। ऐनाले "
+            "प्रकाशलाई राम्रोसँग फर्काउँछ, त्यसैले त्यसमा वस्तुको प्रतिबिम्ब देखिन्छ। "
+            "समथर र चिल्लो सतहमा प्रतिबिम्ब प्रस्ट देखिन्छ, तर खस्रो सतहमा प्रकाश धेरै "
+            "दिशामा छरिने भएकाले प्रतिबिम्ब प्रस्ट देखिँदैन।"
+        )
 
     if "soil erosion" in text:
         return (
@@ -147,6 +336,9 @@ def normalize_question_mock(question: str) -> str:
     if "soil erosion" in text or ("mato" in text and "katan" in text):
         return "What is soil erosion?"
 
+    if "reflection" in text or "mirror" in text or "ainaa" in text or "aaina" in text:
+        return "What is reflection of light?"
+
     if "photosynthesis" in text or ("prakash" in text and "sansleshan" in text):
         return "What is photosynthesis?"
 
@@ -205,6 +397,23 @@ def extract_mixed_language_topic(text: str) -> str:
     return topic
 
 
+def mock_quiz_questions(normalized_question: str) -> list[str]:
+    text = normalized_question.lower()
+
+    if "reflection" in text:
+        return [
+            "What happens to light during reflection?",
+            "Why does a mirror show a clear image?",
+            "Why do rough surfaces not show clear reflections?",
+        ]
+
+    return [
+        "What is the main idea from the explanation?",
+        "Can you give one simple example?",
+        "Can you explain it in your own words?",
+    ]
+
+
 def format_quiz(quiz_questions: list[Any]) -> str:
     questions = [
         str(question).strip()
@@ -225,6 +434,52 @@ def format_quiz(quiz_questions: list[Any]) -> str:
     )
 
 
+def format_sources(sources: list[Any]) -> str:
+    if not sources:
+        return "No retrieved sources returned."
+
+    formatted = []
+
+    for source in sources[:5]:
+        if not isinstance(source, dict):
+            continue
+
+        metadata = source.get("metadata", {}) if isinstance(source.get("metadata"), dict) else {}
+        filename = metadata.get("filename", "textbook")
+        chunk_index = metadata.get("chunk_index", "unknown")
+        score = source.get("score", 0)
+        text = str(source.get("text", "")).strip()
+        formatted.append(
+            f"Source: {filename}, chunk {chunk_index}, score {float(score):.3f}\n{text}"
+        )
+
+    return "\n\n".join(formatted) if formatted else "No retrieved sources returned."
+
+
+def format_grade(data: dict[str, Any]) -> str:
+    lines = [f"Score: {data.get('score', 0)} / {data.get('total', 0)}"]
+    weak_areas = data.get("weak_areas", [])
+
+    if weak_areas:
+        lines.append(f"Weak areas: {', '.join(str(item) for item in weak_areas)}")
+
+    for item in data.get("results", []):
+        status = "Correct" if item.get("is_correct") else "Needs practice"
+        lines.append(f"{status}: {item.get('question', '')}")
+
+        if not item.get("is_correct"):
+            lines.append(f"Expected idea: {item.get('expected_answer', '')}")
+
+    return "\n".join(lines)
+
+
+def _response_error(response: requests.Response, fallback: str) -> str:
+    try:
+        return str(response.json().get("detail", fallback))
+    except ValueError:
+        return fallback
+
+
 def truncate(text: str, max_length: int) -> str:
     if len(text) <= max_length:
         return text
@@ -232,54 +487,81 @@ def truncate(text: str, max_length: int) -> str:
     return f"{text[: max_length - 3]}..."
 
 
-with gr.Blocks(title="Pathshala AI", theme=gr.themes.Soft()) as demo:
+with gr.Blocks(title=APP_NAME, theme=gr.themes.Soft()) as demo:
     gr.Markdown(
         """
         # Pathshala AI
-        Bilingual AI tutor for rural primary students in Nepal. Try English, Nepali,
-        or romanized Nepali questions like `soil erosion vaneko ke ho`.
+        Bilingual AI tutor for rural primary students in Nepal. Upload a PDF when a
+        public backend is configured, or paste textbook context for the Space demo.
         """
     )
 
+    quiz_state = gr.State({})
+
     with gr.Row():
-        with gr.Column(scale=1):
-            question_input = gr.Textbox(
-                label="Student question",
-                placeholder=EXAMPLE_QUESTION,
-                value=EXAMPLE_QUESTION,
-                lines=2,
-            )
-            context_input = gr.Textbox(
-                label="Optional textbook context",
-                placeholder="Paste a short textbook paragraph here.",
-                value=EXAMPLE_CONTEXT,
-                lines=5,
-            )
-            ask_button = gr.Button("Ask Tutor", variant="primary")
+        student_id_input = gr.Textbox(
+            label="Student ID",
+            value="hf-space-demo",
+            scale=1,
+        )
+        status_output = gr.Textbox(
+            label="Status",
+            value=(
+                "Backend connected." if BACKEND_URL else
+                "Demo fallback active. Set BACKEND_URL in Space settings for full RAG."
+            ),
+            interactive=False,
+            scale=2,
+        )
 
-        with gr.Column(scale=1):
-            english_output = gr.Textbox(
-                label="English explanation",
-                lines=6,
-            )
-            nepali_output = gr.Textbox(
-                label="Nepali explanation",
-                lines=6,
-            )
-            quiz_output = gr.Textbox(
-                label="3 quiz questions",
-                lines=5,
-            )
+    with gr.Tab("Ask"):
+        with gr.Row():
+            with gr.Column(scale=1):
+                pdf_input = gr.File(label="Upload textbook or worksheet PDF", file_types=[".pdf"], type="filepath")
+                upload_button = gr.Button("Upload PDF")
+                upload_output = gr.Textbox(label="Upload result", lines=3, interactive=False)
+
+                question_input = gr.Textbox(
+                    label="Student question",
+                    placeholder=EXAMPLE_QUESTION,
+                    value=EXAMPLE_QUESTION,
+                    lines=2,
+                )
+                context_input = gr.Textbox(
+                    label="Optional textbook context",
+                    placeholder="Paste a short textbook paragraph here.",
+                    value=EXAMPLE_CONTEXT,
+                    lines=7,
+                )
+                ask_button = gr.Button("Ask Tutor", variant="primary")
+
+            with gr.Column(scale=1):
+                english_output = gr.Textbox(label="English explanation", lines=8)
+                nepali_output = gr.Textbox(label="Nepali explanation", lines=8)
+                quiz_output = gr.Textbox(label="3 quiz questions", lines=5)
+
+        sources_output = gr.Textbox(label="Retrieved sources", lines=8)
+
+    with gr.Tab("Quiz"):
+        answer_1 = gr.Textbox(label="Your answer 1")
+        answer_2 = gr.Textbox(label="Your answer 2")
+        answer_3 = gr.Textbox(label="Your answer 3")
+        grade_button = gr.Button("Submit Quiz Answers", variant="primary")
+        grade_output = gr.Textbox(label="Quiz result", lines=10)
+
+    with gr.Tab("Parent Summary"):
+        summary_button = gr.Button("Show Parent/Teacher Summary")
+        summary_output = gr.Textbox(label="Summary", lines=14)
 
     gr.Examples(
         examples=[
             [EXAMPLE_QUESTION, EXAMPLE_CONTEXT],
             [
-                "What is a fraction?",
+                "What is reflection of light?",
                 (
-                    "A fraction shows a part of a whole. The top number tells how many "
-                    "parts we have. The bottom number tells how many equal parts the "
-                    "whole is divided into."
+                    "When an object is placed in front of the mirror, the image is formed "
+                    "due to reflection of light from the mirror. Flat and smooth surfaces "
+                    "reflect light clearly, while rough surfaces do not."
                 ),
             ],
             [
@@ -291,15 +573,44 @@ with gr.Blocks(title="Pathshala AI", theme=gr.themes.Soft()) as demo:
             ],
         ],
         inputs=[question_input, context_input],
-        outputs=[english_output, nepali_output, quiz_output],
-        fn=ask_tutor,
+        outputs=[
+            english_output,
+            nepali_output,
+            quiz_output,
+            sources_output,
+            status_output,
+            quiz_state,
+        ],
+        fn=lambda question, context: ask_tutor(question, "hf-space-demo", context),
         cache_examples=False,
     )
 
+    upload_button.click(
+        fn=upload_textbook,
+        inputs=[pdf_input],
+        outputs=[upload_output],
+    )
     ask_button.click(
         fn=ask_tutor,
-        inputs=[question_input, context_input],
-        outputs=[english_output, nepali_output, quiz_output],
+        inputs=[question_input, student_id_input, context_input],
+        outputs=[
+            english_output,
+            nepali_output,
+            quiz_output,
+            sources_output,
+            status_output,
+            quiz_state,
+        ],
+    )
+    grade_button.click(
+        fn=grade_quiz,
+        inputs=[answer_1, answer_2, answer_3, student_id_input, quiz_state],
+        outputs=[grade_output],
+    )
+    summary_button.click(
+        fn=parent_summary,
+        inputs=[student_id_input],
+        outputs=[summary_output],
     )