@danielsimonjr/memoryjs 1.0.0

package/dist/search/QueryCostEstimator.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Query Cost Estimator
+ *
+ * Phase 10 Sprint 4: Estimates the cost of different search methods
+ * and recommends the optimal method based on query characteristics
+ * and graph size.
+ *
+ * Phase 12 Sprint 4: Enhanced with adaptive depth calculation,
+ * layer recommendations, and token estimation.
+ *
+ * @module search/QueryCostEstimator
+ */
+import type { SearchMethod, QueryCostEstimate, QueryCostEstimatorOptions, QueryAnalysis } from '../types/index.js';
+/**
+ * Phase 12 Sprint 4: Layer type for hybrid search.
+ */
+export type SearchLayer = 'semantic' | 'lexical' | 'symbolic';
+/**
+ * Phase 12 Sprint 4: Extended cost estimate with layer recommendations.
+ */
+export interface ExtendedQueryCostEstimate extends QueryCostEstimate {
+    /** Recommended layers in priority order */
+    recommendedLayers: SearchLayer[];
+    /** Estimated tokens for this query */
+    estimatedTokens: number;
+    /** Adaptive depth (k_dyn) for search results */
+    adaptiveDepth: number;
+    /** Layer-specific cost estimates */
+    layerCosts: Record<SearchLayer, number>;
+}
+/**
+ * Phase 12 Sprint 4: Layer recommendation options.
+ */
+export interface LayerRecommendationOptions {
+    /** Query analysis from QueryAnalyzer */
+    analysis?: QueryAnalysis;
+    /** Whether semantic search is available */
+    semanticAvailable?: boolean;
+    /** Maximum layers to recommend (default: 3) */
+    maxLayers?: number;
+}
+/**
+ * Phase 12 Sprint 4: Token estimation options.
+ */
+export interface TokenEstimationOptions {
+    /** Average characters per token (default: 4) */
+    charsPerToken?: number;
+    /** Include entity count in estimate (default: true) */
+    includeEntityCount?: boolean;
+}
+/**
+ * Phase 12 Sprint 4: Adaptive depth calculation parameters.
+ */
+export interface AdaptiveDepthConfig {
+    /** Base number of results (k_base, default: 10) */
+    kBase?: number;
+    /** Complexity scaling factor (δ, delta, default: 0.5) */
+    delta?: number;
+    /** Maximum depth cap (default: 100) */
+    maxDepth?: number;
+}
+/**
+ * Phase 10 Sprint 4: Estimates search query costs and recommends optimal methods.
+ *
+ * Analyzes query characteristics and graph size to estimate execution time
+ * and recommend the most appropriate search method.
+ *
+ * @example
+ * ```typescript
+ * const estimator = new QueryCostEstimator();
+ *
+ * // Get estimate for a specific method
+ * const estimate = estimator.estimateMethod('ranked', 'test query', 1000);
+ *
+ * // Get the recommended method for a query
+ * const recommendation = estimator.recommendMethod('test query', 1000);
+ *
+ * // Get estimates for all methods
+ * const allEstimates = estimator.estimateAllMethods('test query', 1000);
+ * ```
+ */
+export declare class QueryCostEstimator {
+    private options;
+    private adaptiveDepthConfig;
+    private tokenEstimationConfig;
+    /**
+     * Create a new QueryCostEstimator instance.
+     *
+     * @param options - Optional configuration overrides
+     * @param adaptiveDepthConfig - Optional adaptive depth configuration
+     * @param tokenEstimationConfig - Optional token estimation configuration
+     */
+    constructor(options?: QueryCostEstimatorOptions, adaptiveDepthConfig?: AdaptiveDepthConfig, tokenEstimationConfig?: TokenEstimationOptions);
+    /**
+     * Estimate the cost of a specific search method.
+     *
+     * @param method - The search method to estimate
+     * @param query - The search query
+     * @param entityCount - Number of entities in the graph
+     * @returns Cost estimate for the method
+     */
+    estimateMethod(method: SearchMethod, query: string, entityCount: number): QueryCostEstimate;
+    /**
+     * Internal method to estimate without triggering recursion.
+     * @private
+     */
+    private estimateMethodInternal;
+    /**
+     * Get just the recommended method without full estimate (avoids recursion).
+     * @private
+     */
+    private getRecommendedMethodOnly;
+    /**
+     * Get estimates for all available search methods.
+     *
+     * @param query - The search query
+     * @param entityCount - Number of entities in the graph
+     * @returns Array of estimates for all methods
+     */
+    estimateAllMethods(query: string, entityCount: number): QueryCostEstimate[];
+    /**
+     * Recommend the best search method for a query.
+     *
+     * @param query - The search query
+     * @param entityCount - Number of entities in the graph
+     * @param preferredMethods - Optional array of methods to consider (default: all)
+     * @returns The recommended method and reason
+     */
+    recommendMethod(query: string, entityCount: number, preferredMethods?: SearchMethod[]): {
+        method: SearchMethod;
+        reason: string;
+        estimate: QueryCostEstimate;
+    };
+    /**
+     * Get the base time per entity for a search method.
+     * @private
+     */
+    private getBaseTimeForMethod;
+    /**
+     * Calculate a complexity factor based on query characteristics.
+     * @private
+     */
+    private getQueryComplexityFactor;
+    /**
+     * Get the complexity level based on entity count.
+     * @private
+     */
+    private getComplexity;
+    /**
+     * Generate a human-readable recommendation.
+     * @private
+     */
+    private getRecommendation;
+    /**
+     * Score a method based on query characteristics and graph size.
+     * Higher score = better fit.
+     * @private
+     */
+    private scoreMethod;
+    /**
+     * Get a human-readable reason for why a method was selected.
+     * @private
+     */
+    private getSelectionReason;
+    /**
+     * Calculate adaptive depth (k_dyn) based on query complexity.
+     *
+     * Formula: k_dyn = k_base × (1 + δ × C_q)
+     * where:
+     *   - k_base: base number of results
+     *   - δ (delta): complexity scaling factor
+     *   - C_q: query complexity score (0-1)
+     *
+     * @param query - The search query
+     * @param analysis - Optional query analysis for more accurate complexity
+     * @returns Adaptive depth value
+     */
+    calculateAdaptiveDepth(query: string, analysis?: QueryAnalysis): number;
+    /**
+     * Calculate query complexity score (0-1).
+     * @private
+     */
+    private calculateComplexityScore;
+    /**
+     * Estimate tokens for query and expected results.
+     *
+     * @param query - The search query
+     * @param entityCount - Number of entities in the graph
+     * @param expectedResults - Expected number of results (default: 10)
+     * @returns Estimated token count
+     */
+    estimateTokens(query: string, entityCount: number, expectedResults?: number): number;
+    /**
+     * Recommend search layers based on query characteristics.
+     *
+     * @param query - The search query
+     * @param options - Layer recommendation options
+     * @returns Ordered array of recommended layers (fastest first)
+     */
+    recommendLayers(query: string, options?: LayerRecommendationOptions): SearchLayer[];
+    /**
+     * Estimate cost for a specific layer.
+     * @private
+     */
+    private estimateLayerCost;
+    /**
+     * Score lexical layer for query.
+     * @private
+     */
+    private scoreLexicalLayer;
+    /**
+     * Score symbolic layer for query.
+     * @private
+     */
+    private scoreSymbolicLayer;
+    /**
+     * Score semantic layer for query.
+     * @private
+     */
+    private scoreSemanticLayer;
+    /**
+     * Get extended cost estimate with all Phase 12 features.
+     *
+     * @param method - The search method
+     * @param query - The search query
+     * @param entityCount - Number of entities in the graph
+     * @param analysis - Optional query analysis
+     * @returns Extended cost estimate
+     */
+    estimateExtended(method: SearchMethod, query: string, entityCount: number, analysis?: QueryAnalysis): ExtendedQueryCostEstimate;
+    /**
+     * Get layers sorted by estimated cost (fastest first).
+     *
+     * @param query - The search query
+     * @param entityCount - Number of entities
+     * @param semanticAvailable - Whether semantic search is available
+     * @returns Layers sorted by cost
+     */
+    getLayersByCost(query: string, entityCount: number, semanticAvailable?: boolean): Array<{
+        layer: SearchLayer;
+        estimatedMs: number;
+    }>;
+}
+//# sourceMappingURL=QueryCostEstimator.d.ts.map

package/dist/search/QueryCostEstimator.d.ts.map

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