feat(api): add GET /specs/map endpoint

New endpoint returns one row per spec — id, title, best-impl
preview URLs (light/dark), best-impl quality_score, spec-level tags
and impl-level tags — for the upcoming /map page that clusters
specs by tag similarity.

Best-impl selection: highest quality_score with lexicographic
library_id tiebreak for determinism. Specs without implementations
are skipped, mirroring _build_specs_list.

Route is registered before /specs/{spec_id} so the path-parameter
route doesn't capture "map". Cache key specs_map is invalidated
alongside specs_list whenever a spec changes.

Refs #5646

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MarkusNeusinger

api/cache.py

@@ -178,6 +178,7 @@ def clear_spec_cache(spec_id: str) -> int:
     count += clear_cache_by_pattern(f"spec:{spec_id}")
     count += clear_cache_by_pattern(f"spec_images:{spec_id}")
     count += clear_cache_by_pattern("specs_list")  # List might have changed
+    count += clear_cache_by_pattern("specs_map")  # Map page payload might have changed
     count += clear_cache_by_pattern("filter:")  # Filters might be affected
     count += clear_cache_by_pattern("stats")  # Stats might have changed
     count += clear_cache_by_pattern("sitemap")  # Sitemap includes spec URLs

api/routers/specs.py

@@ -6,7 +6,7 @@
 from api.cache import cache_key, get_or_set_cache
 from api.dependencies import require_db
 from api.exceptions import raise_not_found
-from api.schemas import ImplementationResponse, SpecDetailResponse, SpecListItem
+from api.schemas import ImplementationResponse, SpecDetailResponse, SpecListItem, SpecMapItem
 from core.config import settings
 from core.database import ImplRepository, SpecRepository
 from core.database.connection import get_db_context
@@ -28,6 +28,33 @@ async def _build_specs_list(db: AsyncSession) -> list[SpecListItem]:
     ]
 
 
+async def _build_specs_map(db: AsyncSession) -> list[SpecMapItem]:
+    """One row per spec with its best-rated impl image + spec/impl tag bag for the /map page.
+
+    Best-impl tiebreak: highest quality_score, then lexicographic library_id for determinism.
+    Specs without any implementations are skipped (mirrors _build_specs_list).
+    """
+    repo = SpecRepository(db)
+    specs = await repo.get_all()
+    items: list[SpecMapItem] = []
+    for spec in specs:
+        if not spec.impls:
+            continue
+        best = max(spec.impls, key=lambda i: ((i.quality_score or 0.0), i.library_id))
+        items.append(
+            SpecMapItem(
+                id=spec.id,
+                title=spec.title,
+                preview_url_light=best.preview_url_light,
+                preview_url_dark=best.preview_url_dark,
+                quality_score=best.quality_score,
+                tags=spec.tags,
+                impl_tags=best.impl_tags,
+            )
+        )
+    return items
+
+
 async def _build_spec_detail(db: AsyncSession, spec_id: str) -> SpecDetailResponse:
     repo = SpecRepository(db)
     spec = await repo.get_by_id(spec_id)
@@ -125,6 +152,25 @@ async def _refresh() -> list[SpecListItem]:
     )
 
 
+@router.get("/specs/map", response_model=list[SpecMapItem])
+async def get_specs_map(db: AsyncSession = Depends(require_db)):
+    """Get one row per spec (best-impl image + tag bag) for the /map clustering page.
+
+    NOTE: must stay declared before /specs/{spec_id} so the path-parameter route doesn't capture "map".
+    """
+
+    async def _fetch() -> list[SpecMapItem]:
+        return await _build_specs_map(db)
+
+    async def _refresh() -> list[SpecMapItem]:
+        async with get_db_context() as fresh_db:
+            return await _build_specs_map(fresh_db)
+
+    return await get_or_set_cache(
+        cache_key("specs_map"), _fetch, refresh_after=settings.cache_refresh_after, refresh_factory=_refresh
+    )
+
+
 @router.get("/specs/{spec_id}", response_model=SpecDetailResponse)
 async def get_spec(spec_id: str, db: AsyncSession = Depends(require_db)):
     """Get detailed spec information including all implementations."""

api/schemas.py

@@ -69,6 +69,18 @@ class SpecListItem(BaseModel):
     library_count: int = 0
 
 
+class SpecMapItem(BaseModel):
+    """One row per spec for the /map page: best-impl preview + full tag bag for client-side similarity clustering."""
+
+    id: str
+    title: str
+    preview_url_light: str | None = None
+    preview_url_dark: str | None = None
+    quality_score: float | None = None
+    tags: dict[str, Any] | None = None
+    impl_tags: dict[str, Any] | None = None
+
+
 class ImageResponse(BaseModel):
     """Image/plot response for grid display."""
 

tests/unit/api/test_routers.py

@@ -347,6 +347,101 @@ def test_spec_detail_not_found(self, client: TestClient) -> None:
             response = client.get("/specs/nonexistent")
             assert response.status_code == 404
 
+    def test_specs_map_without_db(self, client: TestClient) -> None:
+        """Specs map should return 503 when DB not configured."""
+        with patch(DB_CONFIG_PATCH, return_value=False):
+            response = client.get("/specs/map")
+            assert response.status_code == 503
+
+    def test_specs_map_returns_list(self, client: TestClient, mock_spec) -> None:
+        """Specs map returns one row per spec with best-impl preview + tag bag."""
+        mock_spec_repo = MagicMock()
+        mock_spec_repo.get_all = AsyncMock(return_value=[mock_spec])
+
+        with (
+            patch(DB_CONFIG_PATCH, return_value=True),
+            patch("api.routers.specs.get_or_set_cache", side_effect=_passthrough_cache),
+            patch("api.routers.specs.SpecRepository", return_value=mock_spec_repo),
+        ):
+            response = client.get("/specs/map")
+            assert response.status_code == 200
+            data = response.json()
+            assert isinstance(data, list)
+            assert len(data) == 1
+            row = data[0]
+            assert row["id"] == "scatter-basic"
+            assert row["title"] == "Basic Scatter Plot"
+            assert row["preview_url_light"] == TEST_IMAGE_URL
+            assert row["quality_score"] == 92.5
+            assert row["tags"] == {
+                "plot_type": ["scatter"],
+                "domain": ["statistics"],
+                "data_type": ["numeric"],
+                "features": ["basic"],
+            }
+            assert row["impl_tags"] == {"patterns": ["data-generation"], "styling": ["alpha-blending"]}
+
+    def test_specs_map_picks_best_impl(self, client: TestClient, mock_spec) -> None:
+        """Specs map picks the impl with the highest quality_score per spec."""
+        # Append a second, lower-rated impl with a distinct preview URL
+        worse_impl = MagicMock()
+        worse_impl.library_id = "seaborn"
+        worse_impl.preview_url_light = "https://example.com/worse-light.png"
+        worse_impl.preview_url_dark = None
+        worse_impl.quality_score = 60.0
+        worse_impl.impl_tags = {"patterns": ["should-not-appear"]}
+        mock_spec.impls = [worse_impl, mock_spec.impls[0]]  # quality 60 then quality 92.5
+
+        mock_spec_repo = MagicMock()
+        mock_spec_repo.get_all = AsyncMock(return_value=[mock_spec])
+
+        with (
+            patch(DB_CONFIG_PATCH, return_value=True),
+            patch("api.routers.specs.get_or_set_cache", side_effect=_passthrough_cache),
+            patch("api.routers.specs.SpecRepository", return_value=mock_spec_repo),
+        ):
+            response = client.get("/specs/map")
+            assert response.status_code == 200
+            data = response.json()
+            assert len(data) == 1
+            assert data[0]["preview_url_light"] == TEST_IMAGE_URL  # higher-rated matplotlib impl
+            assert data[0]["quality_score"] == 92.5
+            assert data[0]["impl_tags"] == {"patterns": ["data-generation"], "styling": ["alpha-blending"]}
+
+    def test_specs_map_skips_specs_without_impls(self, client: TestClient, mock_spec) -> None:
+        """Specs map omits specs with zero implementations (matches /specs behavior)."""
+        empty_spec = MagicMock()
+        empty_spec.id = "no-impls"
+        empty_spec.title = "No Implementations Yet"
+        empty_spec.impls = []
+
+        mock_spec_repo = MagicMock()
+        mock_spec_repo.get_all = AsyncMock(return_value=[mock_spec, empty_spec])
+
+        with (
+            patch(DB_CONFIG_PATCH, return_value=True),
+            patch("api.routers.specs.get_or_set_cache", side_effect=_passthrough_cache),
+            patch("api.routers.specs.SpecRepository", return_value=mock_spec_repo),
+        ):
+            response = client.get("/specs/map")
+            assert response.status_code == 200
+            data = response.json()
+            assert [row["id"] for row in data] == ["scatter-basic"]
+
+    def test_specs_map_empty_db(self, client: TestClient) -> None:
+        """Specs map returns [] (not 404) when there are no specs."""
+        mock_spec_repo = MagicMock()
+        mock_spec_repo.get_all = AsyncMock(return_value=[])
+
+        with (
+            patch(DB_CONFIG_PATCH, return_value=True),
+            patch("api.routers.specs.get_or_set_cache", side_effect=_passthrough_cache),
+            patch("api.routers.specs.SpecRepository", return_value=mock_spec_repo),
+        ):
+            response = client.get("/specs/map")
+            assert response.status_code == 200
+            assert response.json() == []
+
 
 class TestDownloadRouter:
     """Tests for download router."""