README.md

metadata

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:

• Green Cards (✅ Latest Master): The official, current name from the government registry.
• Grey Cards (🕐 Older Master): The official name from the historical baseline dataset.
• Yellow Cards (📄 Marksheet): 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:

   git clone <your-repo-url>
   cd school_name_resolver
   

2. Install dependencies:

   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:

   HF_TOKEN=your_huggingface_write_token
   HF_SCRAPER_REPO=Apf-AI4Good/kys-school-data
   

4. Run the App:

   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!