Add release readiness docs and checks

Author: bt1142msstate

.github/workflows/tests.yml

@@ -21,9 +21,18 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
       - name: Compile source
         run: |
-          python -m py_compile src/address_dataset_generator.py src/address_resolver.py src/resolver_app.py
+          python -m py_compile src/*.py
+
+      - name: Check browser JavaScript syntax
+        run: |
+          node --check src/static/app.js
 
       - name: Run tests
         run: |

DATA_SOURCES.md

@@ -0,0 +1,58 @@
+# Data Sources
+
+Ady Resolver is built around real address records, but no free public source
+tested here proves that every current Mississippi address is present. Treat the
+public feeds as strong baselines and use authoritative or licensed data when
+you need true production coverage.
+
+## Supported Source Types
+
+- **MS811/MARIS county point-address ZIPs**: best configured route for
+  authoritative Mississippi point-address coverage when obtained through the
+  MARIS distribution process. Use `--real-address-format maris` and keep
+  `--require-ms-county-coverage` enabled.
+- **Public MARIS Point Addressing ZIPs**: easiest public point-address source.
+  It is useful, but public availability is county-limited and should not be
+  presented as exhaustive.
+- **Public MARIS parcel service**: broad statewide public fallback using
+  parcel situs fields. It covers all county names in the configured service,
+  but parcel situs rows are not equivalent to authoritative point addresses.
+- **OpenAddresses processed extracts**: useful supplemental and development
+  source. Current Mississippi extracts are not exhaustive and many records lack
+  strong locality fields.
+- **OpenAddresses direct ESRI source catalog**: queries current configured
+  source services and caches normalized CSVs. This is useful supplemental data
+  when source conform files expose situs locality fields.
+- **USDOT National Address Database**: parser support exists, but the tested
+  Mississippi rows were not useful for this project’s current reference cache.
+- **Manual verified supplement**: local CSV/XLSX additions for confirmed
+  missing addresses. The app can import these rows and update the live resolver
+  reference index.
+
+## Coverage Expectations
+
+- The generator samples from loaded real source records and fails when the real
+  pool is too small instead of inventing replacement addresses.
+- `--require-ms-county-coverage` checks for all 82 Mississippi county names in
+  source file paths. That is a coverage guard, not proof that every address in
+  each county is present.
+- ZIP-to-city enrichment only adds conservative derived variants when a ZIP has
+  at least 25 real records and one city has at least a 98% share.
+- Manual verified additions should be used for known misses from public feeds.
+  They are tracked separately in
+  `datasets/source_cache/manual_verified_ms/verified_addresses.csv`.
+
+## Recommended Strategies
+
+- **Best public baseline**: merge MARIS parcels, public MARIS Point Addressing,
+  OpenAddresses processed extracts, OpenAddresses direct ESRI CSVs, and the
+  manual verified supplement.
+- **Best Mississippi address-point route**: obtain the local/state NG9-1-1 or
+  full MS811/MARIS county point-address distribution.
+- **Best postal deliverability route**: use a licensed USPS/CASS/DPV-capable
+  source or API. That is validation-grade for mail delivery, but it is not the
+  same thing as a free downloadable address list.
+
+Generated `datasets/` and `runs/` directories are ignored because public-source
+caches and full reference builds can be several GB. Rebuild them with the
+README commands instead of committing them.

Makefile

@@ -0,0 +1,30 @@
+PYTHON ?= python3
+APP_HOST ?= 127.0.0.1
+APP_PORT ?= 8765
+SMOKE_OUTPUT_DIR ?= /tmp/ady_resolver_demo_smoke
+
+.PHONY: compile js-check unit test smoke app
+
+compile:
+	$(PYTHON) -m py_compile src/*.py
+
+js-check:
+	node --check src/static/app.js
+
+unit:
+	$(PYTHON) -m unittest discover -s tests -v
+
+test: compile js-check unit
+
+smoke:
+	rm -rf "$(SMOKE_OUTPUT_DIR)"
+	$(PYTHON) src/address_resolver.py \
+		--mode predict \
+		--eval-dataset-dir examples/demo_reference \
+		--model-path models/stage2_model.json \
+		--output-dir "$(SMOKE_OUTPUT_DIR)" \
+		--compare-variants \
+		--jobs 1
+
+app:
+	$(PYTHON) src/resolver_app.py --host "$(APP_HOST)" --port "$(APP_PORT)"

README.md

@@ -56,6 +56,14 @@ cd Ady-Resolver
 python3 -m unittest discover -s tests -v
 ```
 
+Common development commands are also available through `make`:
+
+```bash
+make test    # compile Python, check browser JS syntax, run unit tests
+make smoke   # run the checked-in demo resolver accuracy smoke
+make app     # start the local browser app on 127.0.0.1:8765
+```
+
 Run the local app after building or restoring a reference cache:
 
 ```bash
@@ -66,13 +74,23 @@ Then open `http://127.0.0.1:8765`.
 
 ## Repository Contents
 
-- `src/address_dataset_generator.py` - source downloading, cache handling,
-  parsing, cleanup, and training/evaluation dataset generation.
-- `src/address_resolver.py` - Stage 1 resolver, Stage 2 model, metrics, and
-  CLI entry points.
-- `src/resolver_app.py` - local web app and reference-cache builder.
+- `src/address_dataset_generator.py` - compatibility CLI/facade for dataset
+  generation. Source loading, noise generation, and dataset assembly live in
+  focused modules such as `address_source_*`, `address_openaddresses.py`,
+  `address_maris.py`, `address_noise.py`, and `address_dataset_build.py`.
+- `src/address_resolver.py` - compatibility CLI/facade for the resolver. Shared
+  models, parsing, reference loading, and Stage 2 training/scoring live in
+  `resolver_models.py`, `resolver_parsing.py`, `resolver_reference.py`, and
+  `resolver_stage2.py`.
+- `src/resolver_app.py` - local web app entrypoint. App config, persistence,
+  service logic, HTTP routing, reference-cache building, batch file handling,
+  and static UI assets are split across `resolver_app_*`,
+  `resolver_reference_cache.py`, `resolver_batch_io.py`, `resolver_http.py`,
+  and `src/static/`.
 - `src/train_from_addresses.py` - one-command dataset generation and model
   training for custom address CSVs.
+- `DATA_SOURCES.md` - concise source and coverage guidance for supported public,
+  authoritative, licensed, and manual address data paths.
 - `models/` - small checked-in Stage 2 model JSON artifacts.
 - `examples/` - a small demo reference set and custom-address CSV example for
   fresh clones.
@@ -98,6 +116,9 @@ The generator now supports real address sources for Mississippi. For exhaustive
 Mississippi coverage, use the MS811/MARIS county shapefile ZIP set and keep the
 county-coverage guard enabled.
 
+See [DATA_SOURCES.md](DATA_SOURCES.md) for a shorter source-quality and
+coverage guide.
+
 - MS811/MARIS full county shapefile ZIPs: production source for all 82
   Mississippi counties when obtained through the MARIS distribution agreement.
 - Public MARIS Mississippi Point Addressing ZIPs: easiest public Mississippi
@@ -413,10 +434,23 @@ flag, match ID, stage, and the top three candidate addresses.
 ## Tests
 
 ```bash
-python3 -m py_compile src/address_dataset_generator.py src/address_resolver.py src/resolver_app.py
+python3 -m py_compile src/*.py
+node --check src/static/app.js
 python3 -m unittest discover -s tests -v
 ```
 
+Or run the same local check set with:
+
+```bash
+make test
+```
+
+Run the checked-in demo accuracy smoke with:
+
+```bash
+make smoke
+```
+
 ## License
 
 Ady Resolver is open source under the [MIT License](LICENSE).

tests/test_demo_accuracy_smoke.py

@@ -0,0 +1,49 @@
+import sys
+import unittest
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+SRC_DIR = PROJECT_ROOT / "src"
+sys.path.insert(0, str(SRC_DIR))
+
+from address_resolver import (  # noqa: E402
+    Resolver,
+    build_city_lookup,
+    choose_combined_resolution,
+    load_model,
+    load_queries,
+    load_reference,
+)
+
+
+class DemoAccuracySmokeTests(unittest.TestCase):
+    def test_demo_hard_cases_resolve_as_expected(self) -> None:
+        dataset_dir = PROJECT_ROOT / "examples" / "demo_reference"
+        reference_rows, _reference_by_id = load_reference(dataset_dir / "reference_addresses.csv")
+        resolver = Resolver(reference_rows, build_city_lookup(reference_rows))
+        model, accept_threshold, review_threshold, _metadata = load_model(
+            PROJECT_ROOT / "models" / "stage2_model.json",
+            resolver,
+        )
+
+        for query in load_queries(dataset_dir / "queries.csv"):
+            with self.subTest(query_id=query.query_id, query_address=query.query_address):
+                parsed = resolver.parse(query.query_address)
+                stage1 = resolver.resolve_stage1(parsed, review_threshold=review_threshold)
+                stage2 = model.resolve(
+                    parsed,
+                    accept_threshold=accept_threshold,
+                    review_threshold=review_threshold,
+                )
+                combined = choose_combined_resolution(stage1, stage2)
+
+                if query.label:
+                    self.assertEqual(query.true_match_id, combined.predicted_match_id)
+                    self.assertEqual(query.canonical_address, combined.predicted_canonical_address)
+                else:
+                    self.assertEqual("", combined.predicted_match_id)
+
+
+if __name__ == "__main__":
+    unittest.main()