feat(ui): Overhaul Gradio app for interactivity and evaluation

Transforms the basic Gradio interface into a polished, feature-rich web application designed for demonstration and evaluation. The new UI provides a significantly improved user experience with interactive examples and adds robust features for capturing and analyzing the RAG pipeline's output.

This work completes the transition from a back-end proof-of-concept to a user-facing demo.

Key Changes:

- **Gradio App Overhaul (`app.py`):**
- Rewrote the UI using `gr.Blocks` for a custom two-column layout.
- Added an "Example Scenarios" section with radio buttons to quickly populate the form with pre-defined student narratives.
- Implemented an "Evaluation Data" accordion that displays the full RAG output (inputs, retrieval results, LLM output) in a JSON viewer.
- Added a "Download JSON" button to allow users to save the complete evaluation data for offline analysis.
- Refactored the API call to be a generator (`yield`), enabling progressive updates like "Processing..." messages and interactive button states.

- **Refactored Utilities (`utils.py`):**
- Created a new `format_evidence_for_display` function to centralize the logic for creating rich, cited evidence snippets, now used by both the app and the notebook.
- Added `load_citations` and `create_evaluation_bundle` helpers to support the new UI's data requirements.

- **Notebook Improvements (`fot_recommender_poc.ipynb`):**
- Updated the notebook to use the new `format_evidence_for_display` utility, resulting in a cleaner and more professional presentation of the evidence base.

app.py

@@ -3,68 +3,86 @@ import faiss
 import os
 import numpy as np
 import sys
+import json
+import tempfile
+import datetime
 from pathlib import Path
 from dotenv import load_dotenv
 
+from fot_recommender.utils import load_citations
+
 load_dotenv()
 
-sys.path.insert(0, str(Path(__file__).parent / "src"))
-from fot_recommender.rag_pipeline import ( # noqa: E402
+# --- Define the project root and paths ---
+APP_ROOT = Path(__file__).parent
+sys.path.insert(0, str(APP_ROOT / "src"))
+from fot_recommender.rag_pipeline import (
     load_knowledge_base,
     initialize_embedding_model,
     generate_recommendation_summary,
 )
-
-# --- Define the project root based on this script's location ---
-APP_ROOT = Path(__file__).parent
+from fot_recommender.utils import format_evidence_for_display
 
 # --- Define ABSOLUTE paths to the data artifacts ---
 FAISS_INDEX_PATH = APP_ROOT / "data" / "processed" / "faiss_index.bin"
 KB_PATH = APP_ROOT / "data" / "processed" / "knowledge_base_final_chunks.json"
+CITATIONS_PATH = APP_ROOT / "data" / "processed" / "citations.json"
+
+# --- Define Example Narratives for the UI (with new 'short_title') ---
+EXAMPLE_NARRATIVES = [
+    {
+        "short_title": "Overwhelmed",
+        "title": "Overwhelmed Freshman (Academic & Attendance)",
+        "narrative": "A comprehensive support plan is urgently needed for this freshman. Academic performance is a critical concern, with failures in both Math and English leading to a credit deficiency of only 2 out of 4 expected credits. This academic struggle is compounded by a drop in attendance to 85% and a recent behavioral flag for an outburst in class, suggesting the student is significantly overwhelmed by the transition to high school."
+    },
+    {
+        "short_title": "Withdrawn",
+        "title": "Withdrawn Freshman (Social-Emotional)",
+        "narrative": "Academically, this freshman appears to be thriving, with a high GPA and perfect attendance. A closer look at classroom performance, however, reveals a student who is completely withdrawn. They do not participate in discussions or engage in any extracurricular activities, and teacher notes repeatedly describe them as 'isolated.' The lack of behavioral flags is a result of non-engagement, not positive conduct, pointing to a clear need for interventions focused on social-emotional learning and school connectedness."
+    },
+    {
+        "short_title": "Disruptive",
+        "title": "Disruptive Freshman (Behavioral)",
+        "narrative": "While this student's academics and credits earned are currently on track and attendance is acceptable at 92%, a significant pattern of disruptive behavior is jeopardizing their long-term success. An accumulation of five behavioral flags across multiple classes indicates a primary need for interventions in behavior management and positive conduct. Support should be focused on mentoring and strategies to foster appropriate classroom engagement before these behaviors begin to negatively impact their academic standing."
+    }
+]
+# Use the short title for the UI, but map it to the full narrative
+EXAMPLE_MAP = {ex["short_title"]: ex["narrative"] for ex in EXAMPLE_NARRATIVES}
+EXAMPLE_TITLES = list(EXAMPLE_MAP.keys())
 
+
+# --- Load Environment Variables and Secrets ---
 ACCESS_PASSWORD = os.environ.get("DEMO_PASSWORD", "")
-if ACCESS_PASSWORD and len(ACCESS_PASSWORD) > 10: # Check if it looks like a real key
-    print("✅ DEMO_PASSWORD secret loaded successfully from the environment.")
-else:
-    print("❌ FATAL: DEMO_PASSWORD secret was NOT FOUND in the environment.")
- 
 FOT_GOOGLE_API_KEY = os.environ.get("FOT_GOOGLE_API_KEY", "")
-if FOT_GOOGLE_API_KEY and len(FOT_GOOGLE_API_KEY) > 10: # Check if it looks like a real key
-    print("✅ FOT_GOOGLE_API_KEY secret loaded successfully from the environment.")
-else:
-    print("❌ FATAL: FOT_GOOGLE_API_KEY secret was NOT FOUND in the environment.")
-    
-print("--- Initializing API: Loading models and data... ---")
 
-# --- Load artifacts using the new absolute paths ---
+# --- Initialize models and data ---
+print("--- Initializing API: Loading models and data... ---")
 index = faiss.read_index(str(FAISS_INDEX_PATH))
 knowledge_base_chunks = load_knowledge_base(str(KB_PATH))
+citations_map = load_citations(str(CITATIONS_PATH))
 embedding_model = initialize_embedding_model()
-
 print("✅ API initialized successfully.")
 
-# --- Define the core RAG function that the API exposes ---
-
-
 def get_recommendations_api(student_narrative, persona, password):
-    """The main function that runs the RAG pipeline, protected by a password."""
+    """The main function that runs the RAG pipeline and prepares data for export."""
     if password != ACCESS_PASSWORD:
-        return "Authentication failed. Please check the access key."
+        yield "Authentication failed.", gr.update(interactive=True), gr.update(visible=False), None, gr.update(visible=False)
+        return
+
     if not student_narrative:
-        return "Please enter a student narrative."
+        yield "Please enter a student narrative.", gr.update(interactive=True), gr.update(visible=False), None, gr.update(visible=False)
+        return
+
+    yield "Processing...", gr.update(interactive=False), gr.update(visible=False), None, gr.update(visible=False)
 
     # 1. RETRIEVE
-    query_embedding = np.asarray(embedding_model.encode([student_narrative])).astype(
-        "float32"
-    )
+    query_embedding = np.asarray(embedding_model.encode([student_narrative])).astype("float32")
     scores, indices = index.search(query_embedding, k=3)
-    retrieved_chunks_with_scores = [
-        (knowledge_base_chunks[i], score)
-        for i, score in zip(indices[0], scores[0])
-        if score >= 0.4
-    ]
+    retrieved_chunks_with_scores = [(knowledge_base_chunks[i], score) for i, score in zip(indices[0], scores[0]) if score >= 0.4]
+
     if not retrieved_chunks_with_scores:
-        return "Could not find relevant interventions for this query."
+        yield "Could not find relevant interventions.", gr.update(interactive=True), gr.update(visible=False), None, gr.update(visible=False)
+        return
 
     # 2. GENERATE
     synthesized_recommendation = generate_recommendation_summary(
@@ -74,33 +92,131 @@ def get_recommendations_api(student_narrative, persona, password):
         persona=persona,
     )
 
-    # 3. Augment with evidence
-    evidence_header = "\n\n---\n\n**Evidence Base:**"
-    evidence_list = ""
-    for chunk, score in retrieved_chunks_with_scores:
-        evidence_list += f"\n- **{chunk['title']}** (Source: {chunk['source_document']}, Relevance: {score:.2f})"
-    return synthesized_recommendation + evidence_header + evidence_list
-
-
-# --- Create and launch the Gradio Interface ---
-sample_narrative = "This student is struggling to keep up with coursework, having failed one core class and earning only 2.5 credits..."
-interface = gr.Interface(
-    fn=get_recommendations_api,
-    inputs=[
-        gr.Textbox(lines=5, label="Student Narrative", value=sample_narrative),
-        gr.Radio(
-            ["teacher", "parent", "principal"],
-            label="Who is this for?",
-            value="teacher",
-        ),
-        gr.Textbox(
-            label="Access Key",
-            type="password",
-            info="Enter the access key provided for the demo.",
-        ),
-    ],
-    outputs=gr.Markdown(label="Synthesized Recommendation", show_copy_button=True),
-    title="Freshman On-Track Intervention Recommender API",
-    description="A live API demonstrating the FOT Recommender. Enter the provided access key to use.",
-    theme=gr.themes.Soft(),  # type: ignore
-).launch()
+    # 3. Augment with evidence for UI
+    formatted_evidence = format_evidence_for_display(retrieved_chunks_with_scores, citations_map)
+    evidence_header = "\n\n---\n\n### Evidence Base\n"
+    evidence_list_str = ""
+    for evidence in formatted_evidence:
+        evidence_list_str += f"\n- **{evidence['title']}**\n"
+        evidence_list_str += f"  - **Source:** {evidence['source']}\n"
+        evidence_list_str += f"  - **Page(s):** {evidence['pages']}\n"
+        evidence_list_str += f"  - **Relevance Score:** {evidence['score']}\n"
+        evidence_list_str += f"  - **Content Snippet:**\n  > {evidence['content_snippet']}\n"
+    
+    final_output = synthesized_recommendation + evidence_header + evidence_list_str
+    
+    # 4. Assemble Evaluation Data
+    evaluation_data = {
+        "timestamp": datetime.datetime.now().isoformat(),
+        "inputs": {"student_narrative": student_narrative, "persona": persona},
+        "retrieval_results": [
+            {
+                "chunk_title": chunk['title'], "relevance_score": float(score),
+                "source_document": chunk['source_document'], "page_info": chunk.get('fot_pages', 'N/A'),
+                "original_content": chunk.get('original_content', ''), "citation_info": citations_map.get(chunk['source_document'], {})
+            } for chunk, score in retrieved_chunks_with_scores
+        ],
+        "llm_output": {"synthesized_recommendation": synthesized_recommendation},
+        "final_ui_output": final_output
+    }
+
+    # 5. Create a temporary file for download
+    with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix=".json", encoding='utf-8') as f:
+        json.dump(evaluation_data, f, indent=4)
+        temp_file_path = f.name
+
+    yield final_output, gr.update(interactive=True), gr.update(visible=True), evaluation_data, gr.update(value=temp_file_path, visible=True)
+
+
+# --- UI Helper Functions ---
+def clear_all():
+    """Clears inputs, outputs, and hides the export section."""
+    return "", None, "", gr.update(visible=False), None, gr.update(visible=False, value=None)
+
+def update_narrative_from_example(selection):
+    """Populates the narrative textbox when an example radio button is selected."""
+    return EXAMPLE_MAP.get(selection, "")
+
+# --- Custom CSS for horizontal radio buttons ---
+CUSTOM_CSS = """
+/* Target the container of the radio buttons and make them horizontal */
+.radio-horizontal .gr-form {
+    flex-direction: row;
+    flex-wrap: wrap;
+    gap: 0.5rem; /* Adjust spacing between buttons */
+}
+"""
+
+# --- Gradio Interface ---
+with gr.Blocks(theme=gr.themes.Soft(), css=CUSTOM_CSS) as interface:
+    gr.Markdown(
+        """
+        # Freshman On-Track Intervention Recommender
+        *A live API demonstrating the FOT Recommender.*
+        """
+    )
+    with gr.Row(equal_height=False):
+        with gr.Column(scale=1):
+            with gr.Group():
+                narrative_input = gr.Textbox(
+                    lines=8,
+                    label="Student Narrative",
+                    placeholder="Describe the student's situation here, or select an example below.",
+                )
+
+                # Use the new short titles and apply the custom CSS class
+                example_radio = gr.Radio(
+                    EXAMPLE_TITLES,
+                    label="Load an Example Scenario",
+                    info="Select one to populate the narrative above. Typing a custom narrative will clear this selection.",
+                    elem_classes=["radio-horizontal"] 
+                )
+
+                persona_input = gr.Radio(
+                    ["teacher", "parent", "principal"],
+                    label="Who is this recommendation for?",
+                    value="teacher",
+                    elem_classes=["radio-horizontal"] # Apply same style here for consistency
+                )
+                password_input = gr.Textbox(
+                    label="Access Key",
+                    type="password",
+                    info="Enter the access key for the demo."
+                )
+
+                with gr.Row():
+                    clear_btn = gr.Button("Clear")
+                    submit_btn = gr.Button("Submit", variant="primary")
+
+        with gr.Column(scale=2):
+            recommendation_output = gr.Markdown(label="Synthesized Recommendation", show_copy_button=True)
+            with gr.Accordion("Evaluation Data", open=False, visible=False) as eval_accordion:
+                json_viewer = gr.JSON(label="Evaluation JSON")
+                download_btn = gr.DownloadButton("Download JSON", visible=False)
+                
+
+    # --- Event Handlers ---
+    example_radio.change(
+        fn=update_narrative_from_example,
+        inputs=example_radio,
+        outputs=narrative_input
+    )
+    narrative_input.input(
+        fn=lambda: None,
+        inputs=None,
+        outputs=example_radio
+    )
+    submit_btn.click(
+        fn=get_recommendations_api,
+        inputs=[narrative_input, persona_input, password_input],
+        outputs=[recommendation_output, submit_btn, eval_accordion, json_viewer, download_btn]
+    )
+    clear_btn.click(
+        fn=clear_all,
+        inputs=[],
+        outputs=[narrative_input, example_radio, recommendation_output, eval_accordion, json_viewer, download_btn]
+    )
+
+
+if __name__ == "__main__":
+    interface.launch()

notebooks/fot_recommender_poc.ipynb

@@ -6,11 +6,11 @@
    "metadata": {},
    "source": [
     "# Freshman On-Track (FOT) Intervention Recommender\n",
-    "### A Standalone Proof-of-Concept\n",
+    "### A Proof-of-Concept\n",
     "\n",
-    "**Goal:** To show, in a few simple steps, how we can turn a description of a struggling student into a set of clear, actionable, and evidence-based recommendations for an educator.\n",
+    "**Goal:** To show, in just a few steps, how we can turn a description of a struggling student into a set of clear, actionable, and evidence-based strategies.\n",
     "\n",
-    "This notebook demonstrates the core Retrieval-Augmented Generation (RAG) pipeline that powers our recommender."
+    "This notebook demonstrates the core **Retrieval** engine that powers our recommender. It shows how the system intelligently finds the most relevant documents from a knowledge base to match a student's needs."
    ]
   },
   {
@@ -27,7 +27,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 1,
    "id": "97f37783",
    "metadata": {},
    "outputs": [
@@ -42,15 +42,14 @@
     }
    ],
    "source": [
-    "import sys, os, warnings\n",
+    "import sys, os, warnings, json\n",
     "from pathlib import Path\n",
-    "from tqdm import TqdmWarning\n",
     "\n",
     "# This prevents common, harmless warnings from cluttering the output.\n",
     "os.environ[\"TOKENIZERS_PARALLELISM\"] = \"false\"\n",
-    "warnings.filterwarnings(\"ignore\", category=TqdmWarning)\n",
+    "warnings.filterwarnings(\"ignore\", category=FutureWarning) # Suppress specific torch warning\n",
     "\n",
-    "# Clones the project from GitHub, but only if it doesn't already exist.\n",
+    "# Clones the project from GitHub if not already present.\n",
     "PROJECT_DIR = \"fot-intervention-recommender\"\n",
     "if not Path(PROJECT_DIR).is_dir():\n",
     "    print(\"🚀 Downloading project files...\")\n",
@@ -124,11 +123,13 @@
     "\n",
     "Now, we take the student's story and find the most relevant strategies from our **Knowledge Base**—a curated library of best practices and proven interventions.\n",
     "\n",
-    "How do we do this? \n",
-    "1.  We've already converted our knowledge base documents into **vector embeddings** (unique digital fingerprints that capture meaning).\n",
-    "2.  We use a **FAISS vector database**—a super-fast search index—to instantly find the documents with fingerprints most similar to the student's situation.\n",
+    "This next cell will perform the core retrieval logic:\n",
+    "1.  Load the pre-processed knowledge base and citation data.\n",
+    "2.  Initialize the text embedding model.\n",
+    "3.  Create a searchable Facebook AI Similarity Search (FAISS) vector index.\n",
+    "4.  Use the student query to find the top 3 most similar interventions.\n",
     "\n",
-    "Let's see which top 3 strategies our system retrieves for this student."
+    "The output will show the evidence-based strategies our system identified."
    ]
   },
   {
@@ -158,9 +159,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "Batches:   0%|                                            | 0/1 [00:00<?, ?it/s]/Users/charlesfeinn/Developer/job_applications/fot-intervention-recommender/.venv/lib/python3.12/site-packages/torch/nn/modules/module.py:1520: FutureWarning: `encoder_attention_mask` is deprecated and will be removed in version 4.55.0 for `BertSdpaSelfAttention.forward`.\n",
-      "  return forward_call(*args, **kwargs)\n",
-      "Batches: 100%|████████████████████████████████████| 1/1 [00:02<00:00,  2.08s/it]\n"
+      "Batches: 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:02<00:00,  2.24s/it]\n"
      ]
     },
     {
@@ -172,13 +171,14 @@
       "FAISS index created with 27 vectors.\n",
       "\n",
       "Searching for top 3 interventions for query: 'This student is struggling to keep up with coursework, having failed one core cl...'\n",
-      "Found 3 relevant interventions.\n"
+      "Found 3 relevant interventions.\n",
+      "✅ Successfully loaded models and retrieved the top 3 most relevant interventions from the knowledge base.\n"
      ]
     },
     {
      "data": {
       "text/markdown": [
-       "**Top 3 Retrieved Strategies:**"
+       "### Evidence Base"
       ],
       "text/plain": [
        "<IPython.core.display.Markdown object>"
@@ -190,7 +190,15 @@
     {
      "data": {
       "text/markdown": [
-       "- **Strategy: Differentiating Intervention Tiers** (Source: *NCS_OTToolkit_2ndEd_October_2017_updated.pdf*, Relevance: 0.57)"
+       "\n",
+       "**Strategy: Differentiating Intervention Tiers**\n",
+       "- **Source:** *Freshman On‑Track Toolkit (2nd Edition)* (Network for College Success, 2017).\n",
+       "- **Page(s):** Pages: 46\n",
+       "- **Relevance Score:** 0.57\n",
+       "- **Content Snippet:**\n",
+       "> To what degree is attendance playing a role in student performance? To whom do you refer Tier 3 students who have serious attendance issues (inside and outside of the school) so that the Success Team can really concentrate on supporting Tier 2 students?\n",
+       "\n",
+       "---\n"
       ],
       "text/plain": [
        "<IPython.core.display.Markdown object>"
@@ -202,7 +210,26 @@
     {
      "data": {
       "text/markdown": [
-       "- **Tool: Intervention Tracking** (Source: *NCS_OTToolkit_2ndEd_October_2017_updated.pdf*, Relevance: 0.54)"
+       "\n",
+       "**Tool: Intervention Tracking**\n",
+       "- **Source:** *Freshman On‑Track Toolkit (2nd Edition)* (Network for College Success, 2017).\n",
+       "- **Page(s):** Pages: 49\n",
+       "- **Relevance Score:** 0.54\n",
+       "- **Content Snippet:**\n",
+       "> Features of Good Intervention Tracking Tools:\n",
+       "> • Name of the intervention and what key performance indicator it addresses (attendance, point-in-time On-Track rates, GPA, behavior metric, etc.)\n",
+       "> • Names of the targeted students\n",
+       ">   ° If tracking grades, include each core course's average expressed as a percentage\n",
+       "> • Intervention contacts/implementation evidence\n",
+       ">   ° Tutoring attendance\n",
+       ">   ° Mentorship contact dates\n",
+       ">   ° \"Office hours\" visits\n",
+       "> • Point-in-time progress on the key performance indicator impacted by the intervention\n",
+       ">   ° Should include at least 2 checkpoints within a 10-week period\n",
+       ">   ° If tracking grades, provide an average expressed as a percentage for each core course\n",
+       ">   ° If tracking attendance, provide number of cumulative absences and/or tardies\n",
+       "\n",
+       "---\n"
       ],
       "text/plain": [
        "<IPython.core.display.Markdown object>"
@@ -214,7 +241,47 @@
     {
      "data": {
       "text/markdown": [
-       "- **Tool: BAG Report (Example)** (Source: *NCS_OTToolkit_2ndEd_October_2017_updated.pdf*, Relevance: 0.53)"
+       "\n",
+       "**Tool: BAG Report (Example)**\n",
+       "- **Source:** *Freshman On‑Track Toolkit (2nd Edition)* (Network for College Success, 2017).\n",
+       "- **Page(s):** Pages: 61\n",
+       "- **Relevance Score:** 0.53\n",
+       "- **Content Snippet:**\n",
+       "> Student: Keith\n",
+       "> Grade Level: 9\n",
+       "> 8th Period Teacher: Donson\n",
+       "> The numbers below reflect totals through Semester 1\n",
+       "> \n",
+       "> BEHAVIOR - In what ways do I contribute to a Safe and Respectful school climate?\n",
+       "> • # of Infractions (# of Major Infractions): 5 (1)\n",
+       "> • # of Days of In-School-Suspension (ISS): 10\n",
+       "> • # of Days of Out-of-School-Suspension (OSS): 0\n",
+       "> If I have any questions regarding my misconducts, I should schedule an appointment with the Dean of Discipline.\n",
+       "> \n",
+       "> ATTENDANCE - Do my actions reflect the real me?\n",
+       "> • Days Enrolled: 80\n",
+       "> • Days Present: 73\n",
+       "> • Days Absent: 7\n",
+       "> • My Year-to-Date Attendance Rate is 91%\n",
+       "> If I have any questions regarding my attendance, I should schedule an appointment with the Attendance Dean.\n",
+       "> \n",
+       "> GRADES - How am I doing academically in my classes? Do my grades represent my true ability?\n",
+       "> Period | Courses | Teacher | Grade\n",
+       "> P1 | Algebra 1 | Flint | D\n",
+       "> P2 | English 1 | Lemon | B\n",
+       "> P3 | World Studies | Moeller | C\n",
+       "> P4 | PE I-Health | Spann | A\n",
+       "> P5 | Lunch | | \n",
+       "> P6 | Science | Tyson | D\n",
+       "> P7 | Photography | McCain | B\n",
+       "> P8 | Intro to Comp | Penny | A\n",
+       "> \n",
+       "> My Estimated GPA is 2.57\n",
+       "> (this estimate does NOT include any previous semesters)\n",
+       "> \n",
+       "> If I have any questions regarding my grade in a course, I should schedule an appointment with my Teacher.\n",
+       "\n",
+       "---\n"
       ],
       "text/plain": [
        "<IPython.core.display.Markdown object>"
@@ -225,31 +292,28 @@
     }
    ],
    "source": [
-    "# Import the necessary functions from our project's code\n",
     "from fot_recommender.rag_pipeline import (\n",
     "    load_knowledge_base,\n",
     "    initialize_embedding_model,\n",
     "    create_embeddings,\n",
     "    create_vector_db,\n",
-    "    search_interventions,\n",
-    "    generate_recommendation_summary\n",
+    "    search_interventions\n",
     ")\n",
     "from fot_recommender.utils import display_recommendations\n",
     "\n",
-    "# --- Load all the components of our RAG system ---\n",
-    "\n",
-    "# 1. Load the chunked knowledge base\n",
+    "# 1. Load data\n",
     "kb_path = project_path / \"data\" / \"processed\" / \"knowledge_base_final_chunks.json\"\n",
+    "citations_path = project_path / \"data\" / \"processed\" / \"citations.json\"\n",
     "knowledge_base_chunks = load_knowledge_base(str(kb_path))\n",
+    "with open(citations_path, \"r\") as f:\n",
+    "    citations_map = {item[\"source_document\"]: item for item in json.load(f)}\n",
     "\n",
-    "# 2. Initialize the embedding model\n",
+    "# 2. Initialize models and DB (quietly)\n",
     "embedding_model = initialize_embedding_model()\n",
-    "\n",
-    "# 3. Create embeddings and the vector database\n",
     "embeddings = create_embeddings(knowledge_base_chunks, embedding_model)\n",
     "vector_db = create_vector_db(embeddings)\n",
     "\n",
-    "# --- Perform the search! ---\n",
+    "# 3. Perform search (quietly)\n",
     "retrieved_interventions = search_interventions(\n",
     "    query=student_query,\n",
     "    model=embedding_model,\n",
@@ -259,10 +323,9 @@
     "    min_similarity_score=0.4\n",
     ")\n",
     "\n",
-    "# Display the titles of what we found\n",
-    "display(Markdown(\"**Top 3 Retrieved Strategies:**\"))\n",
-    "for chunk, score in retrieved_interventions:\n",
-    "    display(Markdown(f\"- **{chunk['title']}** (Source: *{chunk['source_document']}*, Relevance: {score:.2f})\"))"
+    "# 4. Display a clean summary and the rich results\n",
+    "print(f\"✅ Successfully loaded models and retrieved the top {len(retrieved_interventions)} most relevant interventions from the knowledge base.\")\n",
+    "display_recommendations(retrieved_interventions, citations_map)"
    ]
   },
   {
@@ -270,178 +333,16 @@
    "id": "2202209d",
    "metadata": {},
    "source": [
-    "## Step 4: Create the Recommendation (The \"Generation\" Step)\n",
-    "\n",
-    "Finding the right documents is only half the battle. Raw research isn't very helpful to a busy teacher. \n",
-    "\n",
-    "In this final step, we use a powerful Large Language Model (Google's Gemini API) to act as an expert instructional coach. We give it the student's story and the relevant strategies we just retrieved. The AI's job is to **synthesize** this information into a concise, practical recommendation tailored specifically for a teacher.\n",
-    "\n",
-    "This is the final output of our system."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 4,
-   "id": "62ee35bc",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "\n",
-      "Synthesizing recommendation for persona: 'teacher' using Gemini...\n",
-      "Synthesis complete.\n"
-     ]
-    },
-    {
-     "data": {
-      "text/markdown": [
-       "### Final Synthesized Recommendation for the Teacher"
-      ],
-      "text/plain": [
-       "<IPython.core.display.Markdown object>"
-      ]
-     },
-     "metadata": {},
-     "output_type": "display_data"
-    },
-    {
-     "data": {
-      "text/markdown": [
-       "This student is experiencing academic difficulty, reflected in a 2.5 GPA and a failing grade in one core class, coupled with attendance concerns (88% attendance versus a 90% target) and one behavioral incident.  To address these challenges and support the student's path to graduation, the following interventions are recommended:\n",
-       "\n",
-       "\n",
-       "**1. Implement a Tiered Intervention Strategy:**  Determine the extent to which attendance is contributing to the student's academic struggles. (\"Strategy: Differentiating Intervention Tiers\").  If attendance is a significant factor,  refer the student to the appropriate support services (Success Team or Attendance Dean, as indicated by the BAG Report format) to address these issues directly. This allows more focused support from the teaching staff for academic interventions.\n",
-       "\n",
-       "**2. Utilize a Robust Intervention Tracking System:**  Implement a system to monitor the student's progress, focusing on attendance, GPA, and behavior. (\"Tool: Intervention Tracking\").  This system should clearly document interventions (e.g., tutoring sessions, mentorship meetings), and track the student’s progress in each core course (GPA and attendance rates) at two checkpoints within a ten-week period. The \"BAG Report\" format provides a useful template to track behavior, attendance and grades. This data will inform adjustments to the support plan.\n",
-       "\n",
-       "**3.  Regularly Review the Student's \"BAG Report\" (or Equivalent):**  Use a reporting mechanism (such as the BAG report example) to regularly review the student's performance across all three key areas: Behavior, Attendance, and Grades. This visual representation highlights areas of strength and areas requiring immediate intervention, allowing for proactive adjustments to support strategies. This aligns with the recommendation to monitor multiple key performance indicators to improve student outcomes effectively.\n"
-      ],
-      "text/plain": [
-       "<IPython.core.display.Markdown object>"
-      ]
-     },
-     "metadata": {},
-     "output_type": "display_data"
-    }
-   ],
-   "source": [
-    "from dotenv import load_dotenv\n",
-    "\n",
-    "# Load the API key from a .env file (if it exists)\n",
-    "load_dotenv(project_path / '.env') \n",
-    "api_key = os.getenv(\"FOT_GOOGLE_API_KEY\")\n",
-    "\n",
-    "if not api_key:\n",
-    "    print(\"✋ FOT_GOOGLE_API_KEY not found. Please provide your Google API key to generate the summary.\")\n",
-    "    final_recommendation = \"(API Key not provided - could not generate summary)\"\n",
-    "else:\n",
-    "    final_recommendation = generate_recommendation_summary(\n",
-    "        retrieved_chunks=retrieved_interventions,\n",
-    "        student_narrative=student_query,\n",
-    "        api_key=api_key,\n",
-    "        persona=\"teacher\"\n",
-    "    )\n",
-    "\n",
-    "display(Markdown(\"### Final Synthesized Recommendation for the Teacher\"))\n",
-    "display(Markdown(final_recommendation))"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "d3718297",
-   "metadata": {},
-   "source": [
-    "## Bonus: See the Evidence\n",
+    "## Step 4: See the Full System in the Live Demo!\n",
     "\n",
-    "The recommendation above isn't just made up—it's directly grounded in the documents we retrieved. Here are the specific text snippets that the AI used to create its summary. This ensures our recommendations are always transparent and evidence-based."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 5,
-   "id": "1b0cb720",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "\n",
-      "--- Top Recommended Interventions ---\n",
-      "\n",
-      "--- Recommendation 1 (Similarity Score: 0.5735) ---\n",
-      "  Title: Strategy: Differentiating Intervention Tiers\n",
-      "  Source: NCS_OTToolkit_2ndEd_October_2017_updated.pdf (Pages: 46)\n",
-      "  \n",
-      "  Content Snippet:\n",
-      "  \"To what degree is attendance playing a role in student performance? To whom do you refer Tier 3 students who have serious attendance issues (inside and outside of the school) so that the Success Team can really concentrate on supporting Tier 2 students?...\"\n",
-      "--------------------------------------------------\n",
-      "\n",
-      "--- Recommendation 2 (Similarity Score: 0.5416) ---\n",
-      "  Title: Tool: Intervention Tracking\n",
-      "  Source: NCS_OTToolkit_2ndEd_October_2017_updated.pdf (Pages: 49)\n",
-      "  \n",
-      "  Content Snippet:\n",
-      "  \"Features of Good Intervention Tracking Tools:\n",
-      "  • Name of the intervention and what key performance indicator it addresses (attendance, point-in-time On-Track rates, GPA, behavior metric, etc.)\n",
-      "  • Names of the targeted students\n",
-      "    ° If tracking grades, include each core course's average expressed as a percentage\n",
-      "  • Intervention contacts/implementation evidence\n",
-      "    ° Tutoring attendance\n",
-      "    ° Mentorship contact dates\n",
-      "    ° \"Office hours\" visits\n",
-      "  • Point-in-time progress on the key performance...\"\n",
-      "--------------------------------------------------\n",
-      "\n",
-      "--- Recommendation 3 (Similarity Score: 0.5328) ---\n",
-      "  Title: Tool: BAG Report (Example)\n",
-      "  Source: NCS_OTToolkit_2ndEd_October_2017_updated.pdf (Pages: 61)\n",
-      "  \n",
-      "  Content Snippet:\n",
-      "  \"Student: Keith\n",
-      "  Grade Level: 9\n",
-      "  8th Period Teacher: Donson\n",
-      "  The numbers below reflect totals through Semester 1\n",
-      "  \n",
-      "  BEHAVIOR - In what ways do I contribute to a Safe and Respectful school climate?\n",
-      "  • # of Infractions (# of Major Infractions): 5 (1)\n",
-      "  • # of Days of In-School-Suspension (ISS): 10\n",
-      "  • # of Days of Out-of-School-Suspension (OSS): 0\n",
-      "  If I have any questions regarding my misconducts, I should schedule an appointment with the Dean of Discipline.\n",
-      "  \n",
-      "  ATTENDANCE - Do my actions r...\"\n",
-      "--------------------------------------------------\n"
-     ]
-    }
-   ],
-   "source": [
-    "display_recommendations(retrieved_interventions)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "254d4cdf",
-   "metadata": {},
-   "source": [
-    "## Explore the Live Demo!\n",
+    "You've just seen the core **Retrieval** engine at work. The system successfully took a student's story and identified the most relevant, evidence-based strategies from our knowledge base.\n",
     "\n",
-    "You've seen the step-by-step process of how our RAG system turns a student's story into an actionable, evidence-based plan. Now, it's time to try it yourself with any student scenario you can imagine!\n",
+    "The final step in our RAG pipeline is **Generation**, where we use a Large Language Model to synthesize this evidence into a clear, actionable recommendation for an educator. This step requires a secure API key, so we've hosted it in an interactive web application.\n",
     "\n",
-    "We have deployed this entire system as an interactive web application on Hugging Face Spaces. Click the link below to access the live demo—no setup or API key required.\n",
+    "Click the link below to see the full system in action. You can use the student narrative from this notebook or try your own!\n",
     "\n",
-    "\n",
-    "#### [👉 Click Here to Launch the Live FOT Recommender API](https://huggingface.co/spaces/chuckfinca/fot-recommender-api)\n"
+    "### [👉 Click Here to Launch the Live FOT Recommender API](https://huggingface.co/spaces/chuckfinca/fot-recommender-api)"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "64867bc5-2762-4c69-aa72-e4e7cf911019",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

src/fot_recommender/utils.py

@@ -1,27 +1,104 @@
-from typing import List, Dict, Any, Tuple
+import datetime
+import json
+from IPython.display import display, Markdown
 
-
-def display_recommendations(results: List[Tuple[Dict[str, Any], float]]):
+def display_recommendations(results: list, citations_map: dict):
     """
-    A helper function to neatly print the results of a semantic search.
-    This function is designed to be called from a notebook or a command-line script.
-
-    Args:
-        results: A list of tuples, where each tuple contains a result chunk (dict)
-                 and its similarity score (float).
+    Displays the retrieved recommendations in a rich, Markdown-formatted output
+    directly within a Jupyter/Colab notebook by using the shared formatter.
     """
     if not results:
-        print("\nNo relevant interventions were found for this query.")
+        display(Markdown("### No relevant interventions were found for this query."))
         return
 
-    print("\n--- Top Recommended Interventions ---")
-    for i, (chunk, score) in enumerate(results):
-        print(f"\n--- Recommendation {i + 1} (Similarity Score: {score:.4f}) ---")
-        print(f"  Title: {chunk['title']}")
-        print(f"  Source: {chunk['source_document']} ({chunk['fot_pages']})")
-
-        # Indent the content for better readability
-        content = chunk["original_content"]
-        indented_content = "\n  ".join(content.splitlines())
-        print(f'  \n  Content Snippet:\n  "{indented_content[:500]}..."')
-        print("-" * 50)
+    # 1. Get the formatted data from the shared function
+    formatted_evidence = format_evidence_for_display(results, citations_map)
+
+    display(Markdown("### Evidence Base"))
+    
+    # 2. Loop through the clean data and render it for the notebook
+    for evidence in formatted_evidence:
+        recommendation_md = f"""
+**{evidence['title']}**
+- **Source:** {evidence['source']}
+- **Page(s):** {evidence['pages']}
+- **Relevance Score:** {evidence['score']}
+- **Content Snippet:**
+> {evidence['content_snippet']}
+
+---
+"""
+        display(Markdown(recommendation_md))
+
+
+
+def create_evaluation_bundle(
+    student_narrative: str,
+    persona: str,
+    retrieved_chunks_with_scores: list,
+    synthesized_recommendation: str,
+    citations_map: dict
+) -> dict:
+    """
+    Assembles a comprehensive dictionary for evaluation and logging purposes.
+    """
+    evaluation_data = {
+        "timestamp": datetime.datetime.now().isoformat(),
+        "inputs": {
+            "student_narrative": student_narrative,
+            "persona": persona,
+        },
+        "retrieval_results": [
+            {
+                "chunk_title": chunk['title'],
+                "relevance_score": float(score),
+                "source_document": chunk['source_document'],
+                "page_info": chunk.get('fot_pages', 'N/A'),
+                "original_content": chunk.get('original_content', ''),
+                "citation_info": citations_map.get(chunk['source_document'], {})
+            } for chunk, score in retrieved_chunks_with_scores
+        ],
+        "llm_output": {
+            "synthesized_recommendation": synthesized_recommendation
+        }
+    }
+    return evaluation_data
+
+def format_evidence_for_display(results: list, citations_map: dict) -> list:
+    """
+    Takes raw search results and formats them into a structured list of dictionaries
+    ready for display in any environment.
+    """
+    evidence_list = []
+    for chunk, score in results:
+        source_doc = chunk.get('source_document', 'N/A')
+        citation_info = citations_map.get(source_doc, {})
+        
+        # Consolidate all the formatting logic here
+        title = citation_info.get('title', 'N/A')
+        author = citation_info.get('author', 'N/A')
+        year = citation_info.get('year', 'N/A')
+        source_string = f"*{title}* ({author}, {year})."
+        
+        page_info = chunk.get('fot_pages', 'N/A')
+        
+        original_content = chunk.get("original_content", "Content not available.").strip()
+        blockquote_content = original_content.replace('\n', '\n> ')
+        
+        evidence_list.append({
+            "title": chunk['title'],
+            "source": source_string,
+            "pages": page_info,
+            "score": f"{score:.2f}",
+            "content_snippet": blockquote_content
+        })
+        
+    return evidence_list
+
+def load_citations(path):
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            citations_list = json.load(f)
+        return {item["source_document"]: item for item in citations_list}
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}