Merge pull request #167 from helpfulengineering/fix/direct-matching-distance

in direct matching layer, false positives could cause failure mode in which NLP layer is not invoked. It should instead be used as a second opinion on every call unless either a strong direct match is found, or explicitly disabled

Author: touchthesun

.repo-map.md

@@ -525,6 +525,10 @@ Total Python files: 310
 │       │       │       def _build_optional_human_summary()
 │       │       │       def _build_match_suggestions()
 │       │       │       def _detect_domain_from_manifest()
+│       │       │       def _resolve_matching_local_okw_json_dir()
+│       │       │       def _load_facilities_from_local_okw_json_dir()
+│       │       │       def _extract_facility_process_names_for_prefilter()
+│       │       │       def _prefilter_facilities_by_required_processes()
 │       │       │       def _matches_filters()
 │       │       ├── okh.py
 │       │       ├── okw.py
@@ -1578,7 +1582,7 @@ The converte...
 
 Orchestrates direc...
 
-**Internal Dependencies:** 1 imports
+**Internal Dependencies:** 4 imports
 
 ### `src/core/services/okh_service.py`
 
@@ -3972,7 +3976,7 @@ This module combines the functionality fr...
 - `render_match_summary(match_summary)`
   - Render a compact human-readable line from a structured match summary....
 
-**Internal Dependencies:** 5 imports
+**Internal Dependencies:** 7 imports
 
 ### `src/core/api/routes/okh.py`
 

src/config/settings.py

@@ -196,6 +196,11 @@ def _get_secret_or_env(key: str, default: str = None) -> str:
     else:
         raise
 
+# When true, skip StorageOrganizer .gitkeep seeding on app startup (no PUTs to remote).
+STORAGE_SKIP_DIRECTORY_BOOTSTRAP = _get_secret_or_env(
+    "STORAGE_SKIP_DIRECTORY_BOOTSTRAP", "false"
+).lower() in ("true", "1", "t")
+
 # Cache Configuration
 CACHE_ENABLED = _get_secret_or_env("CACHE_ENABLED", "true").lower() in (
     "true",
@@ -241,3 +246,34 @@ def _get_secret_or_env(key: str, default: str = None) -> str:
         f"MAX_DEPTH ({MAX_DEPTH}) is outside recommended range (0-10). "
         "Consider using a value between 1-5 for optimal performance."
     )
+
+# NLP veto (second opinion on fuzzy direct + heuristic hits)
+MATCHING_NLP_VETO_ENABLED = _get_secret_or_env(
+    "MATCHING_NLP_VETO_ENABLED", "false"
+).lower() in ("true", "1", "t")
+MATCHING_NLP_VETO_THRESHOLD = float(
+    _get_secret_or_env("MATCHING_NLP_VETO_THRESHOLD", "0.2")
+)
+if not 0.0 <= MATCHING_NLP_VETO_THRESHOLD <= 1.0:
+    logger.warning(
+        f"MATCHING_NLP_VETO_THRESHOLD ({MATCHING_NLP_VETO_THRESHOLD}) should be in [0, 1]; "
+        "clamping may occur at runtime."
+    )
+
+# When set, match requests with no inline `okw_facilities` load `*.json` from this path
+# (recursively) instead of listing remote storage — avoids hanging curls when cloud
+# storage is slow or misconfigured. Production should normally leave this unset.
+_match_local = _get_secret_or_env("MATCHING_LOCAL_OKW_JSON_DIR", "") or ""
+MATCHING_LOCAL_OKW_JSON_DIR = _match_local.strip() if _match_local.strip() else None
+
+# When true (default), MatchingService.initialize() eagerly loads spaCy models for
+# each domain. When false, models load on first NLP use — avoids long stalls inside
+# FastAPI Depends(get_matching_service) on constrained or cold-start environments.
+MATCHING_PREINIT_NLP = _get_secret_or_env("MATCHING_PREINIT_NLP", "true").lower() in (
+    "true",
+    "1",
+    "t",
+)
+
+# Do not log MATCHING_* here: this module imports before main.setup_logging(), so
+# INFO lines would be dropped by the default root logger (WARNING). Log from lifespan.

src/core/api/models/match/request.py

@@ -44,6 +44,15 @@ class MatchRequest(BaseAPIRequest, LLMRequestMixin):
     location: Optional[str] = None
     capabilities: Optional[List[str]] = None
     materials: Optional[List[str]] = None
+    max_candidate_facilities: Optional[int] = Field(
+        200,
+        ge=1,
+        le=5000,
+        description=(
+            "Upper bound on facilities considered during matching after requirement-aware "
+            "prefiltering. Lower values improve latency on large OKW pools."
+        ),
+    )
 
     # Advanced filtering parameters
     max_distance_km: Optional[float] = None  # Distance filter