Sprint2/prompt design v1 2.3

backend/README.md

@@ -46,3 +46,121 @@ Run simple Gemini connection test:
 ```bash
 python tests/test_gemini_simple.py
 ```
+
+
+---
+
+## Study Generation Prompt System (v1)
+
+The backend now uses a centralized prompt module for AI study generation.
+
+Location:
+
+```
+backend/prompts/study_gen_v1.py
+```
+
+This module defines how Gemini transforms raw notes into:
+
+- bullet-point summaries
+- multiple-choice quiz questions
+
+
+### How it connects to the API
+
+The `/api/v1/generate` endpoint builds a prompt using:
+
+```python
+prompt = build_study_generation_prompt(request.text)
+```
+
+Then sends it to Gemini:
+
+```python
+response = await gemini_service.call_gemini(prompt)
+```
+
+The prompt module handles:
+
+- system instructions
+- output schema
+- few-shot examples
+- formatting rules
+- quality validation
+
+
+### Prompt builder functions
+
+#### Full study pack
+
+```python
+build_study_generation_prompt(notes)
+```
+
+Returns summary + quiz.
+
+#### Quiz only
+
+```python
+build_custom_quiz_prompt(notes, num_questions=3)
+```
+
+Generates quiz-only output.
+
+#### Summary only
+
+```python
+build_summary_only_prompt(notes)
+```
+
+Generates summary-only output.
+
+
+### Versioning
+
+Current version:
+
+```
+study_gen_v1.py → VERSION 1.0.0
+```
+
+Future prompt improvements should create:
+
+```
+study_gen_v2.py
+study_gen_v3.py
+```
+
+Never silently change v1 behavior — version prompts explicitly.
+
+
+### Quality checks
+
+After Gemini responds, quiz output is validated using:
+
+```python
+validate_quiz_quality()
+```
+
+This detects:
+
+- duplicate options
+- invalid answers
+- weak question structure
+
+Warnings are logged for debugging.
+
+
+### Editing prompts safely
+
+If you change prompt behavior:
+
+1. Keep JSON schema identical
+2. Do not change API response format
+3. Test with messy notes input
+4. Verify frontend still parses correctly
+
+Breaking schema can end up breaking frontend.
+
+---
+

backend/main.py

@@ -6,6 +6,12 @@
 
 from services import GeminiService
 
+# Import the new prompt system
+from backend.prompts.study_gen_v1 import (
+    build_study_generation_prompt,
+    validate_quiz_quality
+)
+
 
 app = FastAPI(title="Socrato")
 
@@ -86,26 +92,32 @@ async def generate_study_materials(request: GenerateRequest):
         - quiz (QuizQuestion[]): Array of quiz questions
     """
     # Call Gemini to generate study materials
-    prompt = f"""You are a study assistant. Based on the following notes, generate:
-1. A summary as a list of bullet points (3-5 key points)
-2. A quiz with 3 multiple choice questions
-
-Notes:
-{request.text}
-
-Respond in this exact JSON format:
-{{
-    "summary": ["point 1", "point 2", "point 3"],
-    "quiz": [
-        {{
-            "question": "Question text?",
-            "options": ["A", "B", "C", "D"],
-            "answer": "A"
-        }}
-    ]
-}}
-
-Return ONLY valid JSON, no markdown or extra text."""
+    # prompt = f"""You are a study assistant. Based on the following notes, generate:
+    # 1. A summary as a list of bullet points (3-5 key points)
+    # 2. A quiz with 3 multiple choice questions
+
+    # Notes:
+    # {request.text}
+
+    # Respond in this exact JSON format:
+    # {{
+    #     "summary": ["point 1", "point 2", "point 3"],
+    #     "quiz": [
+    #         {{
+    #             "question": "Question text?",
+    #             "options": ["A", "B", "C", "D"],
+    #             "answer": "A"
+    #         }}
+    #     ]
+    # }}
+
+    # Return ONLY valid JSON, no markdown or extra text."""
+
+    # Build prompt using the centralized prompt system
+    prompt = build_study_generation_prompt(
+        user_notes=request.text,
+        include_examples=True  # Include few-shot examples for better quality
+    )
 
     response = await gemini_service.call_gemini(prompt)
 
@@ -161,6 +173,13 @@ async def generate_study_materials(request: GenerateRequest):
                 answer=q["answer"]
             ))
 
+        # Optional: Run quality checks on the quiz
+        quality_warnings = validate_quiz_quality(data.get("quiz", []))
+        if quality_warnings:
+            print(f"[generate] Quality warnings: {quality_warnings}")
+            # Can log these or return them to the frontend in the future
+
+
         return GenerateResponse(
             summary=data.get("summary", []),
             quiz=quiz_questions