Split fuzzy search from the LLM path: /search/fuzzy and /geometry/{id}

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Format check
+        run: ruff format --check src/ tests/
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+      - name: Sync dependencies
+        run: uv sync --all-extras
+      - name: Type check
+        run: uv run mypy --explicit-package-bases src/gazet tests/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+      - name: Sync dependencies
+        run: uv sync --all-extras
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short

README.md

@@ -58,6 +58,11 @@ For now, gazet relies on [ollama](https://ollama.com/). For remote (cloud) model
 ```bash
 python -m gazet
 # then GET http://localhost:8000/search?q=Border%20between%20Loja%20and%20Piura
+# pure fuzzy match, no LLM, raw geometry only:
+# GET http://localhost:8000/search/fuzzy?q=Loja&limit=5
+# cheap ID-only search, then fetch geometry for just the one you want:
+# GET http://localhost:8000/search/fuzzy?q=Loja&limit=5&ids_only=true
+# GET http://localhost:8000/geometry/25f85439-e054-44e3-9ad4-9fbf755e3183
 ```
 
 ### API + Streamlit demo
@@ -77,13 +82,18 @@ uv run streamlit run gazet_demo.py   # demo UI
 | `schemas.py` | `SUBTYPES`, `COUNTRIES`, `Place`, `PlacesResult` |
 | `lm.py` | DSPy signatures + LM init (`extract`, `write_sql`) |
 | `search.py` | fuzzy search against `divisions_area` / `natural_earth` |
+| `geometry.py` | geometry simplification / GeoJSON normalization (no LLM dependency) |
 | `sql.py` | code-act SQL generation loop |
 | `export.py` | GeoJSON FeatureCollection writer |
-| `api.py` | FastAPI app with `/search?q=...` returning GeoJSON FeatureCollection |
+| `api.py` | FastAPI app: `/search` (LLM), `/search/fuzzy` (fuzzy-only), `/geometry/{id}` (direct ID lookup) |
 
 ## Design notes
 
-- `api.py` exposes GET `/search?q=<query>`; returns GeoJSON FeatureCollection and logs intermediate output.
+- `api.py` exposes GET `/search?q=<query>`; returns GeoJSON FeatureCollection and logs intermediate output. This path runs two LLM calls (place extraction, then SQL generation for candidate selection/disambiguation and GIS ops).
+- `api.py` also exposes GET `/search/fuzzy?q=<place name>&limit=5&simplify=true&sources=divisions_area,natural_earth` — pure Jaro-Winkler fuzzy match with no LLM involved. `q` is a place-name string, not a natural-language query (there's no place-extraction step). Returns the combined top-`limit` matches across sources as a GeoJSON FeatureCollection with raw (or simplified, if `simplify=true`) geometry attached. Pass `ids_only=true` to skip full geometry and get back `{"ids": [{"source", "id", "name", "country", "subtype", "admin_level", "bbox"}, ...]}` — `country`/`subtype`/`admin_level` disambiguate same-named places (e.g. multiple real "Loja"s across Ecuador and Spain, or Ecuador's "Loja" region vs. its nested "Loja" county), and `bbox` is `[minx, miny, maxx, maxy]`, a much smaller payload than full geometry, for picking a candidate before fetching its full geometry.
+- Fuzzy matching (`search.py`) ranks exact-substring matches (query literally contained in the name, e.g. "Loja" in "Loja Province") ahead of pure edit-distance near-misses (e.g. "Lodja"), even when the near-miss scores a slightly higher raw Jaro-Winkler similarity. `divisions_area` matches against `names.primary` (not `names.common.en`, which is null for 77% of rows and would otherwise exclude most of the dataset from every fuzzy search).
+- `api.py` also exposes GET `/geometry/{id}?source=divisions_area&simplify=true` — fetch a single feature's geometry directly by ID, no fuzzy matching or LLM involved. `source` is inferred from the ID if omitted (Natural Earth IDs are prefixed `ne_`). Returns a single GeoJSON Feature, 404 if not found.
+- The spatial extension is loaded once at API startup (FastAPI `lifespan`) onto a shared DuckDB connection stored on `app.state`; each request gets a cheap `cursor()` off it instead of paying DuckDB's ~90ms `LOAD spatial` cost per call.
 - LM is initialised at import time in `lm.py`, suitable for a long-lived server process.
 - Data lives in `data/overture/` and `data/natural_earth_geoparquet/` (not tracked in git).
 

gazet_demo.py

@@ -295,7 +295,7 @@ def _track(event_name: str, **props):
     st.caption("Built by")
     st.image(DEVSEED_LOGO_PATH, width=180)
 
-backend = "gguf"
+backend = os.environ.get("GAZET_BACKEND", "gguf")
 
 if "run_q" not in st.session_state:
     st.session_state.run_q = None

pyproject.toml

@@ -19,14 +19,47 @@ dependencies = [
     "httpx>=0.28.1",
     "sqlparse>=0.5.5",
 ]
-optional-dependencies = { demo = ["streamlit", "requests", "pydeck"], dev = ["ruff"] }
+optional-dependencies = { demo = ["streamlit", "requests", "pydeck"], dev = ["ruff", "mypy>=1.15", "pandas-stubs>=2.0", "pytest>=8.0", "pytest-asyncio>=0.24"] }
 
 [project.scripts]
 gazet-dataset = "dataset.scripts.cli:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/gazet", "dataset"]
 
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = ["-ra", "--strict-markers"]
+
+[tool.mypy]
+python_version = "3.13"
+mypy_path = "src"
+strict = true
+disallow_any_generics = false  # pandas-stubs use Any heavily
+warn_return_any = false  # dspy returns Any; noisy without value
+disallow_untyped_defs = false  # too noisy on test files
+
+[[tool.mypy.overrides]]
+module = "dspy.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "duckdb.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+check_untyped_defs = false
+disallow_untyped_defs = false
+warn_return_any = false
+
+[[tool.mypy.overrides]]
+module = "gazet.lm"
+# dspy has no stubs — its classes (Signature, Module, Predict, LM) are all typed as Any.
+# Suppressing the resulting noise while keeping the rest of the codebase strict.
+disable_error_code = ["misc", "no-untyped-def", "no-untyped-call"]
+
 [dependency-groups]
 dataset = [
     "modal>=1.4.0",

ruff.toml

@@ -0,0 +1,7 @@
+target-version = "py313"
+
+[lint]
+# BLE001 – catching Exception is intentional in health checks and error-handling paths
+# S110 – try/except/pass is intentional for health probes that must not crash
+# B017 – pytest.raises(Exception) is acceptable for pydantic validation error checks
+ignore = ["BLE001", "S110", "B017"]