feat: Enhance persona prompts and RAG evaluation logging

This commit significantly improves the "Generation" and evaluation capabilities of the RAG pipeline by fully implementing persona-based prompts and enriching the evaluation data.

The initial implementation had placeholder prompts for the 'parent' and 'principal' personas. Furthermore, the evaluation log did not capture the exact prompt details sent to the LLM, making it difficult to debug or audit the generation step.

This commit addresses these gaps by:

- **Fully implements the 'parent' and 'principal' persona prompts** in `prompts.py`. Each prompt is now tailored with specific instructions for tone, content, and formatting to align with the requirements of the performance task brief.

- **Refactors the `generate_recommendation_summary` function** in the RAG pipeline. It no longer returns just the final text, but now also returns a detailed dictionary containing the prompt template, the variables used, and the final formatted prompt text sent to the LLM.

- **Updates the Gradio app (`app.py`)** to log this detailed prompt information under a new `llm_prompt_details` key in the downloadable evaluation JSON, providing complete traceability for each request.

- **Adjusts the console entry point (`main.py`)** to maintain compatibility with the refactored pipeline function.

app.py

@@ -7,7 +7,10 @@ import numpy as np
 import sys
 from pathlib import Path
 
-from fot_recommender.config import (
+APP_ROOT = Path(__file__).parent
+sys.path.insert(0, str(APP_ROOT / "src"))
+
+from fot_recommender.config import ( # noqa: E402
     FAISS_INDEX_PATH,
     FINAL_KB_CHUNKS_PATH,
     CITATIONS_PATH,
@@ -16,8 +19,8 @@ from fot_recommender.config import (
     SEARCH_RESULT_COUNT_K,
     MIN_SIMILARITY_SCORE,
 )
-from fot_recommender.utils import load_citations, format_evidence_for_display
-from fot_recommender.rag_pipeline import (
+from fot_recommender.utils import load_citations, format_evidence_for_display # noqa: E402
+from fot_recommender.rag_pipeline import ( # noqa: E402
     load_knowledge_base,
     initialize_embedding_model,
     generate_recommendation_summary,
@@ -115,7 +118,7 @@ def get_recommendations_api(student_narrative, persona, password):
         return
 
     # 2. GENERATE
-    synthesized_recommendation = generate_recommendation_summary(
+    synthesized_recommendation, llm_prompt_details = generate_recommendation_summary(
         retrieved_chunks=retrieved_chunks_with_scores,
         student_narrative=student_narrative,
         api_key=FOT_GOOGLE_API_KEY,
@@ -136,8 +139,7 @@ def get_recommendations_api(student_narrative, persona, password):
         evidence_list_str += (
             f"  - **Content Snippet:**\n  > {evidence['content_snippet']}\n"
         )
-
-    final_output = synthesized_recommendation + evidence_header + evidence_list_str
+    final_ui_output = synthesized_recommendation + evidence_header + evidence_list_str
 
     # 4. Assemble Evaluation Data
     evaluation_data = {
@@ -154,8 +156,11 @@ def get_recommendations_api(student_narrative, persona, password):
             }
             for chunk, score in retrieved_chunks_with_scores
         ],
-        "llm_output": {"synthesized_recommendation": synthesized_recommendation},
-        "final_ui_output": final_output,
+        "llm_prompt_details": llm_prompt_details,
+        "outputs": {
+            "llm_synthesized_recommendation": synthesized_recommendation,
+            "final_formatted_ui_output": final_ui_output,
+        },
     }
 
     # 5. Create a temporary file for download
@@ -166,7 +171,7 @@ def get_recommendations_api(student_narrative, persona, password):
         temp_file_path = f.name
 
     yield (
-        final_output,
+        final_ui_output,
         gr.update(interactive=True),
         gr.update(visible=True),
         evaluation_data,
@@ -268,7 +273,4 @@ with gr.Blocks(theme=gr.themes.Soft(), css=CUSTOM_CSS) as interface:  # type: ig
 
 
 if __name__ == "__main__":
-    # Add project src to the sys.path for when running as a script
-    APP_ROOT = Path(__file__).parent
-    sys.path.insert(0, str(APP_ROOT / "src"))
     interface.launch()

src/fot_recommender/main.py

@@ -87,7 +87,7 @@ def main():
     if not api_key:
         return "ERROR: FOT_GOOGLE_API_KEY not found. Please create a .env file and add your key."
 
-    synthesized_recommendation = generate_recommendation_summary(
+    synthesized_recommendation, _ = generate_recommendation_summary(
         top_interventions, student_query, api_key=api_key, persona="teacher"
     )
 

src/fot_recommender/prompts.py

@@ -13,25 +13,61 @@ Based on the student's profile, the following intervention strategies have been
 --- END CONTEXT ---
 
 **Your Task:**
-Synthesize the provided context to write a concise, actionable recommendation for the student's teacher.
+Synthesize the provided evidence to write a concise, actionable recommendation for the student's teacher.
 
 **Instructions:**
-1.  Start with a brief summary of the student's key challenges.
-2.  Recommend 2-3 concrete, actionable strategies derived *only* from the provided context.
-3.  For each strategy, briefly explain *why* it is relevant to this student, citing the core ideas from the sources.
-4.  Do not invent information. Ground your entire response in the provided context.
-5.  Format the output clearly using Markdown for readability.
+1.  Start with a brief, one-sentence summary of the student's key challenges.
+2.  Recommend 2-3 concrete, actionable strategies derived *only* from the provided evidence. These should be steps the teacher can take in their classroom or in collaboration with the school's support team.
+3.  For each strategy, briefly explain *why* it is relevant to this student, citing the core ideas from the source evidence.
+4.  Do not invent information or suggest strategies not present in the context. Ground your entire response in the provided evidence.
+5.  Format the output clearly using Markdown for readability (e.g., headings and bullet points).
 """,
     "parent": """
-# THIS IS A PLACEHOLDER PROMPT. A detailed prompt would be developed next.
-# Synthesize the context into simple, non-jargon language for a parent.
-# Student: {student_narrative}
-# Context: {context}
+You are a helpful and empathetic AI guidance assistant designed to support parents. Your tone must be supportive, clear, and reassuring. You must avoid educational jargon, acronyms, and overly technical terms.
+
+**Student's Situation:**
+{student_narrative}
+
+**Potential Support Strategies (Based on School Resources):**
+Based on your child's situation, we've identified some effective support strategies from our resource library:
+
+--- BEGIN CONTEXT ---
+{context}
+--- END CONTEXT ---
+
+**Your Task:**
+Synthesize the provided information into a supportive and easy-to-understand message for the student's parent or guardian.
+
+**Instructions:**
+1.  Start with a warm, reassuring opening that summarizes the situation in simple, positive terms (e.g., "Thank you for being a partner in your child's success. Here are a few ways we can work together to help them get back on track.").
+2.  Translate the core ideas from the evidence into 2-3 simple, practical suggestions for how the parent can provide support at home.
+3.  For each suggestion, briefly explain in plain language how it can help their child.
+4.  Maintain a collaborative and non-judgmental tone throughout.
+5.  Conclude with an encouraging statement that emphasizes partnership between home and school.
+6.  Do not invent strategies. Base all suggestions on the core ideas presented in the context, but rephrase them for a parent audience.
 """,
     "principal": """
-# THIS IS A PLACEHOLDER PROMPT. A detailed prompt would be developed next.
-# Synthesize the context into a strategic overview for a principal.
-# Student: {student_narrative}
-# Context: {context}
+You are an expert AI strategist and administrative partner for a high school principal. Your tone is strategic, data-informed, and focused on resource allocation and system-level thinking.
+
+**Student Profile:**
+{student_narrative}
+
+**Relevant Intervention Data:**
+The following evidence-based intervention strategies have been retrieved that match the student's profile:
+
+--- BEGIN CONTEXT ---
+{context}
+--- END CONTEXT ---
+
+**Your Task:**
+Synthesize the retrieved data into a strategic summary for the school principal. The output should be a high-level overview suitable for administrative action and planning.
+
+**Instructions:**
+1.  Begin with a one-sentence "Executive Summary" of the student's on-track status and primary risk factors (e.g., "Student is off-track due to attendance and core course failure.").
+2.  Identify the strategic *type* of intervention needed based on the evidence (e.g., Tier 2 Academic Support, Mentoring, Behavioral Intervention).
+3.  Highlight any **resource or staffing implications** suggested by the evidence. This is critical. For example, if the evidence mentions 'Check & Connect', you should note the need for a dedicated staff monitor. If it mentions 'tutoring', note the need for qualified tutors.
+4.  Recommend a clear, actionable next step for the principal or their designee (e.g., "Task the Freshman Success Team with creating a BAG report," or "Recommend counselor initiate a Check & Connect protocol.").
+5.  Ground all recommendations in the provided context. Do not invent information.
+6.  Keep the entire summary concise and formatted for quick reading.
 """,
 }

src/fot_recommender/rag_pipeline.py

@@ -109,14 +109,21 @@ def generate_recommendation_summary(
     api_key: str,
     persona: str = "teacher",
     model_name: str = GENERATIVE_MODEL_NAME,
-) -> str:
+) -> Tuple[str, Dict[str, Any]]:  # Return text and a details dictionary
     """
     Generates a synthesized recommendation using the Google Gemini API.
+
+    Returns:
+        A tuple containing:
+        - The synthesized recommendation text (str).
+        - A dictionary with detailed prompt information for logging (Dict).
     """
     genai.configure(api_key=api_key)  # type: ignore
 
+    prompt_details = {}
     if persona not in PROMPT_TEMPLATES:
-        return f"ERROR: Persona '{persona}' is not a valid choice."
+        error_message = f"ERROR: Persona '{persona}' is not a valid choice."
+        return error_message, {"error": error_message}
 
     context = ""
     for i, (chunk, _) in enumerate(retrieved_chunks):
@@ -130,6 +137,18 @@ def generate_recommendation_summary(
         student_narrative=student_narrative, context=context
     )
 
+    # --- Assemble the prompt dictionary ---
+    prompt_details = {
+        "persona": persona,
+        "llm_model_used": model_name,
+        "prompt_template": prompt_template,
+        "prompt_variables": {
+            "student_narrative": student_narrative,
+            "context": context,
+        },
+        "final_prompt_text": prompt,
+    }
+
     try:
         print(
             f"\nSynthesizing recommendation for persona: '{persona}' using {model_name}..."
@@ -137,6 +156,7 @@ def generate_recommendation_summary(
         model = genai.GenerativeModel(model_name)  # type: ignore
         response = model.generate_content(prompt)
         print("Synthesis complete.")
-        return response.text
+        return response.text, prompt_details
     except Exception as e:
-        return f"An error occurred while calling the Gemini API: {e}"
+        error_message = f"An error occurred while calling the Gemini API: {e}"
+        return error_message, prompt_details