initial commit

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sarah Bentley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,13 +1,157 @@
 ---
-title: Bps Chatbot1
-emoji: 📊
-colorFrom: red
-colorTo: yellow
+title: 6.S041 Staff Chatbot
+emoji: 🚀
+colorFrom: blue
+colorTo: red
 sdk: gradio
-sdk_version: 5.25.1
+sdk_version: 5.23.3
+python_version: "3.10"
 app_file: app.py
 pinned: false
-short_description: bps chatbot finetuned on FAQs
+secrets:
+  - HF_TOKEN
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Boston Public School Selection Chatbot
+
+This is a skeleton repo you can use to design your school choice chatbot. Feel free to change it however you'd like! This repo is compatible with CPU (using your own computer) because it uses models on HuggingFace. You can also load models locally if you'd like, but we recommend using smaller ones.
+
+The end goal: make the chatbot and upload it to a Huggingface Space. We have included instructions for using HuggingFace below. [Here's an example](https://huggingface.co/spaces/sbentley/Boston-School-Choice) of a chatbot made by the course staff. Yours should be much better!
+
+Note: We encourage you to use AI tools (like Cursor or LLMs) to help you on this assignment. Learn how to leverage these tools.
+
+## Setup
+
+1. Make a virtual environment and install the required dependencies:
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+2. Make a HuggingFace account and make an access token:
+   - Visit [Hugging Face](https://huggingface.co)
+   - Make an account if you don't already have one
+   - Click on your profile, then "Access Tokens" and make a new token
+   - Make a .env file with `HF_TOKEN=<insert your token here>`
+   - Now, log in to Hugging Face in the terminal as well:
+   ```bash
+   huggingface-cli login
+   ```
+
+3. Choose a base model:
+   - In config.py, set the BASE_MODEL variable to your base model of choice from HuggingFace.
+   - Keep in mind it's better to have a small, lightweight model if you plan on finetuning.
+
+
+
+## Repository Organization
+
+```
+6.s041-chatbot/
+├── app.py              # Gradio web interface - implement the chat function
+├── requirements.txt    # Python dependencies
+├── chatbot_development.ipynb     # Notebook for developing and testing your chatbot
+├── .env     # Add this file yourself for storing your HF_TOKEN
+├── config.py     # Holds variables for the models from HuggingFace you will use
+├── chatbot_conversation_example.txt     # Example conversation we might want to have with this chatbot
+└── src/
+    └── chat.py        # SchoolChatbot class (implement this)
+```
+
+### Key Files:
+
+- **app.py**: Creates the web interface using Gradio. You only need to implement the `chat` function that generates responses.
+
+- **chat.py**: Contains the `SchoolChatbot` class where you'll implement:
+  - `format_prompt`: Format user input into proper prompts
+  - `get_response`: Generate responses using the model
+
+- **config.py**: Contains the `BASE_MODEL` and `MY_MODEL` variables, which are names of models on HuggingFace. Update the `MY_MODEL` variable if you create a new model and upload it to the HuggingFace Hub.
+
+- **chatbot_development.ipynb**: Jupyter notebook for:
+  - Experimenting with the chatbot
+  - Trying different approaches
+  - Testing responses before deployment
+
+### What You Need to Implement:
+
+1. In `chat.py`:
+   - Complete the `SchoolChatbot` class methods
+   - Design how the chatbot formats prompts
+   - Implement response generation
+
+2. In `app.py`:
+   - Implement the `chat` function to work with Gradio
+   - The rest of the file is already set up
+
+3. Use `chatbot_development.ipynb` to:
+   - Develop and test your implementation
+   - Try different approaches
+   - Verify everything works before deployment
+
+4. After you update the code, you can run the chatbot locally:
+```bash
+python app.py
+```
+
+
+## Deploying to Hugging Face
+
+To deploy your chatbot as a free web interface using Hugging Face Spaces:
+
+1. Create a Hugging Face Space:
+   - Go to [Hugging Face Spaces](https://huggingface.co/spaces)
+   - Click "New Space"
+   - Choose a name for your space (e.g., "boston-school-chatbot")
+   - Select "Gradio" as the SDK
+   - Choose "CPU" as the hardware (free tier)
+   - Make it "Public" so others can use your chatbot
+
+2. Prepare your files:
+   Your repository should already have all needed files:
+   ```
+   6.so41-midterm/
+   ├── README.md           # Description of your chatbot
+   ├── app.py             # Your Gradio interface
+   ├── requirements.txt   # Already set up with needed dependencies
+   └── src/              # Your implementation files
+   ```
+
+3. Push your code to the Space:
+   ```bash
+   git init
+   git add .
+   git commit -m "Initial commit"
+   git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+   git push -u origin main
+   ```
+
+4. Add your HF_TOKEN to the space as a secret.
+   - Go to Files.
+   - Go to Settings.
+   - Under secrets, add HF_TOKEN.
+   
+
+5. Important Free Tier Considerations:
+   - Use free tier model (already configured in model.py)
+   - Free CPU spaces have 2GB RAM limit
+   - The interface might queue requests when multiple users access it. Sometimes there will be 503 errors.
+
+6. After Deployment:
+   - Your chatbot will be available at: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
+   - Anyone can use it through their web browser
+   - You can update the deployment anytime by pushing changes:
+     ```bash
+     git add .
+     git commit -m "Update chatbot"
+     git push
+     ```
+
+7. Troubleshooting:
+   - Check the Space's logs if the chatbot isn't working
+   - Verify the chatbot works locally before deploying
+   - Remember free tier has limited resources. Sometimes if you get a 503 error it means the server is overloaded. Just try again a few seconds later.
+
+Your chatbot should now be accessible to anyone through their web browser!
+

app.py

@@ -0,0 +1,85 @@
+"""
+Gradio Web Interface for Boston School Chatbot
+
+This script creates a web interface for your chatbot using Gradio.
+You only need to implement the chat function.
+
+Key Features:
+- Creates a web UI for your chatbot
+- Handles conversation history
+- Provides example questions
+- Can be deployed to Hugging Face Spaces
+
+Example Usage:
+    # Run locally:
+    python app.py
+    
+    # Access in browser:
+    # http://localhost:7860
+"""
+
+import gradio as gr
+from src.chat import SchoolChatbot
+
+def create_chatbot():
+    """
+    Creates and configures the chatbot interface.
+    """
+    chatbot = SchoolChatbot()
+    
+    def chat(message, history):
+        """
+        TODO:Generate a response for the current message in a Gradio chat interface.
+        
+        This function is called by Gradio's ChatInterface every time a user sends a message.
+        You only need to generate and return the assistant's response - Gradio handles the
+        chat display and history management automatically.
+
+        Args:
+            message (str): The current message from the user
+            history (list): List of previous message pairs, where each pair is
+                           [user_message, assistant_message]
+                           Example:
+                           [
+                               ["What schools offer Spanish?", "The Hernandez School..."],
+                               ["Where is it located?", "The Hernandez School is in Roxbury..."]
+                           ]
+
+        Returns:
+            str: The assistant's response to the current message.
+
+
+        Note:
+            - Gradio automatically:
+                - Displays the user's message
+                - Displays your returned response
+                - Updates the chat history
+                - Maintains the chat interface
+            - You only need to:
+                - Generate an appropriate response to the current message
+                - Return that response as a string
+        """
+        # TODO: Generate and return response
+        try:
+            response = chatbot.get_response(message)
+            return response
+        except Exception as e:
+            return f"Sorry, something went wrong: {str(e)}"
+
+    
+    
+    # Create Gradio interface. Customize the interface however you'd like!
+    demo = gr.ChatInterface(
+        chat,
+        title="Boston Public School Selection Assistant",
+        description="Ask me anything about Boston public schools! Since I am a free tier chatbot, I may give a 503 error when I'm busy. If that happens, please try again a few seconds later.",
+        examples=[
+            "I live in Jamaica Plain and want to send my child to kindergarten. What schools are available?"
+        ]
+    )
+    
+    return demo
+
+if __name__ == "__main__":
+    demo = create_chatbot()
+    demo.launch()

chatbot_conversation_example.txt

@@ -0,0 +1,71 @@
+User: Hi, I'm looking for a public school in Boston for my child who will be starting kindergarten next year.
+
+Bot: Hello! I'd be happy to help you find the right public school in Boston. To better assist you, could you tell me:
+1. Which neighborhood do you live in?
+2. Do you have any specific preferences (like language programs, special education services, or after-school programs)?
+3. Would you prefer a traditional public school or a charter school?
+
+User: We live in Jamaica Plain, and I'm interested in schools with strong language programs. My child is already showing interest in learning Spanish.
+
+Bot: Great! I can help you with that. There are several excellent options in Jamaica Plain and nearby areas. Let me suggest a few schools that might be a good fit:
+
+1. The Hernandez K-8 School in Roxbury (about 1.5 miles from JP) offers a Spanish-English dual language program starting from kindergarten. They have a strong academic reputation and diverse student body.
+
+2. The Mozart Elementary School in JP has a Spanish language immersion program and is known for its strong arts integration.
+
+3. The Mission Hill K-8 School in Roxbury offers Spanish language classes and has a progressive education model.
+
+Would you like to know more about any of these schools? I can provide details about:
+- Class sizes
+- Test scores
+- Special programs
+- Parent reviews
+- Transportation options
+
+User: Could you tell me more about the Hernandez School? I've heard good things about it.
+
+Bot: Certainly! The Hernandez K-8 School has several notable features:
+
+- Their dual language program is one of the strongest in the district, with 50% of instruction in Spanish and 50% in English
+- Average class size is 22 students
+- They offer free breakfast and lunch programs
+- The school has a strong parent-teacher organization
+- They provide after-school programs until 6 PM
+- The school is accessible by public transportation (Orange Line and several bus routes)
+
+Would you like to know about:
+1. Their enrollment process?
+2. How to schedule a school tour?
+3. Their academic performance metrics?
+4. Specific programs for kindergarten students?
+
+User: Yes, how do I schedule a tour?
+
+Bot: You can schedule a tour of the Hernandez School in two ways:
+
+1. Call the main office at (617) 635-XXXX during school hours (8:00 AM - 4:00 PM)
+2. Visit the Boston Public Schools website and use their online tour scheduling system
+
+Tours are typically offered on Tuesday and Thursday mornings at 9:00 AM. They last about 45 minutes and include:
+- A classroom visit
+- Meeting with the principal
+- Q&A session
+- Overview of the dual language program
+
+Would you like me to provide the exact contact information for scheduling a tour?
+
+User: Yes, please.
+
+Bot: Here's the contact information for the Hernandez School:
+
+Main Office: (617) 635-XXXX
+Email: [email protected]
+Address: 61 School Street, Roxbury, MA 02119
+
+The school's website is: www.bostonpublicschools.org/hernandez
+
+Is there anything else you'd like to know about the school or other options in the area?
+
+User: No, that's very helpful! Thank you.
+
+Bot: You're welcome! Good luck with your school search. If you have any more questions about Boston public schools or need help with the enrollment process, feel free to ask. Have a great day! 

chatbot_development.ipynb

@@ -0,0 +1,161 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Chatbot Development\n",
+    "\n",
+    "Use this notebook to load the model and then initialize, update, and test the chatbot."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Setup and Imports"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import torch\n",
+    "from huggingface_hub import login\n",
+    "\n",
+    "\n",
+    "from src.chat import SchoolChatbot\n",
+    "from config import BASE_MODEL, MY_MODEL"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "50617a1a9bdc434d9b897a5e9b529b52",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "VBox(children=(HTML(value='<center> <img\\nsrc=https://huggingface.co/front/assets/huggingface_logo-noborder.sv…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "\"\"\"\n",
+    "TODO: Add your Hugging Face token\n",
+    "Options:\n",
+    "1. Use login() and enter token when prompted. It won't ask for your token if you already logged in using the command: huggingface-cli login in the terminal.\n",
+    "2. Set environment variable HUGGINGFACE_TOKEN\n",
+    "3. Pass token directly (not recommended for shared notebooks)\n",
+    "\"\"\"\n",
+    "\n",
+    "login()\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Initialize and test chatbot"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "\"\"\"\n",
+    "Create chatbot instance using chat.py\n",
+    "\"\"\"\n",
+    "chatbot = SchoolChatbot()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "Question: I live in Jamaica Plain and want to send my child to a school that offers Spanish classes. What schools are available?\n",
+      "Response: There are several Boston Public Schools in and around Jamaica Plain that offer Spanish language instruction. Here are some options:\n",
+      "\n",
+      "1. Joseph P. Kelly Elementary School: This school offers Spanish bilingual education for students in grades Pre-K through 5. It is located at 1200 Columbus Ave, Boston, MA 02130.\n",
+      "\n",
+      "2. Edwin M. Bacon Elementary School: This school offers Spanish language instruction in grades Pre-K through 6. It is located at 30 Fayette St, Boston, MA 02130.\n",
+      "\n",
+      "3. Samuel J. & Dorothy Donnelly Elementary School: This school offers a Spanish Dual Language Learning Program in grades Pre-K through 5. It is located at 524 Cummins Highway, Roxbury, MA 02119.\n",
+      "\n",
+      "4. James Otis Elementary School: This school offers a Spanish Bilingual Program in grades Pre-K through 6. It is located at 1234 Columbus Ave, Boston, MA 02120.\n",
+      "\n",
+      "5. The John D. O'Bryant School of Mathematics and Science: This middle school (grades 6-8) offers Spanish language instruction as part of its academic program. It is located at 1345 Tremont St, Roxbury, MA 02120.\n",
+      "\n",
+      "It's recommended that you contact these schools directly to learn more about their programs and enrollment processes. Good luck!\n"
+     ]
+    }
+   ],
+   "source": [
+    "\"\"\"\n",
+    "Test out generating some responses from the chatbot.\n",
+    "Inference time\n",
+    "\"\"\"\n",
+    "test_question = \"I live in Jamaica Plain and want to send my child to a school that offers Spanish classes. What schools are available?\"\n",
+    "\n",
+    "print(f\"\\nQuestion: {test_question}\")\n",
+    "response = chatbot.get_response(test_question)\n",
+    "print(f\"Response: {response}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# TODO: Update pre-trained Llama to be a school choice chatbot\n",
+    "\n",
+    "This part is up to you! You might want to finetune the model, simply make a really good system prompt, use RAG, provide the model boston school choice data in-context, etc. Be creative!\n",
+    "\n",
+    "You can also feel free to do this in another script and then evaluate the model here.\n",
+    "\n",
+    "Tips:\n",
+    "- HuggingFace has built-in methods to finetune models, if you choose that route. Take advantage of those methods! You can then save your new, finetuned model in the HuggingFace Hub. Change MY_MODEL in config.py to the name of the model in the hub to make your chatbot use it.\n",
+    "- You may also want to consider LoRA if you choose finetuning."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

config.py

@@ -0,0 +1,16 @@
+import os
+from dotenv import load_dotenv
+
+# Load from .env file. Store your HF token in the .env file.
+load_dotenv()
+
+BASE_MODEL = "HuggingFaceH4/zephyr-7b-beta"
+# BASE_MODEL = "TinyLlama/TinyLlama-1.1B-Chat-v1.0"
+# Other options:
+# MODEL = "meta-llama/Llama-2-7b-chat-hf"
+# MODEL = "openlm-research/open_llama_3b"
+
+# If you finetune the model or change it in any way, save it to huggingface hub, then set MY_MODEL to your model ID. The model ID is in the format "your-username/your-model-name".
+MY_MODEL = None
+
+HF_TOKEN = os.getenv("HF_TOKEN")

requirements.txt

@@ -0,0 +1,10 @@
+torch>=2.1.0
+transformers>=4.34.0
+datasets>=2.14.0
+accelerate>=0.24.0
+sentencepiece>=0.1.99
+gradio>=3.50.0
+huggingface-hub>=0.19.0
+numpy<2.0.0
+ipywidgets>=8.0.0
+python-dotenv>=1.1.0

src/chat.py

@@ -0,0 +1,73 @@
+from huggingface_hub import InferenceClient
+from config import BASE_MODEL, MY_MODEL, HF_TOKEN
+
+class SchoolChatbot:
+    """
+    This class is extra scaffolding around a model. Modify this class to specify how the model recieves prompts and generates responses.
+
+    Example usage:
+        chatbot = SchoolChatbot()
+        response = chatbot.get_response("What schools offer Spanish programs?")
+    """
+
+    def __init__(self):
+        """
+        Initialize the chatbot with a HF model ID
+        """
+        model_id = MY_MODEL if MY_MODEL else BASE_MODEL # define MY_MODEL in config.py if you create a new model in the HuggingFace Hub
+        self.client = InferenceClient(model=model_id, token=HF_TOKEN)
+        
+    def format_prompt(self, user_input):
+        """
+        TODO: Implement this method to format the user's input into a proper prompt.
+        
+        This method should:
+        1. Add any necessary system context or instructions
+        2. Format the user's input appropriately
+        3. Add any special tokens or formatting the model expects
+
+        Args:
+            user_input (str): The user's question about Boston schools
+
+        Returns:
+            str: A formatted prompt ready for the model
+        
+        Example prompt format:
+            "You are a helpful assistant that specializes in Boston schools...
+             User: {user_input}
+             Assistant:"
+        """
+        return (
+            "<|system|>You are a helpful assistant that specializes in Boston public school enrollment.<|end|>\n"
+            f"<|user|>{user_input}<|end|>\n"
+            "<|assistant|>"
+        )
+        
+    def get_response(self, user_input):
+        """
+        TODO: Implement this method to generate responses to user questions.
+        
+        This method should:
+        1. Use format_prompt() to prepare the input
+        2. Generate a response using the model
+        3. Clean up and return the response
+
+        Args:
+            user_input (str): The user's question about Boston schools
+
+        Returns:
+            str: The chatbot's response
+
+        Implementation tips:
+        - Use self.format_prompt() to format the user's input
+        - Use self.client to generate responses
+        """
+        prompt = self.format_prompt(user_input)
+        response = self.client.text_generation(
+            prompt,
+            max_new_tokens=512,
+            temperature=0.7,
+            top_p=0.9,
+            stop_sequences=["<|end|>"]
+        )
+        return response.strip()