@reftrixmcp/ml 0.1.7

package/src/search/hybrid.ts

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2025-2026 Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Hybrid Search Service
+ *
+ * Combines vector search (pgvector cosine similarity) and full-text search
+ * (PostgreSQL tsvector/tsquery) using Reciprocal Rank Fusion (RRF).
+ *
+ * Default weights: 60% vector + 40% full-text
+ */
+
+import { mergeWithRRF, normalizeRRFScore } from "./rrf.js";
+import type { RankedItem, RRFScoredItem } from "./rrf.js";
+
+/**
+ * Configuration for hybrid search execution
+ */
+export interface HybridSearchConfig {
+  /** Weight for vector search results (default 0.6) */
+  vectorWeight?: number;
+  /** Weight for full-text search results (default 0.4) */
+  fulltextWeight?: number;
+  /** RRF constant k (default 60) */
+  k?: number;
+}
+
+/**
+ * Result from hybrid search with normalized similarity score
+ */
+export interface HybridSearchResult {
+  id: string;
+  /** Normalized similarity score (0-1) */
+  similarity: number;
+  /** Source information for debugging */
+  source: {
+    vectorRank?: number;
+    fulltextRank?: number;
+  };
+  /** Additional data from the search result */
+  data: Record<string, unknown>;
+}
+
+const DEFAULT_CONFIG: Required<HybridSearchConfig> = {
+  vectorWeight: 0.6,
+  fulltextWeight: 0.4,
+  k: 60,
+};
+
+/**
+ * Execute hybrid search by combining vector and full-text search results with RRF
+ *
+ * Both search functions are executed in parallel via Promise.all for minimum latency.
+ * Results are merged using Reciprocal Rank Fusion (RRF) with configurable weights.
+ *
+ * @param vectorSearchFn - Function that returns vector search results (ranked by cosine similarity)
+ * @param fulltextSearchFn - Function that returns full-text search results (ranked by ts_rank_cd)
+ * @param config - Optional hybrid search configuration
+ * @returns Merged results sorted by normalized RRF similarity score
+ */
+export async function executeHybridSearch(
+  vectorSearchFn: () => Promise<RankedItem[]>,
+  fulltextSearchFn: () => Promise<RankedItem[]>,
+  config?: HybridSearchConfig
+): Promise<HybridSearchResult[]> {
+  const { vectorWeight, fulltextWeight, k } = {
+    ...DEFAULT_CONFIG,
+    ...config,
+  };
+
+  // Execute both searches in parallel for minimum latency
+  const [vectorResults, fulltextResults] = await Promise.all([
+    vectorSearchFn(),
+    fulltextSearchFn(),
+  ]);
+
+  // If one source returns empty, fall back to the other source only
+  if (vectorResults.length === 0 && fulltextResults.length === 0) {
+    return [];
+  }
+
+  // Merge with RRF
+  const merged: RRFScoredItem[] = mergeWithRRF(
+    vectorResults,
+    fulltextResults,
+    vectorWeight,
+    fulltextWeight,
+    k
+  );
+
+  // Normalize scores and format output
+  return merged.map((item: RRFScoredItem): HybridSearchResult => {
+    const source: HybridSearchResult["source"] = {};
+    if (item.vectorRank !== undefined) {
+      source.vectorRank = item.vectorRank;
+    }
+    if (item.fulltextRank !== undefined) {
+      source.fulltextRank = item.fulltextRank;
+    }
+    return {
+      id: item.id,
+      similarity: normalizeRRFScore(item.rrfScore),
+      source,
+      data: item.data,
+    };
+  });
+}

package/src/search/index.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Search utilities exports
+ *
+ * RRF utilities and types for WebDesign search services.
+ */
+
+export { calculateRRF, mergeWithRRF, normalizeRRFScore, toRankedItems } from "./rrf.js";
+export type { RankedItem, RRFScoredItem } from "./rrf.js";
+export { executeHybridSearch } from "./hybrid.js";
+export { buildFulltextConditions, buildFulltextRankExpression } from "./fulltext-helpers.js";
+export type { HybridSearchConfig, HybridSearchResult } from "./hybrid.js";
+export type {
+  SearchFilters,
+  SearchOptions,
+  HybridSearchOptions,
+  SearchResult,
+  SummarySearchResult,
+  SearchResultItem,
+  SummarySearchResultItem,
+  VectorSearchRawResult,
+  FullTextSearchRawResult,
+} from "./types.js";

package/src/search/rrf.ts

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Reciprocal Rank Fusion (RRF) implementation
+ *
+ * RRF is a method for combining rankings from multiple search sources.
+ * It's particularly useful for hybrid search combining vector and full-text results.
+ *
+ * Formula: score = 1 / (k + rank)
+ * where k is a constant (typically 60) that prevents high-ranked items from
+ * dominating the final ranking.
+ */
+
+/**
+ * Item with ranking information from a single source
+ */
+export interface RankedItem {
+  id: string;
+  rank: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Item with combined RRF score
+ */
+export interface RRFScoredItem {
+  id: string;
+  rrfScore: number;
+  vectorRank?: number;
+  fulltextRank?: number;
+  data: Record<string, unknown>;
+}
+
+/**
+ * Calculate RRF score for a single rank position
+ *
+ * @param rank - Rank position (1-based)
+ * @param k - Ranking constant (default 60)
+ * @returns RRF score
+ */
+export function calculateRRF(rank: number, k: number = 60): number {
+  return 1 / (k + rank);
+}
+
+/**
+ * Merge results from vector and full-text search using RRF
+ *
+ * @param vectorResults - Results from vector similarity search
+ * @param fulltextResults - Results from full-text search
+ * @param vectorWeight - Weight for vector search results (default 0.6)
+ * @param fulltextWeight - Weight for full-text search results (default 0.4)
+ * @param k - RRF constant (default 60)
+ * @returns Merged and sorted results
+ */
+export function mergeWithRRF(
+  vectorResults: RankedItem[],
+  fulltextResults: RankedItem[],
+  vectorWeight: number = 0.6,
+  fulltextWeight: number = 0.4,
+  k: number = 60
+): RRFScoredItem[] {
+  const scoreMap = new Map<string, RRFScoredItem>();
+
+  // Process vector search results
+  vectorResults.forEach((item, index) => {
+    const rank = index + 1; // 1-based rank
+    const rrfScore = calculateRRF(rank, k) * vectorWeight;
+
+    const existing = scoreMap.get(item.id);
+    if (existing) {
+      existing.rrfScore += rrfScore;
+      existing.vectorRank = rank;
+    } else {
+      const { id: _id, rank: _, ...data } = item;
+      scoreMap.set(item.id, {
+        id: item.id,
+        rrfScore,
+        vectorRank: rank,
+        data: data as Record<string, unknown>,
+      });
+    }
+  });
+
+  // Process full-text search results
+  fulltextResults.forEach((item, index) => {
+    const rank = index + 1; // 1-based rank
+    const rrfScore = calculateRRF(rank, k) * fulltextWeight;
+
+    const existing = scoreMap.get(item.id);
+    if (existing) {
+      existing.rrfScore += rrfScore;
+      existing.fulltextRank = rank;
+      // Merge additional data if not present
+      existing.data = { ...item, ...existing.data };
+    } else {
+      const { id: _id, rank: _, ...data } = item;
+      scoreMap.set(item.id, {
+        id: item.id,
+        rrfScore,
+        fulltextRank: rank,
+        data: data as Record<string, unknown>,
+      });
+    }
+  });
+
+  // Convert to array and sort by RRF score (descending)
+  const merged = Array.from(scoreMap.values());
+  merged.sort((a, b) => b.rrfScore - a.rrfScore);
+
+  if (process.env.NODE_ENV === "development") {
+    // eslint-disable-next-line no-console
+    console.log("[Search] RRF merge completed:", {
+      vectorCount: vectorResults.length,
+      fulltextCount: fulltextResults.length,
+      mergedCount: merged.length,
+      topScore: merged[0]?.rrfScore,
+    });
+  }
+
+  return merged;
+}
+
+/**
+ * Convert an array of rows (with an `id` field) into RankedItem[] with 1-based ranks.
+ *
+ * The array order is preserved and used for rank assignment.
+ * All fields from each row are spread into the resulting RankedItem.
+ *
+ * @param rows - Array of objects that each contain at least an `id: string` field
+ * @returns RankedItem[] with rank starting from 1
+ */
+export function toRankedItems<T extends { id: string }>(rows: T[]): RankedItem[] {
+  return rows.map((row, index) => ({
+    ...row,
+    rank: index + 1,
+  }));
+}
+
+/**
+ * Calculate effective score from RRF for display purposes
+ * Normalizes the RRF score to a 0-1 range
+ *
+ * @param rrfScore - Raw RRF score
+ * @param maxPossibleScore - Maximum possible score (sum of max vector and fulltext scores)
+ * @returns Normalized similarity score (0-1)
+ */
+export function normalizeRRFScore(rrfScore: number, maxPossibleScore?: number): number {
+  // Default max score: best possible rank (1) in both searches with default weights
+  const defaultMax = calculateRRF(1, 60) * 0.6 + calculateRRF(1, 60) * 0.4;
+  const maxScore = maxPossibleScore ?? defaultMax;
+
+  return Math.min(1, rrfScore / maxScore);
+}

package/src/search/types.ts

@@ -0,0 +1,141 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Search service type definitions
+ *
+ * WebDesign専用 - Layout (SectionPattern) and Motion (MotionPattern) search
+ */
+
+/**
+ * Search filter options for WebDesign patterns
+ */
+export interface SearchFilters {
+  /** Pattern type filter (hero, feature, cta, footer, etc.) */
+  type?: string | undefined;
+  /** Trigger filter for motion patterns (scroll, hover, click, load) */
+  trigger?: string | undefined;
+  /** Category filter for motion patterns (entrance, exit, emphasis, etc.) */
+  category?: string | undefined;
+  /** Tag filters */
+  tags?: string[] | undefined;
+  /** Page ID filter */
+  pageId?: string | undefined;
+}
+
+/**
+ * Search options for all search methods
+ */
+export interface SearchOptions {
+  /** Maximum number of results to return */
+  limit: number;
+  /** Offset for pagination */
+  offset?: number | undefined;
+  /** Search filters */
+  filters?: SearchFilters | undefined;
+  /** Summary mode: returns only id, name, similarity (default: false) */
+  summary?: boolean | undefined;
+}
+
+/**
+ * Hybrid search options extending base options
+ */
+export interface HybridSearchOptions extends SearchOptions {
+  /** Weight for vector search results (default 0.6) */
+  vectorWeight?: number | undefined;
+  /** Weight for full-text search results (default 0.4) */
+  fulltextWeight?: number | undefined;
+  /** Minimum similarity threshold (0-1) */
+  minSimilarity?: number | undefined;
+}
+
+/**
+ * Individual search result item for WebDesign patterns
+ */
+export interface SearchResultItem {
+  id: string;
+  name: string;
+  type: string;
+  description: string | undefined;
+  similarity: number;
+  /** HTML snippet for layout patterns */
+  htmlSnippet?: string | undefined;
+  /** Raw CSS for motion patterns */
+  rawCss?: string | undefined;
+  /** Trigger type for motion patterns */
+  trigger?: string | undefined;
+  /** Category for motion patterns */
+  category?: string | undefined;
+  /** Associated page ID */
+  pageId?: string | undefined;
+  createdAt: Date;
+}
+
+/**
+ * Summary search result item (lightweight, only essential fields)
+ */
+export interface SummarySearchResultItem {
+  id: string;
+  name: string;
+  similarity: number;
+}
+
+/**
+ * Search result with pagination info
+ */
+export interface SearchResult {
+  items: SearchResultItem[];
+  total: number;
+  limit: number;
+  offset: number;
+  searchTimeMs?: number;
+  /** Summary mode flag (only present when summary=true) */
+  _summary_mode?: true;
+}
+
+/**
+ * Summary search result with pagination info (lightweight response)
+ */
+export interface SummarySearchResult {
+  items: SummarySearchResultItem[];
+  total: number;
+  limit: number;
+  offset: number;
+  searchTimeMs?: number;
+  /** Summary mode flag (always true for summary results) */
+  _summary_mode: true;
+}
+
+/**
+ * Vector search raw result from database (section_patterns / motion_patterns)
+ */
+export interface VectorSearchRawResult {
+  id: string;
+  name: string;
+  type: string;
+  description?: string;
+  similarity: number;
+  html_snippet?: string;
+  raw_css?: string;
+  trigger?: string;
+  category?: string;
+  page_id?: string;
+  created_at: Date;
+}
+
+/**
+ * Full-text search raw result from database
+ */
+export interface FullTextSearchRawResult {
+  id: string;
+  name: string;
+  type: string;
+  description?: string;
+  rank: number;
+  html_snippet?: string;
+  raw_css?: string;
+  trigger?: string;
+  category?: string;
+  page_id?: string;
+  created_at: Date;
+}