Build Pocket Tutor Space

.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+.ruff_cache/
+.pyright/
+.env
+*.pyc
+*.log

README.md

@@ -0,0 +1,90 @@
+---
+title: Pocket Tutor
+emoji: 🎒
+colorFrom: green
+colorTo: yellow
+sdk: gradio
+sdk_version: 6.17.3
+app_file: app.py
+python_version: "3.12"
+short_description: Photo-first homework coaching for students and parents
+pinned: false
+tags:
+- build-small-hackathon
+- backyard-ai
+- openbmb
+- off-brand
+- best-agent
+- multimodal
+- modal
+- well-tuned
+---
+
+# Pocket Tutor
+
+Pocket Tutor is a multimodal homework coach for students and parents. It accepts
+a worksheet photo, a typed question, or microphone input, then returns a compact
+tutoring plan: what the problem is asking, known information, a strategy, worked
+steps, a quality check, the next hint, and a parent support note.
+
+## Model Plan
+
+- Primary model: `openbmb/MiniCPM-V-4.6` for image + text tutoring
+- Text fallback: `openbmb/MiniCPM3-4B`
+- Speech input: `openai/whisper-small` local transcription
+- Fine-tuned adapter: `build-small-hackathon/pocket-tutor-minicpmv-socratic`
+- Training: Modal A10G QLoRA on current app-format tutoring examples
+- Parameter cap: every planned model is under the 32B hackathon limit
+
+The app does not call an external answer API. If local model execution is still
+loading or unavailable, it returns a deterministic tutoring scaffold instead of
+silently failing.
+
+## Hackathon Alignment
+
+| Requirement | Pocket Tutor implementation |
+|---|---|
+| Gradio Space in `build-small-hackathon` | `build-small-hackathon/pocket-tutor` |
+| Track | Backyard AI |
+| Sponsor focus | OpenBMB MiniCPM-V multimodal tutoring |
+| Merit targets | Off-Brand, Best Agent, Well-Tuned |
+| Multimodal input | Image upload/webcam, typed question, microphone transcript |
+| Fine-tuning | Modal QLoRA adapter trained on app-format Socratic tutoring examples |
+| Demo/social links | Add final demo video and social post links after recording |
+
+## Links
+
+- GitHub Repo: https://github.com/awilliams88/pocket-tutor
+- Hugging Face Space: https://huggingface.co/spaces/build-small-hackathon/pocket-tutor
+- Fine-tuned Model: https://huggingface.co/build-small-hackathon/pocket-tutor-minicpmv-socratic
+- Demo Video: pending final recording
+- Social Post: pending final post
+
+## Local Development
+
+```bash
+./run.sh setup
+./run.sh app
+./run.sh verify
+```
+
+## Codebase
+
+| Path | Purpose |
+|---|---|
+| `app.py` | Hugging Face Spaces entry point |
+| `env/` | Runtime patches, constants, model IDs, links |
+| `core/` | Prompt orchestration, speech transcription, inference, parsing |
+| `ui/` | Gradio layout, examples, custom chalkboard CSS |
+| `modal/` | Modal QLoRA training job, synthetic dataset, adapter card |
+
+## Safety
+
+Pocket Tutor is meant to teach reasoning, not help students cheat. Requests for
+active tests or exams should be redirected toward study guidance.
+
+## Training Data
+
+The Modal dataset includes math, science, reading, writing, statistics, blurry
+image recovery, follow-up confusion, and explicit cheating refusal examples. The
+training target is the current production UI format, not an earlier seed format.

app.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import os
+from env.runtime import patch_asyncio_cleanup_warning
+from ui.layout import create_app, get_theme
+from ui.styles import CUSTOM_CSS
+
+# Keep Spaces startup predictable for this custom Gradio layout.
+os.environ.setdefault("GRADIO_SSR_MODE", "false")
+
+# Hide a harmless local Gradio teardown warning.
+patch_asyncio_cleanup_warning()
+
+# Build the app once for Hugging Face Spaces discovery.
+demo = create_app()
+
+if __name__ == "__main__":
+    # Direct Python launch is used by run.sh and Spaces.
+    demo.launch(theme=get_theme(), css=CUSTOM_CSS)

core/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

core/analyzer.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+try:
+    import spaces
+except ImportError:
+    # Use a no-op GPU decorator during local development.
+    class _LocalSpacesFallback:
+        @staticmethod
+        def GPU(
+            duration: int = 30,
+        ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+            def decorator(function: Callable[..., Any]) -> Callable[..., Any]:
+                return function
+
+            return decorator
+
+    spaces = _LocalSpacesFallback()
+
+from core.inference import run_tutor_inference, transcribe_audio
+from core.parser import parse_sections, stringify_content, validate_image_path
+from env.config import MODEL_ID, PARAMETER_COUNT, QUESTION_LIMIT, TRANSCRIPT_LIMIT
+
+# The tutor prompt keeps the app educational rather than answer-dumping.
+TUTOR_SYSTEM_PROMPT = (
+    "You are Pocket Tutor, a patient multimodal homework coach. "
+    "Help the learner understand the problem without shaming them or simply dumping final answers. "
+    "For math and science, show compact steps and check the answer. "
+    "For writing or reading, explain the reasoning and offer a revision or clue. "
+    "If the uploaded image is unclear, say what information is missing. "
+    "Do not solve active graded tests, exams, or requests to cheat; offer study guidance instead."
+)
+
+
+@dataclass(frozen=True)
+class TutorReport:
+    """Structure containing the prompt context, execution logs, and parsed tutoring result."""
+
+    student_context: str
+    model_path: str
+    problem: str
+    knowns: str
+    strategy: str
+    steps: str
+    check: str
+    hint: str
+    parent: str
+
+
+def build_tutor_prompt(
+    question: str,
+    transcript: str,
+    grade_band: str,
+    help_mode: str,
+    image_status: str,
+) -> str:
+    """Builds the multimodal tutoring prompt expected by the fine-tuned adapter."""
+    combined_question = "\n".join(
+        part for part in [question.strip(), transcript.strip()] if part
+    ).strip()
+    return f"""{TUTOR_SYSTEM_PROMPT}
+
+Student grade band: {grade_band}
+Help mode: {help_mode}
+Image status: {image_status}
+
+Return exactly these sections:
+
+=== PROBLEM READ ===
+[Briefly restate what the learner is asking.]
+
+=== KNOWNS ===
+- [List useful givens, facts, or constraints.]
+
+=== STRATEGY ===
+[Explain the plan in 2-4 sentences.]
+
+=== WORKED STEPS ===
+[Give concise step-by-step help. For hint mode, stop before the final answer.]
+
+=== CHECK ===
+[Check units, logic, or answer quality.]
+
+=== NEXT HINT ===
+[Ask one short follow-up question or give the smallest next hint.]
+
+=== PARENT NOTE ===
+[One sentence a parent/tutor can use to support the learner.]
+
+Learner question:
+{combined_question[:QUESTION_LIMIT] or "The learner uploaded an image and did not type a question."}
+"""
+
+
+def analyze_homework(
+    image_file: object | None,
+    question: Any,
+    audio_path: object | None,
+    grade_band: str,
+    help_mode: str,
+) -> TutorReport:
+    """Orchestrates image validation, speech transcription, inference, and parsing."""
+    # Convert text and microphone input before building the model prompt.
+    typed_question = stringify_content(question)[:QUESTION_LIMIT]
+    transcript, transcript_log = transcribe_audio(audio_path)
+    transcript = transcript[:TRANSCRIPT_LIMIT]
+    image_path, image_status = validate_image_path(image_file)
+
+    # Build a traceable prompt that matches the Modal training format.
+    prompt = build_tutor_prompt(
+        typed_question,
+        transcript,
+        grade_band,
+        help_mode,
+        image_status,
+    )
+    response, inference_log = run_tutor_inference(prompt, image_path)
+    sections = parse_sections(response)
+
+    # Keep diagnostics clear but never hide whether fallback logic ran.
+    model_path = "\n".join(
+        [
+            f"Primary model: {MODEL_ID}",
+            f"Parameters: {PARAMETER_COUNT}",
+            "Execution flow: local Space runtime; no external answer API",
+            "---",
+            image_status,
+            transcript_log,
+            inference_log,
+        ]
+    )
+    student_context = "\n".join(
+        part
+        for part in [
+            f"Grade band: {grade_band}",
+            f"Help mode: {help_mode}",
+            f"Typed question: {typed_question}" if typed_question else "",
+            f"Voice transcript: {transcript}" if transcript else "",
+            image_status,
+        ]
+        if part
+    )
+    return TutorReport(student_context, model_path, *sections)
+
+
+@spaces.GPU(duration=45)
+def analyze_homework_ui(
+    image_file: object | None,
+    question: Any,
+    audio_path: object | None,
+    grade_band: str,
+    help_mode: str,
+) -> tuple[str, str, str, str, str, str, str, str, str]:
+    """Gradio-compatible GPU entry point for tutoring analysis."""
+    # Convert the report into stable component outputs.
+    report = analyze_homework(image_file, question, audio_path, grade_band, help_mode)
+    return (
+        report.student_context,
+        report.model_path,
+        report.problem,
+        report.knowns,
+        report.strategy,
+        report.steps,
+        report.check,
+        report.hint,
+        report.parent,
+    )
+
+
+def reset_outputs() -> tuple[str, str, str, str, str, str, str, str, str]:
+    """Clears visible outputs before a fresh tutoring run."""
+    # Keep click feedback immediate while the model loads.
+    return (
+        "Preparing tutoring context...",
+        "Starting local model execution...",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+    )

core/inference.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+from env.config import ADAPTER_REPO_ID, FALLBACK_MODEL_ID, MODEL_ID, SPEECH_MODEL_ID
+
+# Keep model instances warm after first use.
+_vl_model: Any = None
+_vl_tokenizer: Any = None
+_text_model: Any = None
+_text_tokenizer: Any = None
+_speech_pipeline: Any = None
+_adapter_applied = False
+
+_THINK_BLOCK_PATTERN = re.compile(r"<think>.*?</think>", re.IGNORECASE | re.DOTALL)
+_THINK_START_PATTERN = re.compile(r"<think>.*", re.IGNORECASE | re.DOTALL)
+
+
+def clean_generated_text(text: str) -> str:
+    """Removes hidden reasoning and chat-template leftovers from model output."""
+    # Prefer visible content after a completed thinking block.
+    if "</think>" in text.lower():
+        text = re.split(r"</think>", text, flags=re.IGNORECASE, maxsplit=1)[-1]
+    text = _THINK_BLOCK_PATTERN.sub("", text)
+    text = _THINK_START_PATTERN.sub("", text)
+    for marker in ("<|im_end|>", "<|im_start|>", "\nUser:", "\nAssistant:"):
+        if marker in text:
+            text = text.split(marker, 1)[0]
+    text = re.sub(r"[ \t]+", " ", text)
+    text = "\n".join(line.strip() for line in text.splitlines())
+    return re.sub(r"\n{3,}", "\n\n", text).strip()
+
+
+def _format_chat_prompt(tokenizer: Any, messages: list[dict[str, str]]) -> str:
+    """Formats chat input while disabling hidden reasoning when supported."""
+    try:
+        return tokenizer.apply_chat_template(
+            messages,
+            tokenize=False,
+            add_generation_prompt=True,
+            enable_thinking=False,
+        )
+    except TypeError:
+        return tokenizer.apply_chat_template(
+            messages,
+            tokenize=False,
+            add_generation_prompt=True,
+        )
+
+
+def transcribe_audio(audio_path: object | None) -> tuple[str, str]:
+    """Transcribes optional microphone input using a local speech model when available."""
+    global _speech_pipeline
+    if not audio_path:
+        return "", "No microphone input provided."
+    try:
+        from transformers import pipeline
+
+        if _speech_pipeline is None:
+            _speech_pipeline = pipeline(
+                "automatic-speech-recognition",
+                model=SPEECH_MODEL_ID,
+                token=os.environ.get("HF_TOKEN"),
+            )
+        result = _speech_pipeline(str(audio_path))
+        transcript = str(result.get("text", "")).strip()
+        return transcript, f"Transcribed microphone input with {SPEECH_MODEL_ID}."
+    except Exception as exc:
+        return "", f"Speech transcription unavailable: {exc}"
+
+
+def _load_text_model(log_lines: list[str]) -> tuple[Any, Any]:
+    """Loads the compact fallback tutor model for text-only requests."""
+    global _adapter_applied, _text_model, _text_tokenizer
+    if _text_model is None:
+        import torch
+        from peft import PeftModel
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+
+        # Load tokenizer and base text model for local fallback tutoring.
+        log_lines.append(f"Loading tokenizer: {FALLBACK_MODEL_ID}")
+        _text_tokenizer = AutoTokenizer.from_pretrained(
+            FALLBACK_MODEL_ID,
+            trust_remote_code=True,
+            token=os.environ.get("HF_TOKEN"),
+        )
+        dtype = torch.bfloat16 if torch.cuda.is_available() else torch.float32
+        log_lines.append(f"Loading model: {FALLBACK_MODEL_ID}")
+        _text_model = AutoModelForCausalLM.from_pretrained(
+            FALLBACK_MODEL_ID,
+            dtype=dtype,
+            low_cpu_mem_usage=True,
+            trust_remote_code=True,
+            token=os.environ.get("HF_TOKEN"),
+        )
+        try:
+            log_lines.append(f"Loading LoRA adapter: {ADAPTER_REPO_ID}")
+            _text_model = PeftModel.from_pretrained(
+                _text_model,
+                ADAPTER_REPO_ID,
+                token=os.environ.get("HF_TOKEN"),
+            )
+            _adapter_applied = True
+            log_lines.append("LoRA adapter applied to fallback text model.")
+        except Exception as exc:
+            _adapter_applied = False
+            log_lines.append(f"Adapter unavailable for fallback model: {exc}")
+        if torch.cuda.is_available():
+            _text_model = _text_model.to("cuda")
+    else:
+        adapter_status = "with LoRA adapter" if _adapter_applied else "without adapter"
+        log_lines.append(f"Using cached fallback text model {adapter_status}.")
+    return _text_model, _text_tokenizer
+
+
+def run_tutor_inference(prompt: str, image_path: str | None) -> tuple[str, str]:
+    """Executes local tutoring inference, preferring vision-language when an image exists."""
+    log_lines: list[str] = []
+    if image_path:
+        response, logs = _run_vision_inference(prompt, image_path)
+        if response:
+            return response, logs
+        log_lines.append(logs)
+
+    # Text-only fallback keeps typed and transcribed questions usable.
+    try:
+        log_lines.append("Initializing text tutoring fallback...")
+        model, tokenizer = _load_text_model(log_lines)
+        device = str(model.device)
+        messages = [{"role": "user", "content": prompt}]
+        text = _format_chat_prompt(tokenizer, messages)
+        model_inputs = tokenizer([text], return_tensors="pt").to(device)
+        generated_ids = model.generate(
+            **model_inputs,
+            max_new_tokens=640,
+            do_sample=False,
+            repetition_penalty=1.08,
+        )
+        generated_ids = [
+            output_ids[len(input_ids) :]
+            for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
+        ]
+        response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]
+        log_lines.append("Text tutoring fallback completed.")
+        return clean_generated_text(response), "\n".join(log_lines)
+    except Exception as exc:
+        log_lines.append(f"Local model execution failed: {exc}")
+        log_lines.append("Returning a deterministic tutoring scaffold.")
+        return _fallback_tutoring_response(prompt), "\n".join(log_lines)
+
+
+def _run_vision_inference(prompt: str, image_path: str) -> tuple[str, str]:
+    """Runs MiniCPM-V when the runtime supports its remote-code interface."""
+    global _vl_model, _vl_tokenizer
+    log_lines: list[str] = []
+    try:
+        import torch
+        from PIL import Image
+        from transformers import AutoModel, AutoTokenizer
+
+        if _vl_model is None:
+            # MiniCPM-V uses custom modeling code, so trust_remote_code is required.
+            log_lines.append(f"Loading tokenizer: {MODEL_ID}")
+            _vl_tokenizer = AutoTokenizer.from_pretrained(
+                MODEL_ID,
+                trust_remote_code=True,
+                token=os.environ.get("HF_TOKEN"),
+            )
+            dtype = torch.bfloat16 if torch.cuda.is_available() else torch.float32
+            log_lines.append(f"Loading vision-language model: {MODEL_ID}")
+            _vl_model = AutoModel.from_pretrained(
+                MODEL_ID,
+                trust_remote_code=True,
+                dtype=dtype,
+                low_cpu_mem_usage=True,
+                token=os.environ.get("HF_TOKEN"),
+            )
+            if torch.cuda.is_available():
+                _vl_model = _vl_model.to("cuda")
+            _vl_model.eval()
+        else:
+            log_lines.append("Using cached vision-language model.")
+
+        # Use the model's chat API when available.
+        image = Image.open(image_path).convert("RGB")
+        msgs = [{"role": "user", "content": [image, prompt]}]
+        response = _vl_model.chat(image=None, msgs=msgs, tokenizer=_vl_tokenizer)
+        log_lines.append("Vision tutoring inference completed.")
+        return clean_generated_text(str(response)), "\n".join(log_lines)
+    except Exception as exc:
+        log_lines.append(f"Vision model execution failed: {exc}")
+        return "", "\n".join(log_lines)
+
+
+def _fallback_tutoring_response(prompt: str) -> str:
+    """Returns a stable tutor-shaped response when local weights are unavailable."""
+    return (
+        "=== PROBLEM READ ===\n"
+        "I can help, but the local model is still loading or unavailable. I will treat your typed question as the source.\n\n"
+        "=== KNOWNS ===\n"
+        f"- Student question: {prompt[:240] or 'No question text provided.'}\n\n"
+        "=== STRATEGY ===\n"
+        "Restate the problem in your own words, identify the given values, then choose the smallest rule or example that applies.\n\n"
+        "=== WORKED STEPS ===\n"
+        "1. Copy the exact problem statement.\n"
+        "2. Underline what is being asked.\n"
+        "3. List the givens and the unknown.\n"
+        "4. Try one step, then check whether the units or logic still make sense.\n\n"
+        "=== CHECK ===\n"
+        "The answer should satisfy the original question, use the right units, and not contradict any given information.\n\n"
+        "=== NEXT HINT ===\n"
+        "Tell me which line confuses you most, and I will give only the next hint.\n\n"
+        "=== PARENT NOTE ===\n"
+        "Ask the learner to explain their first step out loud before correcting the answer."
+    )

core/parser.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from pathlib import Path
+import re
+from typing import Any
+
+from env.config import SUPPORTED_IMAGE_SUFFIXES
+
+# Match headings that the tutoring model is instructed to emit.
+_SECTION_MARKER_PATTERN = re.compile(
+    r"(?im)^[ \t]*(?:[-*][ \t]*)?(?:#{1,6}[ \t]*)?"
+    r"(?:\*\*)?(?:={2,}[ \t]*)?"
+    r"(?P<label>"
+    r"problem read|knowns?|strategy|worked steps?|check|next hint|parent note"
+    r")"
+    r"\b"
+    r"(?:[ \t]*={2,})?(?:\*\*)?[ \t]*(?::|-)?[ \t]*"
+    r"(?P<trailing>[^\n]*)$"
+)
+
+_SECTION_ORDER = (
+    "problem",
+    "knowns",
+    "strategy",
+    "steps",
+    "check",
+    "hint",
+    "parent",
+)
+
+_SECTION_DEFAULTS = {
+    "problem": "Upload a homework image or type the question to begin.",
+    "knowns": "- No givens identified yet.",
+    "strategy": "No strategy generated yet.",
+    "steps": "No worked steps generated yet.",
+    "check": "No answer check generated yet.",
+    "hint": "Ask for a hint after the first explanation.",
+    "parent": "Parent support note will appear here.",
+}
+
+
+def resolve_path(file_input: object | None) -> Path | None:
+    """Normalizes Gradio file payload variants into a local path."""
+    # Empty upload components should let text or audio drive the request.
+    if not file_input:
+        return None
+    if isinstance(file_input, (list, tuple)):
+        for item in file_input:
+            path = resolve_path(item)
+            if path:
+                return path
+        return None
+    if isinstance(file_input, dict):
+        for key in ("path", "name", "orig_name"):
+            value = file_input.get(key)
+            if value:
+                return Path(str(value))
+        return None
+    return Path(str(file_input))
+
+
+def validate_image_path(file_input: object | None) -> tuple[str | None, str]:
+    """Returns a usable image path and a short validation message."""
+    # Accept common classroom photo formats only.
+    path = resolve_path(file_input)
+    if not path:
+        return None, "No image uploaded."
+    suffix = path.suffix.lower()
+    if suffix not in SUPPORTED_IMAGE_SUFFIXES:
+        return None, f"Unsupported image format: {suffix}."
+    if not path.exists():
+        return None, "Uploaded image was not found in the local runtime."
+    return str(path), f"Image accepted: {path.name}"
+
+
+def stringify_content(content: Any) -> str:
+    """Converts Gradio text, audio transcripts, and message payloads into prompt-safe text."""
+    # Plain textbox messages arrive as strings.
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content.strip()
+    if isinstance(content, (list, tuple)):
+        parts = [stringify_content(item) for item in content]
+        return " ".join(part for part in parts if part).strip()
+    if isinstance(content, dict):
+        for key in ("text", "value", "path", "url", "name", "alt_text"):
+            value = content.get(key)
+            if value:
+                return stringify_content(value)
+        return ""
+    return str(content).strip()
+
+
+def _canonical_section(label: str) -> str:
+    """Maps model heading variants onto the app's fixed output cards."""
+    normalized = re.sub(r"[^a-z]+", " ", label.lower()).strip()
+    if "problem" in normalized:
+        return "problem"
+    if "known" in normalized:
+        return "knowns"
+    if "strategy" in normalized:
+        return "strategy"
+    if "worked" in normalized or "step" in normalized:
+        return "steps"
+    if "check" in normalized:
+        return "check"
+    if "hint" in normalized:
+        return "hint"
+    return "parent"
+
+
+def parse_sections(response: str) -> tuple[str, str, str, str, str, str, str]:
+    """Extracts tutoring sections from a structured model response."""
+    # Find candidate headings and keep defaults when a section is absent.
+    matches = list(_SECTION_MARKER_PATTERN.finditer(response))
+    sections = dict(_SECTION_DEFAULTS)
+    if not matches:
+        return (
+            sections["problem"],
+            sections["knowns"],
+            sections["strategy"],
+            sections["steps"],
+            sections["check"],
+            sections["hint"],
+            sections["parent"],
+        )
+
+    # Prefer the best ordered block of sections in the generation.
+    best_values: dict[str, str] = {}
+    best_count = -1
+    for start_index, _ in enumerate(matches):
+        values: dict[str, str] = {}
+        last_order_index = -1
+        for current_index in range(start_index, len(matches)):
+            current = matches[current_index]
+            section = _canonical_section(current.group("label"))
+            order_index = _SECTION_ORDER.index(section)
+            if order_index <= last_order_index:
+                break
+            next_start = (
+                matches[current_index + 1].start()
+                if current_index + 1 < len(matches)
+                else len(response)
+            )
+            value = "\n".join(
+                [current.group("trailing"), response[current.end() : next_start]]
+            ).strip()
+            if value:
+                values[section] = value
+            last_order_index = order_index
+        if len(values) >= best_count:
+            best_values = values
+            best_count = len(values)
+
+    # Merge extracted values over stable UI defaults.
+    sections.update(best_values)
+    return (
+        sections["problem"],
+        sections["knowns"],
+        sections["strategy"],
+        sections["steps"],
+        sections["check"],
+        sections["hint"],
+        sections["parent"],
+    )

env/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

env/config.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+# App copy shown in the Gradio header.
+APP_TITLE = "Pocket Tutor"
+APP_DESCRIPTION = "Photo-first homework coaching for students and parents."
+
+# Input limits keep local prompts compact and predictable.
+QUESTION_LIMIT = 3000
+TRANSCRIPT_LIMIT = 1200
+SUPPORTED_IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".webp"}
+
+# Public links shown in the Space footer.
+GITHUB_URL = "https://github.com/awilliams88/pocket-tutor"
+SPACE_URL = "https://huggingface.co/spaces/build-small-hackathon/pocket-tutor"
+
+# Model metadata keeps docs, logs, and UI aligned.
+MODEL_ID = "openbmb/MiniCPM-V-4.6"
+FALLBACK_MODEL_ID = "openbmb/MiniCPM3-4B"
+SPEECH_MODEL_ID = "openai/whisper-small"
+ADAPTER_REPO_ID = "build-small-hackathon/pocket-tutor-minicpmv-socratic"
+SPONSOR_NAME = "OpenBMB"
+PARAMETER_COUNT = "~1B vision-language"

env/runtime.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import asyncio.base_events as base_events
+import os
+from pathlib import Path
+from typing import Any
+
+
+def patch_asyncio_cleanup_warning() -> None:
+    """Keeps local Gradio teardown from surfacing a known invalid-fd warning."""
+    # Skip patching when this Python runtime does not expose the cleanup hook.
+    original_del = getattr(base_events.BaseEventLoop, "__del__", None)
+    if original_del is None or getattr(original_del, "_pocket_tutor_patched", False):
+        return
+
+    # Preserve normal cleanup while ignoring the harmless file descriptor case.
+    def patched_del(self: Any) -> None:
+        try:
+            original_del(self)
+        except ValueError as exc:
+            if str(exc) != "Invalid file descriptor: -1":
+                raise
+
+    # Mark the patch so repeated imports stay idempotent.
+    setattr(patched_del, "_pocket_tutor_patched", True)
+    setattr(base_events.BaseEventLoop, "__del__", patched_del)
+
+
+def load_env() -> None:
+    """Loads simple KEY=value pairs from a local .env file when present."""
+    # Search the project folder before the parent hackathon workspace.
+    for path in [Path(".env"), Path("../.env")]:
+        if path.is_file():
+            try:
+                with open(path, encoding="utf-8") as f:
+                    for line in f:
+                        line = line.strip()
+                        if line and not line.startswith("#") and "=" in line:
+                            key, value = line.split("=", 1)
+                            os.environ.setdefault(
+                                key.strip(), value.strip().strip("'\"")
+                            )
+                break
+            except Exception:
+                pass
+
+
+# Load local secrets before model or Modal clients are used.
+load_env()

modal/CARD.md

@@ -0,0 +1,57 @@
+---
+base_model: openbmb/MiniCPM3-4B
+library_name: peft
+pipeline_tag: text-generation
+language:
+- en
+tags:
+- peft
+- lora
+- qlora
+- tutoring
+- education
+- multimodal
+- build-small-hackathon
+---
+
+# Pocket Tutor Socratic LoRA
+
+Pocket Tutor Socratic LoRA is a QLoRA adapter trained for the Pocket Tutor
+Space. The production app uses OpenBMB vision-language input when available and
+falls back to this compact MiniCPM text adapter for typed or transcribed
+homework questions.
+
+## Intended Use
+
+- Explaining homework from photos, typed questions, or microphone input
+- Producing concise Socratic hints and step-by-step support
+- Helping parents ask better guiding questions
+- Refusing requests to cheat on active tests or exams
+
+## Output Format
+
+The adapter is trained on the current production UI format:
+
+```text
+=== PROBLEM READ ===
+=== KNOWNS ===
+=== STRATEGY ===
+=== WORKED STEPS ===
+=== CHECK ===
+=== NEXT HINT ===
+=== PARENT NOTE ===
+```
+
+## Training Recipe
+
+- Base model: `openbmb/MiniCPM3-4B`
+- Method: QLoRA with 4-bit NF4 quantization
+- Hardware: Modal NVIDIA A10G
+- Training data: synthetic app-format tutoring examples and short follow-up turns
+- Sequence length: 1536 tokens
+- Runtime pairing: OpenBMB MiniCPM-V for image context plus adapter-backed text tutoring
+
+## Limitations
+
+This model can make mistakes and should not be used to cheat on graded work. It
+is designed to teach process and reasoning, not replace a teacher.

modal/dataset.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+# The training prompt mirrors the production tutoring sections.
+TUTOR_SYSTEM_PROMPT = (
+    "You are Pocket Tutor, a patient multimodal homework coach. "
+    "Help the learner understand the problem without shaming them or simply dumping final answers. "
+    "For math and science, show compact steps and check the answer. "
+    "For writing or reading, explain the reasoning and offer a revision or clue. "
+    "If the uploaded image is unclear, say what information is missing. "
+    "Do not solve active graded tests, exams, or requests to cheat; offer study guidance instead."
+)
+
+
+def build_training_prompt(question: str, grade_band: str, help_mode: str) -> str:
+    """Builds a text-only surrogate prompt for MiniCPM-V tutoring adapter training."""
+    return f"""{TUTOR_SYSTEM_PROMPT}
+
+Student grade band: {grade_band}
+Help mode: {help_mode}
+Image status: Synthetic text surrogate for worksheet/photo content.
+
+Return exactly these sections:
+
+=== PROBLEM READ ===
+=== KNOWNS ===
+=== STRATEGY ===
+=== WORKED STEPS ===
+=== CHECK ===
+=== NEXT HINT ===
+=== PARENT NOTE ===
+
+Learner question:
+{question}
+"""
+
+
+def get_training_examples() -> list[dict[str, str]]:
+    """Returns synthetic tutoring examples matching the production output format."""
+    return [
+        {
+            "grade": "Middle school",
+            "mode": "Coach me",
+            "question": "A recipe uses 3/4 cup of flour for one batch. How much flour is needed for 2 1/2 batches?",
+            "response": "=== PROBLEM READ ===\nYou need to scale a recipe from 1 batch to 2 1/2 batches.\n\n=== KNOWNS ===\n- 1 batch uses 3/4 cup of flour\n- You need 2 1/2 batches\n\n=== STRATEGY ===\nMultiply the flour for one batch by the number of batches. Convert the mixed number so the multiplication is easier.\n\n=== WORKED STEPS ===\n1. Rewrite 2 1/2 as 5/2.\n2. Multiply: 3/4 x 5/2 = 15/8.\n3. Convert 15/8 to 1 7/8.\n\n=== CHECK ===\nThe answer is more than 3/4 cup and less than 2 cups, which fits 2 1/2 batches.\n\n=== NEXT HINT ===\nCan you explain why multiplying by 5/2 makes sense here?\n\n=== PARENT NOTE ===\nAsk the learner to draw two full batches and a half batch before simplifying.",
+        },
+        {
+            "grade": "High school",
+            "mode": "Step-by-step",
+            "question": "If a bike travels 18 meters in 6 seconds, what is its average speed?",
+            "response": "=== PROBLEM READ ===\nThe question asks for average speed from distance and time.\n\n=== KNOWNS ===\n- Distance = 18 meters\n- Time = 6 seconds\n\n=== STRATEGY ===\nUse average speed = distance divided by time. Keep the units attached through the calculation.\n\n=== WORKED STEPS ===\n1. Write the formula: speed = distance / time.\n2. Substitute: speed = 18 meters / 6 seconds.\n3. Divide: 18 / 6 = 3.\n4. Attach units: 3 meters per second.\n\n=== CHECK ===\n3 m/s for 6 seconds gives 18 meters, so the result matches the original distance.\n\n=== NEXT HINT ===\nWhat would change if the time doubled but the distance stayed the same?\n\n=== PARENT NOTE ===\nHave the learner say the units out loud as 'meters per second' before calculating.",
+        },
+        {
+            "grade": "Middle school",
+            "mode": "Hint only",
+            "question": "Which sentence best shows the narrator is nervous? The passage says: My palms stuck to the note cards, and every chair squeaked louder than thunder.",
+            "response": "=== PROBLEM READ ===\nYou need to find evidence that reveals the narrator's nervous feeling.\n\n=== KNOWNS ===\n- The narrator notices physical details\n- Palms are sticky\n- Ordinary sounds feel exaggerated\n\n=== STRATEGY ===\nLook for a sentence that shows body reactions or anxious attention instead of a sentence that simply states the emotion.\n\n=== WORKED STEPS ===\nThe phrase about palms sticking to note cards is strong evidence because it shows a physical sign of nerves.\n\n=== CHECK ===\nThe evidence should connect directly to nervousness, not just describe the room.\n\n=== NEXT HINT ===\nWhich detail is about the narrator's body rather than the furniture?\n\n=== PARENT NOTE ===\nAsk the learner to point to the exact words that reveal the feeling.",
+        },
+        {
+            "grade": "High school",
+            "mode": "Coach me",
+            "question": "My thesis says school uniforms are good. How can I make it stronger?",
+            "response": "=== PROBLEM READ ===\nYou want to revise a broad thesis into a specific, arguable claim.\n\n=== KNOWNS ===\n- Topic: school uniforms\n- Current claim: uniforms are good\n- Need: more precise reasoning\n\n=== STRATEGY ===\nName the exact benefit and preview why it matters. A strong thesis should be debatable and focused.\n\n=== WORKED STEPS ===\nTry: 'School uniforms can help students focus on learning by reducing visible income comparisons and simplifying morning routines.' This gives two reasons the essay can develop.\n\n=== CHECK ===\nThe revised thesis is specific, arguable, and gives the reader a roadmap.\n\n=== NEXT HINT ===\nWhich reason do you have the best evidence for: focus, cost, safety, or identity?\n\n=== PARENT NOTE ===\nAsk the learner to underline the claim and circle each reason in the thesis.",
+        },
+        {
+            "grade": "Elementary",
+            "mode": "Coach me",
+            "question": "There are 4 bags with 6 marbles in each bag. Then 5 marbles are lost. How many marbles are left?",
+            "response": "=== PROBLEM READ ===\nThe problem asks you to find a total first, then subtract the marbles that were lost.\n\n=== KNOWNS ===\n- 4 bags\n- 6 marbles in each bag\n- 5 marbles are lost\n\n=== STRATEGY ===\nUse multiplication for equal groups, then subtraction for the lost marbles. This is a two-step problem.\n\n=== WORKED STEPS ===\n1. Find the starting total: 4 x 6 = 24 marbles.\n2. Subtract the lost marbles: 24 - 5 = 19.\n\n=== CHECK ===\nThe answer should be less than 24 because some marbles were lost. 19 fits.\n\n=== NEXT HINT ===\nCan you draw four groups of six and cross out five marbles?\n\n=== PARENT NOTE ===\nAsk the learner which word in the problem tells them to subtract.",
+        },
+        {
+            "grade": "Middle school",
+            "mode": "Step-by-step",
+            "question": "Solve 3x + 7 = 22. I know I need to move something but I get lost.",
+            "response": "=== PROBLEM READ ===\nYou need to isolate x in a one-step-then-divide equation.\n\n=== KNOWNS ===\n- Equation: 3x + 7 = 22\n- Goal: find x\n\n=== STRATEGY ===\nUndo the operations in reverse order. Subtract 7 first, then divide by 3.\n\n=== WORKED STEPS ===\n1. Start with 3x + 7 = 22.\n2. Subtract 7 from both sides: 3x = 15.\n3. Divide both sides by 3: x = 5.\n\n=== CHECK ===\nSubstitute x = 5: 3(5) + 7 = 15 + 7 = 22, so it works.\n\n=== NEXT HINT ===\nWhy do we subtract 7 before dividing by 3?\n\n=== PARENT NOTE ===\nHave the learner say each inverse operation before writing it.",
+        },
+        {
+            "grade": "High school",
+            "mode": "Hint only",
+            "question": "In the photo, the triangle has sides 6, 8, and x. The worksheet asks for the hypotenuse.",
+            "response": "=== PROBLEM READ ===\nThe problem is asking for the longest side of a right triangle.\n\n=== KNOWNS ===\n- One leg is 6\n- One leg is 8\n- The unknown is the hypotenuse\n\n=== STRATEGY ===\nUse the Pythagorean theorem because the problem mentions a right triangle and the hypotenuse.\n\n=== WORKED STEPS ===\nStart with a^2 + b^2 = c^2. Your next setup is 6^2 + 8^2 = x^2. Stop there and simplify the squares next.\n\n=== CHECK ===\nThe hypotenuse must be longer than both 6 and 8.\n\n=== NEXT HINT ===\nWhat are 6 squared and 8 squared?\n\n=== PARENT NOTE ===\nAsk the learner to point to the right angle and label the side across from it.",
+        },
+        {
+            "grade": "Middle school",
+            "mode": "Coach me",
+            "question": "A graph starts at 2 and goes up by 3 each time. What is the rule?",
+            "response": "=== PROBLEM READ ===\nYou need to describe a pattern that begins at 2 and increases by 3 for each step.\n\n=== KNOWNS ===\n- Starting value is 2\n- The value increases by 3 each time\n\n=== STRATEGY ===\nA linear rule uses starting value plus repeated change. Use the step number as the input.\n\n=== WORKED STEPS ===\nIf n is the step number starting at 0, the rule is y = 2 + 3n. If the worksheet starts counting at 1, the rule may be y = 3n - 1.\n\n=== CHECK ===\nFor n = 0, y = 2. For n = 1, y = 5. That matches going up by 3.\n\n=== NEXT HINT ===\nDoes your table start counting the first point as step 0 or step 1?\n\n=== PARENT NOTE ===\nHave the learner write the first four outputs before choosing the equation.",
+        },
+        {
+            "grade": "High school",
+            "mode": "Coach me",
+            "question": "The chemistry question asks why temperature affects reaction rate. I don't know what to say.",
+            "response": "=== PROBLEM READ ===\nThe question asks for a cause-and-effect explanation about temperature and reaction speed.\n\n=== KNOWNS ===\n- Higher temperature means particles have more kinetic energy\n- Reactions need effective collisions\n\n=== STRATEGY ===\nConnect temperature to particle motion, then connect particle motion to collision frequency and energy.\n\n=== WORKED STEPS ===\nA strong answer is: Increasing temperature gives particles more kinetic energy, so they move faster and collide more often. More particles also have enough energy to react, which increases the reaction rate.\n\n=== CHECK ===\nThe explanation names both more frequent collisions and more energetic collisions.\n\n=== NEXT HINT ===\nWhich phrase from your notes mentions activation energy?\n\n=== PARENT NOTE ===\nAsk the learner to explain it using a simple bumper-car analogy first.",
+        },
+        {
+            "grade": "Middle school",
+            "mode": "Step-by-step",
+            "question": "The prompt asks me to compare two characters. I keep summarizing the plot instead.",
+            "response": "=== PROBLEM READ ===\nYou need to compare character traits, not retell every event.\n\n=== KNOWNS ===\n- Task: compare two characters\n- Problem: answer is becoming plot summary\n\n=== STRATEGY ===\nChoose one trait for each character, then use one event as evidence for each trait. Keep the event short and explain what it shows.\n\n=== WORKED STEPS ===\n1. Name character A's trait.\n2. Give one short quote or event that proves it.\n3. Name character B's trait.\n4. Give one short quote or event that proves it.\n5. End with how they are alike or different.\n\n=== CHECK ===\nIf most sentences start with 'then this happened,' you are summarizing. If they explain what a choice reveals, you are comparing.\n\n=== NEXT HINT ===\nWhat is one adjective that describes each character?\n\n=== PARENT NOTE ===\nAsk the learner to make a two-column trait chart before writing.",
+        },
+        {
+            "grade": "College",
+            "mode": "Coach me",
+            "question": "I need to interpret a p-value of 0.03 for a two-sided test at alpha 0.05.",
+            "response": "=== PROBLEM READ ===\nYou need to decide whether the test result is statistically significant and explain the meaning carefully.\n\n=== KNOWNS ===\n- p-value = 0.03\n- alpha = 0.05\n- two-sided test\n\n=== STRATEGY ===\nCompare the p-value with alpha. Then describe evidence against the null hypothesis without saying the null is proven false.\n\n=== WORKED STEPS ===\nBecause 0.03 is less than 0.05, the result is statistically significant at the 5% level. You reject the null hypothesis for this test.\n\n=== CHECK ===\nDo not say there is a 3% chance the null hypothesis is true. The p-value is about the probability of data this extreme if the null were true.\n\n=== NEXT HINT ===\nWhat is the null hypothesis in your specific problem?\n\n=== PARENT NOTE ===\nFor older learners, ask them to separate the decision rule from the real-world conclusion.",
+        },
+    ]
+
+
+def get_chat_training_examples() -> list[list[dict[str, str]]]:
+    """Returns follow-up examples that teach concise Socratic coaching."""
+    return [
+        [
+            {"role": "system", "content": TUTOR_SYSTEM_PROMPT},
+            {"role": "user", "content": "I still don't get why 2 1/2 becomes 5/2."},
+            {
+                "role": "assistant",
+                "content": "Two whole batches are 4 halves, and the extra half makes 5 halves total. That is why 2 1/2 equals 5/2. Can you draw five half-batches and count them?",
+            },
+        ],
+        [
+            {"role": "system", "content": TUTOR_SYSTEM_PROMPT},
+            {"role": "user", "content": "Just give me the answer, this is due now."},
+            {
+                "role": "assistant",
+                "content": "I can help you finish faster, but I should still show the step that makes the answer trustworthy. Write the formula first, then I will help check your substitution.",
+            },
+        ],
+        [
+            {"role": "system", "content": TUTOR_SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": "My worksheet photo is blurry but I think it says 3x plus 7 equals 22.",
+            },
+            {
+                "role": "assistant",
+                "content": "Thanks for reading the unclear part out loud. If the equation is 3x + 7 = 22, the first move is subtracting 7 from both sides. Can you confirm whether the symbol before 7 is plus or minus?",
+            },
+        ],
+        [
+            {"role": "system", "content": TUTOR_SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": "I got 15/8 but the answer key says one and seven eighths.",
+            },
+            {
+                "role": "assistant",
+                "content": "Those are the same value written in different forms. 15/8 is an improper fraction, and 1 7/8 is the mixed number form. How many whole groups of 8 fit inside 15?",
+            },
+        ],
+        [
+            {"role": "system", "content": TUTOR_SYSTEM_PROMPT},
+            {"role": "user", "content": "This is an exam question, just solve it."},
+            {
+                "role": "assistant",
+                "content": "I cannot solve an active exam for you, but I can help you study the method. Tell me the topic, and I will walk through a similar practice problem step by step.",
+            },
+        ],
+    ]

modal/tune.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import modal
+
+modal_any: Any = modal
+
+# Modal app groups the remote fine-tuning job.
+app = modal_any.App("pocket-tutor-tuner")
+
+# Custom container image with the training stack and local dataset code.
+image = (
+    modal_any.Image.debian_slim()
+    .pip_install(
+        "torch",
+        "transformers>=4.45.0",
+        "peft",
+        "trl",
+        "accelerate",
+        "bitsandbytes",
+        "datasets",
+        "huggingface_hub",
+        "pillow",
+    )
+    .add_local_file(
+        os.path.join(os.path.dirname(__file__), "dataset.py"),
+        "/root/dataset.py",
+    )
+)
+
+# Volume keeps checkpoints available across Modal runs.
+volume = modal_any.Volume.from_name("pocket-tutor-checkpoints", create_if_missing=True)
+
+# Base model remains under the hackathon parameter limit.
+MODEL_ID = "openbmb/MiniCPM3-4B"
+ADAPTER_REPO_ID = "build-small-hackathon/pocket-tutor-minicpmv-socratic"
+
+
+@app.function(
+    image=image,
+    gpu="A10G",
+    timeout=7200,
+    volumes={"/checkpoints": volume},
+    secrets=[modal_any.Secret.from_name("huggingface-secret")],
+)
+def train_lora(
+    model_card_content: str,
+    hf_token: str | None = None,
+    repo_id: str | None = None,
+):
+    """Fine-tunes a compact MiniCPM tutor adapter on app-format Socratic examples."""
+    # Remote-only imports are installed inside the Modal container.
+    import io
+    import os as remote_os
+
+    import torch
+    from datasets import Dataset
+    from huggingface_hub import login, upload_file
+    from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
+    from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+    from trl import SFTConfig, SFTTrainer
+
+    from dataset import (
+        build_training_prompt,
+        get_chat_training_examples,
+        get_training_examples,
+    )
+
+    # Load tokenizer and prepare app-format conversations.
+    print(f"Loading tokenizer for {MODEL_ID}...")
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, trust_remote_code=True)
+    formatted_dataset = []
+    for item in get_training_examples():
+        messages = [
+            {
+                "role": "user",
+                "content": build_training_prompt(
+                    str(item["question"]),
+                    str(item["grade"]),
+                    str(item["mode"]),
+                ),
+            },
+            {"role": "assistant", "content": str(item["response"])},
+        ]
+        formatted_dataset.append(
+            {"text": tokenizer.apply_chat_template(messages, tokenize=False)}
+        )
+    for messages in get_chat_training_examples():
+        formatted_dataset.append(
+            {"text": tokenizer.apply_chat_template(messages, tokenize=False)}
+        )
+    dataset = Dataset.from_list(formatted_dataset)
+    print(f"Prepared {len(dataset)} tutoring conversations.")
+
+    # QLoRA keeps adapter training feasible on a single A10G.
+    bnb_config = BitsAndBytesConfig(
+        load_in_4bit=True,
+        bnb_4bit_quant_type="nf4",
+        bnb_4bit_compute_dtype=torch.bfloat16,
+        bnb_4bit_use_double_quant=True,
+    )
+    model = AutoModelForCausalLM.from_pretrained(
+        MODEL_ID,
+        quantization_config=bnb_config,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+    model.config.pad_token_id = tokenizer.eos_token_id
+    model = prepare_model_for_kbit_training(model)
+
+    # Target common attention projections for structured tutoring behavior.
+    peft_config = LoraConfig(
+        r=16,
+        lora_alpha=32,
+        target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
+        lora_dropout=0.05,
+        bias="none",
+        task_type="CAUSAL_LM",
+    )
+    model = get_peft_model(model, peft_config)
+    model.print_trainable_parameters()
+
+    # Train on the current production section format, not an earlier seed format.
+    training_args = SFTConfig(
+        output_dir="/checkpoints/pocket-tutor-lora",
+        per_device_train_batch_size=1,
+        gradient_accumulation_steps=4,
+        warmup_steps=8,
+        max_steps=180,
+        learning_rate=2e-4,
+        bf16=True,
+        logging_steps=5,
+        save_strategy="steps",
+        save_steps=45,
+        save_total_limit=2,
+        report_to="none",
+        dataset_text_field="text",
+        max_length=1536,
+    )
+    trainer = SFTTrainer(model=model, train_dataset=dataset, args=training_args)
+    trainer.train()
+
+    # Save the final adapter into the persistent Modal volume.
+    model.save_pretrained("/checkpoints/pocket-tutor-final")
+    tokenizer.save_pretrained("/checkpoints/pocket-tutor-final")
+    volume.commit()
+
+    # Publish the adapter and model card when credentials are available.
+    hf_token = hf_token or remote_os.environ.get("HF_TOKEN")
+    repo_id = repo_id or ADAPTER_REPO_ID
+    if hf_token:
+        login(token=hf_token)
+        model.push_to_hub(repo_id)
+        tokenizer.push_to_hub(repo_id)
+        upload_file(
+            path_or_fileobj=io.BytesIO(model_card_content.encode("utf-8")),
+            path_in_repo="README.md",
+            repo_id=repo_id,
+            repo_type="model",
+            commit_message="Update Pocket Tutor adapter model card",
+        )
+    else:
+        print("HF_TOKEN not set. Skipping Hub publish.")
+
+
+@app.local_entrypoint()
+def main():
+    # Read the model card at launch so edits are included in the run.
+    meta_path = os.path.join(os.path.dirname(__file__), "CARD.md")
+    with open(meta_path, encoding="utf-8") as f:
+        model_card = f.read()
+    train_lora.remote(model_card_content=model_card)

pyrightconfig.json

@@ -0,0 +1,4 @@
+{
+  "reportMissingImports": "none",
+  "reportFunctionMemberAccess": "none"
+}

requirements.txt

@@ -0,0 +1,10 @@
+gradio==6.17.3
+ruff==0.15.16
+transformers>=4.45.0
+torch
+accelerate
+peft
+sentencepiece
+pillow
+pyright
+modal

run.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# run.sh — local dev utility for Pocket Tutor.
+# Usage: ./run.sh [setup|verify|app]
+set -euo pipefail
+
+# Set ROOT_DIR
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT_DIR"
+
+# Set PYTHON and TARGET
+PYTHON=".venv/bin/python"
+TARGET="${1:-app}"
+
+# Create the virtual environment and install dependencies.
+setup() {
+  if [ ! -x "$PYTHON" ]; then
+    echo "Creating virtual environment..."
+    python3 -m venv .venv
+  fi
+  echo "Installing dependencies..."
+  "$PYTHON" -m pip install --quiet --upgrade pip
+  "$PYTHON" -m pip install --quiet -r requirements.txt
+  echo "Setup complete."
+}
+
+# Abort early if the virtual environment is missing.
+ensure_venv() {
+  if [ ! -x "$PYTHON" ]; then
+    echo "Error: run ./run.sh setup first."
+    exit 1
+  fi
+}
+
+case "$TARGET" in
+  setup)
+    setup
+    ;;
+
+  verify)
+    [ ! -x "$PYTHON" ] && setup
+    echo "-> format"
+    "$PYTHON" -m ruff format app.py env/*.py core/*.py ui/*.py modal/*.py
+    echo "-> lint"
+    "$PYTHON" -m ruff check --fix app.py env/*.py core/*.py ui/*.py modal/*.py
+    echo "-> types"
+    "$PYTHON" -m pyright app.py env/*.py core/*.py ui/*.py modal/*.py
+    echo "-> compile"
+    "$PYTHON" -m compileall -q app.py env/ core/ ui/ modal/
+    echo "All checks passed."
+    ;;
+
+  app | run | *)
+    ensure_venv
+    "$PYTHON" app.py
+    ;;
+esac
+
+# Remove Python and linter cache dirs on exit.
+cleanup() {
+  find "$ROOT_DIR" \
+    -not -path "$ROOT_DIR/.git/*" \
+    -not -path "$ROOT_DIR/.venv/*" \
+    \( -type d -name "__pycache__" -o -type d -name ".ruff_cache" \) \
+    -exec rm -rf {} + 2>/dev/null || true
+}
+trap cleanup EXIT

ui/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

ui/examples.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from html import escape
+import gradio as gr
+
+# Examples cover math, science, reading, and writing support.
+EXAMPLE_CARDS = [
+    {
+        "title": "Fraction Word Problem",
+        "grade": "Middle school",
+        "mode": "Coach me",
+        "text": "A recipe uses 3/4 cup of flour for one batch. How much flour is needed for 2 1/2 batches?",
+    },
+    {
+        "title": "Physics Units",
+        "grade": "High school",
+        "mode": "Step-by-step",
+        "text": "If a bike travels 18 meters in 6 seconds, what is its average speed? I keep mixing up the units.",
+    },
+    {
+        "title": "Reading Evidence",
+        "grade": "Middle school",
+        "mode": "Hint only",
+        "text": "The question asks which sentence best shows the narrator is nervous. How do I choose evidence without guessing?",
+    },
+    {
+        "title": "Essay Thesis",
+        "grade": "High school",
+        "mode": "Coach me",
+        "text": "My essay is about whether school uniforms help students focus. My thesis sounds too broad.",
+    },
+]
+
+
+def _example_card_html(title: str, grade: str, text: str) -> str:
+    """Builds a compact example card with clear grade context."""
+    return (
+        '<div class="pt-example-copy">'
+        '<div class="pt-example-head">'
+        f"<span>{escape(title)}</span>"
+        f"<strong>{escape(grade)}</strong>"
+        "</div>"
+        f"<p>{escape(text)}</p>"
+        "</div>"
+    )
+
+
+def _select_example(
+    text: str, grade: str, mode: str
+) -> tuple[None, str, None, str, str]:
+    """Populates the tutor form from an example card."""
+    return None, text, None, grade, mode
+
+
+def render_examples(
+    image_input: gr.Image,
+    question_input: gr.Textbox,
+    audio_input: gr.Audio,
+    grade_input: gr.Dropdown,
+    mode_input: gr.Radio,
+) -> gr.Column:
+    """Renders examples and wires card buttons to the tutor form."""
+    with gr.Column(elem_classes=["pt-examples-section"]) as section:
+        gr.Markdown("## Try a Homework Scenario")
+        with gr.Row(elem_classes=["pt-example-grid"]):
+            for example in EXAMPLE_CARDS:
+                with gr.Column(elem_classes=["pt-example-card"]):
+                    gr.HTML(
+                        _example_card_html(
+                            str(example["title"]),
+                            str(example["grade"]),
+                            str(example["text"]),
+                        )
+                    )
+                    use_example = gr.Button(
+                        "Use example",
+                        size="sm",
+                        elem_classes=["pt-example-btn"],
+                    )
+                    use_example.click(
+                        fn=lambda text=str(example["text"]), grade=str(example["grade"]), mode=str(example["mode"]): (
+                            _select_example(text, grade, mode)
+                        ),
+                        inputs=[],
+                        outputs=[
+                            image_input,
+                            question_input,
+                            audio_input,
+                            grade_input,
+                            mode_input,
+                        ],
+                        queue=False,
+                    )
+    return section

ui/layout.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from typing import Any
+import gradio as gr
+from gradio.themes import Soft
+
+from core.analyzer import analyze_homework_ui, reset_outputs
+from env.config import APP_DESCRIPTION, APP_TITLE, GITHUB_URL, SPACE_URL
+from ui.examples import render_examples
+
+
+def get_theme() -> Any:
+    """Returns the custom soft theme configured for chalkboard teal styling."""
+    # Pair the CSS with a calm tutoring palette.
+    return Soft(primary_hue="teal", secondary_hue="amber", neutral_hue="slate")
+
+
+def create_app() -> gr.Blocks:
+    """Creates and lays out the Gradio interface for Pocket Tutor."""
+    with gr.Blocks(title=APP_TITLE) as demo:
+        # Header gives the product promise without a marketing page.
+        gr.Markdown(f"# {APP_TITLE}\n{APP_DESCRIPTION}", elem_id="pt-header")
+        gr.Markdown(
+            "Snap a worksheet, ask by voice, or type the confusing line. The tutor explains the next useful step.",
+            elem_id="pt-kicker",
+        )
+
+        with gr.Row(elem_classes=["pt-main-grid"]):
+            # Left column collects multimodal homework context.
+            with gr.Column(scale=1, elem_classes=["pt-input-panel"]):
+                gr.Markdown("## Homework Input")
+                image_input = gr.Image(
+                    label="Upload or capture a worksheet/photo",
+                    type="filepath",
+                    sources=["upload", "webcam", "clipboard"],
+                    elem_classes=["pt-image-input"],
+                )
+                question_input = gr.Textbox(
+                    label="What should we work on?",
+                    lines=5,
+                    placeholder="Type the problem, the line that confused you, or what you already tried.",
+                    elem_id="pt-question-input",
+                )
+                audio_input = gr.Audio(
+                    label="Ask with your microphone",
+                    sources=["microphone", "upload"],
+                    type="filepath",
+                    elem_classes=["pt-audio-input"],
+                )
+                with gr.Row(elem_classes=["pt-control-row"]):
+                    grade_input = gr.Dropdown(
+                        ["Elementary", "Middle school", "High school", "College"],
+                        value="Middle school",
+                        label="Grade band",
+                    )
+                    mode_input = gr.Radio(
+                        ["Coach me", "Hint only", "Step-by-step"],
+                        value="Coach me",
+                        label="Help mode",
+                    )
+                run_button = gr.Button(
+                    "Tutor This",
+                    variant="primary",
+                    elem_classes=["pt-run-btn"],
+                )
+
+            # Right column gives the step-by-step tutoring answer.
+            with gr.Column(scale=1, elem_classes=["pt-output-panel"]):
+                gr.Markdown("## Tutoring Plan")
+                problem_output = gr.Textbox(
+                    label="Problem Read",
+                    lines=4,
+                    interactive=False,
+                    elem_classes=["pt-output-card", "pt-problem-card"],
+                )
+                knowns_output = gr.Textbox(
+                    label="Knowns",
+                    lines=4,
+                    interactive=False,
+                    elem_classes=["pt-output-card", "pt-knowns-card"],
+                )
+                strategy_output = gr.Textbox(
+                    label="Strategy",
+                    lines=5,
+                    interactive=False,
+                    elem_classes=["pt-output-card", "pt-strategy-card"],
+                )
+
+        with gr.Column(elem_classes=["pt-analysis-section"]):
+            gr.Markdown("## Workbench")
+            with gr.Row(elem_classes=["pt-card-grid"]):
+                steps_output = gr.Textbox(
+                    label="Worked Steps",
+                    lines=7,
+                    interactive=False,
+                    elem_classes=["pt-output-card", "pt-steps-card"],
+                )
+                check_output = gr.Textbox(
+                    label="Check",
+                    lines=7,
+                    interactive=False,
+                    elem_classes=["pt-output-card", "pt-check-card"],
+                )
+            with gr.Row(elem_classes=["pt-card-grid"]):
+                hint_output = gr.Textbox(
+                    label="Next Hint",
+                    lines=5,
+                    interactive=False,
+                    elem_classes=["pt-output-card", "pt-hint-card"],
+                )
+                parent_output = gr.Textbox(
+                    label="Parent Note",
+                    lines=5,
+                    interactive=False,
+                    elem_classes=["pt-output-card", "pt-parent-card"],
+                )
+
+        render_examples(
+            image_input,
+            question_input,
+            audio_input,
+            grade_input,
+            mode_input,
+        )
+
+        gr.Markdown(
+            f"[GitHub repo]({GITHUB_URL}) | [Hugging Face Space]({SPACE_URL})",
+            elem_id="pt-links",
+        )
+
+        with gr.Accordion("Diagnostics & Local Execution Logs", open=False):
+            context_output = gr.Textbox(
+                label="Student context",
+                lines=4,
+                interactive=False,
+                elem_classes=["pt-log-box"],
+            )
+            model_output = gr.Textbox(
+                label="System execution logs",
+                lines=5,
+                interactive=False,
+                elem_classes=["pt-log-box"],
+            )
+
+        # Reset outputs immediately, then run the GPU-backed tutoring function.
+        reset_event = run_button.click(
+            fn=reset_outputs,
+            inputs=[],
+            outputs=[
+                context_output,
+                model_output,
+                problem_output,
+                knowns_output,
+                strategy_output,
+                steps_output,
+                check_output,
+                hint_output,
+                parent_output,
+            ],
+            queue=False,
+        )
+        reset_event.then(
+            fn=analyze_homework_ui,
+            inputs=[
+                image_input,
+                question_input,
+                audio_input,
+                grade_input,
+                mode_input,
+            ],
+            outputs=[
+                context_output,
+                model_output,
+                problem_output,
+                knowns_output,
+                strategy_output,
+                steps_output,
+                check_output,
+                hint_output,
+                parent_output,
+            ],
+        )
+
+    return demo

ui/styles.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+# Gradio CSS overrides create a distinct chalkboard tutoring interface.
+CUSTOM_CSS = """
+body, .gradio-container {
+    background-color: #071512 !important;
+    color: #e6fffb !important;
+    font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif !important;
+}
+
+#pt-header {
+    text-align: center;
+    margin: 0 auto 0.65rem auto;
+    padding: 0.35rem 0 0.65rem 0;
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+}
+#pt-header h1 {
+    color: #5eead4 !important;
+    font-size: 2.7rem !important;
+    font-weight: 750 !important;
+    letter-spacing: 0 !important;
+    margin-bottom: 0.35rem !important;
+}
+#pt-header p {
+    color: #a7f3d0 !important;
+    font-size: 1.08rem !important;
+    margin: 0 !important;
+}
+#pt-kicker {
+    width: fit-content;
+    max-width: 92%;
+    margin: 0 auto 1.5rem auto;
+    padding: 0.7rem 1.6rem !important;
+    background-color: rgba(20, 184, 166, 0.08) !important;
+    border: 1px solid rgba(94, 234, 212, 0.5) !important;
+    border-radius: 8px !important;
+    text-align: center;
+    color: #ccfbf1 !important;
+}
+
+.pt-main-grid, .pt-card-grid, .pt-example-grid, .pt-control-row {
+    gap: 1rem !important;
+    align-items: stretch !important;
+}
+.pt-main-grid > .form, .pt-main-grid > .row, .pt-main-grid > div,
+.pt-card-grid > .form, .pt-card-grid > .row, .pt-card-grid > div,
+.pt-example-grid > .form, .pt-example-grid > .row, .pt-example-grid > div {
+    display: flex !important;
+    flex-wrap: wrap !important;
+    gap: 1rem !important;
+}
+.pt-input-panel, .pt-output-panel, .pt-analysis-section, .pt-examples-section {
+    background-color: #0e211d !important;
+    border: 1px solid rgba(45, 212, 191, 0.25) !important;
+    border-radius: 8px !important;
+    box-shadow: 0 4px 14px rgba(0, 0, 0, 0.28) !important;
+    padding: 1.15rem !important;
+}
+.pt-analysis-section, .pt-examples-section {
+    margin-top: 1rem !important;
+}
+.pt-input-panel, .pt-output-panel {
+    flex: 1 1 330px !important;
+}
+.pt-input-panel h3, .pt-output-panel h3, .pt-analysis-section h3, .pt-examples-section h3 {
+    color: #fef3c7 !important;
+    margin: 0 0 0.75rem 0 !important;
+}
+
+#pt-question-input textarea, .pt-log-box textarea {
+    background-color: #081714 !important;
+    color: #f8fafc !important;
+    border: 1px solid rgba(94, 234, 212, 0.28) !important;
+    border-radius: 8px !important;
+    line-height: 1.5 !important;
+}
+.pt-image-input, .pt-audio-input {
+    border-radius: 8px !important;
+    overflow: hidden !important;
+}
+.pt-run-btn {
+    background: #f59e0b !important;
+    color: #071512 !important;
+    border: none !important;
+    border-radius: 8px !important;
+    font-weight: 750 !important;
+    min-height: 50px !important;
+}
+.pt-run-btn:hover {
+    opacity: 0.9 !important;
+}
+
+.pt-output-card {
+    min-width: 0 !important;
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+}
+.pt-card-grid .block {
+    flex: 1 1 280px !important;
+    min-width: 0 !important;
+}
+.pt-output-card textarea {
+    background-color: #081714 !important;
+    color: #f8fafc !important;
+    border-radius: 8px !important;
+    font-size: 0.98rem !important;
+    line-height: 1.5 !important;
+    padding: 0.85rem !important;
+    overflow-wrap: anywhere !important;
+}
+.pt-problem-card textarea { border: 1px solid rgba(94, 234, 212, 0.48) !important; }
+.pt-knowns-card textarea { border: 1px solid rgba(250, 204, 21, 0.48) !important; }
+.pt-strategy-card textarea { border: 1px solid rgba(56, 189, 248, 0.48) !important; }
+.pt-steps-card textarea { border: 1px solid rgba(167, 139, 250, 0.48) !important; }
+.pt-check-card textarea { border: 1px solid rgba(52, 211, 153, 0.48) !important; }
+.pt-hint-card textarea { border: 1px solid rgba(251, 146, 60, 0.48) !important; }
+.pt-parent-card textarea { border: 1px solid rgba(244, 114, 182, 0.48) !important; }
+
+.pt-example-card {
+    flex: 1 1 245px !important;
+    background-color: #081714 !important;
+    border: 1px solid rgba(148, 163, 184, 0.22) !important;
+    border-radius: 8px !important;
+    padding: 0.85rem !important;
+}
+.pt-example-copy {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+}
+.pt-example-head {
+    display: flex;
+    justify-content: space-between;
+    gap: 0.8rem;
+    color: #ccfbf1;
+    font-weight: 700;
+}
+.pt-example-head strong {
+    color: #fbbf24;
+    white-space: nowrap;
+}
+.pt-example-copy p {
+    color: #b6e7df;
+    margin: 0;
+    line-height: 1.45;
+}
+.pt-example-btn {
+    border-radius: 8px !important;
+}
+#pt-links {
+    text-align: center;
+    margin-top: 1rem;
+    color: #99f6e4 !important;
+}
+"""