---
title: School Name Resolver
emoji: 🏫
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
---

# 🏫 School Name Resolver

The **School Name Resolver** is an internal tool built for the Scholarship Operations Team. It is designed to quickly cross-reference, verify, and resolve discrepancies between the school names written on student marksheets and the official government UDISE records.

By allowing the operations team to save custom "Marksheet Aliases," the system learns different variations of the same school name, completely eliminating the need to manually verify the same mismatched school names year after year!

---

## 🏗️ Architecture & Data Sources

The application is entirely stateless. It reads from and writes directly to a centralized, cloud-hosted dataset repository on HuggingFace: **`Apf-AI4Good/kys-school-data`**.

This central repository houses two critical types of data:

1. **Master Records (`.parquet` files)**:
   - **✅ Latest Master**: The most recently scraped government UDISE data, representing the absolute source of truth for the current year. (e.g., `scraped_data/mapped/mapped_master_2026_jul_01_10_19_pm.parquet`)
   - **📚 Old Master**: The historical baseline dataset used in previous scholarship cycles. It serves as a fallback to ensure continuity for students who applied in previous years. (`mapping_rules/baseline_master.parquet`)

2. **Alias Dictionary (`school_aliases.csv`)**:
   - A centralized CSV file that acts as the memory for the application. Whenever an operations team member encounters a marksheet name that doesn't perfectly match the official masters, they map it in the UI. The app immediately updates this CSV file (sorting it by UDISE code for perfect grouping) and pushes it back to HuggingFace.

---

## 🖥️ Using the App

The app is divided into two distinct steps for the user:

### Step 1 — Enter Location & Name
You can locate a school in two ways:
- **Location Search**: Use the cascading dropdowns to select the `State` ➔ `District` ➔ `Block` ➔ `Village`. The app will fuzzy-match the school name you enter against all schools in that specific village. (Note: The dropdowns strictly enforce hierarchy to prevent invalid selections).
- **UDISE Search**: If you already have the 11-digit UDISE code, you can select it directly from the dropdown to instantly pull up the school's records.

### Step 2 — Search Results & Mapping
The app will display all known names for the selected school(s) as distinct color-coded cards:
- <strong style="color: #16a34a;">Green Cards (✅ Latest Master)</strong>: The official, current name from the government registry.
- <strong style="color: #94a3b8;">Grey Cards (🕐 Older Master)</strong>: The official name from the historical baseline dataset.
- <strong style="color: #d97706;">Yellow Cards (📄 Marksheet)</strong>: Custom aliases that were previously saved by the operations team.

**Saving an Alias**:
If the student's marksheet says something different (e.g., "NC High School" instead of "Nandeswar Chakravarty High School"), simply type "NC High School" into the main **Search Box** at the top of the page, select the specific Month and Year the marksheet is from, and click **Save Alias**. The app will push this mapping to the cloud, and future searches for this school will instantly recognize "NC High School" as a valid alias!

**Deleting an Alias**:
If an incorrect alias was saved by mistake, every Yellow Marksheet card features a red **🗑️ Delete** button on the right. Clicking it will instantly purge that specific alias from the cloud dictionary.

---

## ⚙️ Setup & Deployment

### Local Development
To run this application on your local machine for development:

1. **Clone the repository**:
   ```bash
   git clone <your-repo-url>
   cd school_name_resolver
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure Environment Variables**:
   Create a `.env` file in the root directory (you can copy `.env.example`). You only need two variables:
   ```env
   HF_TOKEN=your_huggingface_write_token
   HF_SCRAPER_REPO=Apf-AI4Good/kys-school-data
   ```

4. **Run the App**:
   ```bash
   python app.py
   ```
   The app will start a local server, usually at `http://localhost:7862`.

### Production Deployment
This application is designed to be hosted directly as a **HuggingFace Space**.
- **Docker**: The repository includes a `Dockerfile` that HuggingFace automatically uses to build and launch the environment.
- **Secrets**: In your HuggingFace Space Settings, simply add your `HF_TOKEN` as a Secret, and `HF_SCRAPER_REPO` as a public Variable.
- **Updates**: Any code pushed to the `main` branch of this repository will trigger HuggingFace to automatically rebuild and redeploy the live application!