Merge origin/master into feature/bm25

Resolved conflicts:
- viz_routes.py: Kept bm25's extract_dense_vector() function for robust vector handling
- hybrid.py: Removed (bm25 uses native Qdrant RRF fusion instead)
- uv.lock: Regenerated after accepting master's dependencies

This merge brings in:
- RAG evaluation framework (ADR-013)
- Performance optimizations (double-fetch elimination)
- Migration from asyncio to anyio
- OpenTelemetry tracing improvements
- Notes app enhancements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

nextcloud_mcp_server/auth/storage.py

@@ -1310,7 +1310,7 @@ async def generate_encryption_key() -> str:
 
 # Example usage
 if __name__ == "__main__":
-    import asyncio
+    import anyio
 
     async def main():
         # Generate a key for testing
@@ -1318,4 +1318,4 @@ if __name__ == "__main__":
         print(f"Generated encryption key: {key}")
         print(f"Set this in your environment: export TOKEN_ENCRYPTION_KEY='{key}'")
 
-    asyncio.run(main())
+    anyio.run(main)

nextcloud_mcp_server/auth/token_broker.py

@@ -14,11 +14,11 @@ The Token Broker provides:
 - Session vs background token separation (RFC 8693)
 """
 
-import asyncio
 import logging
 from datetime import datetime, timedelta, timezone
 from typing import Dict, Optional, Tuple
 
+import anyio
 import httpx
 import jwt
 from cryptography.fernet import Fernet
@@ -43,7 +43,7 @@ class TokenCache:
         self._cache: Dict[str, Tuple[str, datetime]] = {}
         self._ttl = timedelta(seconds=ttl_seconds)
         self._early_refresh = timedelta(seconds=early_refresh_seconds)
-        self._lock = asyncio.Lock()
+        self._lock = anyio.Lock()
 
     async def get(self, user_id: str) -> Optional[str]:
         """Get cached token if valid."""

nextcloud_mcp_server/auth/userinfo_routes.py

@@ -719,6 +719,11 @@ async def user_info_html(request: Request) -> HTMLResponse:
                     }},
 
                     renderPlot(coordinates, results) {{
+                        // Calculate score range for auto-scaling
+                        const scores = results.map(r => r.score);
+                        const minScore = Math.min(...scores);
+                        const maxScore = Math.max(...scores);
+
                         const trace = {{
                             x: coordinates.map(c => c[0]),
                             y: coordinates.map(c => c[1]),
@@ -726,11 +731,18 @@ async def user_info_html(request: Request) -> HTMLResponse:
                             type: 'scatter',
                             text: results.map(r => `${{r.title}}<br>Score: ${{r.score.toFixed(3)}}`),
                             marker: {{
-                                size: 8,
-                                color: results.map(r => r.score),
+                                // Multi-channel encoding: size + opacity + color for visual hierarchy
+                                // Power scaling (score^2) amplifies visual differences dramatically
+                                // score=0.0 → 6px, score=0.5 → 9.5px, score=1.0 → 20px
+                                size: results.map(r => 6 + (Math.pow(r.score, 2) * 14)),
+                                // Linear opacity scaling (0.2-1.0 range keeps all points visible)
+                                opacity: results.map(r => 0.2 + (r.score * 0.8)),
+                                // Color gradient shows score
+                                color: scores,
                                 colorscale: 'Viridis',
                                 showscale: true,
-                                colorbar: {{ title: 'Score' }},
+                                colorbar: {{ title: 'Relative Score' }},
+                                // Scores are normalized 0-1 within result set
                                 cmin: 0,
                                 cmax: 1
                             }}

nextcloud_mcp_server/auth/viz_routes.py

@@ -11,6 +11,7 @@ All processing happens server-side following ADR-012:
 """
 
 import logging
+import time
 
 import numpy as np
 from starlette.authentication import requires
@@ -362,56 +363,17 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
     )
 
     try:
+        # Start total request timer
+        request_start = time.perf_counter()
         # Get authenticated HTTP client from session
         # In BasicAuth mode: uses username/password from session
         # In OAuth mode: uses access token from session
         from nextcloud_mcp_server.auth.userinfo_routes import (
             _get_authenticated_client_for_userinfo,
         )
-        from nextcloud_mcp_server.client.notes import NotesClient
 
-        async with await _get_authenticated_client_for_userinfo(request) as http_client:
-            # Create NotesClient directly with authenticated HTTP client
-            notes_client = NotesClient(http_client, username)
-
-            # Wrap in a minimal client object for search algorithms
-            # This conforms to NextcloudClientProtocol but only implements notes
-            class MinimalNextcloudClient:
-                def __init__(self, notes_client, username):
-                    self._notes = notes_client
-                    self.username = username
-
-                @property
-                def notes(self):
-                    return self._notes
-
-                @property
-                def webdav(self):
-                    return None
-
-                @property
-                def calendar(self):
-                    return None
-
-                @property
-                def contacts(self):
-                    return None
-
-                @property
-                def deck(self):
-                    return None
-
-                @property
-                def cookbook(self):
-                    return None
-
-                @property
-                def tables(self):
-                    return None
-
-            nextcloud_client = MinimalNextcloudClient(notes_client, username)
-
-            # Create search algorithm
+        async with await _get_authenticated_client_for_userinfo(request) as http_client:  # noqa: F841
+            # Create search algorithm (no client needed - verification removed)
             if algorithm == "semantic":
                 search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
             elif algorithm == "bm25_hybrid":
@@ -424,6 +386,7 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
 
             # Execute search (supports cross-app when doc_types=None)
             # Get unverified results with buffer for filtering
+            search_start = time.perf_counter()
             all_results = []
             if doc_types is None or len(doc_types) == 0:
                 # Cross-app search - search all indexed types
@@ -449,13 +412,28 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
                 # Sort by score before verification
                 all_results.sort(key=lambda r: r.score, reverse=True)
 
-            # Verify access for all results (deduplicates and filters)
-            from nextcloud_mcp_server.search.verification import verify_search_results
+            # No verification needed for visualization - we only need Qdrant metadata
+            # (title, excerpt, doc_type) which is already in search results.
+            # Verification is only needed for sampling (LLM needs full content).
+            search_results = all_results[:limit]
+            search_duration = time.perf_counter() - search_start
 
-            verified_results = await verify_search_results(
-                all_results, nextcloud_client
+        # Normalize scores relative to this result set for better visualization
+        # (best result = 1.0, worst result = 0.0 within THIS result set)
+        # This makes visual encoding meaningful regardless of RRF normalization
+        if search_results:
+            scores = [r.score for r in search_results]
+            min_score, max_score = min(scores), max(scores)
+            score_range = max_score - min_score if max_score > min_score else 1.0
+
+            logger.info(
+                f"Normalizing scores for viz: original range [{min_score:.3f}, {max_score:.3f}] "
+                f"→ [0.0, 1.0]"
             )
-            search_results = verified_results[:limit]
+
+            # Rescale each result's score to 0-1 within this result set
+            for r in search_results:
+                r.score = (r.score - min_score) / score_range
 
         if not search_results:
             return JSONResponse(
@@ -468,6 +446,7 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             )
 
         # Fetch vectors for matching results from Qdrant
+        vector_fetch_start = time.perf_counter()
         qdrant_client = await get_qdrant_client()
         doc_ids = [r.id for r in search_results]
 
@@ -518,6 +497,7 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
         vectors = np.array(
             [v for v in (extract_dense_vector(p) for p in points) if v is not None]
         )
+        vector_fetch_duration = time.perf_counter() - vector_fetch_start
 
         if len(vectors) < 2:
             # Not enough points for PCA
@@ -540,8 +520,10 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             )
 
         # Apply PCA dimensionality reduction (768-dim → 2D)
+        pca_start = time.perf_counter()
         pca = PCA(n_components=2)
         coords_2d = pca.fit_transform(vectors)
+        pca_duration = time.perf_counter() - pca_start
 
         # After fit, these attributes are guaranteed to be set
         assert pca.explained_variance_ratio_ is not None
@@ -574,6 +556,18 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             for r in search_results
         ]
 
+        # Calculate total request duration
+        total_duration = time.perf_counter() - request_start
+
+        # Log comprehensive timing metrics
+        logger.info(
+            f"Viz search timing: total={total_duration * 1000:.1f}ms, "
+            f"search={search_duration * 1000:.1f}ms ({search_duration / total_duration * 100:.1f}%), "
+            f"vector_fetch={vector_fetch_duration * 1000:.1f}ms ({vector_fetch_duration / total_duration * 100:.1f}%), "
+            f"pca={pca_duration * 1000:.1f}ms ({pca_duration / total_duration * 100:.1f}%), "
+            f"results={len(search_results)}, vectors={len(vectors)}"
+        )
+
         return JSONResponse(
             {
                 "success": True,
@@ -583,6 +577,14 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
                     "pc1": float(pca.explained_variance_ratio_[0]),
                     "pc2": float(pca.explained_variance_ratio_[1]),
                 },
+                "timing": {
+                    "total_ms": round(total_duration * 1000, 2),
+                    "search_ms": round(search_duration * 1000, 2),
+                    "vector_fetch_ms": round(vector_fetch_duration * 1000, 2),
+                    "pca_ms": round(pca_duration * 1000, 2),
+                    "num_results": len(search_results),
+                    "num_vectors": len(vectors),
+                },
             }
         )