Initial Commit

.dockerignore

@@ -0,0 +1,29 @@
+# Environment variables
+.env
+
+# Virtual environment (Docker will install its own packages)
+venv/
+env/
+.venv/
+
+# Python cache (prevent copying compiled files into the container)
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Data files (App downloads these from HF Dataset at runtime, don't build them into the image)
+*.csv
+*.xlsx
+*.parquet
+
+# Git files
+.git/
+.gitignore
+.dockerignore
+
+# IDE and OS files
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

.env.example

@@ -0,0 +1,3 @@
+HF_TOKEN=hf_your_token_here
+HF_SCRAPER_REPO=Apf-AI4Good/kys-school-data
+HF_RESOLVER_REPO=Apf-AI4Good/school-name-resolver-data

.gitignore

@@ -0,0 +1,24 @@
+# Environment variables (Never push secrets!)
+.env
+
+# Virtual environment
+venv/
+env/
+.venv/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Data files (These belong in the HF Dataset, NOT the HF Space code)
+*.csv
+*.xlsx
+*.parquet
+
+# IDE and OS files
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application
+COPY . .
+
+# HuggingFace Spaces exposes port 7860
+EXPOSE 7860
+
+ENV PORT=7860
+
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,140 @@
+---
+title: School Name Resolver
+emoji: 🏫
+colorFrom: indigo
+colorTo: purple
+sdk: docker
+pinned: false
+---
+
+# 🏫 School Name Resolver
+
+A comprehensive, Gradio-based web application built for the **Scholarship Operations Team** to efficiently resolve discrepancies in school names when validating applicant marksheets. 
+
+---
+
+## 📖 The Problem Context
+
+In the Indian education system, a school's **11-digit UDISE Code** acts as a permanent, immutable identifier. However, the **name of the school** can (and often does) change over time due to upgrades (e.g., from a Junior College to a Senior Secondary School), government renamings, or simply varying data entry practices.
+
+When an Operations Team member reviews a student's printed marksheet, they might see a name like `"N. C. HIGH SCHOOL"`. When they look up that student's UDISE code in the internal Scholarship System (the "Old Master"), it might show the older or newer name `"NANDESWAR CHAKRAVARTY HIGH SCHOOL"`. This discrepancy causes confusion and delays in verification.
+
+## 💡 The Solution
+
+The **School Name Resolver** bridges this gap by acting as a unified search engine and mapping utility. It allows the Ops Team to:
+1. **Search** a UDISE code and instantly pull every known name for that school across historical datasets.
+2. **Compare** the name written on the physical marksheet against historical names.
+3. **Map** all these names together into a persistent, cloud-hosted **Alias Dictionary**.
+
+---
+
+## 🏗️ Architecture & Data Flow
+
+This application is built with a serverless data architecture using **HuggingFace Datasets** as the primary storage layer. It does not require a traditional SQL database.
+
+### 1. Data Sources Searched
+When a UDISE code is searched, the application concurrently queries:
+- **📄 The Marksheet Name**: Entered manually by the Ops user.
+- **📚 Old Master (`master_all_states.csv`)**: The current database used by the Scholarship Application system. This file contains over 200,000 baseline school records.
+- **✅ Latest Scraped Master**: The most recent Parquet file generated by the upstream KYS (Know Your School) Scraper app.
+- **🕐 Older Scraped Masters**: Historical Parquet snapshots to catch historical name changes.
+
+### 2. The Alias Dictionary (`school_aliases.json`)
+When the user clicks "Map All Names Together", the application collects all unique names found during the search and upserts them into a persistent dictionary.
+- **Storage Strategy**: The dictionary is stored as a standard JSON file (`school_aliases.json`) directly on a private HuggingFace dataset.
+- **Schema**: It uses a clean JSON dictionary format where keys are UDISE codes.
+  ```json
+  {
+    "18050406004": {
+      "names": ["SARUPETA GIRLS HE SCHOOL", "VIDYAMANDIR HIGH SCHOOL,SARUPETA"],
+      "last_updated": "2026-07-07"
+    }
+  }
+  ```
+- **Deduplication**: Mapping is strictly case-insensitive. If an Ops user attempts to map a name that already exists in the `names` array, the application will silently skip the duplicate to maintain a clean dataset.
+
+### 3. In-Memory Caching (`hf_reader.py`)
+To ensure high performance without straining HuggingFace bandwidth, the application uses module-level caching:
+- The 45MB `master_all_states.csv` and all mapped `.parquet` files are downloaded and loaded into Pandas DataFrames on the *first* search request.
+- Subsequent searches pull directly from RAM, making them virtually instantaneous.
+- A "Refresh Data Cache" button in the UI allows users to force-reload the cache if the upstream KYS scraper pushes new master files.
+
+---
+
+## 🚀 Setup & Deployment Guide
+
+This app is designed to be hosted on **HuggingFace Spaces** using Docker.
+
+### Step 1: Create the Resolver Dataset
+The app requires its own dedicated dataset repository to store the baseline and alias dictionary.
+1. Go to HuggingFace and create a new **Private Dataset** (e.g., `Apf-AI4Good/school-name-resolver-data`).
+2. Upload your existing `master_all_states.csv` (the Old Master) to the root of this dataset.
+*(Note: You do not need to create `school_aliases.json`. The app will automatically create it the first time an ops user maps a school.)*
+
+### Step 2: Configure Space Secrets & Variables
+When creating the HuggingFace Space for this application, configure the following in the **Settings → Variables and Secrets** tab:
+
+**🔒 Secrets:**
+| Name | Description |
+|---|---|
+| `HF_TOKEN` | A HuggingFace Access Token with **Write** permissions. Used to read the baselines and write the alias JSON. |
+
+**⚙️ Variables:**
+| Name | Description |
+|---|---|
+| `HF_SCRAPER_REPO` | The Repository ID of your upstream KYS Scraper dataset (e.g., `Apf-AI4Good/kys-school-data`). |
+| `HF_RESOLVER_REPO` | The Repository ID of the new dataset created in Step 1 (e.g., `Apf-AI4Good/school-name-resolver-data`). |
+
+### Step 3: Deploy
+Push all files in this directory (including the provided `Dockerfile` and `requirements.txt`) to the HuggingFace Space. The Docker environment will automatically build and launch the Gradio server on port `7860`.
+
+---
+
+## 💻 Local Development
+
+If you need to test the application locally on a Windows machine:
+
+```powershell
+# 1. Create and activate a virtual environment
+python -m venv venv
+.\venv\Scripts\activate
+
+# 2. Install lightweight dependencies
+pip install -r requirements.txt
+
+# 3. Configure environment variables
+# Copy the example env file and fill in your HuggingFace details
+copy .env.example .env
+
+# 4. Run the application
+python app.py
+```
+*Note: The local app is configured with `inbrowser=True`, meaning it will automatically open a new tab in your default web browser (usually at `http://127.0.0.1:7862`) once the server starts.*
+
+---
+
+## 🎨 UI Layout & User Flow
+
+The User Interface was completely custom-designed using Gradio Blocks with injected CSS for a modern, premium experience.
+
+1. **Step 1 — Enter Details**: A clean input form requiring only the UDISE code and an optional physical marksheet name.
+2. **Step 2 — Review Names**: Results are rendered as visual, color-coded HTML cards rather than a raw data table.
+   - 🟡 **Amber**: Marksheet Name
+   - 🔵 **Blue**: Old Master Name
+   - 🟢 **Green**: Latest Scraped Master
+   - ⚫ **Grey**: Older Scraped Masters
+3. **Step 3 — Save Aliases**: A one-click mapping button that executes the upsert logic and commits to HuggingFace.
+4. **Alias Dictionary View**: A live, searchable HTML render of the `school_aliases.json` file, visually grouping all known aliases into interactive accordion dropdowns under distinct UDISE code blocks for easy reading.
+
+---
+
+## 🛠️ File Structure
+
+| File | Purpose |
+|---|---|
+| `app.py` | The main Gradio interface, routing, custom CSS, and HTML component builders. |
+| `hf_reader.py` | The data layer responsible for fetching, caching, and searching CSV/Parquet files from HuggingFace. |
+| `alias_store.py` | The CRUD operations and deduplication logic for managing the `school_aliases.json` dictionary. |
+| `requirements.txt` | Python dependencies (`gradio`, `huggingface-hub`, `pandas`, `pyarrow`, `python-dotenv`). |
+| `Dockerfile` | Python 3.11-slim container configuration for HF Spaces deployment. |
+| `.env.example` | Template for local environment variable setup. |

alias_store.py

@@ -0,0 +1,120 @@
+"""
+alias_store.py — Manages the school_aliases.json file stored on HuggingFace.
+
+Schema:
+{
+  "18050406004": {
+    "names": ["SARUPETA GIRLS HE SCHOOL", "VIDYAMANDIR HIGH SCHOOL,SARUPETA"],
+    "last_updated": "2026-07-07"
+  },
+  "18150113702": {
+    "names": ["N. C. HIGH SCHOOL", "NANDESWAR CHAKRAVARTY HIGH SCHOOL"],
+    "last_updated": "2026-07-07"
+  }
+}
+"""
+
+import os
+import json
+import tempfile
+from datetime import datetime, timezone
+from huggingface_hub import HfApi, hf_hub_download
+
+HF_TOKEN = os.getenv("HF_TOKEN", "")
+HF_RESOLVER_REPO = os.getenv("HF_RESOLVER_REPO", "")
+ALIAS_FILE = "school_aliases.json"
+
+
+def load_aliases() -> dict:
+    """
+    Download and return the alias dictionary from HF as a Python dict.
+    Returns an empty dict {} if the file doesn't exist yet.
+    """
+    if not HF_RESOLVER_REPO:
+        return {}
+    try:
+        path = hf_hub_download(
+            repo_id=HF_RESOLVER_REPO,
+            filename=ALIAS_FILE,
+            repo_type="dataset",
+            token=HF_TOKEN or None,
+            force_download=True,
+        )
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        if "404" in str(e) or "not found" in str(e).lower() or "Entry Not Found" in str(e):
+            return {}
+        print(f"[alias_store] Error loading aliases: {e}")
+        return {}
+
+
+def save_aliases(new_entries: list[dict]) -> str:
+    """
+    Upsert new alias entries into the cloud JSON.
+
+    Each entry should have: udise_code, alias_name, source_label
+    """
+    if not HF_RESOLVER_REPO:
+        return "⚠️ HF_RESOLVER_REPO is not configured — cannot save aliases."
+    if not new_entries:
+        return "⚠️ No entries provided."
+
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    data = load_aliases()
+
+    added_count = 0
+    skipped_count = 0
+
+    for entry in new_entries:
+        code = str(entry.get("udise_code", "")).strip()
+        name = str(entry.get("alias_name", "")).strip()
+        if not code or not name:
+            continue
+
+        if code not in data:
+            data[code] = {"names": [], "last_updated": today}
+
+        existing_upper = {n.upper() for n in data[code]["names"]}
+        
+        if name.upper() in existing_upper:
+            skipped_count += 1
+            continue
+
+        data[code]["names"].append(name)
+        data[code]["last_updated"] = today
+        added_count += 1
+
+    if added_count == 0:
+        return f"ℹ️ All {skipped_count} name(s) already in dictionary — nothing new to save."
+
+    # Upload to HF
+    try:
+        api = HfApi()
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False, encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+            tmp_path = f.name
+
+        udise_sample = new_entries[0].get("udise_code", "unknown")
+        api.upload_file(
+            path_or_fileobj=tmp_path,
+            path_in_repo=ALIAS_FILE,
+            repo_id=HF_RESOLVER_REPO,
+            repo_type="dataset",
+            token=HF_TOKEN or None,
+            commit_message=f"Add aliases for UDISE {udise_sample} ({added_count} new name(s))",
+        )
+
+        msg = f"✅ Saved! {added_count} new name(s) added."
+        if skipped_count:
+            msg += f" ({skipped_count} duplicate(s) skipped.)"
+        return msg
+
+    except Exception as e:
+        return f"❌ Failed to save aliases: {e}"
+
+
+def get_names_for_udise(udise_code: str) -> list[str]:
+    """Return all known names for a specific UDISE code as a list."""
+    data = load_aliases()
+    return data.get(str(udise_code).strip(), {}).get("names", [])

app.py

@@ -0,0 +1,560 @@
+"""
+app.py — Main Gradio application for the School Name Resolver.
+
+Run locally:  python app.py
+HF Spaces:    launched automatically by Dockerfile
+"""
+
+import os
+import gradio as gr
+import pandas as pd
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from hf_reader import search_udise, refresh_all_caches, get_config_status
+from alias_store import load_aliases, save_aliases
+
+# ─── CSS ──────────────────────────────────────────────────────────────────────
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap');
+
+*, *::before, *::after { box-sizing: border-box; margin: 0; }
+
+body, .gradio-container {
+    background: #f0f4ff !important;
+    font-family: 'Inter', 'Segoe UI', sans-serif !important;
+    color: #1e293b !important;
+}
+
+/* ── Header ── */
+.app-header {
+    background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%);
+    border-radius: 18px;
+    padding: 28px 36px;
+    margin-bottom: 20px;
+    text-align: center;
+    box-shadow: 0 8px 32px rgba(79,70,229,0.25);
+}
+.app-header h1 {
+    font-size: 1.9rem;
+    font-weight: 800;
+    color: #ffffff;
+    letter-spacing: -0.5px;
+    margin-bottom: 6px;
+}
+.app-header p {
+    color: rgba(255,255,255,0.75);
+    font-size: 0.95rem;
+}
+
+/* ── Step cards ── */
+.step-box {
+    background: #ffffff;
+    border-radius: 14px;
+    padding: 22px 24px;
+    box-shadow: 0 2px 12px rgba(0,0,0,0.07);
+    margin-bottom: 16px;
+}
+.step-label {
+    display: inline-block;
+    background: #ede9fe;
+    color: #6d28d9;
+    font-size: 0.72rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    padding: 3px 10px;
+    border-radius: 20px;
+    margin-bottom: 10px;
+}
+
+/* ── Inputs ── */
+label span {
+    color: #475569 !important;
+    font-size: 0.82rem !important;
+    font-weight: 600 !important;
+    text-transform: uppercase !important;
+    letter-spacing: 0.5px !important;
+}
+input[type=text], textarea {
+    background: #f8fafc !important;
+    border: 1.5px solid #e2e8f0 !important;
+    border-radius: 10px !important;
+    color: #1e293b !important;
+    font-size: 0.97rem !important;
+    font-family: 'Inter', sans-serif !important;
+    transition: border-color 0.2s, box-shadow 0.2s !important;
+}
+input[type=text]:focus, textarea:focus {
+    border-color: #6d28d9 !important;
+    box-shadow: 0 0 0 3px rgba(109,40,217,0.1) !important;
+    outline: none !important;
+}
+
+/* ── Buttons ── */
+.btn-search button {
+    background: linear-gradient(135deg, #4f46e5, #7c3aed) !important;
+    color: white !important;
+    font-weight: 700 !important;
+    font-size: 1rem !important;
+    border-radius: 12px !important;
+    border: none !important;
+    box-shadow: 0 4px 16px rgba(79,70,229,0.35) !important;
+    transition: all 0.2s !important;
+    padding: 12px !important;
+}
+.btn-search button:hover {
+    transform: translateY(-1px) !important;
+    box-shadow: 0 6px 22px rgba(79,70,229,0.45) !important;
+}
+
+.btn-map button {
+    background: linear-gradient(135deg, #059669, #0891b2) !important;
+    color: white !important;
+    font-weight: 700 !important;
+    font-size: 1rem !important;
+    border-radius: 12px !important;
+    border: none !important;
+    box-shadow: 0 4px 16px rgba(5,150,105,0.3) !important;
+    transition: all 0.2s !important;
+    padding: 12px !important;
+}
+.btn-map button:hover {
+    transform: translateY(-1px) !important;
+    box-shadow: 0 6px 22px rgba(5,150,105,0.4) !important;
+}
+
+.btn-secondary button {
+    background: #f1f5f9 !important;
+    color: #64748b !important;
+    font-weight: 600 !important;
+    border-radius: 10px !important;
+    border: 1.5px solid #e2e8f0 !important;
+    transition: all 0.15s !important;
+}
+.btn-secondary button:hover {
+    background: #e2e8f0 !important;
+    color: #334155 !important;
+}
+
+/* ── Result cards ── */
+.result-panel {
+    background: #ffffff;
+    border-radius: 14px;
+    padding: 20px 22px;
+    box-shadow: 0 2px 12px rgba(0,0,0,0.07);
+}
+.result-heading {
+    font-size: 0.75rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.8px;
+    color: #94a3b8;
+    padding-bottom: 12px;
+    border-bottom: 1.5px solid #f1f5f9;
+    margin-bottom: 14px;
+}
+.name-card {
+    padding: 14px 16px;
+    border-radius: 11px;
+    margin-bottom: 10px;
+    border-left: 4px solid;
+}
+.card-marksheet   { background: #fffbeb; border-color: #f59e0b; }
+.card-legacy      { background: #eff6ff; border-color: #3b82f6; }
+.card-latest      { background: #f0fdf4; border-color: #22c55e; }
+.card-old         { background: #f8fafc; border-color: #cbd5e1; }
+
+.card-tag {
+    font-size: 0.68rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.6px;
+    margin-bottom: 4px;
+}
+.card-marksheet .card-tag { color: #d97706; }
+.card-legacy    .card-tag { color: #2563eb; }
+.card-latest    .card-tag { color: #16a34a; }
+.card-old       .card-tag { color: #94a3b8; }
+
+.card-name {
+    font-size: 1.05rem;
+    font-weight: 700;
+    color: #1e293b;
+    line-height: 1.35;
+}
+.card-location {
+    font-size: 0.78rem;
+    color: #94a3b8;
+    margin-top: 3px;
+}
+.match-badge {
+    display: inline-block;
+    background: #dcfce7;
+    color: #16a34a;
+    font-size: 0.65rem;
+    font-weight: 700;
+    padding: 2px 7px;
+    border-radius: 8px;
+    margin-left: 8px;
+    vertical-align: middle;
+    text-transform: uppercase;
+}
+
+/* ── Status text ── */
+.map-status textarea, .map-status input {
+    background: #f0fdf4 !important;
+    border-color: #bbf7d0 !important;
+    color: #15803d !important;
+    font-weight: 600 !important;
+    border-radius: 10px !important;
+}
+
+/* ── Alias table ── */
+.alias-section {
+    background: #ffffff;
+    border-radius: 14px;
+    padding: 22px 24px;
+    box-shadow: 0 2px 12px rgba(0,0,0,0.07);
+    margin-top: 6px;
+}
+.section-heading {
+    font-size: 1rem;
+    font-weight: 700;
+    color: #1e293b;
+    margin-bottom: 14px;
+}
+.section-sub {
+    font-size: 0.8rem;
+    color: #94a3b8;
+    margin-bottom: 14px;
+    font-weight: 400;
+}
+
+/* ── Empty / no result ── */
+.empty-msg {
+    text-align: center;
+    padding: 40px 0;
+    color: #cbd5e1;
+    font-size: 0.95rem;
+}
+
+/* ── Accordion ── */
+details { border-radius: 12px !important; }
+details summary {
+    color: #64748b !important;
+    font-weight: 600 !important;
+    font-size: 0.88rem !important;
+    padding: 10px 14px !important;
+    background: #f8fafc !important;
+    border-radius: 10px !important;
+}
+"""
+
+# ─── HTML builders ────────────────────────────────────────────────────────────
+
+def build_results_html(results: list[dict], udise_code: str) -> str:
+    if not results:
+        return ""
+
+    ms_name = next((r["name"] for r in results if r["source_type"] == "marksheet"), "")
+
+    cards = []
+    for r in results:
+        st   = r.get("source_type", "")
+        name = r.get("name", "").strip()
+        src  = r.get("source", "")
+        loc  = " › ".join(p for p in [r.get("state",""), r.get("district",""), r.get("block","")] if p and p not in ("nan","none",""))
+
+        css  = {"marksheet": "card-marksheet", "legacy_db": "card-legacy",
+                "latest_master": "card-latest", "old_master": "card-old"}.get(st, "card-old")
+        icon = {"marksheet": "📄 Marksheet", "legacy_db": "📚 Old Master",
+                "latest_master": "✅ Latest Master", "old_master": "🕐 Older Master"}.get(st, src)
+
+        badge = ""
+        if ms_name and st != "marksheet" and name.upper() == ms_name.upper():
+            badge = '<span class="match-badge">✓ Same Name</span>'
+
+        display = name if name and name.lower() not in ("nan","none","") else "<em style='color:#cbd5e1'>Not found</em>"
+        loc_html = f'<div class="card-location">📍 {loc}</div>' if loc else ""
+
+        cards.append(f"""
+        <div class="name-card {css}">
+            <div class="card-tag">{icon}</div>
+            <div class="card-name">{display}{badge}</div>
+            {loc_html}
+        </div>""")
+
+    unique = len(set(r["name"].strip().upper() for r in results if r.get("name") and r["name"].lower() not in ("nan","none","")))
+    diff_note = f"<strong style='color:#e11d48'>{unique} different names found</strong>" if unique > 1 else "<strong style='color:#16a34a'>All sources agree on the name ✓</strong>"
+
+    return f"""
+    <div class="result-panel">
+        <div class="result-heading">
+            UDISE: {udise_code} &nbsp;·&nbsp; {len(results)} source(s) checked &nbsp;·&nbsp; {diff_note}
+        </div>
+        {"".join(cards)}
+    </div>"""
+
+
+def build_empty_html():
+    return """<div class="result-panel">
+        <div class="empty-msg">
+            🔍 Enter a UDISE code above and click <strong>Search</strong><br>
+            <span style="font-size:0.82rem;color:#e2e8f0">All known names for that school will appear here</span>
+        </div>
+    </div>"""
+
+
+# ─── Event handlers ───────────────────────────────────────────────────────────
+
+def on_search(udise_code: str, marksheet_name: str):
+    udise_code = str(udise_code).strip()
+    if not udise_code:
+        return gr.update(value=build_empty_html()), gr.update(visible=False), gr.update(visible=False, value=""), []
+
+    results = search_udise(udise_code, marksheet_name.strip() if marksheet_name else "")
+
+    if not results:
+        html = f"""<div class="result-panel">
+            <div class="empty-msg">❌ No schools found for UDISE <strong>{udise_code}</strong> in any data source.</div>
+        </div>"""
+        return gr.update(value=html), gr.update(visible=False), gr.update(visible=False, value=""), []
+
+    return (
+        gr.update(value=build_results_html(results, udise_code)),
+        gr.update(visible=True),
+        gr.update(visible=False, value=""),
+        results,
+    )
+
+
+def on_map(udise_code: str, marksheet_name: str, search_results: list):
+    udise_code = str(udise_code).strip()
+    if not udise_code or not search_results:
+        return gr.update(visible=True, value="⚠️ Search for a UDISE code first."), build_alias_html()
+
+    entries, seen = [], set()
+    if marksheet_name and marksheet_name.strip():
+        ms = marksheet_name.strip()
+        entries.append({"udise_code": udise_code, "alias_name": ms, "source_label": "Marksheet"})
+        seen.add(ms.upper())
+
+    for r in search_results:
+        name = str(r.get("name","")).strip()
+        if name and name.lower() not in ("nan","none","") and name.upper() not in seen:
+            entries.append({"udise_code": udise_code, "alias_name": name, "source_label": r.get("source","")})
+            seen.add(name.upper())
+
+    msg = save_aliases(entries)
+    return gr.update(visible=True, value=msg), build_alias_html()
+
+
+def build_alias_html(query: str = "") -> str:
+    """Render the alias dictionary as accordion cards (one per UDISE code)."""
+    data = load_aliases()
+    if not data:
+        return '<div style="text-align:center;padding:40px;color:#94a3b8;font-size:0.95rem">📭 No aliases saved yet. Search for a school and click <strong>Map All Names Together</strong>.</div>'
+
+    filtered = {}
+    if query and query.strip():
+        q = query.strip().upper()
+        for udise, info in data.items():
+            if q in udise.upper() or any(q in n.upper() for n in info.get("names", [])):
+                filtered[udise] = info
+    else:
+        filtered = data
+
+    if not filtered:
+        return f'<div style="text-align:center;padding:30px;color:#94a3b8">No results for <strong>"{query}"</strong></div>'
+
+    cards = []
+    for udise in sorted(filtered.keys()):
+        info = filtered[udise]
+        names = info.get("names", [])
+        updated = info.get("last_updated", "")[:10]
+
+        pills = ""
+        for i, name in enumerate(names):
+            if i == 0:
+                bg, dot = "#fffbeb", "🟡"
+            elif i == len(names) - 1:
+                bg, dot = "#f0fdf4", "🟢"
+            else:
+                bg, dot = "#eff6ff", "🔵"
+
+            pills += f"""
+            <div style="display:flex;align-items:center;gap:10px;padding:9px 12px;
+                        background:{bg};border-radius:9px;margin-bottom:6px;">
+                <span>{dot}</span>
+                <span style="font-size:0.97rem;font-weight:700;color:#1e293b">{name}</span>
+            </div>"""
+
+        open_attr = "open" if query and query.strip() else ""
+
+        cards.append(f"""
+        <details {open_attr} style="background:#fff;border-radius:14px;padding:12px 20px;
+                        box-shadow:0 2px 10px rgba(0,0,0,0.07);margin-bottom:14px;cursor:pointer;">
+            <summary style="display:flex;align-items:center;justify-content:space-between;list-style:none;">
+                <div style="display:flex;align-items:center;">
+                    <span style="font-size:0.65rem;font-weight:700;text-transform:uppercase;
+                                 letter-spacing:1px;color:#6d28d9;background:#ede9fe;
+                                 padding:3px 9px;border-radius:20px">UDISE</span>
+                    <span style="font-size:1.05rem;font-weight:800;color:#1e293b;margin-left:12px">{udise}</span>
+                </div>
+                <span style="font-size:0.75rem;color:#94a3b8">{len(names)} name(s) · ▼</span>
+            </summary>
+            <div style="margin-top:16px;">
+                {pills}
+            </div>
+        </details>""")
+
+    return f"""
+    <div style="font-size:0.78rem;color:#94a3b8;font-weight:600;text-transform:uppercase;
+                letter-spacing:0.6px;margin-bottom:12px">{len(filtered)} school(s) in dictionary</div>
+    {"".join(cards)}
+    <style>details > summary::-webkit-details-marker {{ display: none; }}</style>
+    """
+
+
+
+def on_alias_search(query: str) -> str:
+    return build_alias_html(query)
+
+
+def on_refresh_caches():
+    return refresh_all_caches()
+
+
+def _alias_df() -> str:
+    return build_alias_html()
+
+
+# ─── Theme ────────────────────────────────────────────────────────────────────
+THEME = gr.themes.Base(
+    primary_hue=gr.themes.colors.violet,
+    secondary_hue=gr.themes.colors.blue,
+    neutral_hue=gr.themes.colors.slate,
+    font=[gr.themes.GoogleFont("Inter"), "ui-sans-serif", "system-ui"],
+)
+
+# ─── UI ───────────────────────────────────────────────────────��───────────────
+with gr.Blocks(title="School Name Resolver") as app:
+
+    search_state = gr.State([])
+
+    # ── Header ──────────────────────────────────────────────────────────────
+    gr.HTML("""
+    <div class="app-header">
+        <h1>🏫 School Name Resolver</h1>
+        <p>Look up all known names for a school using its UDISE code</p>
+    </div>
+    """)
+
+    # ── Step 1 + 2: Inputs ──────────────────────────────────────────────────
+    gr.HTML('<div class="step-box"><span class="step-label">Step 1 — Enter Details</span>')
+
+    with gr.Row():
+        udise_input = gr.Textbox(
+            label="UDISE Code",
+            placeholder="e.g.  18150113702",
+            max_lines=1,
+            scale=1,
+        )
+        marksheet_input = gr.Textbox(
+            label="School Name on Marksheet  (optional)",
+            placeholder="Paste the name exactly as written on the student's marksheet…",
+            max_lines=1,
+            scale=2,
+        )
+
+    search_btn = gr.Button("🔍  Search All Sources", elem_classes="btn-search", size="lg")
+    gr.HTML('</div>')
+
+    # ── Step 2: Results ──────────────────────────────────────────────────────
+    gr.HTML('<div style="margin-bottom:4px"><span class="step-label" style="background:#dbeafe;color:#1d4ed8">Step 2 — Review Names</span></div>')
+    results_html = gr.HTML(value=build_empty_html())
+
+    # ── Step 3: Map ──────────────────────────────────────────────────────────
+    gr.HTML('<div style="margin:12px 0 4px"><span class="step-label" style="background:#dcfce7;color:#15803d">Step 3 — Save Aliases</span></div>')
+    map_btn = gr.Button(
+        "🗺️  Map All Names Together",
+        elem_classes="btn-map",
+        size="lg",
+        visible=False,
+    )
+    map_status = gr.Textbox(
+        show_label=False,
+        interactive=False,
+        visible=False,
+        placeholder="",
+        elem_classes="map-status",
+        max_lines=1,
+    )
+
+    gr.HTML("<hr style='border:none;border-top:1.5px solid #e2e8f0;margin:24px 0'>")
+
+    # ── Alias Dictionary ─────────────────────────────────────────────────────
+    with gr.Accordion("📖 Alias Dictionary", open=False, elem_classes="alias-section"):
+        gr.HTML('<div class="section-sub" style="margin-bottom:15px">All school names that have been mapped together so far</div>')
+
+        with gr.Row():
+            alias_search_box = gr.Textbox(
+                show_label=False,
+                placeholder="🔎  Search by UDISE code or school name…",
+                max_lines=1,
+                scale=4,
+            )
+            refresh_alias_btn = gr.Button("🔄 Refresh", scale=1, elem_classes="btn-secondary")
+
+        alias_html = gr.HTML(value="")
+
+    # ── Settings accordion ───────────────────────────────────────────────────
+    with gr.Accordion("⚙️  Settings & Cache", open=False):
+        gr.Markdown("""
+**Environment Variables required:**
+
+| Variable | Purpose |
+|---|---|
+| `HF_TOKEN` | HuggingFace token (read + write) |
+| `HF_SCRAPER_REPO` | Existing KYS scraper dataset (has scraped masters) |
+| `HF_RESOLVER_REPO` | New resolver dataset (has master_all_states.csv) |
+
+Use **Refresh Cache** after building a new master sheet in the scraper app.
+        """)
+        refresh_cache_btn = gr.Button("🔄 Refresh Data Cache", elem_classes="btn-secondary")
+        cache_status = gr.Textbox(show_label=False, interactive=False, max_lines=2)
+
+    # ── Events ───────────────────────────────────────────────────────────────
+    search_btn.click(
+        fn=on_search,
+        inputs=[udise_input, marksheet_input],
+        outputs=[results_html, map_btn, map_status, search_state],
+    )
+    udise_input.submit(
+        fn=on_search,
+        inputs=[udise_input, marksheet_input],
+        outputs=[results_html, map_btn, map_status, search_state],
+    )
+    map_btn.click(
+        fn=on_map,
+        inputs=[udise_input, marksheet_input, search_state],
+        outputs=[map_status, alias_html],
+    )
+    alias_search_box.change(fn=on_alias_search, inputs=[alias_search_box], outputs=[alias_html])
+    refresh_alias_btn.click(fn=lambda: build_alias_html(), outputs=[alias_html])
+    refresh_cache_btn.click(fn=on_refresh_caches, outputs=[cache_status])
+    app.load(fn=build_alias_html, outputs=[alias_html])
+
+
+# ─── Launch ───────────────────────────────────────────────────────────────────
+if __name__ == "__main__":
+    port = int(os.getenv("PORT", 7862))
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=port,
+        theme=THEME,
+        css=CSS,
+        inbrowser=True,
+    )

hf_reader.py

@@ -0,0 +1,204 @@
+"""
+hf_reader.py — HuggingFace data layer for the School Name Resolver.
+
+Reads:
+  1. master_all_states.csv  (Old Master) from HF_RESOLVER_REPO
+  2. scraped_data/mapped/*.parquet  (new masters) from HF_SCRAPER_REPO
+
+All data is cached in memory after first load. Call refresh_all_caches() to force reload.
+"""
+
+import os
+import re
+import pandas as pd
+from huggingface_hub import HfApi, hf_hub_download
+from datetime import datetime
+
+HF_TOKEN = os.getenv("HF_TOKEN", "")
+HF_SCRAPER_REPO = os.getenv("HF_SCRAPER_REPO", "")
+HF_RESOLVER_REPO = os.getenv("HF_RESOLVER_REPO", "")
+
+# ─── Module-level caches ───────────────────────────────────────────────────────
+_old_master_df: pd.DataFrame | None = None
+_mapped_masters: dict[str, pd.DataFrame] = {}
+_cache_loaded: bool = False
+
+
+# ─── Internal helpers ──────────────────────────────────────────────────────────
+
+def _load_old_master() -> pd.DataFrame:
+    """Download and return master_all_states.csv from HF_RESOLVER_REPO."""
+    if not HF_RESOLVER_REPO:
+        print("[hf_reader] HF_RESOLVER_REPO not set — skipping Old Master load.")
+        return pd.DataFrame()
+    try:
+        path = hf_hub_download(
+            repo_id=HF_RESOLVER_REPO,
+            filename="master_all_states.csv",
+            repo_type="dataset",
+            token=HF_TOKEN or None,
+            force_download=True,
+        )
+        df = pd.read_csv(path, dtype=str, low_memory=False)
+        df["School_Udise_Code__c"] = df["School_Udise_Code__c"].astype(str).str.strip()
+        print(f"[hf_reader] Old Master loaded: {len(df):,} rows.")
+        return df
+    except Exception as e:
+        print(f"[hf_reader] Could not load master_all_states.csv: {e}")
+        return pd.DataFrame()
+
+
+def _load_mapped_masters() -> dict[str, pd.DataFrame]:
+    """Download all parquet files from scraped_data/mapped/ in HF_SCRAPER_REPO."""
+    if not HF_SCRAPER_REPO:
+        print("[hf_reader] HF_SCRAPER_REPO not set — skipping mapped masters load.")
+        return {}
+
+    api = HfApi()
+    results: dict[str, pd.DataFrame] = {}
+
+    try:
+        all_files = list(api.list_repo_files(
+            repo_id=HF_SCRAPER_REPO,
+            repo_type="dataset",
+            token=HF_TOKEN or None,
+        ))
+        mapped_files = sorted(
+            [f for f in all_files if f.startswith("scraped_data/mapped/") and f.endswith(".parquet")],
+            reverse=True,
+        )
+        print(f"[hf_reader] Found {len(mapped_files)} mapped master(s) in scraper repo.")
+
+        for file_path in mapped_files:
+            try:
+                local_path = hf_hub_download(
+                    repo_id=HF_SCRAPER_REPO,
+                    filename=file_path,
+                    repo_type="dataset",
+                    token=HF_TOKEN or None,
+                    force_download=True,
+                )
+                df = pd.read_parquet(local_path)
+                if "School_Udise_Code__c" in df.columns:
+                    df["School_Udise_Code__c"] = df["School_Udise_Code__c"].astype(str).str.strip()
+                stem = file_path.split("/")[-1].replace(".parquet", "")
+                results[stem] = df
+                print(f"[hf_reader]   Loaded: {stem}  ({len(df):,} rows)")
+            except Exception as e:
+                print(f"[hf_reader]   Failed to load {file_path}: {e}")
+
+    except Exception as e:
+        print(f"[hf_reader] Could not list scraper repo files: {e}")
+
+    return results
+
+
+def _ensure_loaded():
+    """Load all caches if they haven't been loaded yet."""
+    global _old_master_df, _mapped_masters, _cache_loaded
+    if not _cache_loaded:
+        _old_master_df = _load_old_master()
+        _mapped_masters = _load_mapped_masters()
+        _cache_loaded = True
+
+
+# ─── Public API ───────────────────────────────────────────────────────────────
+
+def refresh_all_caches() -> str:
+    """Force-reload all data from HuggingFace. Returns a status message."""
+    global _old_master_df, _mapped_masters, _cache_loaded
+    _cache_loaded = False
+    _old_master_df = None
+    _mapped_masters = {}
+    _ensure_loaded()
+    n_masters = len(_mapped_masters)
+    sf_rows = len(_old_master_df) if _old_master_df is not None else 0
+    return (
+        f"✅ Caches refreshed — Old Master: {sf_rows:,} rows, "
+        f"Mapped Masters: {n_masters} file(s) loaded."
+    )
+
+
+def _pretty_label(stem: str, idx: int) -> str:
+    """Turn a filename stem like 'mapped_master_20250707_123456' into a readable label."""
+    match = re.search(r"(\d{4})(\d{2})(\d{2})", stem)
+    if match:
+        y, m, d = match.group(1), match.group(2), match.group(3)
+        date_str = f"{d}/{m}/{y}"
+    else:
+        date_str = stem
+
+    if idx == 0:
+        return f"Latest Scraped Master ({date_str})"
+    else:
+        return f"Older Scraped Master ({date_str})"
+
+
+def search_udise(udise_code: str, marksheet_name: str = "") -> list[dict]:
+    """
+    Search for a UDISE code across all data sources.
+
+    Returns a list of dicts, each with:
+        source       str  — human-readable source label
+        source_type  str  — 'marksheet' | 'legacy_db' | 'latest_master' | 'old_master'
+        name         str  — school name found
+        state        str  — state (if available)
+        district     str  — district (if available)
+        block        str  — block (if available)
+    """
+    _ensure_loaded()
+    results: list[dict] = []
+
+    if marksheet_name and marksheet_name.strip():
+        results.append({
+            "source": "Marksheet (entered by you)",
+            "source_type": "marksheet",
+            "name": marksheet_name.strip(),
+            "state": "",
+            "district": "",
+            "block": "",
+        })
+
+    if _old_master_df is not None and not _old_master_df.empty:
+        mask = _old_master_df["School_Udise_Code__c"] == str(udise_code).strip()
+        matches = _old_master_df[mask]
+        for _, row in matches.iterrows():
+            results.append({
+                "source": "Old Master (master_all_states.csv)",
+                "source_type": "legacy_db",
+                "name": str(row.get("School_Name__c", "")).strip(),
+                "state": str(row.get("School_State__c", "")).strip(),
+                "district": str(row.get("School_District__c", "")).strip(),
+                "block": str(row.get("School_Block__c", "")).strip(),
+            })
+
+    for idx, (stem, df) in enumerate(_mapped_masters.items()):
+        if "School_Udise_Code__c" not in df.columns:
+            continue
+        mask = df["School_Udise_Code__c"] == str(udise_code).strip()
+        matches = df[mask]
+        label = _pretty_label(stem, idx)
+        source_type = "latest_master" if idx == 0 else "old_master"
+        for _, row in matches.iterrows():
+            results.append({
+                "source": label,
+                "source_type": source_type,
+                "name": str(row.get("School_Name__c", "")).strip(),
+                "state": str(row.get("School_State__c", "")).strip(),
+                "district": str(row.get("School_District__c", "")).strip(),
+                "block": str(row.get("School_Block__c", "")).strip(),
+            })
+
+    return results
+
+
+def get_config_status() -> dict:
+    """Return a dict describing the current configuration state."""
+    _ensure_loaded()
+    return {
+        "scraper_repo": HF_SCRAPER_REPO or "⚠️ Not set (HF_SCRAPER_REPO)",
+        "resolver_repo": HF_RESOLVER_REPO or "⚠️ Not set (HF_RESOLVER_REPO)",
+        "sf_baseline_rows": len(_old_master_df) if _old_master_df is not None else 0,
+        "mapped_masters_count": len(_mapped_masters),
+        "token_set": bool(HF_TOKEN),
+    }

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=4.44.0
+huggingface-hub>=0.24.0
+pandas>=2.0.0
+pyarrow>=14.0.0
+python-dotenv>=1.0.0