Update README to match production version and add manuscript information

README.md

@@ -19,42 +19,38 @@ Schema Study is a modern, interactive study app designed to help biology student
 
 - **API Key Authentication:** Enter your OpenAI API key in the sidebar to enable chat functionality.
 - **Customizable Terms:** Use your own CSV file of terms and definitions.
-- **Prompt Templates:** Engage with the material using creative, research-based prompts.
-- **AI-Enhanced Feedback:** Get instant, formative feedback and guidance using GPT-5.1 (default) or GPT-4.1.
+- **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.
 
 ## How to Use (Students)
 
-1. **Access the App:** Go to your Hugging Face Space URL.
-2. **Enter API Key:** Provide your OpenAI API key in the sidebar configuration section.
-3. **Select a Term:** Use the dropdown to pick a course term.
-4. **Start Studying:** Respond to the prompt or use a template button to begin your session.
-5. **Chat with the AI:** Ask questions, answer prompts, and explore the term in depth.
+1. **Access the App:** Go to your Hugging Face Space URL. Enter your OpenAI API key in the sidebar configuration section.
+2. **Select a Term:** Use the dropdown to pick a course term.
+3. **Start Studying:** Respond to the prompt or use a template button to begin your session.
+4. **Chat with the AI:** Ask questions, answer prompts, and explore the term in depth.
 
 ## How to Use (Instructors)
 
 ### Setup
 
 1. **Clone or Fork the Space:**
-
    ```bash
    git clone https://huggingface.co/spaces/<your-username>/<your-space-name>
    cd <your-space-name>
    ```
 
 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.
 
 3. **Set Secrets (Optional):**
-
    - If you want to use Streamlit secrets instead of sidebar API key input, create `.streamlit/secrets.toml` file locally or use Hugging Face Space secrets:
      ```toml
      OPENAI_API_KEY = "your_openai_api_key"
@@ -62,7 +58,6 @@ Schema Study is a modern, interactive study app designed to help biology student
    - For Hugging Face Spaces, go to **Settings > Repository secrets** and add the API key.
 
 4. **Push Changes:**
-
    ```bash
    git add .
    git commit -m "Update configuration and terms"
@@ -71,55 +66,63 @@ 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
 
-All settings are in `config.py` (title, instructions, prompt templates, resources, AI model parameters, etc).
-
-Theming is managed via `.streamlit/config.toml` and custom CSS in `app.py`.
-
-Dependencies are listed in `requirements.txt`.
+- All settings are in `config.py` (title, instructions, prompt templates, resources, AI model parameters, etc).
+- Theming is managed via `.streamlit/config.toml` and custom CSS in `app.py`.
+- Dependencies are listed in `requirements.txt`.
 
 ## Technical Details
 
 ### API & Models
 
 - **API Framework:** OpenAI Responses API (streaming-enabled)
-- **Supported Models:** GPT-5.1 (default), GPT-4.1
-- **Streaming:** Real-time token-by-token response streaming with event-based handling
+- **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
-- **Error Handling:** Comprehensive error handling for streaming events and recovery
 
 ### File Structure
 
-`app.py` — Main Streamlit app with Responses API integration
+- `app.py` — Main Streamlit app with Responses API integration
+- `config.py` — All app settings and customization (model selection, web search, prompt templates, system prompt)
+- `.streamlit/secrets.toml` — Optional authentication credentials and API key (not tracked in git)
+- `requirements.txt` — Python dependencies
+- `terms.csv` — Your course terms and definitions (CSV format: term, context)
+- `example_syllabus.pdf` — Example resource file (replace with your own syllabus)
+- `LICENSE` — GNU GPL-3 License file
 
-`config.py` — All app settings and customization (model selection, web search, prompt templates)
+## License
 
-`.streamlit/secrets.toml` — Optional API key storage (not tracked in git)
+This project is licensed under the GNU GPL-3 License. See the [LICENSE](LICENSE) file for details.
 
-`requirements.txt` — Python dependencies
+## Research & Citation
 
-`terms.csv` — Your course terms and definitions (CSV format: term, context)
+This app, its corresponding manuscript, and all documentation was authored, edited, and tested by Keefe Reuther, [Liam O Mueller](https://biology.ucsd.edu/research/faculty/lomueller), Grace Constantian, Albert Nguyen, and the members of the Reuther Lab. 
 
-`BILD_5_Syllabus_Reuther_F25.pdf` — Example resource
+Schema Study was developed to address critical challenges in undergraduate biology education: providing immediate, personalized formative feedback to increasingly large, diverse classes. The app uses evidence-based teaching practices and Socratic questioning to deepen understanding, correct misconceptions, and encourage students to find connections among course concepts.
 
-## License
+If you use this app in your research or teaching, please cite the associated manuscript:
 
-This project is licensed under the GNU GPL-3 License. See the [LICENSE](LICENSE) file for details.
+**Reuther, K., Mueller, L. O., Constantian, G., & Nguyen, A. (2025). Schema Study: A Large Language Model (LLM) Application for Asynchronous Student Learning and Inquiry. *CourseSource Teaching Tools and Strategies*.**
+
+The production version of this app can be found at [https://huggingface.co/spaces/keefereuther/Schema_Study](https://huggingface.co/spaces/keefereuther/Schema_Study).
 
 ## 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.
+
+For questions about creating your own version of this application for use in your classroom, please email kdreuther@ucsd.edu.

config.py

@@ -183,6 +183,7 @@ resources = [
 # DO NOT REMOVE/EDIT anything inside the curly braces = '{selected_term}', '{selected_context}', '{term_list}'
 # These are placeholder variables that get filled in automatically by the app
 
+
 def term_prompt(selected_term, selected_context, term_list):
     return f"""You are Pliny 😊, a friendly and knowledgeable AI biology tutor for university students. Your mission is to help students build a robust understanding of these course-relevant biology terms and concepts: '{term_list}' This includes clarifying definitions, providing examples, addressing misconceptions, exploring applications, and encouraging connections between terms. You NEVER directly answer a question without first trying to get the student to answer it themselves EXCEPT if it a term related to the course syllabus, If it is related to the syllabus or course logistics, give a complete and accurate immediate answer.
 
@@ -190,19 +191,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 +214,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 +229,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.").
@@ -232,4 +242,5 @@ def term_prompt(selected_term, selected_context, term_list):
   - Do NOT answer multiple-choice, fill-in-the-blank, or true/false questions I give you to answer. These are not allowed. However you are encouraged to create your own multiple-choice, fill-in-the-blank, or true/false questions to challenge the student. When you do so, still obey the **one-question-per-turn** rule by presenting only one item.
 
 By following these instructions, you will provide clear and relevant guidance, helping students learn effectively while maintaining the course's academic integrity.
-"""
+"""
+