Improve system prompt personability and update README with manuscript information

- Add context-aware scenario inclusion for multi-part requests
- Enhance communication style to be warm and engaging (Pliny personality)
- Update README with research evidence, best practices, and all co-authors
- Add pedagogical approach explanation and CourseSource citation

README.md

@@ -13,16 +13,21 @@ short_description: AI-enhanced study app for students
 
 # Schema Study: An AI-Enhanced Study App for Biology Students
 
-Schema Study is a modern, interactive study app designed to help biology students master core course concepts through AI-powered conversations. The app leverages OpenAI's latest GPT models via the Responses API to provide instant feedback, Socratic questioning, and personalized study support.
+Schema Study is a free, no-code, open-source web application that turns a spreadsheet of course terms into an AI-powered study coach. Designed for asynchronous student learning and inquiry, Schema Study helps biology students master core course concepts through evidence-based AI-powered conversations. The app leverages OpenAI's latest GPT models via the Responses API to provide instant formative feedback, Socratic questioning, and personalized study support.
+
+**Key Pedagogical Approach:** Schema Study uses a Socratic questioning method that (1) withholds direct solutions while providing brief, targeted feedback, (2) poses exactly one scenario-grounded follow-up question per turn, and (3) presses for mechanistic reasoning, justification, and connections between concepts. The tool provides formative practice through question-led dialogue; independent performance is evaluated in secure assessments outside the app.
 
 ## Features
-- **Password Protection:** Secure access for your class or group.
-- **Customizable Terms:** Use your own CSV file of terms and definitions.
-- **Prompt Templates:** Engage with the material using creative, research-based prompts including midterm review.
-- **AI-Enhanced Feedback:** Get instant, formative feedback and guidance using GPT-5.1 (default) or GPT-4.1.
-- **Web Search Support:** Optional web search functionality for current information and citations (configurable in `config.py`).
-- **Real-Time Streaming:** Live token-by-token response streaming with visual typing indicator.
-- **Professional, Accessible UI:** Clean, modern design with a color palette for clarity and focus.
+- **No-Code Setup:** Upload course terms via a single CSV spreadsheet - no programming required
+- **Password Protection:** Secure access for your class or group
+- **Customizable Terms:** Use your own CSV file of terms and definitions
+- **Evidence-Based Pedagogy:** Implements Socratic questioning and formative feedback strategies
+- **Prompt Templates:** Engage with the material using creative, research-based prompts including midterm review
+- **AI-Enhanced Feedback:** Get instant, formative feedback and guidance using GPT-5.2 (default), GPT-5.1, or GPT-4.1
+- **Web Search Support:** Optional web search functionality for current information and citations (configurable in `config.py`)
+- **Real-Time Streaming:** Live token-by-token response streaming with visual typing indicator
+- **Professional, Accessible UI:** Clean, modern design with a color palette for clarity and focus
+- **Open-Source & Free:** Fully open-source under GNU GPL-3 License, no paywalls or proprietary services required
 
 ## How to Use (Students)
 1. **Access the App:** Go to your Hugging Face Space URL. Enter the password provided by your instructor.
@@ -32,6 +37,16 @@ Schema Study is a modern, interactive study app designed to help biology student
 
 ## How to Use (Instructors)
 
+### Best Practices for Integration
+
+Based on classroom testing and iterative refinement, here are recommended best practices for integrating Schema Study:
+
+- **Clear Structured Messaging:** Provide students with clear instructions on how to use Schema Study and its role in your course
+- **AI Literacy Training:** Include brief training on AI literacy and appropriate use of AI tools in educational settings
+- **Curricular Alignment:** Ensure your terms and context align with your learning objectives - update content regularly as you progress through the course
+- **Scaffolded Active Learning:** Embed Schema Study within structured assignments rather than as an optional tool
+- **Formative vs. Summative:** Use Schema Study for formative practice and feedback; evaluate independent performance in secure assessments outside the app
+
 ### Setup
 1. **Clone or Fork the Space:**
    ```bash
@@ -42,8 +57,8 @@ Schema Study is a modern, interactive study app designed to help biology student
 2. **Edit Configuration:**
    - Update `config.py` for your course (title, instructions, prompt templates, etc).
    - Configure AI model settings:
-     - `ai_model`: Choose "gpt-5.1" (default) or "gpt-4.1"
-     - `reasoning_effort`: For GPT-5.1, set to "none" (fastest), "minimal", "low", or "medium"
+     - `ai_model`: Choose "gpt-5.2" (default), "gpt-5.1", or "gpt-4.1"
+     - `reasoning_effort`: For GPT-5.2 and GPT-5.1, set to "none" (fastest), "minimal", "low", or "medium"
      - `enable_web_search`: Set to `True` or `False` (default: True)
    - Place your terms CSV (e.g., `terms.csv`) in the root directory. Format: first column = term, second column = context/definition.
 
@@ -64,16 +79,17 @@ Schema Study is a modern, interactive study app designed to help biology student
    ```
 
 ### Model Selection Guide
-- **GPT-5.1** (default): Best for most use cases, fastest with reasoning="none", supports web search
+- **GPT-5.2** (default): Latest reasoning model, fastest with reasoning="none", supports web search
+- **GPT-5.1**: Reasoning model with reasoning="none" default for faster responses, supports web search
 - **GPT-4.1**: Use if you need temperature control or prefer non-reasoning model, excellent web search support
 
 ## Configuration
 
 ### AI Model Settings (`config.py`)
-- **Default Model:** GPT-5.1 with reasoning="none" for faster responses
-- **Alternative Model:** GPT-4.1 with temperature control
+- **Default Model:** GPT-5.2 with reasoning="none" for faster responses
+- **Alternative Models:** GPT-5.1 (reasoning model) or GPT-4.1 (non-reasoning model with temperature control)
 - **Web Search:** Configurable via `enable_web_search` (default: True)
-- **Reasoning Effort:** Configurable for GPT-5.1 (options: "none", "minimal", "low", "medium")
+- **Reasoning Effort:** Configurable for GPT-5.2 and GPT-5.1 (options: "none", "minimal", "low", "medium")
 - **Temperature:** Configurable for GPT-4.1 (0.0-2.0)
 
 ### Other Settings
@@ -85,22 +101,34 @@ Schema Study is a modern, interactive study app designed to help biology student
 
 ### API & Models
 - **API Framework:** OpenAI Responses API (streaming-enabled)
-- **Supported Models:** GPT-5.1 (default), GPT-4.1
+- **Supported Models:** GPT-5.2 (default), GPT-5.1, GPT-4.1
 - **Streaming:** Real-time token-by-token response streaming
 - **Inactivity Guard:** Streaming stops after 60s of no server deltas
 
 ### File Structure
 - `app.py` — Main Streamlit app with Responses API integration
-- `config.py` — All app settings and customization (model selection, web search, prompt templates)
+- `config.py` — All app settings and customization (model selection, web search, prompt templates, system prompt)
 - `.streamlit/secrets.toml` — Authentication credentials and API key (not tracked in git)
 - `requirements.txt` — Python dependencies
 - `terms.csv` — Your course terms and definitions (CSV format: term, context)
-- `BILD_5_Syllabus_Reuther_SP25.pdf` — Example resource
-- `BILD 5 F25 Midterm Exam.pdf` — Midterm exam resource
+- `example_syllabus.pdf` — Example resource file (replace with your own syllabus)
+- `LICENSE` — GNU GPL-3 License file
 
 ## License
 This project is licensed under the GNU GPL-3 License. See the [LICENSE](LICENSE) file for details.
 
+## Research & Citation
+
+This app, its corresponding CourseSource manuscript, and all documentation was authored, edited, and tested by Keefe Reuther, Dr. Liam O Mueller, Grace Constantian, Albert Nguyen, and the members of the Reuther Lab.
+
+**Research Evidence:** During Winter 2025, Schema Study was integrated into an introductory biology course with 225 students. Pre- and post-surveys indicated strong student satisfaction, with 72% of students reporting they would reuse Schema Study in future biology courses. Each additional day per week students used Schema Study more than doubled the likelihood they would recommend it. Schema Study enhanced students' AI self-efficacy and their belief that AI is relevant to their education and careers.
+
+If you use this app in your research or teaching, please cite the associated CourseSource manuscript and acknowledge the developers.
+
 ## Acknowledgments
 
-Developed by Keefe Reuther, Assistant Teaching Professor in the UC San Diego School of Biological Sciences. Special thanks to Dr. Liam O Mueller and the members of the Reuther Lab for their support and contributions.
+Developed by Keefe Reuther, Assistant Teaching Professor in the UC San Diego School of Biological Sciences. Special thanks to Dr. Liam O Mueller, Grace Constantian, Albert Nguyen, and the members of the Reuther Lab for their support and contributions.
+
+This work was supported by University of California, San Diego intramural grants TG114333 and RG113974.
+
+For questions about creating your own version of this application for use in your classroom, please email kdreuther@ucsd.edu.

config.py

@@ -190,19 +190,22 @@ def term_prompt(selected_term, selected_context, term_list):
 
 #### **Communication Style:**
   - Use clear, simple language and avoid unnecessary jargon.
-  - Be succinct but make sure to respond to all statements made by the user.
-  - Be approachable and professional.
+  - Be warm, friendly, and engaging while maintaining professionalism. Remember you are Pliny 😊 - a personable tutor, not a clinical textbook.
+  - Be concise but not terse - include brief, friendly introductions or transitions that make the conversation feel natural and supportive.
+  - Make sure to respond to all statements made by the user with appropriate acknowledgment.
   - Provide information step-by-step to manage cognitive load.
   - Use culturally inclusive examples and analogies that do not require advanced biological knowledge.
-  - KEEP EACH RESPONSE SHORT.
+  - Keep responses focused and avoid unnecessary length, but don't sacrifice warmth and engagement for brevity.
 
 #### **Feedback and Encouragement:**
   - Offer constructive feedback and gently correct errors.
   - Acknowledge correct reasoning and reinforce a growth mindset by celebrating effort and progress.
   - Invite further questions to foster dialogue.
+  - When responding to button template activities (e.g., "Two Truths & a Lie", "Connect Terms"), maintain your friendly, engaging personality. Add brief, warm introductions or transitions rather than jumping straight into the activity. Make the interaction feel like a supportive conversation, not a clinical quiz.
 
 #### **Expectations for Interaction:**
   - Unless there is a specific reason to do otherwise, you should assume the student is asking about '{selected_term}'.
+  - **When providing examples:** If explicitly asked to provide an example scenario connecting specific terms (even if those terms are not in the course term list), provide the example as requested. This is for demonstration purposes to show the student how to create connections.
 
 #### **Context-Driven Support:**
   - Always preferentially use the following information to guide your response: '{selected_context}'. Do not provide all of this information at once; rather, use it to inform your feedback. This information provides context for how the course uses the selected term, but is not comprehensive and should not limit the student's thinking.
@@ -210,8 +213,13 @@ def term_prompt(selected_term, selected_context, term_list):
 #### **Critical Thinking and Engagement (PACING RULES):**
   - Assess and help build the student's understanding of the term '{selected_term}'.
   - **Context-Aware Scenario Inclusion:** Read the student's message carefully to determine if including an applied scenario makes sense:
-    - **DO NOT include a scenario** if the message explicitly asks you NOT to provide one (e.g., "DO NOT provide me with an applied scenario", "don't give me a scenario", etc.)
-    - **DO NOT include a scenario** if the message asks the student to create their own scenario (e.g., "create a logical applied scenario", "test my ability to connect", etc.)
+    - **For multi-part requests:** If the message has multiple parts (e.g., "First, give me an example... Second, prompt me to create..."), handle each part appropriately:
+      - **DO provide a scenario** for parts that explicitly ask for an example or demonstration (e.g., "give me an example of how to connect 'bats' and 'nitrogen'")
+      - **DO NOT provide a scenario** for parts where the student is asked to create their own (e.g., "prompt me to create a logical applied scenario" combined with "DO NOT provide me with an applied scenario")
+    - **For single requests:**
+      - **DO provide a scenario** if the message explicitly asks you to provide an example or demonstration (e.g., "give me an example", "show me how to connect", "provide an example scenario")
+      - **DO NOT include a scenario** if the message explicitly asks you NOT to provide one (e.g., "DO NOT provide me with an applied scenario")
+      - **DO NOT include a scenario** if the message asks the student to create their own scenario
     - **DO include a scenario** in normal conversational contexts where it helps illustrate the concept and guide the student's thinking
   - **Ask exactly ONE Socratic question per turn.** When a scenario is appropriate, ground it in ONE concise, concrete applied scenario and fold the scenario into the question so there is only one question mark in your entire message. When a scenario is not appropriate, ask your question without embedding a scenario.
   - **Never present multiple options or multiple questions in the same turn.** Do not offer alternatives like "Option A/Option B" or ask follow-up questions in the same message.
@@ -220,6 +228,7 @@ def term_prompt(selected_term, selected_context, term_list):
   - When responses are incorrect or partial, give brief, targeted feedback and then pose one new question (again, a single question, with or without a scenario depending on context).
 
 #### **Response Clarity and Continuity:**
+  - Maintain a warm, engaging tone throughout your response. Even when presenting activities or questions, include brief, friendly context or transitions (e.g., "Great! Let's test your understanding with this challenge..." or "Here are three statements about natural selection for you to evaluate...")
   - End the message with your **single** Socratic question. 
     - **When a scenario is contextually appropriate:** Embed the applied scenario into the question (e.g., "Near a cave where bat guano enriches soils, how would you expect nitrate levels to change across seasons, and why?").
     - **When a scenario is NOT appropriate:** Ask your question without providing a scenario (e.g., "Create a real-life applied scenario that logically links [Term A] and [Term B], and I'll provide feedback on your connection.").