feat(vector-search): enhance vector search functionality and integrate NVIDIA index

- Added `vector_search_utils.py` for semantic search with threshold capabilities, improving vector search efficiency.
- Updated `video_service.py` to utilize the new semantic search method, maintaining backward compatibility with existing keyword search.
- Introduced `attach_nvidia_vector_index.py` script to manage the NVIDIA Vectorize index for the `content_features` column in the database.
- Modified `schema-astra.cql` to adjust the `content_features` vector dimension to 1024 for optimized performance.
- Updated `pyproject.toml` to include new dependencies and scripts for enhanced functionality.
- Improved logging and error handling across the new and modified components.

Author: pmcfadin

app/services/vector_search_utils.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Tuple
+
+from app.db.astra_client import AstraDBCollection  # noqa: F401
+
+from app.models.video import VideoSummary
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _collect_docs_from_cursor(cursor):
+    """Return a list of docs from an astrapy cursor or a stub list in unit-tests."""
+
+    if asyncio.iscoroutine(cursor):
+        return cursor  # caller should await upstream
+
+    if hasattr(cursor, "to_list"):
+        return cursor.to_list()
+
+    # In unit tests we sometimes pass a list instead of a real cursor
+    return cursor
+
+
+async def semantic_search_with_threshold(
+    *,
+    db_table: AstraDBCollection,
+    vector_column: str,
+    query: str,
+    page: int,
+    page_size: int,
+    similarity_threshold: float = 0.0,
+    overfetch_factor: int = 3,
+) -> Tuple[List[VideoSummary], int]:
+    """Run a vector search and apply a client-side similarity cutoff.
+
+    Parameters
+    ----------
+    db_table : AstraDBCollection
+        Table / collection to query (must contain the *vector_column*).
+    vector_column : str
+        Name of the vector column to sort on, e.g. ``"content_features"``.
+    query : str
+        The natural-language query that will be embedded on-the-fly by Astra.
+    page / page_size : int
+        Standard pagination parameters expected by the public API.
+    similarity_threshold : float, optional
+        Keep only rows whose ``$similarity`` ≥ this value. Default 0 (no trim).
+    overfetch_factor : int, optional
+        How many extra rows to ask Astra for. 3× the *page_size* works well
+        for typical thresholds around 0.7-0.9.
+    """
+
+    if page < 1 or page_size < 1:
+        return [], 0
+
+    # Ask Astra for a generous slice so we can trim client-side.
+    overfetch = page_size * overfetch_factor * page  # grow with page number
+
+    cursor = db_table.find(
+        filter={},
+        sort={vector_column: query},
+        limit=overfetch,
+        include_similarity=True,  # ⭐
+    )
+
+    # Fetch docs.
+    docs: List[Dict[str, Any]]
+    if hasattr(cursor, "to_list"):
+        docs = await cursor.to_list()
+    else:
+        docs = cursor  # type: ignore[assignment]
+
+    logger.debug(
+        "Vector search fetched %s docs (page=%s, overfetch=%s)",
+        len(docs),
+        page,
+        overfetch,
+    )
+
+    if similarity_threshold > 0:
+        pre_trim = len(docs)
+        docs = [d for d in docs if d.get("$similarity", 0) >= similarity_threshold]
+        logger.debug(
+            "Trimmed by threshold %.2f: %s → %s docs", similarity_threshold, pre_trim, len(docs)
+        )
+
+    if docs:
+        logger.debug(
+            "Top doc similarity after trim: %.3f", docs[0].get("$similarity", -1.0)
+        )
+
+    total = len(docs)
+
+    # Slice to requested page.
+    start = (page - 1) * page_size
+    end = start + page_size
+    page_docs = docs[start:end]
+
+    summaries = [VideoSummary.model_validate(d) for d in page_docs]
+
+    return summaries, total 

app/services/video_service.py

@@ -704,25 +704,18 @@ async def search_videos_by_keyword(
     page_size: int,
     db_table: Optional[AstraDBCollection] = None,
 ) -> Tuple[List[VideoSummary], int]:
-    """Basic case-insensitive substring search across title, description, tags."""
+    """Keyword search fallback using Astra's semantic `$vectorize` sort.
 
-    if db_table is None:
-        db_table = await get_table(VIDEOS_TABLE_NAME)
-
-    escaped = re.escape(query)
-    search_filter: Dict[str, Any] = {
-        "$or": [
-            {"name": {"$regex": escaped, "$options": "i"}},
-            {"description": {"$regex": escaped, "$options": "i"}},
-            {"tags": {"$regex": escaped, "$options": "i"}},
-        ],
-    }
+    The Data API does not support `$regex` filters. Instead we rely on the
+    built-in vector search to rank results by textual similarity to *query*.
+    This mirrors what ``search_videos_by_semantic`` does but keeps the public
+    interface unchanged for callers expecting *keyword* search.
+    """
 
-    return await list_videos_with_query(
-        query_filter=search_filter,
+    return await search_videos_by_semantic(
+        query=query,
         page=page,
         page_size=page_size,
-        sort_options={"added_date": -1},
         db_table=db_table,
     )
 
@@ -759,14 +752,25 @@ async def search_videos_by_semantic(
             detail="Query exceeds 512-token limit for semantic search.",
         )
 
-    sort_vector = {"$vectorize": query}
+    # Delegate to reusable helper so we can later swap with server-side
+    # threshold once the Data API supports it natively.
 
-    return await list_videos_with_query(
-        query_filter={},
+    from app.services.vector_search_utils import (
+        semantic_search_with_threshold,
+    )
+
+    if db_table is None:
+        db_table = await get_table(VIDEOS_TABLE_NAME)
+
+    return await semantic_search_with_threshold(
+        db_table=db_table,
+        vector_column="content_features",
+        query=query,
         page=page,
         page_size=page_size,
-        sort_options=sort_vector,
-        db_table=db_table,
+        # NV-Embed scores rarely exceed ~0.75, so 0.65 keeps the top
+        # matches while still trimming weak ones.
+        similarity_threshold=0.65,
     )
 
 

docs/schema-astra.cql

@@ -87,7 +87,7 @@ CREATE TABLE IF NOT EXISTS killrvideo.videos (
     name text,
     preview_image_location text,
     tags set<text>,                              -- Collection for efficient tag storage
-    content_features vector<float, 4096>,         -- Vector type (4096-dim) for NV-Embed semantic search
+    content_features vector<float, 1024>,         -- Vector type (1024-dim) for NV-Embed semantic search
     userid uuid,
     content_rating text,                         -- 'G', 'PG', 'PG-13', 'R', etc.
     category text,
@@ -135,10 +135,13 @@ USING 'StorageAttachedIndex';
 
 -- Vector search index with COSINE similarity function
 -- Enables ANN searches for content-based recommendations
-CREATE CUSTOM INDEX IF NOT EXISTS videos_content_features_idx 
-ON killrvideo.videos(content_features) 
+CREATE CUSTOM INDEX videos_content_features_idx
+ON killrvideo.videos(content_features)
 USING 'StorageAttachedIndex'
-WITH OPTIONS = { 'similarity_function': 'COSINE' };
+WITH OPTIONS = {
+  'similarity_function' : 'COSINE',
+  'source_model'        : 'nv-qa-4'
+};
 
 -- Denormalized table for latest videos
 -- Supports queries: Get latest videos in chronological order