Merge pull request #227 from helpfulengineering/feat/okw-network-map-endpoint

feat(okw): network map endpoint — local facilities ∪ Maps of Making

Author: touchthesun

.repo-map.md

@@ -3,7 +3,7 @@ REPOSITORY MAP (Aider Style)
 ================================================================================
 Repository: supply-graph-ai
 
-Total Python files: 436
+Total Python files: 438
 
 ├── deploy/
 │   ├── __init__.py
@@ -1272,6 +1272,7 @@ Total Python files: 436
 │       │   ├── matching_service.py
 │       │   │       class MatchingService (__init__, _normalize_req_cap_lists, _normalize_capability_list...)
 │       │   ├── mom_bridge.py
+│       │   │       class MoMSpacesCache (__init__, is_fresh, invalidate)
 │       │   ├── okh_service.py
 │       │   │       class OKHService (__init__)
 │       │   ├── okw_service.py
@@ -1679,6 +1680,9 @@ Total Python files: 436
     │   │       def _classify()
     │   │       def test_matching_ab_report_remote_okw()
     │   ├── test_matching_baseline.py
+    │   ├── test_okw_map_route.py
+    │   │       def _facility_content()
+    │   │       def test_map_local_only_returns_source_labeled_points()
     │   ├── test_reverse_facility_match_route.py
     │   │       def _facility_content()
     │   │       def test_reverse_match_unknown_facility_returns_404()
@@ -1944,6 +1948,11 @@ Total Python files: 436
         │       def _request()
         │       def test_parse_match_filters_populates_okw_ids()
         │       def test_parse_match_filters_omits_okw_ids_when_empty()
+        ├── test_okw_map.py
+        │       class _FakeResponse (__init__, raise_for_status, json)
+        │       class _FakeClient (__init__)
+        │       def _bindings()
+        │       def _facility()
         ├── test_package_pin.py
         │       def _sha256()
         │       def _build_fake_package()
@@ -2041,7 +2050,7 @@ Total Python files: 436
 
 ## Overview
 
-Total files analyzed: 436
+Total files analyzed: 438
 
 ## Entry Points
 
@@ -2341,6 +2350,15 @@ Orchestrates direc...
 ### `src/core/services/mom_bridge.py`
 > MoM SPARQL bridge — query Maps of Making for spaces matching an OHM process....
 
+**Exports:** MoMSpacesCache
+
+**Classes:**
+- `MoMSpacesCache`
+  - Methods: is_fresh, invalidate
+  - TTL cache for the MoM all-spaces map layer.
+
+Serves the last successful fetch fo...
+
 ### `src/core/services/okh_service.py`
 
 **Exports:** OKHService
@@ -7608,6 +7626,16 @@ Uses a minima...
 
 **Internal Dependencies:** 4 imports
 
+### `tests/integration/test_okw_map_route.py`
+> Integration test for GET /api/okw/map (network map, review #1).
+
+Runs the full ASGI app in-process. ...
+
+**Exports:** test_map_local_only_returns_source_labeled_points
+
+**Functions:**
+- `test_map_local_only_returns_source_labeled_points(client)`
+
 ### `tests/integration/test_reverse_facility_match_route.py`
 > Integration tests for POST /api/match/facility (reverse matching, review #7).
 
@@ -8048,6 +8076,18 @@ A caller can pre-select which...
 
 **Internal Dependencies:** 11 imports
 
+### `tests/unit/test_okw_map.py`
+> Unit tests for the OKW network map: MoM all-spaces fetch, TTL cache, union.
+
+Covers `fetch_all_mom_s...
+
+**Classes:**
+- `_FakeResponse`
+  - Methods: raise_for_status, json
+- `_FakeClient`
+
+**Internal Dependencies:** 13 imports
+
 ### `tests/unit/test_package_pin.py`
 > Unit tests for OKH package pin record creation and verification (issue #174)....
 

docs/models/okw-docs.md

@@ -581,6 +581,25 @@ if facility.has_process("3d printing"):
 The check searches both `manufacturing_processes` URLs and equipment capability
 descriptions.
 
+## Network Map & Maps of Making
+
+`GET /api/okw/map` (and `ohm okw map`) return the point set for the web UI's
+network map: **local OKW facilities unioned with [Maps of Making](https://mapsofmaking.org)
+(MoM) spaces**. Each point is source-labeled — `{id, name, lat, lon, source}` with
+`source` in `{"local", "mom"}` — so the map layer is source-agnostic and can grow
+to further networks.
+
+- **Coordinates** come from `Location.coordinates()` (the decimal-degrees
+  accessor). Local facilities without parseable coordinates are counted in
+  `dropped_no_coords` rather than plotted.
+- **MoM** is fetched from a **24h TTL cache** (`MoMSpacesCache` in
+  `services/mom_bridge.py`) built on the existing SPARQL bridge. It **degrades
+  gracefully**: if MoM is unreachable the response is local-only with
+  `mom_available: false`, and a stale cache keeps serving until a refresh
+  succeeds. `mom_spaces_cache.refresh()` / `.invalidate()` are the cache-refresh
+  hooks other events can call; the endpoint's `force_refresh=true` (and CLI
+  `--refresh`) trigger a refresh on demand.
+
 ## CLI Commands
 
 | Command | Description |
@@ -593,13 +612,15 @@ descriptions.
 | `ohm okw export` | Export the OKW JSON Schema |
 | `ohm okw template` | Output a blank facility template |
 | `ohm okw create-interactive` | Interactively build a new facility |
+| `ohm okw map` | Network map points: local facilities ∪ Maps of Making (`--no-mom`, `--refresh`) |
 
 ## API Endpoints
 
 | Method | Path | Description |
 |---|---|---|
 | `GET` | `/api/okw/export` | Export OKW JSON Schema |
 | `GET` | `/api/okw/template` | Get blank facility template |
+| `GET` | `/api/okw/map` | Network map points (local OKW ∪ Maps of Making); `include_mom`, `force_refresh` |
 | `POST` | `/api/okw/create` | Create facility from JSON body |
 | `POST` | `/api/okw/validate` | Validate a facility dict |
 | `POST` | `/api/okw/upload` | Upload a facility file |

src/cli/okw.py

@@ -498,6 +498,99 @@ async def fallback_list():
         raise
 
 
+@okw_group.command(name="map")
+@click.option(
+    "--no-mom",
+    is_flag=True,
+    help="Exclude Maps of Making; show local OKW facilities only.",
+)
+@click.option(
+    "--refresh",
+    is_flag=True,
+    help="Force a refresh of the MoM cache before building the map.",
+)
+@standard_cli_command(
+    help_text="""
+    List network map points: local OKW facilities unioned with Maps of Making.
+
+    Each point is source-labeled ("local" or "mom"). Local facilities without
+    coordinates are counted but not plotted. MoM is served from a 24h cache and
+    degrades gracefully — if it is unreachable you get local-only points.
+    """,
+    epilog="""
+    Examples:
+      ohm okw map                 # local + MoM
+      ohm okw map --no-mom        # local facilities only
+      ohm okw map --refresh       # force a MoM cache refresh first
+    """,
+    async_cmd=True,
+    track_performance=True,
+    handle_errors=True,
+    format_output=True,
+    add_llm_config=False,
+)
+@click.pass_context
+async def okw_map(
+    ctx,
+    no_mom: bool,
+    refresh: bool,
+    verbose: bool,
+    output_format: str,
+    use_llm: bool,
+    llm_provider: str,
+    llm_model: Optional[str],
+    quality_level: str,
+    strict_mode: bool,
+):
+    """List network map points (local OKW facilities ∪ Maps of Making)."""
+    cli_ctx = ctx.obj
+    cli_ctx.start_command_tracking("okw-map")
+    include_mom = not no_mom
+
+    try:
+
+        async def http_map():
+            cli_ctx.log("Fetching map points via HTTP API...", "info")
+            params = {
+                "include_mom": str(include_mom).lower(),
+                "force_refresh": str(refresh).lower(),
+            }
+            return await cli_ctx.api_client.request(
+                "GET", "/api/okw/map", params=params
+            )
+
+        async def fallback_map():
+            cli_ctx.log("Building map points via direct service...", "info")
+            okw_service = await OKWService.get_instance()
+            return await okw_service.get_map_points(
+                include_mom=include_mom, force_refresh=refresh
+            )
+
+        command = SmartCommand(cli_ctx)
+        result = await command.execute_with_fallback(http_map, fallback_map)
+        data = result.get("data", result) if isinstance(result, dict) else result
+
+        if output_format == "json":
+            click.echo(json.dumps(data, indent=2))
+        else:
+            mom_state = "available" if data.get("mom_available") else "unavailable"
+            click.echo(
+                f"🗺️  {len(data.get('points', []))} map points "
+                f"({data.get('local_count', 0)} local + {data.get('mom_count', 0)} MoM)"
+            )
+            dropped = data.get("dropped_no_coords", 0)
+            if dropped:
+                click.echo(f"   {dropped} local facility(ies) omitted (no coordinates)")
+            if include_mom:
+                click.echo(f"   Maps of Making: {mom_state}")
+
+        cli_ctx.end_command_tracking()
+
+    except Exception as e:
+        cli_ctx.log(f"Map build failed: {str(e)}", "error")
+        raise
+
+
 @okw_group.command()
 @click.argument("facility_id", type=str)
 @click.option("--force", is_flag=True, help="Force deletion without confirmation")

src/core/api/routes/okw.py

@@ -393,6 +393,49 @@ async def get_okw_template(http_request: Request = None) -> Any:
     }
 
 
+@router.get(
+    "/map",
+    summary="Network map points (local OKW ∪ Maps of Making)",
+    description="""
+    Return source-labeled geographic points for the network map: local OKW
+    facilities unioned with Maps of Making (MoM) spaces.
+
+    Each point is `{id, name, lat, lon, source}` where `source` is `"local"` or
+    `"mom"`. Local facilities without parseable coordinates are counted in
+    `dropped_no_coords` rather than plotted. MoM is served from a 24h TTL cache
+    and degrades gracefully — if MoM is unreachable the response is local-only
+    with `mom_available: false`.
+
+    Query params:
+    - `include_mom` (default true): set false for a local-only map.
+    - `force_refresh` (default false): force a MoM cache refresh first.
+    """,
+)
+async def get_okw_map(
+    include_mom: bool = True,
+    force_refresh: bool = False,
+    okw_service: OKWService = Depends(get_okw_service),
+) -> Any:
+    """Return network-map points (local OKW facilities ∪ MoM spaces)."""
+    try:
+        data = await okw_service.get_map_points(
+            include_mom=include_mom, force_refresh=force_refresh
+        )
+        return {"success": True, **data}
+    except Exception as e:
+        error_response = create_error_response(
+            error=e,
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            request_id=None,
+            suggestion="Please try again or contact support if the issue persists",
+        )
+        logger.error(f"Error building OKW map points: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=error_response.model_dump(mode="json"),
+        )
+
+
 @router.get("/{id}", response_model=OKWResponse)
 async def get_okw(
     id: UUID = Path(..., title="The ID of the OKW facility"),