Search fixes

Author: webstackdev

_TODO.md

@@ -170,8 +170,6 @@ Need a tooltip component for consistency. List to add tooltips to:
 
 ## Support Pages to Style
 
-- /404 (should show search results based on query)
-- /search
 - Bug reporter modal
 - Email templates
 
@@ -213,8 +211,3 @@ All code samples in this article are licensed under the MIT License. Feel free t
 - Home page reorganization: move the "What I Deliver" box from the Hero into the Backstage image. Move the Backstage image / video to the hero.
 
 - Add a "Preview Special" item to our Download CTA that lets the user know the Deep Dive content can be previewed in HTML format, and offer a switch to it.
-
-
-## Search
-
-- The modal on the search page should be different than returning results - maybe the page results should update as you type

package.json

@@ -55,7 +55,8 @@
     "lint:style": "FORCE_COLOR=1 npx stylelint \"src/**/*.{css,astro}\"",
     "lint:tsc:check": "npm run sync && tsc --noEmit -p tsconfig.json --pretty false",
     "search:reindex": "python3 scripts/search-index.py",
-    "search:relevancy": "python3 scripts/test_search_relevancy.py",
+    "search:relevancy": "python3 scripts/search_relevancy.py",
+    "search:relevancy:reranking": "python3 scripts/search_relevancy.py --reranking",
     "sync": "FORCE_COLOR=1 npx astro sync",
     "test": "npm run test:unit && npm run test:e2e",
     "test:coverage": "FORCE_COLOR=1 npx vitest run --coverage",

scripts/search_relevancy.py

@@ -6,7 +6,6 @@
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Final
-from urllib.parse import urlparse
 
 from dotenv import load_dotenv
 from upstash_search import Search
@@ -17,9 +16,9 @@
 
 
 @dataclass(slots=True)
-class ArticleRelevancyRow:
-  path: str
+class SearchRelevancyRow:
   title: str
+  path: str
   score: float
 
 
@@ -61,132 +60,88 @@ def get_value(source: Any, key: str) -> Any:
   return getattr(source, key, None)
 
 
-def normalize_path(value: Any) -> str:
-  if not isinstance(value, str):
-    return ''
-
-  trimmed = value.strip()
-  if not trimmed:
-    return ''
-
-  if trimmed.startswith('http://') or trimmed.startswith('https://'):
-    parsed = urlparse(trimmed)
-    path = parsed.path or ''
-    suffix = ''
-    if parsed.query:
-      suffix = f'?{parsed.query}'
-    if parsed.fragment:
-      suffix = f'{suffix}#{parsed.fragment}'
-    return f'{path}{suffix}'
-
-  return trimmed
-
-
-def get_base_article_path(path: str) -> str:
-  without_query = path.split('?', 1)[0]
-  without_fragment = without_query.split('#', 1)[0]
-  return without_fragment.rstrip('/')
-
-
-def is_article_path(path: str) -> bool:
-  return path.startswith('/articles/') and len(path.split('/')) >= 3
-
-
-def slug_to_title(slug: str) -> str:
-  words = [word for word in slug.replace('_', '-').split('-') if word]
-  return ' '.join(word.capitalize() for word in words)
-
-
-def get_article_title(result: Any, article_path: str) -> str:
+def get_result_title(result: Any) -> str:
   content = get_value(result, 'content') or {}
-  title = get_value(content, 'title')
+  title = get_value(content, 'title') or get_value(content, 'name') or get_value(result, 'id')
   if isinstance(title, str) and title.strip():
-    result_path = normalize_path(
-      get_value(get_value(result, 'metadata') or {}, 'path')
-      or get_value(get_value(result, 'metadata') or {}, 'url')
-      or get_value(content, 'path')
-      or get_value(content, 'url')
-    )
-    if '#' not in result_path:
-      return title.strip()
+    return title.strip()
+  return '(untitled result)'
 
-  slug = article_path.rsplit('/', 1)[-1]
-  return slug_to_title(slug)
 
+def get_result_path(result: Any) -> str:
+  content = get_value(result, 'content') or {}
+  metadata = get_value(result, 'metadata') or {}
+  path = (
+    get_value(metadata, 'path')
+    or get_value(metadata, 'url')
+    or get_value(content, 'path')
+    or get_value(content, 'url')
+  )
 
-def collect_article_relevancy_rows(results: list[Any]) -> list[ArticleRelevancyRow]:
-  grouped: dict[str, ArticleRelevancyRow] = {}
+  if isinstance(path, str) and path.strip():
+    return path.strip()
 
-  for result in results:
-    metadata = get_value(result, 'metadata') or {}
-    content = get_value(result, 'content') or {}
-    path = normalize_path(
-      get_value(metadata, 'path')
-      or get_value(metadata, 'url')
-      or get_value(content, 'path')
-      or get_value(content, 'url')
-    )
+  return '(no path)'
 
-    article_path = get_base_article_path(path)
-    if not is_article_path(article_path):
-      continue
 
+def collect_search_relevancy_rows(results: list[Any]) -> list[SearchRelevancyRow]:
+  rows: list[SearchRelevancyRow] = []
+
+  for result in results:
     raw_score = get_value(result, 'score')
     if not isinstance(raw_score, int | float):
       continue
 
-    candidate = ArticleRelevancyRow(
-      path=article_path,
-      title=get_article_title(result, article_path),
-      score=float(raw_score),
+    rows.append(
+      SearchRelevancyRow(
+        title=get_result_title(result),
+        path=get_result_path(result),
+        score=float(raw_score),
+      )
     )
 
-    existing = grouped.get(article_path)
-    if existing is None:
-      grouped[article_path] = candidate
-      continue
-
-    if candidate.score > existing.score:
-      title = existing.title
-      if '#' not in path and candidate.title.strip():
-        title = candidate.title
-      grouped[article_path] = ArticleRelevancyRow(path=article_path, title=title, score=candidate.score)
-      continue
-
-    if '#' not in path and candidate.title.strip() and existing.title == slug_to_title(article_path.rsplit('/', 1)[-1]):
-      grouped[article_path] = ArticleRelevancyRow(path=article_path, title=candidate.title, score=existing.score)
-
-  return sorted(grouped.values(), key=lambda row: row.score, reverse=True)
+  return rows
 
 
 def format_score(score: float) -> str:
   return f'{score:.6f}'.rstrip('0').rstrip('.')
 
 
-def format_results_table(rows: list[ArticleRelevancyRow]) -> str:
-  title_header = 'Article Title'
+def format_results_table(rows: list[SearchRelevancyRow], *, show_path: bool = True) -> str:
+  title_header = 'Result Title'
+  path_header = 'Path'
   score_header = 'Relevancy Score'
 
   title_width = max([len(title_header), *(len(row.title) for row in rows)])
+  path_width = max([len(path_header), *(len(row.path) for row in rows)]) if show_path else 0
   score_values = [format_score(row.score) for row in rows]
   score_width = max([len(score_header), *(len(value) for value in score_values)])
 
+  if show_path:
+    separator = f'+-{'-' * title_width}-+-{'-' * path_width}-+-{'-' * score_width}-+'
+    header = (
+      f'| {title_header.ljust(title_width)} | '
+      f'{path_header.ljust(path_width)} | '
+      f'{score_header.rjust(score_width)} |'
+    )
+    body = [
+      f'| {row.title.ljust(title_width)} | {row.path.ljust(path_width)} | {format_score(row.score).rjust(score_width)} |'
+      for row in rows
+    ]
+    return '\n'.join([separator, header, separator, *body, separator])
+
   separator = f'+-{'-' * title_width}-+-{'-' * score_width}-+'
   header = f'| {title_header.ljust(title_width)} | {score_header.rjust(score_width)} |'
-
-  body = [
-    f'| {row.title.ljust(title_width)} | {format_score(row.score).rjust(score_width)} |'
-    for row in rows
-  ]
+  body = [f'| {row.title.ljust(title_width)} | {format_score(row.score).rjust(score_width)} |' for row in rows]
 
   return '\n'.join([separator, header, separator, *body, separator])
 
 
-def run_search(*, query: str, limit: int, index_name: str | None = None) -> list[ArticleRelevancyRow]:
+def run_search(*, query: str, limit: int, index_name: str | None = None, reranking: bool = False) -> list[SearchRelevancyRow]:
   url, token, default_index_name = resolve_upstash_credentials()
   client = Search(url=url, token=token)
-  raw_results = client.index(index_name or default_index_name).search(query, limit=limit, reranking=True)
-  return collect_article_relevancy_rows(raw_results)
+  raw_results = client.index(index_name or default_index_name).search(query, limit=limit, reranking=reranking)
+  return collect_search_relevancy_rows(raw_results)
 
 
 def parse_args(argv: list[str]) -> argparse.Namespace:
@@ -196,6 +151,8 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
   parser.add_argument('query', help='Search query. Wrap multi-word queries in quotes.')
   parser.add_argument('--limit', type=int, default=DEFAULT_LIMIT, help='Maximum Upstash results to request.')
   parser.add_argument('--index-name', default=None, help='Override the Upstash index name.')
+  parser.add_argument('--reranking', action='store_true', help='Enable Upstash reranking for the query.')
+  parser.add_argument('--hide-path', action='store_true', help='Hide the path column from the output table.')
   return parser.parse_args(argv)
 
 
@@ -204,16 +161,16 @@ def main(argv: list[str] | None = None) -> int:
 
   try:
     load_environment()
-    rows = run_search(query=args.query, limit=args.limit, index_name=args.index_name)
+    rows = run_search(query=args.query, limit=args.limit, index_name=args.index_name, reranking=args.reranking)
   except Exception as exc:  # noqa: BLE001
     print(f'[search:relevancy] {exc}', file=sys.stderr)
     return 1
 
   if not rows:
-    print(f'No article results found for query: {args.query}')
+    print(f'No results found for query: {args.query}')
     return 0
 
-  print(format_results_table(rows))
+  print(format_results_table(rows, show_path=not args.hide_path))
   return 0
 
 

scripts/test_search_relevancy.py

@@ -1,8 +1,8 @@
-from scripts.search_relevancy import ArticleRelevancyRow, collect_article_relevancy_rows, format_results_table
+from scripts.search_relevancy import SearchRelevancyRow, collect_search_relevancy_rows, format_results_table
 
 
-def test_collect_article_relevancy_rows_groups_sections_by_article() -> None:
-  rows = collect_article_relevancy_rows(
+def test_collect_search_relevancy_rows_preserves_all_scored_results() -> None:
+  rows = collect_search_relevancy_rows(
     [
       {
         'content': {'title': 'Introduction'},
@@ -19,27 +19,48 @@ def test_collect_article_relevancy_rows_groups_sections_by_article() -> None:
         'metadata': {'path': '/case-studies/platform-migration'},
         'score': 0.95,
       },
+      {
+        'content': {'title': 'Missing Score'},
+        'metadata': {'path': '/articles/missing-score'},
+      },
     ]
   )
 
   assert rows == [
-    ArticleRelevancyRow(
-      path='/articles/typescript-best-practices',
+    SearchRelevancyRow(title='Introduction', path='/articles/typescript-best-practices#introduction', score=0.72),
+    SearchRelevancyRow(
       title='TypeScript Best Practices for Modern Development',
+      path='/articles/typescript-best-practices',
       score=1.0,
-    )
+    ),
+    SearchRelevancyRow(title='Case Study', path='/case-studies/platform-migration', score=0.95),
   ]
 
 
-def test_format_results_table_renders_two_columns() -> None:
+def test_format_results_table_renders_path_column_by_default() -> None:
   table = format_results_table(
     [
-      ArticleRelevancyRow(path='/articles/one', title='Article One', score=1.0),
-      ArticleRelevancyRow(path='/articles/two', title='Article Two', score=0.875),
+      SearchRelevancyRow(title='Article One', path='/articles/one', score=1.0),
+      SearchRelevancyRow(title='Article Two', path='/articles/two', score=0.875),
     ]
   )
 
-  assert 'Article Title' in table
+  assert 'Result Title' in table
+  assert 'Path' in table
   assert 'Relevancy Score' in table
   assert 'Article One' in table
-  assert '0.875' in table
+  assert '/articles/one' in table
+  assert '0.875' in table
+
+
+def test_format_results_table_can_hide_path_column() -> None:
+  table = format_results_table(
+    [
+      SearchRelevancyRow(title='Article One', path='/articles/one', score=1.0),
+    ],
+    show_path=False,
+  )
+
+  assert 'Result Title' in table
+  assert 'Path' not in table
+  assert '/articles/one' not in table