@danielsimonjr/memoryjs 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (295) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +266 -0
  3. package/dist/core/EntityManager.d.ts +268 -0
  4. package/dist/core/EntityManager.d.ts.map +1 -0
  5. package/dist/core/EntityManager.js +512 -0
  6. package/dist/core/EntityManager.js.map +1 -0
  7. package/dist/core/GraphEventEmitter.d.ts +202 -0
  8. package/dist/core/GraphEventEmitter.d.ts.map +1 -0
  9. package/dist/core/GraphEventEmitter.js +347 -0
  10. package/dist/core/GraphEventEmitter.js.map +1 -0
  11. package/dist/core/GraphStorage.d.ts +395 -0
  12. package/dist/core/GraphStorage.d.ts.map +1 -0
  13. package/dist/core/GraphStorage.js +786 -0
  14. package/dist/core/GraphStorage.js.map +1 -0
  15. package/dist/core/GraphTraversal.d.ts +141 -0
  16. package/dist/core/GraphTraversal.d.ts.map +1 -0
  17. package/dist/core/GraphTraversal.js +574 -0
  18. package/dist/core/GraphTraversal.js.map +1 -0
  19. package/dist/core/HierarchyManager.d.ts +111 -0
  20. package/dist/core/HierarchyManager.d.ts.map +1 -0
  21. package/dist/core/HierarchyManager.js +225 -0
  22. package/dist/core/HierarchyManager.js.map +1 -0
  23. package/dist/core/ManagerContext.d.ts +76 -0
  24. package/dist/core/ManagerContext.d.ts.map +1 -0
  25. package/dist/core/ManagerContext.js +129 -0
  26. package/dist/core/ManagerContext.js.map +1 -0
  27. package/dist/core/ObservationManager.d.ts +85 -0
  28. package/dist/core/ObservationManager.d.ts.map +1 -0
  29. package/dist/core/ObservationManager.js +124 -0
  30. package/dist/core/ObservationManager.js.map +1 -0
  31. package/dist/core/RelationManager.d.ts +131 -0
  32. package/dist/core/RelationManager.d.ts.map +1 -0
  33. package/dist/core/RelationManager.js +212 -0
  34. package/dist/core/RelationManager.js.map +1 -0
  35. package/dist/core/SQLiteStorage.d.ts +354 -0
  36. package/dist/core/SQLiteStorage.d.ts.map +1 -0
  37. package/dist/core/SQLiteStorage.js +919 -0
  38. package/dist/core/SQLiteStorage.js.map +1 -0
  39. package/dist/core/StorageFactory.d.ts +45 -0
  40. package/dist/core/StorageFactory.d.ts.map +1 -0
  41. package/dist/core/StorageFactory.js +65 -0
  42. package/dist/core/StorageFactory.js.map +1 -0
  43. package/dist/core/TransactionManager.d.ts +464 -0
  44. package/dist/core/TransactionManager.d.ts.map +1 -0
  45. package/dist/core/TransactionManager.js +869 -0
  46. package/dist/core/TransactionManager.js.map +1 -0
  47. package/dist/core/index.d.ts +17 -0
  48. package/dist/core/index.d.ts.map +1 -0
  49. package/dist/core/index.js +20 -0
  50. package/dist/core/index.js.map +1 -0
  51. package/dist/features/AnalyticsManager.d.ts +44 -0
  52. package/dist/features/AnalyticsManager.d.ts.map +1 -0
  53. package/dist/features/AnalyticsManager.js +224 -0
  54. package/dist/features/AnalyticsManager.js.map +1 -0
  55. package/dist/features/ArchiveManager.d.ts +133 -0
  56. package/dist/features/ArchiveManager.d.ts.map +1 -0
  57. package/dist/features/ArchiveManager.js +282 -0
  58. package/dist/features/ArchiveManager.js.map +1 -0
  59. package/dist/features/CompressionManager.d.ts +119 -0
  60. package/dist/features/CompressionManager.d.ts.map +1 -0
  61. package/dist/features/CompressionManager.js +470 -0
  62. package/dist/features/CompressionManager.js.map +1 -0
  63. package/dist/features/IOManager.d.ts +225 -0
  64. package/dist/features/IOManager.d.ts.map +1 -0
  65. package/dist/features/IOManager.js +1093 -0
  66. package/dist/features/IOManager.js.map +1 -0
  67. package/dist/features/KeywordExtractor.d.ts +61 -0
  68. package/dist/features/KeywordExtractor.d.ts.map +1 -0
  69. package/dist/features/KeywordExtractor.js +127 -0
  70. package/dist/features/KeywordExtractor.js.map +1 -0
  71. package/dist/features/ObservationNormalizer.d.ts +90 -0
  72. package/dist/features/ObservationNormalizer.d.ts.map +1 -0
  73. package/dist/features/ObservationNormalizer.js +194 -0
  74. package/dist/features/ObservationNormalizer.js.map +1 -0
  75. package/dist/features/StreamingExporter.d.ts +128 -0
  76. package/dist/features/StreamingExporter.d.ts.map +1 -0
  77. package/dist/features/StreamingExporter.js +212 -0
  78. package/dist/features/StreamingExporter.js.map +1 -0
  79. package/dist/features/TagManager.d.ts +147 -0
  80. package/dist/features/TagManager.d.ts.map +1 -0
  81. package/dist/features/TagManager.js +211 -0
  82. package/dist/features/TagManager.js.map +1 -0
  83. package/dist/features/index.d.ts +14 -0
  84. package/dist/features/index.d.ts.map +1 -0
  85. package/dist/features/index.js +15 -0
  86. package/dist/features/index.js.map +1 -0
  87. package/dist/index.d.ts +15 -0
  88. package/dist/index.d.ts.map +1 -0
  89. package/dist/index.js +20 -0
  90. package/dist/index.js.map +1 -0
  91. package/dist/search/BM25Search.d.ts +148 -0
  92. package/dist/search/BM25Search.d.ts.map +1 -0
  93. package/dist/search/BM25Search.js +340 -0
  94. package/dist/search/BM25Search.js.map +1 -0
  95. package/dist/search/BasicSearch.d.ts +51 -0
  96. package/dist/search/BasicSearch.d.ts.map +1 -0
  97. package/dist/search/BasicSearch.js +138 -0
  98. package/dist/search/BasicSearch.js.map +1 -0
  99. package/dist/search/BooleanSearch.d.ts +98 -0
  100. package/dist/search/BooleanSearch.d.ts.map +1 -0
  101. package/dist/search/BooleanSearch.js +431 -0
  102. package/dist/search/BooleanSearch.js.map +1 -0
  103. package/dist/search/EarlyTerminationManager.d.ts +140 -0
  104. package/dist/search/EarlyTerminationManager.d.ts.map +1 -0
  105. package/dist/search/EarlyTerminationManager.js +280 -0
  106. package/dist/search/EarlyTerminationManager.js.map +1 -0
  107. package/dist/search/EmbeddingCache.d.ts +175 -0
  108. package/dist/search/EmbeddingCache.d.ts.map +1 -0
  109. package/dist/search/EmbeddingCache.js +247 -0
  110. package/dist/search/EmbeddingCache.js.map +1 -0
  111. package/dist/search/EmbeddingService.d.ts +277 -0
  112. package/dist/search/EmbeddingService.d.ts.map +1 -0
  113. package/dist/search/EmbeddingService.js +531 -0
  114. package/dist/search/EmbeddingService.js.map +1 -0
  115. package/dist/search/FuzzySearch.d.ts +118 -0
  116. package/dist/search/FuzzySearch.d.ts.map +1 -0
  117. package/dist/search/FuzzySearch.js +313 -0
  118. package/dist/search/FuzzySearch.js.map +1 -0
  119. package/dist/search/HybridScorer.d.ts +181 -0
  120. package/dist/search/HybridScorer.d.ts.map +1 -0
  121. package/dist/search/HybridScorer.js +258 -0
  122. package/dist/search/HybridScorer.js.map +1 -0
  123. package/dist/search/HybridSearchManager.d.ts +80 -0
  124. package/dist/search/HybridSearchManager.d.ts.map +1 -0
  125. package/dist/search/HybridSearchManager.js +188 -0
  126. package/dist/search/HybridSearchManager.js.map +1 -0
  127. package/dist/search/IncrementalIndexer.d.ts +201 -0
  128. package/dist/search/IncrementalIndexer.d.ts.map +1 -0
  129. package/dist/search/IncrementalIndexer.js +343 -0
  130. package/dist/search/IncrementalIndexer.js.map +1 -0
  131. package/dist/search/OptimizedInvertedIndex.d.ts +163 -0
  132. package/dist/search/OptimizedInvertedIndex.d.ts.map +1 -0
  133. package/dist/search/OptimizedInvertedIndex.js +359 -0
  134. package/dist/search/OptimizedInvertedIndex.js.map +1 -0
  135. package/dist/search/ParallelSearchExecutor.d.ts +172 -0
  136. package/dist/search/ParallelSearchExecutor.d.ts.map +1 -0
  137. package/dist/search/ParallelSearchExecutor.js +310 -0
  138. package/dist/search/ParallelSearchExecutor.js.map +1 -0
  139. package/dist/search/QuantizedVectorStore.d.ts +171 -0
  140. package/dist/search/QuantizedVectorStore.d.ts.map +1 -0
  141. package/dist/search/QuantizedVectorStore.js +308 -0
  142. package/dist/search/QuantizedVectorStore.js.map +1 -0
  143. package/dist/search/QueryAnalyzer.d.ts +76 -0
  144. package/dist/search/QueryAnalyzer.d.ts.map +1 -0
  145. package/dist/search/QueryAnalyzer.js +228 -0
  146. package/dist/search/QueryAnalyzer.js.map +1 -0
  147. package/dist/search/QueryCostEstimator.d.ts +244 -0
  148. package/dist/search/QueryCostEstimator.d.ts.map +1 -0
  149. package/dist/search/QueryCostEstimator.js +653 -0
  150. package/dist/search/QueryCostEstimator.js.map +1 -0
  151. package/dist/search/QueryPlanCache.d.ts +220 -0
  152. package/dist/search/QueryPlanCache.d.ts.map +1 -0
  153. package/dist/search/QueryPlanCache.js +380 -0
  154. package/dist/search/QueryPlanCache.js.map +1 -0
  155. package/dist/search/QueryPlanner.d.ts +58 -0
  156. package/dist/search/QueryPlanner.d.ts.map +1 -0
  157. package/dist/search/QueryPlanner.js +138 -0
  158. package/dist/search/QueryPlanner.js.map +1 -0
  159. package/dist/search/RankedSearch.d.ts +71 -0
  160. package/dist/search/RankedSearch.d.ts.map +1 -0
  161. package/dist/search/RankedSearch.js +239 -0
  162. package/dist/search/RankedSearch.js.map +1 -0
  163. package/dist/search/ReflectionManager.d.ts +120 -0
  164. package/dist/search/ReflectionManager.d.ts.map +1 -0
  165. package/dist/search/ReflectionManager.js +232 -0
  166. package/dist/search/ReflectionManager.js.map +1 -0
  167. package/dist/search/SavedSearchManager.d.ts +79 -0
  168. package/dist/search/SavedSearchManager.d.ts.map +1 -0
  169. package/dist/search/SavedSearchManager.js +147 -0
  170. package/dist/search/SavedSearchManager.js.map +1 -0
  171. package/dist/search/SearchFilterChain.d.ts +120 -0
  172. package/dist/search/SearchFilterChain.d.ts.map +1 -0
  173. package/dist/search/SearchFilterChain.js +186 -0
  174. package/dist/search/SearchFilterChain.js.map +1 -0
  175. package/dist/search/SearchManager.d.ts +326 -0
  176. package/dist/search/SearchManager.d.ts.map +1 -0
  177. package/dist/search/SearchManager.js +454 -0
  178. package/dist/search/SearchManager.js.map +1 -0
  179. package/dist/search/SearchSuggestions.d.ts +27 -0
  180. package/dist/search/SearchSuggestions.d.ts.map +1 -0
  181. package/dist/search/SearchSuggestions.js +58 -0
  182. package/dist/search/SearchSuggestions.js.map +1 -0
  183. package/dist/search/SemanticSearch.d.ts +149 -0
  184. package/dist/search/SemanticSearch.d.ts.map +1 -0
  185. package/dist/search/SemanticSearch.js +324 -0
  186. package/dist/search/SemanticSearch.js.map +1 -0
  187. package/dist/search/SymbolicSearch.d.ts +61 -0
  188. package/dist/search/SymbolicSearch.d.ts.map +1 -0
  189. package/dist/search/SymbolicSearch.js +164 -0
  190. package/dist/search/SymbolicSearch.js.map +1 -0
  191. package/dist/search/TFIDFEventSync.d.ts +85 -0
  192. package/dist/search/TFIDFEventSync.d.ts.map +1 -0
  193. package/dist/search/TFIDFEventSync.js +134 -0
  194. package/dist/search/TFIDFEventSync.js.map +1 -0
  195. package/dist/search/TFIDFIndexManager.d.ts +151 -0
  196. package/dist/search/TFIDFIndexManager.d.ts.map +1 -0
  197. package/dist/search/TFIDFIndexManager.js +433 -0
  198. package/dist/search/TFIDFIndexManager.js.map +1 -0
  199. package/dist/search/VectorStore.d.ts +235 -0
  200. package/dist/search/VectorStore.d.ts.map +1 -0
  201. package/dist/search/VectorStore.js +312 -0
  202. package/dist/search/VectorStore.js.map +1 -0
  203. package/dist/search/index.d.ts +35 -0
  204. package/dist/search/index.d.ts.map +1 -0
  205. package/dist/search/index.js +53 -0
  206. package/dist/search/index.js.map +1 -0
  207. package/dist/types/index.d.ts +13 -0
  208. package/dist/types/index.d.ts.map +1 -0
  209. package/dist/types/index.js +13 -0
  210. package/dist/types/index.js.map +1 -0
  211. package/dist/types/types.d.ts +1811 -0
  212. package/dist/types/types.d.ts.map +1 -0
  213. package/dist/types/types.js +10 -0
  214. package/dist/types/types.js.map +1 -0
  215. package/dist/utils/BatchProcessor.d.ts +271 -0
  216. package/dist/utils/BatchProcessor.d.ts.map +1 -0
  217. package/dist/utils/BatchProcessor.js +377 -0
  218. package/dist/utils/BatchProcessor.js.map +1 -0
  219. package/dist/utils/MemoryMonitor.d.ts +176 -0
  220. package/dist/utils/MemoryMonitor.d.ts.map +1 -0
  221. package/dist/utils/MemoryMonitor.js +306 -0
  222. package/dist/utils/MemoryMonitor.js.map +1 -0
  223. package/dist/utils/WorkerPoolManager.d.ts +233 -0
  224. package/dist/utils/WorkerPoolManager.d.ts.map +1 -0
  225. package/dist/utils/WorkerPoolManager.js +421 -0
  226. package/dist/utils/WorkerPoolManager.js.map +1 -0
  227. package/dist/utils/compressedCache.d.ts +221 -0
  228. package/dist/utils/compressedCache.d.ts.map +1 -0
  229. package/dist/utils/compressedCache.js +349 -0
  230. package/dist/utils/compressedCache.js.map +1 -0
  231. package/dist/utils/compressionUtil.d.ts +214 -0
  232. package/dist/utils/compressionUtil.d.ts.map +1 -0
  233. package/dist/utils/compressionUtil.js +248 -0
  234. package/dist/utils/compressionUtil.js.map +1 -0
  235. package/dist/utils/constants.d.ts +245 -0
  236. package/dist/utils/constants.d.ts.map +1 -0
  237. package/dist/utils/constants.js +253 -0
  238. package/dist/utils/constants.js.map +1 -0
  239. package/dist/utils/entityUtils.d.ts +379 -0
  240. package/dist/utils/entityUtils.d.ts.map +1 -0
  241. package/dist/utils/entityUtils.js +649 -0
  242. package/dist/utils/entityUtils.js.map +1 -0
  243. package/dist/utils/errors.d.ts +95 -0
  244. package/dist/utils/errors.d.ts.map +1 -0
  245. package/dist/utils/errors.js +146 -0
  246. package/dist/utils/errors.js.map +1 -0
  247. package/dist/utils/formatters.d.ts +145 -0
  248. package/dist/utils/formatters.d.ts.map +1 -0
  249. package/dist/utils/formatters.js +133 -0
  250. package/dist/utils/formatters.js.map +1 -0
  251. package/dist/utils/index.d.ts +26 -0
  252. package/dist/utils/index.d.ts.map +1 -0
  253. package/dist/utils/index.js +88 -0
  254. package/dist/utils/index.js.map +1 -0
  255. package/dist/utils/indexes.d.ts +270 -0
  256. package/dist/utils/indexes.d.ts.map +1 -0
  257. package/dist/utils/indexes.js +527 -0
  258. package/dist/utils/indexes.js.map +1 -0
  259. package/dist/utils/logger.d.ts +31 -0
  260. package/dist/utils/logger.d.ts.map +1 -0
  261. package/dist/utils/logger.js +41 -0
  262. package/dist/utils/logger.js.map +1 -0
  263. package/dist/utils/operationUtils.d.ts +124 -0
  264. package/dist/utils/operationUtils.d.ts.map +1 -0
  265. package/dist/utils/operationUtils.js +176 -0
  266. package/dist/utils/operationUtils.js.map +1 -0
  267. package/dist/utils/parallelUtils.d.ts +76 -0
  268. package/dist/utils/parallelUtils.d.ts.map +1 -0
  269. package/dist/utils/parallelUtils.js +192 -0
  270. package/dist/utils/parallelUtils.js.map +1 -0
  271. package/dist/utils/schemas.d.ts +556 -0
  272. package/dist/utils/schemas.d.ts.map +1 -0
  273. package/dist/utils/schemas.js +485 -0
  274. package/dist/utils/schemas.js.map +1 -0
  275. package/dist/utils/searchAlgorithms.d.ts +99 -0
  276. package/dist/utils/searchAlgorithms.d.ts.map +1 -0
  277. package/dist/utils/searchAlgorithms.js +168 -0
  278. package/dist/utils/searchAlgorithms.js.map +1 -0
  279. package/dist/utils/searchCache.d.ts +108 -0
  280. package/dist/utils/searchCache.d.ts.map +1 -0
  281. package/dist/utils/searchCache.js +210 -0
  282. package/dist/utils/searchCache.js.map +1 -0
  283. package/dist/utils/taskScheduler.d.ts +294 -0
  284. package/dist/utils/taskScheduler.d.ts.map +1 -0
  285. package/dist/utils/taskScheduler.js +487 -0
  286. package/dist/utils/taskScheduler.js.map +1 -0
  287. package/dist/workers/index.d.ts +12 -0
  288. package/dist/workers/index.d.ts.map +1 -0
  289. package/dist/workers/index.js +10 -0
  290. package/dist/workers/index.js.map +1 -0
  291. package/dist/workers/levenshteinWorker.d.ts +60 -0
  292. package/dist/workers/levenshteinWorker.d.ts.map +1 -0
  293. package/dist/workers/levenshteinWorker.js +99 -0
  294. package/dist/workers/levenshteinWorker.js.map +1 -0
  295. package/package.json +69 -0
@@ -0,0 +1,172 @@
1
+ /**
2
+ * Parallel Search Executor
3
+ *
4
+ * Phase 12 Sprint 2: Executes search layers (semantic, lexical, symbolic)
5
+ * concurrently using Promise.all with graceful fallback on failures.
6
+ *
7
+ * @module search/ParallelSearchExecutor
8
+ */
9
+ import type { ReadonlyKnowledgeGraph, SymbolicFilters } from '../types/index.js';
10
+ import type { SemanticSearch } from './SemanticSearch.js';
11
+ import type { RankedSearch } from './RankedSearch.js';
12
+ /**
13
+ * Timing information for a search layer.
14
+ */
15
+ export interface LayerTiming {
16
+ /** Layer identifier */
17
+ layer: 'semantic' | 'lexical' | 'symbolic';
18
+ /** Start timestamp */
19
+ startTime: number;
20
+ /** End timestamp */
21
+ endTime: number;
22
+ /** Duration in milliseconds */
23
+ durationMs: number;
24
+ /** Whether the layer succeeded */
25
+ success: boolean;
26
+ /** Error message if failed */
27
+ error?: string;
28
+ /** Number of results returned */
29
+ resultCount: number;
30
+ }
31
+ /**
32
+ * Result from parallel search execution with timing metadata.
33
+ */
34
+ export interface ParallelSearchResult {
35
+ /** Semantic search results: entity name -> similarity score */
36
+ semanticResults: Map<string, number>;
37
+ /** Lexical search results: entity name -> normalized score */
38
+ lexicalResults: Map<string, number>;
39
+ /** Symbolic search results: entity name -> filter match score */
40
+ symbolicResults: Map<string, number>;
41
+ /** Timing information for each layer */
42
+ timings: LayerTiming[];
43
+ /** Total execution time in milliseconds */
44
+ totalTimeMs: number;
45
+ /** Whether all layers succeeded */
46
+ allSucceeded: boolean;
47
+ /** Summary of failed layers */
48
+ failedLayers: string[];
49
+ }
50
+ /**
51
+ * Options for parallel search execution.
52
+ */
53
+ export interface ParallelSearchOptions {
54
+ /** Semantic search options */
55
+ semantic?: {
56
+ minSimilarity?: number;
57
+ topK?: number;
58
+ };
59
+ /** Lexical search options */
60
+ lexical?: {
61
+ useStopwords?: boolean;
62
+ useStemming?: boolean;
63
+ };
64
+ /** Symbolic filter criteria */
65
+ symbolic?: SymbolicFilters;
66
+ /** Maximum results per layer */
67
+ limit?: number;
68
+ /** Timeout per layer in milliseconds (default: 30000) */
69
+ timeoutMs?: number;
70
+ }
71
+ /**
72
+ * ParallelSearchExecutor - Execute search layers concurrently
73
+ *
74
+ * Orchestrates parallel execution of semantic, lexical, and symbolic search
75
+ * layers using Promise.all. Provides:
76
+ * - Concurrent execution for improved latency
77
+ * - Per-layer timing metadata
78
+ * - Graceful fallback on individual layer failures
79
+ * - Layer-specific error isolation
80
+ *
81
+ * @example
82
+ * ```typescript
83
+ * const executor = new ParallelSearchExecutor(semanticSearch, rankedSearch);
84
+ *
85
+ * const result = await executor.execute(graph, 'machine learning', {
86
+ * semantic: { minSimilarity: 0.5 },
87
+ * symbolic: { tags: ['ai'] }
88
+ * });
89
+ *
90
+ * console.log(`Total time: ${result.totalTimeMs}ms`);
91
+ * for (const timing of result.timings) {
92
+ * console.log(`${timing.layer}: ${timing.durationMs}ms, ${timing.resultCount} results`);
93
+ * }
94
+ * ```
95
+ */
96
+ export declare class ParallelSearchExecutor {
97
+ private semanticSearch;
98
+ private rankedSearch;
99
+ private symbolicSearch;
100
+ constructor(semanticSearch: SemanticSearch | null, rankedSearch: RankedSearch);
101
+ /**
102
+ * Execute all search layers in parallel.
103
+ *
104
+ * @param graph - Knowledge graph to search
105
+ * @param query - Search query text
106
+ * @param options - Search options for each layer
107
+ * @returns Parallel search results with timing metadata
108
+ */
109
+ execute(graph: ReadonlyKnowledgeGraph, query: string, options?: ParallelSearchOptions): Promise<ParallelSearchResult>;
110
+ /**
111
+ * Execute semantic search layer with timing.
112
+ */
113
+ private executeSemanticLayer;
114
+ /**
115
+ * Execute lexical search layer (TF-IDF/BM25) with timing.
116
+ */
117
+ private executeLexicalLayer;
118
+ /**
119
+ * Execute symbolic search layer with timing.
120
+ */
121
+ private executeSymbolicLayer;
122
+ /**
123
+ * Create a timeout promise.
124
+ */
125
+ private createTimeout;
126
+ /**
127
+ * Execute a single layer independently.
128
+ *
129
+ * @param layer - Layer to execute
130
+ * @param graph - Knowledge graph
131
+ * @param query - Search query
132
+ * @param options - Layer-specific options
133
+ * @returns Layer results with timing
134
+ */
135
+ executeLayer(layer: 'semantic' | 'lexical' | 'symbolic', graph: ReadonlyKnowledgeGraph, query: string, options?: ParallelSearchOptions): Promise<{
136
+ results: Map<string, number>;
137
+ timing: LayerTiming;
138
+ }>;
139
+ /**
140
+ * Execute only specific layers in parallel.
141
+ *
142
+ * @param layers - Layers to execute
143
+ * @param graph - Knowledge graph
144
+ * @param query - Search query
145
+ * @param options - Search options
146
+ * @returns Partial results for requested layers
147
+ */
148
+ executeSelectedLayers(layers: Array<'semantic' | 'lexical' | 'symbolic'>, graph: ReadonlyKnowledgeGraph, query: string, options?: ParallelSearchOptions): Promise<{
149
+ results: Map<'semantic' | 'lexical' | 'symbolic', Map<string, number>>;
150
+ timings: LayerTiming[];
151
+ totalTimeMs: number;
152
+ }>;
153
+ /**
154
+ * Get timing summary from results.
155
+ *
156
+ * @param timings - Array of layer timings
157
+ * @returns Formatted timing summary
158
+ */
159
+ static formatTimingSummary(timings: LayerTiming[]): string;
160
+ /**
161
+ * Calculate potential speedup from parallel execution.
162
+ *
163
+ * @param timings - Array of layer timings
164
+ * @returns Speedup metrics
165
+ */
166
+ static calculateSpeedup(timings: LayerTiming[]): {
167
+ sequentialTime: number;
168
+ parallelTime: number;
169
+ speedup: number;
170
+ };
171
+ }
172
+ //# sourceMappingURL=ParallelSearchExecutor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ParallelSearchExecutor.d.ts","sourceRoot":"","sources":["../../src/search/ParallelSearchExecutor.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,310 @@
1
+ /**
2
+ * Parallel Search Executor
3
+ *
4
+ * Phase 12 Sprint 2: Executes search layers (semantic, lexical, symbolic)
5
+ * concurrently using Promise.all with graceful fallback on failures.
6
+ *
7
+ * @module search/ParallelSearchExecutor
8
+ */
9
+ import { SymbolicSearch } from './SymbolicSearch.js';
10
+ import { SEMANTIC_SEARCH_LIMITS } from '../utils/constants.js';
11
+ /**
12
+ * ParallelSearchExecutor - Execute search layers concurrently
13
+ *
14
+ * Orchestrates parallel execution of semantic, lexical, and symbolic search
15
+ * layers using Promise.all. Provides:
16
+ * - Concurrent execution for improved latency
17
+ * - Per-layer timing metadata
18
+ * - Graceful fallback on individual layer failures
19
+ * - Layer-specific error isolation
20
+ *
21
+ * @example
22
+ * ```typescript
23
+ * const executor = new ParallelSearchExecutor(semanticSearch, rankedSearch);
24
+ *
25
+ * const result = await executor.execute(graph, 'machine learning', {
26
+ * semantic: { minSimilarity: 0.5 },
27
+ * symbolic: { tags: ['ai'] }
28
+ * });
29
+ *
30
+ * console.log(`Total time: ${result.totalTimeMs}ms`);
31
+ * for (const timing of result.timings) {
32
+ * console.log(`${timing.layer}: ${timing.durationMs}ms, ${timing.resultCount} results`);
33
+ * }
34
+ * ```
35
+ */
36
+ export class ParallelSearchExecutor {
37
+ semanticSearch;
38
+ rankedSearch;
39
+ symbolicSearch;
40
+ constructor(semanticSearch, rankedSearch) {
41
+ this.semanticSearch = semanticSearch;
42
+ this.rankedSearch = rankedSearch;
43
+ this.symbolicSearch = new SymbolicSearch();
44
+ }
45
+ /**
46
+ * Execute all search layers in parallel.
47
+ *
48
+ * @param graph - Knowledge graph to search
49
+ * @param query - Search query text
50
+ * @param options - Search options for each layer
51
+ * @returns Parallel search results with timing metadata
52
+ */
53
+ async execute(graph, query, options = {}) {
54
+ const { semantic = {}, lexical = {}, symbolic = {}, limit = SEMANTIC_SEARCH_LIMITS.DEFAULT_LIMIT, timeoutMs = 30000, } = options;
55
+ const overallStart = Date.now();
56
+ const timings = [];
57
+ const failedLayers = [];
58
+ // Execute all three layers in parallel
59
+ const [semanticResult, lexicalResult, symbolicResult] = await Promise.all([
60
+ this.executeSemanticLayer(graph, query, semantic, limit * 2, timeoutMs),
61
+ this.executeLexicalLayer(query, lexical, limit * 2, timeoutMs),
62
+ this.executeSymbolicLayer(graph.entities, symbolic, timeoutMs),
63
+ ]);
64
+ // Collect timing information
65
+ timings.push(semanticResult.timing);
66
+ timings.push(lexicalResult.timing);
67
+ timings.push(symbolicResult.timing);
68
+ // Track failed layers
69
+ if (!semanticResult.timing.success)
70
+ failedLayers.push('semantic');
71
+ if (!lexicalResult.timing.success)
72
+ failedLayers.push('lexical');
73
+ if (!symbolicResult.timing.success)
74
+ failedLayers.push('symbolic');
75
+ const totalTimeMs = Date.now() - overallStart;
76
+ return {
77
+ semanticResults: semanticResult.results,
78
+ lexicalResults: lexicalResult.results,
79
+ symbolicResults: symbolicResult.results,
80
+ timings,
81
+ totalTimeMs,
82
+ allSucceeded: failedLayers.length === 0,
83
+ failedLayers,
84
+ };
85
+ }
86
+ /**
87
+ * Execute semantic search layer with timing.
88
+ */
89
+ async executeSemanticLayer(graph, query, options, limit, _timeoutMs) {
90
+ const startTime = Date.now();
91
+ const results = new Map();
92
+ let success = true;
93
+ let error;
94
+ if (!this.semanticSearch) {
95
+ // Semantic search not available - treat as graceful degradation
96
+ return {
97
+ results,
98
+ timing: {
99
+ layer: 'semantic',
100
+ startTime,
101
+ endTime: Date.now(),
102
+ durationMs: Date.now() - startTime,
103
+ success: true, // Not an error, just not configured
104
+ resultCount: 0,
105
+ },
106
+ };
107
+ }
108
+ try {
109
+ // Execute semantic search with timeout
110
+ const semanticResults = await Promise.race([
111
+ this.semanticSearch.search(graph, query, options.topK ?? limit, options.minSimilarity ?? 0),
112
+ this.createTimeout(_timeoutMs, 'Semantic search timeout'),
113
+ ]);
114
+ for (const result of semanticResults) {
115
+ results.set(result.entity.name, result.similarity);
116
+ }
117
+ }
118
+ catch (err) {
119
+ success = false;
120
+ error = err instanceof Error ? err.message : String(err);
121
+ }
122
+ const endTime = Date.now();
123
+ return {
124
+ results,
125
+ timing: {
126
+ layer: 'semantic',
127
+ startTime,
128
+ endTime,
129
+ durationMs: endTime - startTime,
130
+ success,
131
+ error,
132
+ resultCount: results.size,
133
+ },
134
+ };
135
+ }
136
+ /**
137
+ * Execute lexical search layer (TF-IDF/BM25) with timing.
138
+ */
139
+ async executeLexicalLayer(query, _options, limit, _timeoutMs) {
140
+ const startTime = Date.now();
141
+ const results = new Map();
142
+ let success = true;
143
+ let error;
144
+ try {
145
+ // Execute lexical search with timeout
146
+ const lexicalResults = await Promise.race([
147
+ this.rankedSearch.searchNodesRanked(query, undefined, // tags
148
+ undefined, // minImportance
149
+ undefined, // maxImportance
150
+ limit),
151
+ this.createTimeout(_timeoutMs, 'Lexical search timeout'),
152
+ ]);
153
+ // Normalize scores to 0-1 range
154
+ const maxScore = Math.max(...lexicalResults.map(r => r.score), 1);
155
+ for (const result of lexicalResults) {
156
+ results.set(result.entity.name, result.score / maxScore);
157
+ }
158
+ }
159
+ catch (err) {
160
+ success = false;
161
+ error = err instanceof Error ? err.message : String(err);
162
+ }
163
+ const endTime = Date.now();
164
+ return {
165
+ results,
166
+ timing: {
167
+ layer: 'lexical',
168
+ startTime,
169
+ endTime,
170
+ durationMs: endTime - startTime,
171
+ success,
172
+ error,
173
+ resultCount: results.size,
174
+ },
175
+ };
176
+ }
177
+ /**
178
+ * Execute symbolic search layer with timing.
179
+ */
180
+ async executeSymbolicLayer(entities, filters, _timeoutMs) {
181
+ const startTime = Date.now();
182
+ const results = new Map();
183
+ let success = true;
184
+ let error;
185
+ try {
186
+ // Symbolic search is synchronous but wrap for consistency
187
+ if (!filters || Object.keys(filters).length === 0) {
188
+ // No filters - give all entities base score
189
+ for (const entity of entities) {
190
+ results.set(entity.name, 0.5);
191
+ }
192
+ }
193
+ else {
194
+ const symbolicResults = this.symbolicSearch.search(entities, filters);
195
+ for (const result of symbolicResults) {
196
+ results.set(result.entity.name, result.score);
197
+ }
198
+ }
199
+ }
200
+ catch (err) {
201
+ success = false;
202
+ error = err instanceof Error ? err.message : String(err);
203
+ }
204
+ const endTime = Date.now();
205
+ return {
206
+ results,
207
+ timing: {
208
+ layer: 'symbolic',
209
+ startTime,
210
+ endTime,
211
+ durationMs: endTime - startTime,
212
+ success,
213
+ error,
214
+ resultCount: results.size,
215
+ },
216
+ };
217
+ }
218
+ /**
219
+ * Create a timeout promise.
220
+ */
221
+ createTimeout(ms, message) {
222
+ return new Promise((_, reject) => {
223
+ setTimeout(() => reject(new Error(message)), ms);
224
+ });
225
+ }
226
+ /**
227
+ * Execute a single layer independently.
228
+ *
229
+ * @param layer - Layer to execute
230
+ * @param graph - Knowledge graph
231
+ * @param query - Search query
232
+ * @param options - Layer-specific options
233
+ * @returns Layer results with timing
234
+ */
235
+ async executeLayer(layer, graph, query, options = {}) {
236
+ const limit = options.limit ?? SEMANTIC_SEARCH_LIMITS.DEFAULT_LIMIT;
237
+ const timeoutMs = options.timeoutMs ?? 30000;
238
+ switch (layer) {
239
+ case 'semantic':
240
+ return this.executeSemanticLayer(graph, query, options.semantic ?? {}, limit * 2, timeoutMs);
241
+ case 'lexical':
242
+ return this.executeLexicalLayer(query, options.lexical ?? {}, limit * 2, timeoutMs);
243
+ case 'symbolic':
244
+ return this.executeSymbolicLayer(graph.entities, options.symbolic, timeoutMs);
245
+ }
246
+ }
247
+ /**
248
+ * Execute only specific layers in parallel.
249
+ *
250
+ * @param layers - Layers to execute
251
+ * @param graph - Knowledge graph
252
+ * @param query - Search query
253
+ * @param options - Search options
254
+ * @returns Partial results for requested layers
255
+ */
256
+ async executeSelectedLayers(layers, graph, query, options = {}) {
257
+ const overallStart = Date.now();
258
+ const results = new Map();
259
+ const timings = [];
260
+ const layerPromises = layers.map(layer => this.executeLayer(layer, graph, query, options).then(result => ({
261
+ layer,
262
+ ...result,
263
+ })));
264
+ const layerExecutionResults = await Promise.all(layerPromises);
265
+ for (const { layer, results: layerData, timing } of layerExecutionResults) {
266
+ results.set(layer, layerData);
267
+ timings.push(timing);
268
+ }
269
+ return {
270
+ results,
271
+ timings,
272
+ totalTimeMs: Date.now() - overallStart,
273
+ };
274
+ }
275
+ /**
276
+ * Get timing summary from results.
277
+ *
278
+ * @param timings - Array of layer timings
279
+ * @returns Formatted timing summary
280
+ */
281
+ static formatTimingSummary(timings) {
282
+ const lines = [];
283
+ let totalTime = 0;
284
+ let maxTime = 0;
285
+ for (const timing of timings) {
286
+ const status = timing.success ? 'OK' : `FAILED: ${timing.error}`;
287
+ lines.push(` ${timing.layer}: ${timing.durationMs}ms (${timing.resultCount} results) [${status}]`);
288
+ totalTime += timing.durationMs;
289
+ maxTime = Math.max(maxTime, timing.durationMs);
290
+ }
291
+ lines.unshift('Search Layer Timings:');
292
+ lines.push(` Total (sequential): ${totalTime}ms`);
293
+ lines.push(` Max (parallel bottleneck): ${maxTime}ms`);
294
+ lines.push(` Speedup: ${(totalTime / maxTime).toFixed(2)}x`);
295
+ return lines.join('\n');
296
+ }
297
+ /**
298
+ * Calculate potential speedup from parallel execution.
299
+ *
300
+ * @param timings - Array of layer timings
301
+ * @returns Speedup metrics
302
+ */
303
+ static calculateSpeedup(timings) {
304
+ const sequentialTime = timings.reduce((sum, t) => sum + t.durationMs, 0);
305
+ const parallelTime = Math.max(...timings.map(t => t.durationMs));
306
+ const speedup = sequentialTime / parallelTime;
307
+ return { sequentialTime, parallelTime, speedup };
308
+ }
309
+ }
310
+ //# sourceMappingURL=ParallelSearchExecutor.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ParallelSearchExecutor.js","sourceRoot":"","sources":["../../src/search/ParallelSearchExecutor.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,171 @@
1
+ /**
2
+ * Quantized Vector Store
3
+ *
4
+ * Phase 12 Sprint 6: 8-bit scalar quantization for 4x vector memory reduction.
5
+ * Uses asymmetric similarity computation for improved accuracy.
6
+ *
7
+ * @module search/QuantizedVectorStore
8
+ */
9
+ /**
10
+ * Quantization parameters for a vector set.
11
+ */
12
+ export interface QuantizationParams {
13
+ /** Minimum value in the original vectors */
14
+ min: number;
15
+ /** Maximum value in the original vectors */
16
+ max: number;
17
+ /** Scale factor for quantization */
18
+ scale: number;
19
+ /** Dimension of vectors */
20
+ dimension: number;
21
+ }
22
+ /**
23
+ * Statistics for the quantized vector store.
24
+ */
25
+ export interface QuantizedVectorStoreStats {
26
+ /** Number of stored vectors */
27
+ vectorCount: number;
28
+ /** Vector dimension */
29
+ dimension: number;
30
+ /** Full precision memory usage (bytes) */
31
+ fullPrecisionBytes: number;
32
+ /** Quantized memory usage (bytes) */
33
+ quantizedBytes: number;
34
+ /** Memory reduction ratio */
35
+ memoryReductionRatio: number;
36
+ /** Average quantization error */
37
+ avgQuantizationError: number;
38
+ }
39
+ /**
40
+ * Search result from quantized vector store.
41
+ */
42
+ export interface QuantizedSearchResult {
43
+ /** Entity ID */
44
+ id: string;
45
+ /** Similarity score (0-1) */
46
+ similarity: number;
47
+ /** Whether result used quantized computation */
48
+ quantized: boolean;
49
+ }
50
+ /**
51
+ * Configuration options for QuantizedVectorStore.
52
+ */
53
+ export interface QuantizedVectorStoreOptions {
54
+ /** Use asymmetric similarity (query in full precision) */
55
+ asymmetric?: boolean;
56
+ /** Minimum vectors before enabling quantization */
57
+ minVectorsForQuantization?: number;
58
+ /** Enable accuracy tracking */
59
+ trackAccuracy?: boolean;
60
+ }
61
+ /**
62
+ * Quantized Vector Store with 8-bit scalar quantization.
63
+ *
64
+ * Provides 4x memory reduction while maintaining >95% accuracy
65
+ * using asymmetric similarity computation.
66
+ *
67
+ * @example
68
+ * ```typescript
69
+ * const store = new QuantizedVectorStore();
70
+ *
71
+ * // Add vectors
72
+ * store.add('entity1', [0.1, 0.2, 0.3, ...]);
73
+ * store.add('entity2', [0.4, 0.5, 0.6, ...]);
74
+ *
75
+ * // Search
76
+ * const results = store.search([0.15, 0.25, 0.35, ...], 10);
77
+ *
78
+ * // Get stats
79
+ * const stats = store.getStats();
80
+ * console.log(`Memory reduction: ${stats.memoryReductionRatio}x`);
81
+ * ```
82
+ */
83
+ export declare class QuantizedVectorStore {
84
+ private fullPrecisionVectors;
85
+ private quantizedVectors;
86
+ private quantizationParams;
87
+ private options;
88
+ private isQuantized;
89
+ private quantizationErrors;
90
+ constructor(options?: QuantizedVectorStoreOptions);
91
+ /**
92
+ * Add a vector to the store.
93
+ *
94
+ * @param id - Entity identifier
95
+ * @param vector - Float vector (any dimension, must be consistent)
96
+ */
97
+ add(id: string, vector: number[]): void;
98
+ /**
99
+ * Remove a vector from the store.
100
+ *
101
+ * @param id - Entity identifier
102
+ * @returns True if vector was removed
103
+ */
104
+ remove(id: string): boolean;
105
+ /**
106
+ * Check if a vector exists.
107
+ *
108
+ * @param id - Entity identifier
109
+ */
110
+ has(id: string): boolean;
111
+ /**
112
+ * Get a vector (dequantized if necessary).
113
+ *
114
+ * @param id - Entity identifier
115
+ * @returns Vector or undefined
116
+ */
117
+ get(id: string): number[] | undefined;
118
+ /**
119
+ * Search for similar vectors.
120
+ *
121
+ * @param query - Query vector
122
+ * @param k - Number of results to return
123
+ * @returns Top k similar vectors with scores
124
+ */
125
+ search(query: number[], k: number): QuantizedSearchResult[];
126
+ /**
127
+ * Compute similarity between a query and specific entity.
128
+ *
129
+ * @param query - Query vector
130
+ * @param id - Entity identifier
131
+ * @returns Similarity score or undefined if not found
132
+ */
133
+ computeSimilarity(query: number[], id: string): number | undefined;
134
+ /**
135
+ * Force quantization of all vectors.
136
+ */
137
+ quantize(): void;
138
+ /**
139
+ * Get store statistics.
140
+ */
141
+ getStats(): QuantizedVectorStoreStats;
142
+ /**
143
+ * Check if store is currently using quantization.
144
+ */
145
+ isUsingQuantization(): boolean;
146
+ /**
147
+ * Get the number of stored vectors.
148
+ */
149
+ size(): number;
150
+ /**
151
+ * Clear all vectors from the store.
152
+ */
153
+ clear(): void;
154
+ /**
155
+ * Export all vectors.
156
+ */
157
+ export(): Map<string, number[]>;
158
+ /**
159
+ * Import vectors from a map.
160
+ *
161
+ * @param vectors - Map of id to vector
162
+ * @param quantize - Whether to quantize after import
163
+ */
164
+ import(vectors: Map<string, number[]>, quantize?: boolean): void;
165
+ private computeQuantizationParams;
166
+ private quantizeVector;
167
+ private dequantizeVector;
168
+ private cosineSimilarity;
169
+ private computeError;
170
+ }
171
+ //# sourceMappingURL=QuantizedVectorStore.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"QuantizedVectorStore.d.ts","sourceRoot":"","sources":["../../src/search/QuantizedVectorStore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gBAAgB;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,0DAA0D;IAC1D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mDAAmD;IACnD,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,+BAA+B;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,oBAAoB,CAA4B;IACxD,OAAO,CAAC,gBAAgB,CAA0B;IAClD,OAAO,CAAC,kBAAkB,CAAmC;IAC7D,OAAO,CAAC,OAAO,CAAwC;IACvD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,kBAAkB,CAAgB;gBAE9B,OAAO,CAAC,EAAE,2BAA2B;IAMjD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAuBvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAM3B;;;;OAIG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAKrC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,qBAAqB,EAAE;IAyB3D;;;;;;OAMG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAelE;;OAEG;IACH,QAAQ,IAAI,IAAI;IAqBhB;;OAEG;IACH,QAAQ,IAAI,yBAAyB;IAsBrC;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAI9B;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAQ/B;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,UAAO,GAAG,IAAI;IAa7D,OAAO,CAAC,yBAAyB;IAkBjC,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,gBAAgB;IAiBxB,OAAO,CAAC,YAAY;CAQrB"}