updating readme

README.md

@@ -9,41 +9,62 @@ app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Boston Public Schools Enrollment Assistant Chatbot
 
-# DeepSeek Chatbot
+This is a Streamlit-based conversational chatbot designed to assist families in navigating the Boston Public Schools (BPS) enrollment process. It uses a local language model (Gemma-2B via llama-cpp) combined with Retrieval-Augmented Generation (RAG) and external APIs to answer questions about school eligibility, required documents, and nearby schools based on user-provided information.
 
-A simple chatbot built with Streamlit and DeepSeek R1 1.5B model using llama_cpp.
+## Features
 
-## Setup
+* **Conversational Interface:** Ask questions naturally about BPS enrollment.
+* **Context Tracking:** Remembers information provided during the conversation (residence, grade, etc.) using a JSON structure.
+* **Document Retrieval (RAG):** Uses information from local text files (in the `docs/` directory) containing BPS rules and regulations to answer questions accurately.
+* **Nearby School Lookup:** Uses the Geoapify API to find schools near a provided Boston residence address.
+* **Local LLM:** Runs inference locally using `llama-cpp-python` with a quantized Gemma-2B GGUF model, suitable for CPU execution on platforms like Hugging Face Spaces free tier.
 
-1. Clone this repository
-2. Install the required dependencies:
-   ```bash
-   pip install -r requirements.txt
-   ```
-3. Set up your Hugging Face token as an environment variable:
-   ```bash
-   export HF_TOKEN=your_token_here
-   ```
+## Technology Stack
 
-## Running the Chatbot
+* **Frontend:** Streamlit
+* **LLM Inference:** `llama-cpp-python`
+* **LLM Model:** `bartowski/gemma-2-2b-it-GGUF` (Q8_0 quantization)
+* **Embeddings:** `sentence-transformers` (`all-MiniLM-L6-v2`)
+* **Vector Store:** FAISS (CPU)
+* **Geocoding/Places API:** Geoapify
+* **Core Language:** Python 3
 
-To run the chatbot locally:
-```bash
-streamlit run app.py
-```
+## Setup and Installation (for Hugging Face Spaces)
 
-## Deployment to Hugging Face Spaces
+1.  **Repository Files:** Ensure the following files are present in your Hugging Face Space repository:
+    * `app.py`: The main Streamlit application script.
+    * `requirements.txt`: Lists all Python dependencies.
+    * `prompts.py`: Contains the prompt strings for the LLM.
+    * `docs/`: A directory containing `.txt` files with BPS enrollment information used for RAG. **You must create this directory and add the relevant text files.**
+    * `.streamlit/secrets.toml`: (Optional but recommended) For storing API keys.
 
-1. Create a new Space on Hugging Face
-2. Choose Streamlit as the SDK
-3. Upload these files to your Space
-4. Add your Hugging Face token as a secret in the Space settings
+2.  **Dependencies:** The `requirements.txt` file ensures all necessary packages are installed automatically by Hugging Face Spaces.
 
-## Features
+3.  **`docs/` Directory:** Create a directory named `docs` in the root of your repository. Place all the `.txt` files containing the Boston Public Schools information you want the chatbot to reference inside this directory. The RAG system relies on these files.
+
+4.  **API Keys:**
+    * **Geoapify:** You need a Geoapify API key for the geocoding and nearby school lookup features.
+    * Create a file named `secrets.toml` inside a directory named `.streamlit` in your repository (i.e., `.streamlit/secrets.toml`).
+    * Add your Geoapify key to this file:
+        ```toml
+        # .streamlit/secrets.toml
+        GEOAPIFY_KEY = "YOUR_ACTUAL_GEOAPIFY_API_KEY_HERE"
+
+        # Optional: Add Hugging Face Token if needed for model downloads
+        # HF_TOKEN = "YOUR_HUGGINGFACE_TOKEN_HERE"
+        ```
+    * **Note:** Protect your API keys. `secrets.toml` is generally included in `.gitignore` for local development but is read by Streamlit Cloud and Hugging Face Spaces when deployed.
+
+## Running the Application
+
+This application is designed to be deployed on Hugging Face Spaces. Once the files (`app.py`, `requirements.txt`, `prompts.py`, `docs/` directory, `.streamlit/secrets.toml`) are correctly set up in the repository, Hugging Face Spaces should automatically build and run the Streamlit application.
+
+## Usage
+
+Interact with the chatbot by typing your questions into the input box at the bottom of the application. Provide information like your address or your child's grade when asked, and the chatbot will use this context, along with retrieved documents and external lookups, to assist you.
+
+## Disclaimer
 
-- Interactive chat interface
-- Powered by DeepSeek R1 1.5B model
-- Efficient inference using llama_cpp
-- Persistent chat history during the session
+This chatbot aims to provide helpful information based on the documents provided in the `docs/` directory and external APIs. However, **Boston Public Schools enrollment rules and policies can change.** Always verify critical information directly with official BPS resources or a BPS Welcome Center before making decisions. The information provided by this chatbot is not guaranteed to be 100% accurate or up-to-date and should be used as a guide only.