CI deploy

.github/workflows/deploy.yml

@@ -0,0 +1,38 @@
+name: Deploy to HF Space
+
+on:
+  push:
+    branches:
+      - main  # deploy on pushes to main branch
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # 1. Checkout repo
+      - uses: actions/checkout@v3
+
+      # 2. Set up Python
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13.6'
+
+      # 3. Install dependencies
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade huggingface_hub
+
+      # 4. Authenticate to HF
+      - name: Hugging Face login
+        env:
+          HF_TOKEN: ${{ secrets.hf_token }}
+        run: hf auth login --token ${HF_TOKEN}
+
+      # 5. Push to HF Space repo
+      - name: Push to HF Space
+        env:
+          HF_TOKEN: ${{ secrets.hf_token }}
+        run: |
+          hf upload --repo-type space --commit-message "CI deploy" vikramvasudevan/paatashaala ./

.gitignore

@@ -0,0 +1,5 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+*.pkl

Dockerfile

@@ -0,0 +1,16 @@
+# Read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
+# you will also find guides on how best to write your Dockerfile
+
+FROM python:3.13.6
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+CMD ["uvicorn", "api.server:app", "--host", "0.0.0.0", "--port", "7860"]

Pipfile

@@ -0,0 +1,13 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+fastapi = "*"
+uvicorn = "*"
+pydantic = "*"
+requests = "*"
+python-dotenv = "*"

Pipfile.lock

@@ -0,0 +1,20 @@
+{
+    "_meta": {
+        "hash": {
+            "sha256": "494d5b4f482f0ef471f49afe28f00ec1a2ff75da2ce65060d8cabaeb3da2f100"
+        },
+        "pipfile-spec": 6,
+        "requires": {
+            "python_version": "3.13"
+        },
+        "sources": [
+            {
+                "name": "pypi",
+                "url": "https://pypi.org/simple",
+                "verify_ssl": true
+            }
+        ]
+    },
+    "default": {},
+    "develop": {}
+}

README.md

@@ -1,11 +1,2 @@
----
-title: Paatashaala
-emoji: 🐢
-colorFrom: pink
-colorTo: green
-sdk: docker
-pinned: false
-short_description: 'An AI app that '
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Paatashaala Quiz API
+This space serves a FastAPI-based quiz API.

api/models.py

@@ -0,0 +1,52 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Dict
+
+# -------------------------------
+# Models
+# -------------------------------
+
+class QuizQuestion(BaseModel):
+    id: str
+    question: str
+    choices: List[str]
+    correctIndex: int
+    explanation: str
+
+class QuizSessionResponse(BaseModel):
+    session_id: str
+    question_index: int
+    total_questions: int
+    question: Optional[QuizQuestion] = None
+    done: bool = False
+    message: Optional[str] = None
+    score : int = 0
+
+class QuizSession:
+    def __init__(self, session_id: str, questions: List[QuizQuestion]):
+        self.session_id = session_id
+        self.questions = questions
+        self.current_index = 0
+        self.score = 0
+
+class QuizRequest(BaseModel):
+    subject: str
+    grade: str
+
+class AnswerPayload(BaseModel):
+    choiceIndex: int
+
+class AnswerResult(BaseModel):
+    is_correct: bool
+    correctIndex: int
+    explanation: str
+    next_question_available: bool
+    score: int 
+
+
+class SubjectsResponse(BaseModel):
+    subjects: List[str]
+
+
+class SubjectListResponse(BaseModel):
+    grade: str
+    subjects: List[str] = Field(..., description="List of subjects appropriate for the given grade")

api/server.py

@@ -0,0 +1,113 @@
+# quiz_app.py
+import uuid
+from fastapi import FastAPI
+from typing import Dict
+
+from api.models import (
+    AnswerPayload,
+    AnswerResult,
+    QuizRequest,
+    QuizSession,
+    QuizSessionResponse,
+)
+from api.utils.quiz_helper import generate_questions, get_subjects_for_grade
+
+app = FastAPI()
+
+# -------------------------------
+# In-memory storage
+# -------------------------------
+SESSIONS: Dict[str, QuizSession] = {}
+
+
+# -------------------------------
+# Routes
+# -------------------------------
+
+
+@app.post("/quiz_session/start_quiz", response_model=QuizSessionResponse)
+def start_quiz(req: QuizRequest):
+    questions = generate_questions(req.subject, req.grade, count=3)
+    session_id = str(uuid.uuid4())
+    session = QuizSession(session_id, questions)
+    SESSIONS[session_id] = session
+
+    return QuizSessionResponse(
+        session_id=session_id,
+        question_index=0,
+        total_questions=len(questions),
+        question=questions[0],
+        done=False,
+        score=session.score,
+    )
+
+
+@app.get("/quiz_session/next_question/{session_id}", response_model=QuizSessionResponse)
+def next_question(session_id: str):
+    session = SESSIONS.get(session_id)
+    if not session:
+        return {"error": "Invalid session"}
+
+    if session.current_index >= len(session.questions):
+        return QuizSessionResponse(
+            session_id=session_id,
+            question_index=session.current_index,
+            total_questions=len(session.questions),
+            question=None,
+            done=True,
+            message="Quiz finished!",
+            score=session.score,
+        )
+
+    q = session.questions[session.current_index]
+    return QuizSessionResponse(
+        session_id=session_id,
+        question_index=session.current_index,
+        total_questions=len(session.questions),
+        question=q,
+        done=False,
+        score=session.score,
+    )
+
+
+@app.post("/quiz_session/submit_answer/{session_id}", response_model=AnswerResult)
+def submit_answer(session_id: str, answer: AnswerPayload):
+    session = SESSIONS.get(session_id)
+    if not session:
+        return {"error": "Invalid session"}
+
+    if session.current_index >= len(session.questions):
+        return {"error": "No more questions"}
+
+    q = session.questions[session.current_index]
+    is_correct = answer.choiceIndex == q.correctIndex
+
+    # advance pointer
+    session.current_index += 1
+
+    if is_correct:
+        session.score += 1
+
+    return AnswerResult(
+        is_correct=is_correct,
+        correctIndex=q.correctIndex,
+        explanation=q.explanation,
+        next_question_available=session.current_index < len(session.questions),
+        score = session.score
+    )
+
+
+SUBJECTS = ["Math", "Science", "History", "English", "Geography"]
+
+
+# @app.get("/subjects", response_model=SubjectsResponse)
+# async def get_subjects():
+#     """
+#     Returns the list of available quiz subjects.
+#     """
+#     return SubjectsResponse(subjects=SUBJECTS)
+
+@app.get("/subjects/{grade}")
+def subjects(grade: str):
+    result = get_subjects_for_grade(grade)
+    return result.model_dump()

api/utils/openai_helper.py

@@ -0,0 +1,39 @@
+import json
+from typing import Any
+from openai import OpenAI
+import logging
+
+logging.basicConfig()
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+class OpenAIHelper:
+    def __init__(self):
+        import os
+        from dotenv import load_dotenv
+
+        load_dotenv()
+        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+
+    def ask(self, prompt: str, response_format: Any, structured_output : bool = False):
+        logger.info("Fetching question for %s", prompt)
+        if structured_output:
+            response = self.client.chat.completions.parse(
+                model="gpt-4o-mini",
+                messages=[{"role": "user", "content": prompt.strip()}],
+                response_format=response_format,
+                # temperature=0.7
+            )
+            parsed = response.choices[0].message.parsed
+            # logger.info("response = %s", parsed.model_dump_json())
+            return parsed
+        else:
+            response = self.client.chat.completions.create(
+                model="gpt-4o-mini",
+                messages=[{"role": "user", "content": prompt}],
+                # temperature=0.7
+            )
+            content = response.choices[0].message.content
+            logger.info("response = %s", content)
+            return content

api/utils/quiz_helper.py

@@ -0,0 +1,79 @@
+import uuid
+from typing import List
+
+from api.models import (
+    QuizQuestion,
+    SubjectListResponse,
+)
+from api.utils.openai_helper import OpenAIHelper
+import logging
+
+logging.basicConfig()
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+# -------------------------------
+# Fake Question Generator
+# -------------------------------
+def generate_questions_fake(
+    subject: str, grade: str, count: int = 3
+) -> List[QuizQuestion]:
+    sample_qs = []
+    for i in range(count):
+        q_id = str(uuid.uuid4())
+        q = QuizQuestion(
+            id=q_id,
+            question=f"What is {i+1} + {i+2} in {subject} grade {grade}?",
+            choices=[str(i + 1), str(i + 2), str(i + 3), str((i + 1) + (i + 2))],
+            correctIndex=3,
+            explanation=f"{i+1} + {i+2} = {(i+1)+(i+2)}",
+        )
+        sample_qs.append(q)
+    return sample_qs
+
+
+def generate_questions(subject: str, grade: str, count: int = 3) -> List[QuizQuestion]:
+    prompt = (
+        f"Generate exactly one unique multiple-choice question for grade {grade} students in {subject}. "
+        "The question must be unique, not repeating any topics or calculations from previous questions. "
+    )
+
+    questions: List[QuizQuestion] = []
+
+    for i in range(count):
+        # If not the first iteration, remind the model of what was already generated
+        if i == 1:
+            prompt += "\nHere are the previous questions you had generated:"
+
+        q = OpenAIHelper().ask(prompt, QuizQuestion, True)
+        q.id = str(uuid.uuid4())
+        questions.append(q)
+        logger.info("response = %s", q.model_dump_json())
+
+        # Append the just-generated question to the prompt for context in the next iteration
+        prompt += f"\n{i+1}. {q.question}"
+
+    return questions
+
+def get_subjects_for_grade(grade: str) -> SubjectListResponse:
+    """
+    Uses LLM to generate a list of subjects appropriate for a given grade.
+    Returns structured JSON compatible with SubjectListResponse.
+    """
+    prompt = f"""
+    Generate a list of school subjects appropriate for grade {grade} students.
+    Return ONLY valid JSON matching this schema:
+    {{
+      "grade": "{grade}",
+      "subjects": ["subject1", "subject2", "subject3"]
+    }}
+    Example response:
+    {{
+      "grade": "{grade}",
+      "subjects": ["Math", "Science", "English", "History"]
+    }}
+    """
+
+    response = OpenAIHelper().ask(prompt, SubjectListResponse, structured_output=True)
+    return response

main.py

@@ -0,0 +1,5 @@
+import uvicorn
+from api.server import app
+
+if __name__ == "__main__":
+    uvicorn.run("api.server:app", host="0.0.0.0", port=8000, reload=True)

start.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+# Make sure this file is executable: chmod +x start.sh
+
+echo "Starting FastAPI Quiz API..."
+
+# Run uvicorn server
+uvicorn api.server:app --host 0.0.0.0 --port 7860 --reload