@weavelogic/knowledge-graph-agent 0.6.0 → 0.7.1

package/dist/vector/services/hybrid-search.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Hybrid Search Service
+ *
+ * Combines vector similarity search with full-text search (FTS) for improved
+ * search relevance. Uses a weighted scoring approach to merge results from
+ * both search methods.
+ *
+ * @module vector/services/hybrid-search
+ */
+import type { EnhancedVectorStore } from './vector-store.js';
+import type { EmbeddingService } from './embedding-service.js';
+/**
+ * Configuration for hybrid search
+ */
+export interface HybridSearchConfig {
+    /**
+     * Weight for vector similarity results (0-1)
+     * Higher values favor semantic similarity
+     * @default 0.6
+     */
+    vectorWeight: number;
+    /**
+     * Weight for full-text search results (0-1)
+     * Higher values favor keyword matching
+     * @default 0.4
+     */
+    ftsWeight: number;
+    /**
+     * Maximum number of results to return
+     * @default 20
+     */
+    limit: number;
+    /**
+     * Minimum combined score threshold (0-1)
+     * Results below this score are filtered out
+     * @default 0.3
+     */
+    minScore: number;
+    /**
+     * Boost factor for results that appear in both vector and FTS
+     * @default 1.2
+     */
+    hybridBoost: number;
+    /**
+     * Whether to normalize scores before combining
+     * @default true
+     */
+    normalizeScores: boolean;
+}
+/**
+ * FTS (Full-Text Search) result from external search provider
+ */
+export interface FTSResult {
+    /**
+     * Node/document ID
+     */
+    id: string;
+    /**
+     * Content that matched
+     */
+    content: string;
+    /**
+     * FTS relevance score (0-1 normalized or raw)
+     */
+    score?: number;
+    /**
+     * Match snippets/highlights
+     */
+    snippets?: string[];
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Extended hybrid search result with source tracking
+ */
+export interface ExtendedHybridSearchResult {
+    /**
+     * Node/document ID
+     */
+    nodeId: string;
+    /**
+     * Content of the matched node
+     */
+    content: string;
+    /**
+     * Vector similarity score (0-1)
+     */
+    vectorScore: number;
+    /**
+     * Full-text search score (0-1)
+     */
+    ftsScore: number;
+    /**
+     * Combined/weighted score
+     */
+    combinedScore: number;
+    /**
+     * Source of this result
+     */
+    source: 'vector' | 'fts' | 'hybrid';
+    /**
+     * Rank in the final result list
+     */
+    rank: number;
+    /**
+     * Optional metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Match snippets for highlighting
+     */
+    snippets?: string[];
+}
+/**
+ * Search query input
+ */
+export interface HybridSearchQuery {
+    /**
+     * Text query for search
+     */
+    query: string;
+    /**
+     * Maximum results to return
+     */
+    limit?: number;
+    /**
+     * Minimum score threshold
+     */
+    minScore?: number;
+    /**
+     * Node types to filter by
+     */
+    nodeTypes?: string[];
+    /**
+     * Override vector weight
+     */
+    vectorWeight?: number;
+    /**
+     * Override FTS weight
+     */
+    ftsWeight?: number;
+    /**
+     * Include match snippets
+     */
+    includeSnippets?: boolean;
+}
+/**
+ * Search statistics
+ */
+export interface SearchStats {
+    /**
+     * Total search time in milliseconds
+     */
+    totalDurationMs: number;
+    /**
+     * Vector search time
+     */
+    vectorSearchMs: number;
+    /**
+     * FTS search time
+     */
+    ftsSearchMs: number;
+    /**
+     * Merge/ranking time
+     */
+    mergeMs: number;
+    /**
+     * Number of vector results before merge
+     */
+    vectorResultCount: number;
+    /**
+     * Number of FTS results before merge
+     */
+    ftsResultCount: number;
+    /**
+     * Final result count after merge and filter
+     */
+    finalResultCount: number;
+}
+/**
+ * Hybrid Search result with stats
+ */
+export interface HybridSearchResponse {
+    /**
+     * Search results
+     */
+    results: ExtendedHybridSearchResult[];
+    /**
+     * Search statistics
+     */
+    stats: SearchStats;
+    /**
+     * Original query
+     */
+    query: string;
+}
+/**
+ * FTS provider interface for pluggable full-text search
+ */
+export interface FTSProvider {
+    /**
+     * Search for documents matching query
+     */
+    search(query: string, limit: number): Promise<FTSResult[]>;
+}
+/**
+ * Hybrid Search Service
+ *
+ * Combines vector similarity search with full-text search to provide
+ * better search relevance. Vector search captures semantic meaning
+ * while FTS captures exact keyword matches.
+ *
+ * @example
+ * ```typescript
+ * const hybridSearch = new HybridSearch(vectorStore, embeddingService);
+ *
+ * // Set up FTS provider (e.g., SQLite FTS5)
+ * hybridSearch.setFTSProvider({
+ *   search: async (query, limit) => {
+ *     return db.searchNodes(query, limit).map(node => ({
+ *       id: node.id,
+ *       content: node.content,
+ *       score: 0.5,
+ *     }));
+ *   }
+ * });
+ *
+ * // Perform hybrid search
+ * const response = await hybridSearch.search({
+ *   query: 'machine learning algorithms',
+ *   limit: 10,
+ * });
+ * ```
+ */
+export declare class HybridSearch {
+    private vectorStore;
+    private embeddingService;
+    private config;
+    private ftsProvider;
+    /**
+     * Create a new HybridSearch instance
+     *
+     * @param vectorStore - Vector store for similarity search
+     * @param embeddingService - Service for generating query embeddings
+     * @param config - Optional configuration overrides
+     */
+    constructor(vectorStore: EnhancedVectorStore, embeddingService: EmbeddingService, config?: Partial<HybridSearchConfig>);
+    /**
+     * Set the full-text search provider
+     *
+     * @param provider - FTS provider implementation
+     */
+    setFTSProvider(provider: FTSProvider): void;
+    /**
+     * Perform hybrid search combining vector and FTS
+     *
+     * @param query - Search query
+     * @returns Search response with results and statistics
+     */
+    search(query: HybridSearchQuery): Promise<HybridSearchResponse>;
+    /**
+     * Perform vector similarity search
+     *
+     * @param query - Text query
+     * @param limit - Max results
+     * @returns Vector search results with timing
+     */
+    private performVectorSearch;
+    /**
+     * Perform full-text search
+     *
+     * @param query - Text query
+     * @param limit - Max results
+     * @returns FTS results with timing
+     */
+    private performFTSSearch;
+    /**
+     * Merge vector and FTS results using weighted scoring
+     *
+     * @param vectorResults - Results from vector search
+     * @param ftsResults - Results from FTS
+     * @param vectorWeight - Weight for vector scores
+     * @param ftsWeight - Weight for FTS scores
+     * @returns Merged and ranked results
+     */
+    private mergeResults;
+    /**
+     * Normalize scores to 0-1 range
+     *
+     * @param items - Items with scores to normalize
+     * @returns Map of id to normalized score
+     */
+    private normalizeScores;
+    /**
+     * Update configuration
+     *
+     * @param config - Configuration updates
+     */
+    updateConfig(config: Partial<HybridSearchConfig>): void;
+    /**
+     * Get current configuration
+     *
+     * @returns Copy of current configuration
+     */
+    getConfig(): HybridSearchConfig;
+}
+/**
+ * Create a hybrid search instance
+ *
+ * Factory function for creating hybrid search services.
+ *
+ * @param vectorStore - Vector store for similarity search
+ * @param embeddingService - Service for generating query embeddings
+ * @param config - Optional configuration overrides
+ * @returns New HybridSearch instance
+ */
+export declare function createHybridSearch(vectorStore: EnhancedVectorStore, embeddingService: EmbeddingService, config?: Partial<HybridSearchConfig>): HybridSearch;
+//# sourceMappingURL=hybrid-search.d.ts.map

package/dist/vector/services/hybrid-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-search.d.ts","sourceRoot":"","sources":["../../../src/vector/services/hybrid-search.ts"],"names":[],"mappings":"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"}

package/dist/vector/services/hybrid-search.js

@@ -0,0 +1,3 @@
+import { createLogger } from "../../utils/logger.js";
+createLogger("hybrid-search");
+//# sourceMappingURL=hybrid-search.js.map

package/dist/vector/services/hybrid-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-search.js","sources":["../../../src/vector/services/hybrid-search.ts"],"sourcesContent":["/**\n * Hybrid Search Service\n *\n * Combines vector similarity search with full-text search (FTS) for improved\n * search relevance. Uses a weighted scoring approach to merge results from\n * both search methods.\n *\n * @module vector/services/hybrid-search\n */\n\nimport type { SearchResult, HybridSearchResult } from '../types.js';\nimport type { EnhancedVectorStore } from './vector-store.js';\nimport type { EmbeddingService } from './embedding-service.js';\nimport { createLogger } from '../../utils/index.js';\n\nconst logger = createLogger('hybrid-search');\n\n/**\n * Configuration for hybrid search\n */\nexport interface HybridSearchConfig {\n  /**\n   * Weight for vector similarity results (0-1)\n   * Higher values favor semantic similarity\n   * @default 0.6\n   */\n  vectorWeight: number;\n\n  /**\n   * Weight for full-text search results (0-1)\n   * Higher values favor keyword matching\n   * @default 0.4\n   */\n  ftsWeight: number;\n\n  /**\n   * Maximum number of results to return\n   * @default 20\n   */\n  limit: number;\n\n  /**\n   * Minimum combined score threshold (0-1)\n   * Results below this score are filtered out\n   * @default 0.3\n   */\n  minScore: number;\n\n  /**\n   * Boost factor for results that appear in both vector and FTS\n   * @default 1.2\n   */\n  hybridBoost: number;\n\n  /**\n   * Whether to normalize scores before combining\n   * @default true\n   */\n  normalizeScores: boolean;\n}\n\n/**\n * Default hybrid search configuration\n */\nconst DEFAULT_CONFIG: HybridSearchConfig = {\n  vectorWeight: 0.6,\n  ftsWeight: 0.4,\n  limit: 20,\n  minScore: 0.3,\n  hybridBoost: 1.2,\n  normalizeScores: true,\n};\n\n/**\n * FTS (Full-Text Search) result from external search provider\n */\nexport interface FTSResult {\n  /**\n   * Node/document ID\n   */\n  id: string;\n\n  /**\n   * Content that matched\n   */\n  content: string;\n\n  /**\n   * FTS relevance score (0-1 normalized or raw)\n   */\n  score?: number;\n\n  /**\n   * Match snippets/highlights\n   */\n  snippets?: string[];\n\n  /**\n   * Additional metadata\n   */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Extended hybrid search result with source tracking\n */\nexport interface ExtendedHybridSearchResult {\n  /**\n   * Node/document ID\n   */\n  nodeId: string;\n\n  /**\n   * Content of the matched node\n   */\n  content: string;\n\n  /**\n   * Vector similarity score (0-1)\n   */\n  vectorScore: number;\n\n  /**\n   * Full-text search score (0-1)\n   */\n  ftsScore: number;\n\n  /**\n   * Combined/weighted score\n   */\n  combinedScore: number;\n\n  /**\n   * Source of this result\n   */\n  source: 'vector' | 'fts' | 'hybrid';\n\n  /**\n   * Rank in the final result list\n   */\n  rank: number;\n\n  /**\n   * Optional metadata\n   */\n  metadata?: Record<string, unknown>;\n\n  /**\n   * Match snippets for highlighting\n   */\n  snippets?: string[];\n}\n\n/**\n * Search query input\n */\nexport interface HybridSearchQuery {\n  /**\n   * Text query for search\n   */\n  query: string;\n\n  /**\n   * Maximum results to return\n   */\n  limit?: number;\n\n  /**\n   * Minimum score threshold\n   */\n  minScore?: number;\n\n  /**\n   * Node types to filter by\n   */\n  nodeTypes?: string[];\n\n  /**\n   * Override vector weight\n   */\n  vectorWeight?: number;\n\n  /**\n   * Override FTS weight\n   */\n  ftsWeight?: number;\n\n  /**\n   * Include match snippets\n   */\n  includeSnippets?: boolean;\n}\n\n/**\n * Search statistics\n */\nexport interface SearchStats {\n  /**\n   * Total search time in milliseconds\n   */\n  totalDurationMs: number;\n\n  /**\n   * Vector search time\n   */\n  vectorSearchMs: number;\n\n  /**\n   * FTS search time\n   */\n  ftsSearchMs: number;\n\n  /**\n   * Merge/ranking time\n   */\n  mergeMs: number;\n\n  /**\n   * Number of vector results before merge\n   */\n  vectorResultCount: number;\n\n  /**\n   * Number of FTS results before merge\n   */\n  ftsResultCount: number;\n\n  /**\n   * Final result count after merge and filter\n   */\n  finalResultCount: number;\n}\n\n/**\n * Hybrid Search result with stats\n */\nexport interface HybridSearchResponse {\n  /**\n   * Search results\n   */\n  results: ExtendedHybridSearchResult[];\n\n  /**\n   * Search statistics\n   */\n  stats: SearchStats;\n\n  /**\n   * Original query\n   */\n  query: string;\n}\n\n/**\n * FTS provider interface for pluggable full-text search\n */\nexport interface FTSProvider {\n  /**\n   * Search for documents matching query\n   */\n  search(query: string, limit: number): Promise<FTSResult[]>;\n}\n\n/**\n * Hybrid Search Service\n *\n * Combines vector similarity search with full-text search to provide\n * better search relevance. Vector search captures semantic meaning\n * while FTS captures exact keyword matches.\n *\n * @example\n * ```typescript\n * const hybridSearch = new HybridSearch(vectorStore, embeddingService);\n *\n * // Set up FTS provider (e.g., SQLite FTS5)\n * hybridSearch.setFTSProvider({\n *   search: async (query, limit) => {\n *     return db.searchNodes(query, limit).map(node => ({\n *       id: node.id,\n *       content: node.content,\n *       score: 0.5,\n *     }));\n *   }\n * });\n *\n * // Perform hybrid search\n * const response = await hybridSearch.search({\n *   query: 'machine learning algorithms',\n *   limit: 10,\n * });\n * ```\n */\nexport class HybridSearch {\n  private vectorStore: EnhancedVectorStore;\n  private embeddingService: EmbeddingService;\n  private config: HybridSearchConfig;\n  private ftsProvider: FTSProvider | null = null;\n\n  /**\n   * Create a new HybridSearch instance\n   *\n   * @param vectorStore - Vector store for similarity search\n   * @param embeddingService - Service for generating query embeddings\n   * @param config - Optional configuration overrides\n   */\n  constructor(\n    vectorStore: EnhancedVectorStore,\n    embeddingService: EmbeddingService,\n    config: Partial<HybridSearchConfig> = {}\n  ) {\n    this.vectorStore = vectorStore;\n    this.embeddingService = embeddingService;\n    this.config = { ...DEFAULT_CONFIG, ...config };\n  }\n\n  /**\n   * Set the full-text search provider\n   *\n   * @param provider - FTS provider implementation\n   */\n  setFTSProvider(provider: FTSProvider): void {\n    this.ftsProvider = provider;\n  }\n\n  /**\n   * Perform hybrid search combining vector and FTS\n   *\n   * @param query - Search query\n   * @returns Search response with results and statistics\n   */\n  async search(query: HybridSearchQuery): Promise<HybridSearchResponse> {\n    const startTime = Date.now();\n    const limit = query.limit ?? this.config.limit;\n    const minScore = query.minScore ?? this.config.minScore;\n    const vectorWeight = query.vectorWeight ?? this.config.vectorWeight;\n    const ftsWeight = query.ftsWeight ?? this.config.ftsWeight;\n\n    let vectorSearchMs = 0;\n    let ftsSearchMs = 0;\n    let vectorResults: SearchResult[] = [];\n    let ftsResults: FTSResult[] = [];\n\n    // Run vector search and FTS in parallel\n    const [vectorResultsPromise, ftsResultsPromise] = await Promise.allSettled([\n      this.performVectorSearch(query.query, limit * 2),\n      this.performFTSSearch(query.query, limit * 2),\n    ]);\n\n    // Extract vector results\n    if (vectorResultsPromise.status === 'fulfilled') {\n      vectorResults = vectorResultsPromise.value.results;\n      vectorSearchMs = vectorResultsPromise.value.durationMs;\n    } else {\n      logger.warn('Vector search failed', {\n        error: vectorResultsPromise.reason,\n      });\n    }\n\n    // Extract FTS results\n    if (ftsResultsPromise.status === 'fulfilled') {\n      ftsResults = ftsResultsPromise.value.results;\n      ftsSearchMs = ftsResultsPromise.value.durationMs;\n    } else {\n      logger.warn('FTS search failed', {\n        error: ftsResultsPromise.reason,\n      });\n    }\n\n    // Merge results\n    const mergeStartTime = Date.now();\n    const merged = this.mergeResults(\n      vectorResults,\n      ftsResults,\n      vectorWeight,\n      ftsWeight\n    );\n\n    // Filter by minimum score\n    const filtered = merged.filter((r) => r.combinedScore >= minScore);\n\n    // Filter by node types if specified\n    let final = filtered;\n    if (query.nodeTypes && query.nodeTypes.length > 0) {\n      final = filtered.filter((r) => {\n        const nodeType = r.metadata?.type as string | undefined;\n        return nodeType && query.nodeTypes!.includes(nodeType);\n      });\n    }\n\n    // Limit and rank results\n    const results = final.slice(0, limit).map((r, i) => ({\n      ...r,\n      rank: i + 1,\n    }));\n\n    const mergeMs = Date.now() - mergeStartTime;\n    const totalDurationMs = Date.now() - startTime;\n\n    logger.info('Hybrid search completed', {\n      query: query.query.slice(0, 50),\n      vectorResults: vectorResults.length,\n      ftsResults: ftsResults.length,\n      finalResults: results.length,\n      totalDurationMs,\n    });\n\n    return {\n      results,\n      stats: {\n        totalDurationMs,\n        vectorSearchMs,\n        ftsSearchMs,\n        mergeMs,\n        vectorResultCount: vectorResults.length,\n        ftsResultCount: ftsResults.length,\n        finalResultCount: results.length,\n      },\n      query: query.query,\n    };\n  }\n\n  /**\n   * Perform vector similarity search\n   *\n   * @param query - Text query\n   * @param limit - Max results\n   * @returns Vector search results with timing\n   */\n  private async performVectorSearch(\n    query: string,\n    limit: number\n  ): Promise<{ results: SearchResult[]; durationMs: number }> {\n    const startTime = Date.now();\n\n    // Generate query embedding\n    const embeddingResult = await this.embeddingService.embed(query);\n\n    // Search vector store\n    const results = await this.vectorStore.search({\n      vector: Array.from(embeddingResult.embedding),\n      k: limit,\n      minScore: 0, // We'll filter by minScore after merge\n    });\n\n    return {\n      results,\n      durationMs: Date.now() - startTime,\n    };\n  }\n\n  /**\n   * Perform full-text search\n   *\n   * @param query - Text query\n   * @param limit - Max results\n   * @returns FTS results with timing\n   */\n  private async performFTSSearch(\n    query: string,\n    limit: number\n  ): Promise<{ results: FTSResult[]; durationMs: number }> {\n    const startTime = Date.now();\n\n    if (!this.ftsProvider) {\n      return { results: [], durationMs: Date.now() - startTime };\n    }\n\n    const results = await this.ftsProvider.search(query, limit);\n\n    return {\n      results,\n      durationMs: Date.now() - startTime,\n    };\n  }\n\n  /**\n   * Merge vector and FTS results using weighted scoring\n   *\n   * @param vectorResults - Results from vector search\n   * @param ftsResults - Results from FTS\n   * @param vectorWeight - Weight for vector scores\n   * @param ftsWeight - Weight for FTS scores\n   * @returns Merged and ranked results\n   */\n  private mergeResults(\n    vectorResults: SearchResult[],\n    ftsResults: FTSResult[],\n    vectorWeight: number,\n    ftsWeight: number\n  ): ExtendedHybridSearchResult[] {\n    const combined = new Map<string, ExtendedHybridSearchResult>();\n\n    // Normalize scores if configured\n    const normalizedVector = this.config.normalizeScores\n      ? this.normalizeScores(vectorResults.map((r) => ({ id: r.id, score: r.score })))\n      : new Map(vectorResults.map((r) => [r.id, r.score]));\n\n    const normalizedFTS = this.config.normalizeScores\n      ? this.normalizeScores(\n          ftsResults.map((r) => ({ id: r.id, score: r.score ?? 0.5 }))\n        )\n      : new Map(ftsResults.map((r) => [r.id, r.score ?? 0.5]));\n\n    // Add vector results\n    for (const result of vectorResults) {\n      const vectorScore = normalizedVector.get(result.id) ?? 0;\n      combined.set(result.id, {\n        nodeId: result.id,\n        content: (result.metadata?.content as string) ?? '',\n        vectorScore,\n        ftsScore: 0,\n        combinedScore: vectorScore * vectorWeight,\n        source: 'vector',\n        rank: 0,\n        metadata: result.metadata,\n      });\n    }\n\n    // Merge FTS results\n    for (const result of ftsResults) {\n      const ftsScore = normalizedFTS.get(result.id) ?? 0;\n      const existing = combined.get(result.id);\n\n      if (existing) {\n        // Result appears in both - apply hybrid boost\n        existing.ftsScore = ftsScore;\n        existing.combinedScore =\n          (existing.vectorScore * vectorWeight + ftsScore * ftsWeight) *\n          this.config.hybridBoost;\n        existing.source = 'hybrid';\n        existing.snippets = result.snippets;\n      } else {\n        // FTS-only result\n        combined.set(result.id, {\n          nodeId: result.id,\n          content: result.content,\n          vectorScore: 0,\n          ftsScore,\n          combinedScore: ftsScore * ftsWeight,\n          source: 'fts',\n          rank: 0,\n          metadata: result.metadata,\n          snippets: result.snippets,\n        });\n      }\n    }\n\n    // Sort by combined score and return\n    return Array.from(combined.values()).sort(\n      (a, b) => b.combinedScore - a.combinedScore\n    );\n  }\n\n  /**\n   * Normalize scores to 0-1 range\n   *\n   * @param items - Items with scores to normalize\n   * @returns Map of id to normalized score\n   */\n  private normalizeScores(\n    items: Array<{ id: string; score: number }>\n  ): Map<string, number> {\n    if (items.length === 0) {\n      return new Map();\n    }\n\n    const scores = items.map((i) => i.score);\n    const min = Math.min(...scores);\n    const max = Math.max(...scores);\n    const range = max - min;\n\n    const result = new Map<string, number>();\n\n    for (const item of items) {\n      const normalized = range === 0 ? 1 : (item.score - min) / range;\n      result.set(item.id, normalized);\n    }\n\n    return result;\n  }\n\n  /**\n   * Update configuration\n   *\n   * @param config - Configuration updates\n   */\n  updateConfig(config: Partial<HybridSearchConfig>): void {\n    this.config = { ...this.config, ...config };\n  }\n\n  /**\n   * Get current configuration\n   *\n   * @returns Copy of current configuration\n   */\n  getConfig(): HybridSearchConfig {\n    return { ...this.config };\n  }\n}\n\n/**\n * Create a hybrid search instance\n *\n * Factory function for creating hybrid search services.\n *\n * @param vectorStore - Vector store for similarity search\n * @param embeddingService - Service for generating query embeddings\n * @param config - Optional configuration overrides\n * @returns New HybridSearch instance\n */\nexport function createHybridSearch(\n  vectorStore: EnhancedVectorStore,\n  embeddingService: EmbeddingService,\n  config?: Partial<HybridSearchConfig>\n): HybridSearch {\n  return new HybridSearch(vectorStore, embeddingService, config);\n}\n"],"names":[],"mappings":";AAee,aAAa,eAAe;"}

package/dist/vector/services/index.d.ts

@@ -5,9 +5,13 @@
  * Includes:
  * - Vector store for HNSW-based similarity search
  * - Trajectory tracker for agent operation logging and self-learning
+ * - Embedding service for generating text embeddings
+ * - Hybrid search for combining vector and full-text search
  *
  * @module vector/services
  */
 export { EnhancedVectorStore, createVectorStore } from './vector-store.js';
 export { TrajectoryTracker, createTrajectoryTracker, type TrajectoryTrackerConfig, type DetectedPattern, } from './trajectory-tracker.js';
+export { EmbeddingService, createEmbeddingService, getDefaultEmbeddingService, type EmbeddingConfig, type EmbeddingResult, type BatchEmbeddingResult, } from './embedding-service.js';
+export { HybridSearch, createHybridSearch, type HybridSearchConfig, type FTSResult, type FTSProvider, type ExtendedHybridSearchResult, type HybridSearchQuery, type HybridSearchResponse, type SearchStats, } from './hybrid-search.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/vector/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/vector/services/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,GACrB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/vector/services/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,GACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,0BAA0B,EAC/B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weavelogic/knowledge-graph-agent",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Knowledge graph agent for Claude Code - generates knowledge graphs, initializes docs, and integrates with claude-flow",
   "type": "module",
   "main": "dist/index.js",
@@ -42,6 +42,7 @@
     "@tanstack/react-query": "^5.62.0",
     "@tanstack/react-table": "^8.20.0",
     "@typescript-eslint/typescript-estree": "^8.51.0",
+    "@xenova/transformers": "^2.17.2",
     "better-sqlite3": "^11.7.0",
     "chalk": "^5.3.0",
     "clsx": "^2.1.0",
@@ -99,5 +100,13 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "agentic-flow": "^1.10.0"
+  },
+  "peerDependenciesMeta": {
+    "agentic-flow": {
+      "optional": true
+    }
   }
 }