Upload 3 files

README.md

@@ -22,4 +22,10 @@ This Hugging Face Space supports:
 - Generating Nepali quiz questions
 - Basic quiz grading
 
-For scanned PDF OCR and persistent progress, deploy the FastAPI backend separately and add a Space variable named `BACKEND_URL`.
+For the full web-app workflow, deploy the FastAPI backend separately and add a Space variable named `BACKEND_URL`.
+
+Without `BACKEND_URL`, the Space can still run the same style of workflow locally. Add these Space secrets/variables to match the web app more closely:
+
+- `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL` for the AMD/vLLM tutor
+- `TRANSLATION_PROVIDER=gemini`, `GEMINI_API_KEY`, `GEMINI_MODEL` for Nepali adaptation and romanized question normalization
+- `OCR_PROVIDER=gemini`, `OCR_MAX_PAGES=5` for scanned or custom-font PDFs

app.py

@@ -1,3 +1,4 @@
+import base64
 import json
 import os
 from functools import lru_cache
@@ -12,6 +13,14 @@ load_dotenv()
 
 APP_NAME = os.getenv("APP_NAME", "Pathshala AI")
 BACKEND_URL = os.getenv("BACKEND_URL", "").rstrip("/")
+LLM_BASE_URL = os.getenv("LLM_BASE_URL", "").strip().rstrip("/")
+LLM_API_KEY = os.getenv("LLM_API_KEY", "")
+LLM_MODEL = os.getenv("LLM_MODEL", "Qwen/Qwen2.5-1.5B-Instruct")
+TRANSLATION_PROVIDER = os.getenv("TRANSLATION_PROVIDER", "mock").strip().lower()
+GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "")
+GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-2.5-flash")
+OCR_PROVIDER = os.getenv("OCR_PROVIDER", "off").strip().lower()
+OCR_MAX_PAGES = int(os.getenv("OCR_MAX_PAGES", "5") or "5")
 EMBEDDING_MODEL = os.getenv(
     "EMBEDDING_MODEL",
     "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
@@ -23,6 +32,7 @@ EXAMPLE_CONTEXT = (
 )
 MIN_CHUNK_CHARS = 250
 MAX_CHUNK_CHARS = 900
+MIN_TEXT_CHARACTERS_FOR_DIRECT_EXTRACTION = 300
 
 
 def upload_textbook(pdf_path):
@@ -36,6 +46,16 @@ def upload_textbook(pdf_path):
 
     try:
         extracted = extract_pdf_text(pdf_path)
+        if is_garbled_pdf_text(extracted["text"]):
+            return (
+                "This PDF has a broken custom-font text layer, so the extracted text "
+                "is not readable Nepali. Use the backend with Gemini OCR enabled, "
+                "upload a Unicode Nepali PDF, or paste a readable lesson paragraph "
+                "into the context box.",
+                "{}",
+                gr.update(),
+            )
+
         chunks = chunk_text(extracted["text"])
         if not chunks:
             return "No readable text chunks could be created from this PDF.", "{}", gr.update()
@@ -52,6 +72,8 @@ def upload_textbook(pdf_path):
             f"Uploaded {state['filename']} inside this Space with "
             f"{state['page_count']} pages and {state['chunk_count']} chunks."
         )
+        if extracted.get("extraction_method"):
+            message = f"{message} Text extraction: {extracted['extraction_method']}."
         return message, encode_state(state), gr.update(value="")
     except Exception as exc:
         return f"Could not process uploaded PDF: {exc}", "{}", gr.update()
@@ -105,16 +127,19 @@ def ask_tutor(question, student_id, textbook_context, textbook_state):
     if not sources:
         sources = sources_from_context(EXAMPLE_CONTEXT)
 
+    normalized_question = normalize_question(question)
     context = "\n\n".join(source["text"] for source in sources)
-    english = (
-        f"Interpreted question: {normalize_question(question)}\n\n"
-        f"Answer from textbook context:\n{truncate(context, 700)}"
-    )
-    nepali = nepali_answer(normalize_question(question), context)
+    english_answer = generate_english_answer(normalized_question, sources)
+    english = f"Interpreted question: {normalized_question}\n\n{english_answer}"
+    nepali = adapt_nepali_answer(question, english_answer, sources)
     quiz_questions = nepali_quiz_questions(context)
     quiz_state = {
         "quiz_questions": quiz_questions,
         "expected_answers": [source_answer(sources)] * 3,
+        "topic": display_topic(normalized_question),
+        "question": question,
+        "score": None,
+        "total": 3,
     }
     return (
         english,
@@ -164,6 +189,187 @@ def ask_backend(question, student_id, textbook_context):
     )
 
 
+def generate_english_answer(question, sources):
+    if not sources:
+        return "I do not have enough textbook context to answer this question."
+
+    if not LLM_BASE_URL:
+        return fallback_english_answer(sources)
+
+    system_prompt = (
+        "You are a primary-school tutor. Use only the provided textbook context. "
+        "Write the answer in simple English. Keep the explanation short. Explain "
+        "the idea in your own words instead of copying long textbook lines. Ignore "
+        "OCR artifacts, broken words, page numbers, and source labels. If the "
+        "context is insufficient, say that you do not have enough textbook context."
+    )
+    prompt = (
+        f"Student question:\n{question}\n\n"
+        f"Textbook context:\n{format_sources_for_prompt(sources)}\n\n"
+        "Answer the student's question directly in 2 to 4 simple sentences."
+    )
+
+    try:
+        return complete_with_llm(
+            prompt=prompt,
+            system_prompt=system_prompt,
+            temperature=0.2,
+            max_tokens=450,
+        )
+    except (requests.RequestException, KeyError, IndexError, TypeError, ValueError):
+        return fallback_english_answer(sources)
+
+
+def complete_with_llm(prompt, system_prompt="", temperature=0.2, max_tokens=512):
+    messages = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    messages.append({"role": "user", "content": prompt})
+
+    headers = {"Content-Type": "application/json"}
+    if LLM_API_KEY:
+        headers["Authorization"] = f"Bearer {LLM_API_KEY}"
+
+    response = requests.post(
+        f"{LLM_BASE_URL}/chat/completions",
+        json={
+            "model": LLM_MODEL,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        },
+        headers=headers,
+        timeout=180,
+    )
+    response.raise_for_status()
+    data = response.json()
+    return str(data["choices"][0]["message"]["content"]).strip()
+
+
+def adapt_nepali_answer(question, english_answer, sources):
+    if TRANSLATION_PROVIDER == "gemini" and GEMINI_API_KEY:
+        try:
+            translated = translate_with_gemini(question, english_answer)
+            translated = remove_source_lines(translated)
+            if is_valid_nepali(translated):
+                return translated
+        except (requests.RequestException, KeyError, IndexError, TypeError, ValueError):
+            pass
+
+    return nepali_answer(question, " ".join(str(source.get("text", "")) for source in sources))
+
+
+def translate_with_gemini(question, english_answer):
+    prompt = (
+        "Translate and simplify this grounded English tutoring answer into natural "
+        "Nepali for a primary-school student in Nepal. Keep the same meaning. "
+        "Use Nepali Devanagari only. Do not add new facts. Do not include source "
+        "citations or headings.\n\n"
+        f"Student question:\n{question}\n\n"
+        f"English answer:\n{english_answer}"
+    )
+    return gemini_generate_text(prompt, temperature=0.1, max_output_tokens=450)
+
+
+def normalize_with_gemini(question):
+    prompt = (
+        "Convert this student question into one clear, simple English question for "
+        "textbook search. The question may be written in English, Nepali Devanagari, "
+        "or romanized Nepali typed with English letters. Do not answer the question. "
+        "Return only the rewritten English question.\n\n"
+        f"Student question:\n{question}"
+    )
+    normalized = gemini_generate_text(prompt, temperature=0, max_output_tokens=80)
+    normalized = normalized.strip().strip("\"'`").splitlines()[0].strip()
+    if normalized and "?" not in normalized and len(normalized.split()) > 1:
+        normalized = f"{normalized}?"
+    if len(normalized) > 180 or len(normalized.strip("?").split()) < 3:
+        return ""
+    return normalized
+
+
+def gemini_generate_text(prompt, temperature=0.1, max_output_tokens=450, parts=None):
+    endpoint = (
+        "https://generativelanguage.googleapis.com/v1beta/"
+        f"models/{GEMINI_MODEL}:generateContent"
+    )
+    content_parts = parts or [{"text": prompt}]
+    response = requests.post(
+        endpoint,
+        json={
+            "contents": [{"parts": content_parts}],
+            "generationConfig": {
+                "temperature": temperature,
+                "maxOutputTokens": max_output_tokens,
+            },
+        },
+        headers={
+            "Content-Type": "application/json",
+            "x-goog-api-key": GEMINI_API_KEY,
+        },
+        timeout=60,
+    )
+    response.raise_for_status()
+    data = response.json()
+    return data["candidates"][0]["content"]["parts"][0]["text"].strip()
+
+
+def fallback_english_answer(sources):
+    context = str(sources[0].get("text", "")).strip()
+    if not context:
+        return "I do not have enough textbook context to answer this question."
+
+    topic_text = " ".join(str(source.get("text", "")) for source in sources[:3]).lower()
+    if "soil erosion" in topic_text or "erosion" in topic_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 protecting soil with plants and controlled water flow is important."
+        )
+    if "photosynthesis" in topic_text or "chlorophyll" in topic_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."
+        )
+
+    return "Based on the textbook context, here is the simple explanation: " + truncate(
+        " ".join(context.split()),
+        500,
+    )
+
+
+def format_sources_for_prompt(sources):
+    formatted = []
+    for index, source in enumerate(sources, start=1):
+        metadata = source.get("metadata", {})
+        filename = metadata.get("filename", "textbook")
+        chunk_index = metadata.get("chunk_index", "unknown")
+        formatted.append(
+            f"[Source {index}: {filename}, chunk {chunk_index}]\n{source.get('text', '')}"
+        )
+    return "\n\n".join(formatted)
+
+
+def is_valid_nepali(text):
+    devanagari_count = sum(1 for character in text if "\u0900" <= character <= "\u097f")
+    latin_count = sum(1 for character in text if character.isascii() and character.isalpha())
+    if devanagari_count < 20 or latin_count > 12:
+        return False
+    forbidden_markers = ["source", "student question", "english answer", "external"]
+    return not any(marker in text.lower() for marker in forbidden_markers)
+
+
+def remove_source_lines(text):
+    lines = []
+    for line in str(text).splitlines():
+        lowered = line.lower()
+        if "source" in lowered or "स्रोत:" in line:
+            continue
+        lines.append(line)
+    return "\n".join(lines).strip()
+
+
 def grade_quiz(answer_1, answer_2, answer_3, student_id, quiz_state):
     state = decode_state(quiz_state)
 
@@ -179,14 +385,18 @@ def grade_quiz(answer_1, answer_2, answer_3, student_id, quiz_state):
                 timeout=45,
             )
             if response.ok:
-                return format_grade(response.json())
+                data = response.json()
+                state["score"] = data.get("score")
+                state["total"] = data.get("total")
+                state["weak_topics"] = data.get("weak_areas", [])
+                return format_grade(data), encode_state(state)
         except (requests.RequestException, ValueError):
             pass
 
     questions = state.get("quiz_questions", [])
     expected_answers = state.get("expected_answers", [])
     if not questions:
-        return "Ask the tutor first so a quiz can be created."
+        return "Ask the tutor first so a quiz can be created.", encode_state(state)
 
     answers = [answer_1, answer_2, answer_3]
     score = 0
@@ -199,15 +409,52 @@ def grade_quiz(answer_1, answer_2, answer_3, student_id, quiz_state):
         lines.append(f"{'Correct' if is_correct else 'Needs practice'}: {question}")
         if not is_correct and expected:
             lines.append(f"Expected idea: {expected}")
-    return f"Score: {score} / {min(len(questions), 3)}\n" + "\n".join(lines)
+
+    state["score"] = score
+    state["total"] = min(len(questions), 3)
+    state["last_result"] = f"Score: {score} / {min(len(questions), 3)}"
+    state["weak_topics"] = [] if score >= state["total"] else [state.get("topic", "मुख्य पाठ")]
+    return f"Score: {score} / {min(len(questions), 3)}\n" + "\n".join(lines), encode_state(state)
 
 
-def parent_summary(student_id):
+def parent_summary(student_id, quiz_state):
     if not BACKEND_URL:
+        state = decode_state(quiz_state)
+        topic = state.get("topic") or "आजको पाठ"
+        score = state.get("score")
+        total = state.get("total") or 3
+        question = state.get("question") or "पाठ्यपुस्तकको प्रश्न"
+
+        if score is None:
+            return (
+                "Parent/teacher summary\n\n"
+                f"विद्यार्थीले {question} बारे प्रश्न सोधेको छ। अझै क्विज पेश गरिएको छैन। "
+                "उत्तर पढेपछि ३ वटा छोटा प्रश्न प्रयास गराउनुहोस्।"
+            )
+
+        if score >= max(total - 1, 1):
+            strength = f"{topic} को मुख्य विचार राम्रोसँग समात्दैछ।"
+            weak = "अहिले कुनै स्पष्ट कमजोर क्षेत्र देखिएको छैन।"
+            next_step = f"{topic} बाट अर्को उदाहरण वा अभ्यास प्रश्न गराउनुहोस्।"
+            note = "विद्यार्थीले राम्रो प्रगति देखाएको छ। छोटो दैनिक अभ्यास जारी राख्नुहोस्।"
+        elif score > 0:
+            strength = "विद्यार्थीले केही मुख्य कुरा बुझ्न थालेको छ।"
+            weak = f"{topic} का परिभाषा, मुख्य शब्द, र उदाहरण अझै अभ्यास गर्नुपर्छ।"
+            next_step = f"{topic} को पाठ फेरि पढेर सजिलो उदाहरणसहित ३ छोटा प्रश्न गराउनुहोस्।"
+            note = "विद्यार्थी प्रयासरत छ। गलत भएका प्रश्नलाई उदाहरणसँग जोडेर दोहोर्‍याउँदा सुधार हुन्छ।"
+        else:
+            strength = "विद्यार्थीले प्रश्न सोधेर अभ्यास सुरु गरेको छ।"
+            weak = f"{topic} को आधारभूत अर्थ र मुख्य शब्दहरू फेरि बुझाउनुपर्छ।"
+            next_step = f"{topic} को छोटो परिभाषा, चित्र/उदाहरण, र एक-एक गरी प्रश्न अभ्यास गराउनुहोस्।"
+            note = "अहिले थप सहारा चाहिन्छ, तर नियमित सानो अभ���यासले सुधार ल्याउँछ।"
+
         return (
             "Parent/teacher summary\n\n"
-            "The student practiced with uploaded or pasted textbook context in this Space. "
-            "For persistent progress, deploy the FastAPI backend and set BACKEND_URL."
+            f"Quiz score: {score} / {total}\n\n"
+            f"Strength\n{strength}\n\n"
+            f"Needs practice\n{weak}\n\n"
+            f"Suggested next practice\n{next_step}\n\n"
+            f"Encouraging note\n{note}"
         )
 
     try:
@@ -243,12 +490,84 @@ def extract_pdf_text(pdf_path):
             if text:
                 page_texts.append(text)
 
-    text = "\n\n".join(page_texts).strip()
-    if not text:
-        raise ValueError(
-            "No selectable text found. For scanned PDFs, use backend OCR or paste a paragraph."
+        text = "\n\n".join(page_texts).strip()
+        if (
+            len(text) >= MIN_TEXT_CHARACTERS_FOR_DIRECT_EXTRACTION
+            and not is_garbled_pdf_text(text)
+        ):
+            return {"text": text, "page_count": page_count, "extraction_method": "pymupdf"}
+
+        ocr_text = extract_text_with_gemini_ocr(document)
+        if ocr_text:
+            combined_text = (
+                ocr_text
+                if is_garbled_pdf_text(text)
+                else "\n\n".join(part for part in [text, ocr_text] if part.strip())
+            )
+            return {
+                "text": combined_text,
+                "page_count": page_count,
+                "extraction_method": "gemini-ocr",
+            }
+
+        if is_garbled_pdf_text(text):
+            raise ValueError(
+                "The PDF text layer is not readable Unicode Nepali. Add GEMINI_API_KEY "
+                "and set OCR_PROVIDER=gemini in the Space secrets, or upload a Unicode "
+                "Nepali PDF."
+            )
+
+        if text:
+            return {"text": text, "page_count": page_count, "extraction_method": "pymupdf-low-text"}
+
+    raise ValueError(
+        "No readable text found. For scanned PDFs, add GEMINI_API_KEY and set "
+        "OCR_PROVIDER=gemini in the Space secrets, or paste a readable lesson paragraph."
+    )
+
+
+def extract_text_with_gemini_ocr(document):
+    import fitz
+
+    if OCR_PROVIDER != "gemini" or not GEMINI_API_KEY:
+        return ""
+
+    page_limit = document.page_count
+    if OCR_MAX_PAGES > 0:
+        page_limit = min(document.page_count, OCR_MAX_PAGES)
+
+    page_texts = []
+    for page_index in range(page_limit):
+        page = document.load_page(page_index)
+        pixmap = page.get_pixmap(matrix=fitz.Matrix(1.5, 1.5), alpha=False)
+        image_data = base64.b64encode(pixmap.tobytes("png")).decode("ascii")
+        prompt = (
+            "Extract all readable textbook text from this page. The text may be in "
+            "Nepali Devanagari or English. Return plain text only. Preserve the original "
+            "language and script. Do not translate or summarize."
         )
-    return {"text": text, "page_count": page_count}
+        try:
+            page_text = gemini_generate_text(
+                prompt,
+                temperature=0,
+                max_output_tokens=1800,
+                parts=[
+                    {"text": prompt},
+                    {
+                        "inline_data": {
+                            "mime_type": "image/png",
+                            "data": image_data,
+                        }
+                    },
+                ],
+            )
+        except (requests.RequestException, KeyError, IndexError, TypeError, ValueError):
+            continue
+
+        if page_text:
+            page_texts.append(f"Page {page_index + 1}\n{page_text}")
+
+    return "\n\n".join(page_texts).strip()
 
 
 def chunk_text(text):
@@ -268,6 +587,28 @@ def chunk_text(text):
     return chunks or ([text.strip()] if text.strip() else [])
 
 
+def is_garbled_pdf_text(text):
+    cleaned = "".join(character for character in str(text) if not character.isspace())
+    if len(cleaned) < 300:
+        return False
+
+    devanagari_count = sum(1 for character in cleaned if "\u0900" <= character <= "\u097f")
+    ascii_letter_count = sum(1 for character in cleaned if character.isascii() and character.isalpha())
+    suspicious_symbol_count = sum(1 for character in cleaned if character in "/\\|;:{}[]'\"`~")
+    suspicious_markers = ["kf7", "lj", "cfwf", "tsnf", ";sf", "PsF", "ofsf"]
+    marker_hits = sum(1 for marker in suspicious_markers if marker in text)
+
+    devanagari_ratio = devanagari_count / len(cleaned)
+    ascii_ratio = ascii_letter_count / len(cleaned)
+    symbol_ratio = suspicious_symbol_count / len(cleaned)
+
+    return (
+        devanagari_ratio < 0.05
+        and ascii_ratio > 0.35
+        and (symbol_ratio > 0.12 or marker_hits >= 2)
+    )
+
+
 @lru_cache(maxsize=1)
 def get_embedding_model():
     from sentence_transformers import SentenceTransformer
@@ -322,14 +663,36 @@ def sources_from_context(text):
 
 
 def normalize_question(question):
-    text = question.lower()
+    cleaned = str(question or "").strip()
+    if TRANSLATION_PROVIDER == "gemini" and GEMINI_API_KEY and cleaned:
+        try:
+            normalized = normalize_with_gemini(cleaned)
+            if normalized:
+                return normalized
+        except (requests.RequestException, KeyError, IndexError, TypeError, ValueError):
+            pass
+
+    text = cleaned.lower()
     if "mato" in text and "katan" in text:
         return "What is soil erosion?"
     if "prakash" in text and "sansleshan" in text:
         return "What is photosynthesis?"
     if "bhinn" in text or "fraction" in text:
         return "What is a fraction?"
-    return question
+    return cleaned
+
+
+def display_topic(question):
+    normalized = str(question).lower()
+    if "photosynthesis" in normalized or "prakash" in normalized:
+        return "प्रकाश संश्लेषण"
+    if "soil erosion" in normalized or ("mato" in normalized and "katan" in normalized):
+        return "माटो कटान"
+    if "fraction" in normalized or "bhinn" in normalized:
+        return "भिन्न"
+    if "oxygen" in normalized:
+        return "अक्सिजन"
+    return str(question).strip() or "आजको पाठ"
 
 
 def nepali_answer(question, context):
@@ -358,7 +721,7 @@ def nepali_quiz_questions(context):
     return [
         "प्राप्त पाठ्यपुस्तक सन्दर्भको मुख्य कुरा के हो?",
         f"यो वाक्यले के बुझाउँछ: {short_context}",
-        "यस विषयलाई आफ्नै सरल शब्दमा कसरी भन्न सकिन्छ?",
+        "यस विषयलाई आफ्नै सरल नेपाली शब्दमा कसरी भन्न सकिन्छ?",
     ]
 
 
@@ -453,6 +816,24 @@ def truncate(text, max_length):
     return text[: max_length - 3] + "..."
 
 
+def startup_status():
+    if BACKEND_URL:
+        return "Backend connected."
+
+    llm_status = "AMD/vLLM tutor enabled." if LLM_BASE_URL else "Local tutor fallback enabled."
+    nepali_status = (
+        "Gemini Nepali adaptation enabled."
+        if TRANSLATION_PROVIDER == "gemini" and GEMINI_API_KEY
+        else "Mock Nepali adaptation enabled."
+    )
+    ocr_status = (
+        "Gemini OCR enabled."
+        if OCR_PROVIDER == "gemini" and GEMINI_API_KEY
+        else "Text-based PDF extraction enabled."
+    )
+    return f"{llm_status} {nepali_status} {ocr_status}"
+
+
 with gr.Blocks(title=APP_NAME, theme=gr.themes.Soft()) as demo:
     gr.Markdown(
         """
@@ -468,10 +849,7 @@ with gr.Blocks(title=APP_NAME, theme=gr.themes.Soft()) as demo:
         student_id_input = gr.Textbox(label="Student ID", value="hf-space-demo")
         status_output = gr.Textbox(
             label="Status",
-            value=(
-                "Backend connected." if BACKEND_URL else
-                "Space-local PDF upload is active. Set BACKEND_URL for full backend OCR/progress."
-            ),
+            value=startup_status(),
             interactive=False,
         )
 
@@ -535,12 +913,12 @@ with gr.Blocks(title=APP_NAME, theme=gr.themes.Soft()) as demo:
     grade_button.click(
         fn=grade_quiz,
         inputs=[answer_1, answer_2, answer_3, student_id_input, quiz_state],
-        outputs=[grade_output],
+        outputs=[grade_output, quiz_state],
         api_name=False,
     )
     summary_button.click(
         fn=parent_summary,
-        inputs=[student_id_input],
+        inputs=[student_id_input, quiz_state],
         outputs=[summary_output],
         api_name=False,
     )

requirements.txt

@@ -1,3 +1,4 @@
+gradio==4.44.1
 python-dotenv>=1.0.0
 requests>=2.31.0
 numpy>=1.26.0