Upload 3 files

README.md

@@ -1,13 +1,91 @@
 ---
-title: SubdivisionProgram2
-emoji: 🦀
-colorFrom: purple
-colorTo: pink
+title: Subdivision Cluster FIPS Validation
+emoji: 🗺️
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
 sdk_version: 6.19.0
-python_version: '3.13'
+python_version: "3.12"
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Subdivision Cluster / FIPS Validation
+
+Ported from the Colab notebook
+`LatestUndeterminedZipCityCensusTract70_Threshold_95_Clusters.ipynb`.
+
+Upload one or more Excel files. The app:
+
+1. Merges them into one table.
+2. Validates every `(city, FIPS)` pair against the **Subdivision Program
+   Safety List** (the reference file).
+3. Fuzzy-clusters `LegalSubDivision` names (RapidFuzz).
+4. Fills city / ZIP / census-tract by majority vote per cluster.
+5. Returns the cities, zips, census-tracts, cluster, and full-output files,
+   plus the FIPS validation audit.
+
+## How the reference (safety) file is handled
+
+The app does **not** accept the safety list as an upload — it's your trusted
+whitelist, so it stays under your control. `get_safety_list_path()` resolves it
+two ways:
+
+### Option A — bundle it in this repo (Space must be PRIVATE)
+
+Commit the xlsx into the Space repo and name it
+`Subdivision_Program_Safety_List.xlsx` (or set the `SAFETY_LIST_FILE` variable
+to your filename). Then set the Space visibility to **Private** in Settings —
+otherwise the file is publicly downloadable.
+
+### Option B — private dataset + token (recommended)
+
+1. Create a **private dataset** repo and upload the safety list there.
+2. In this Space, add these under Settings → **Variables and secrets**:
+   - Secret `HF_TOKEN` — a read access token.
+   - Variable `SAFETY_LIST_REPO` — e.g. `your-username/subdivision-safety-list`.
+   - Variable `SAFETY_LIST_REPO_FILE` — the filename inside that dataset
+     (optional; defaults to `Subdivision_Program_Safety_List.xlsx`).
+
+The list is downloaded once at startup and cached. To update it, just replace
+the file in the dataset — no app redeploy needed.
+
+### Optional per-run override (sidebar)
+
+The sidebar's **"2. Upload Reference File (Optional)"** slot lets you swap in a
+different safety list (xlsx or csv, same `City Name` + `Acceptable FIPS *`
+columns) for a **single run** — handy for testing a candidate list before
+committing it. It is not persisted and does not touch the server-side list.
+
+Security note: because this lets anyone with access to the Space substitute the
+whitelist at request time, it's only appropriate for a **private** Space whose
+members you trust (which is the current setup). To lock the whitelist to the
+server copy only, delete the `reference_in` component and the `reference_file`
+branch in `run_pipeline` (it falls back to `load_whitelist()`).
+
+## Deploy
+
+```bash
+# one-time
+huggingface-cli login
+
+# create the Space (or do it in the web UI: New Space -> Gradio)
+huggingface-cli repo create subdivision-space --type space --space_sdk gradio
+
+git clone https://huggingface.co/spaces/<your-username>/subdivision-space
+cd subdivision-space
+cp /path/to/app.py /path/to/requirements.txt /path/to/README.md .
+git add .
+git commit -m "Initial app"
+git push
+```
+
+The Space builds automatically on push.
+
+## Notes
+
+- The "filter to single most-dominant county" toggle reproduces the notebook's
+  behavior. Turn it off to process every county in the upload at once
+  (clustering already runs per-county, so this is safe).
+- Large outputs: the full CSV is written whole. On the free CPU tier (limited
+  RAM), very large merges may need the upgraded hardware tier.

requirements.txt

@@ -1,10 +1,5 @@
-gradio>=4.0
 pandas>=2.0
 numpy>=1.24
 openpyxl>=3.1
 rapidfuzz>=3.0
-huggingface_hub>=0.23,<1.0
-pydantic>=2.0,<2.11
-fastapi<0.116
-starlette<1.0
-audioop-lts; python_version >= "3.13"
+huggingface_hub>=0.23