@danielsimonjr/memoryjs 1.0.0

package/dist/search/QueryPlanner.js

@@ -0,0 +1,138 @@
+/**
+ * Query Planner
+ *
+ * Phase 11: Generates execution plans for queries based on analysis.
+ *
+ * @module search/QueryPlanner
+ */
+/**
+ * Query Planner generates execution plans from query analysis.
+ *
+ * Creates optimized plans that:
+ * - Select appropriate search layers
+ * - Determine execution strategy (parallel/sequential)
+ * - Set up query dependencies
+ * - Configure merge strategies
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new QueryAnalyzer();
+ * const planner = new QueryPlanner();
+ *
+ * const analysis = analyzer.analyze('Find projects by Alice');
+ * const plan = planner.createPlan('Find projects by Alice', analysis);
+ * // { originalQuery: '...', subQueries: [...], executionStrategy: 'iterative', ... }
+ * ```
+ */
+export class QueryPlanner {
+    /**
+     * Create an execution plan from query analysis.
+     */
+    createPlan(query, analysis) {
+        const subQueries = this.createSubQueries(query, analysis);
+        const executionStrategy = this.selectExecutionStrategy(subQueries);
+        const mergeStrategy = this.selectMergeStrategy(analysis);
+        return {
+            originalQuery: query,
+            subQueries,
+            executionStrategy,
+            mergeStrategy,
+            estimatedComplexity: this.calculateComplexity(subQueries),
+        };
+    }
+    /**
+     * Create sub-queries from analysis.
+     */
+    createSubQueries(query, analysis) {
+        const subQueries = [];
+        let id = 0;
+        // If query was decomposed, create sub-query for each part
+        if (analysis.subQueries && analysis.subQueries.length > 1) {
+            for (const sq of analysis.subQueries) {
+                subQueries.push({
+                    id: `sq_${id++}`,
+                    query: sq,
+                    targetLayer: this.selectLayer(analysis),
+                    priority: id === 1 ? 1 : 2,
+                    dependsOn: id > 1 ? [`sq_${id - 2}`] : undefined,
+                });
+            }
+        }
+        else {
+            // Single query
+            subQueries.push({
+                id: `sq_${id}`,
+                query,
+                targetLayer: this.selectLayer(analysis),
+                priority: 1,
+                filters: this.buildFilters(analysis),
+            });
+        }
+        return subQueries;
+    }
+    /**
+     * Select the most appropriate search layer.
+     */
+    selectLayer(analysis) {
+        // Use symbolic for tag/type/date filtered queries
+        if (analysis.temporalRange || analysis.requiredInfoTypes.includes('temporal')) {
+            return 'symbolic';
+        }
+        // Use semantic for complex concept queries
+        if (analysis.complexity === 'high' || analysis.questionType === 'comparative') {
+            return 'semantic';
+        }
+        // Use hybrid for balanced approach
+        return 'hybrid';
+    }
+    /**
+     * Select execution strategy based on sub-queries.
+     */
+    selectExecutionStrategy(subQueries) {
+        const hasDependencies = subQueries.some(sq => sq.dependsOn && sq.dependsOn.length > 0);
+        if (hasDependencies)
+            return 'sequential';
+        if (subQueries.length > 1)
+            return 'parallel';
+        return 'iterative';
+    }
+    /**
+     * Select merge strategy based on question type.
+     */
+    selectMergeStrategy(analysis) {
+        switch (analysis.questionType) {
+            case 'aggregation': return 'union';
+            case 'comparative': return 'intersection';
+            default: return 'weighted';
+        }
+    }
+    /**
+     * Build symbolic filters from analysis.
+     */
+    buildFilters(analysis) {
+        const filters = {};
+        let hasFilters = false;
+        if (analysis.temporalRange) {
+            filters.dateRange = {
+                start: analysis.temporalRange.start || '',
+                end: analysis.temporalRange.end || '',
+            };
+            hasFilters = true;
+        }
+        return hasFilters ? filters : undefined;
+    }
+    /**
+     * Calculate plan complexity score.
+     */
+    calculateComplexity(subQueries) {
+        let complexity = subQueries.length;
+        for (const sq of subQueries) {
+            if (sq.dependsOn)
+                complexity += sq.dependsOn.length * 0.5;
+            if (sq.filters)
+                complexity += 0.5;
+        }
+        return Math.min(complexity, 10);
+    }
+}
+//# sourceMappingURL=QueryPlanner.js.map

package/dist/search/QueryPlanner.js.map

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

package/dist/search/RankedSearch.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Ranked Search
+ *
+ * TF-IDF relevance-based search with scoring and pre-calculated indexes.
+ *
+ * @module search/RankedSearch
+ */
+import type { SearchResult } from '../types/index.js';
+import type { GraphStorage } from '../core/GraphStorage.js';
+/**
+ * Performs TF-IDF ranked search with optional pre-calculated indexes.
+ */
+export declare class RankedSearch {
+    private storage;
+    private indexManager;
+    /**
+     * Phase 4 Sprint 2: Fallback token cache for entities.
+     * Maps entity name -> pre-tokenized entity data.
+     * Invalidated when graph changes (detected by entity count mismatch).
+     */
+    private fallbackTokenCache;
+    private cachedEntityCount;
+    constructor(storage: GraphStorage, storageDir?: string);
+    /**
+     * Phase 4 Sprint 2: Clear the fallback token cache.
+     * Called when graph changes are detected or explicitly by external code.
+     */
+    clearTokenCache(): void;
+    /**
+     * Initialize and build the TF-IDF index for fast searches.
+     *
+     * Should be called after graph changes to keep index up-to-date.
+     */
+    buildIndex(): Promise<void>;
+    /**
+     * Update the index incrementally after entity changes.
+     *
+     * @param changedEntityNames - Names of entities that were created, updated, or deleted
+     */
+    updateIndex(changedEntityNames: Set<string>): Promise<void>;
+    /**
+     * Load the TF-IDF index from disk if available.
+     */
+    private ensureIndexLoaded;
+    /**
+     * Search with TF-IDF relevance ranking.
+     *
+     * Uses pre-calculated index if available, falls back to on-the-fly calculation.
+     *
+     * @param query - Search query
+     * @param tags - Optional tags filter
+     * @param minImportance - Optional minimum importance
+     * @param maxImportance - Optional maximum importance
+     * @param limit - Maximum results to return (default 50, max 200)
+     * @returns Array of search results sorted by relevance
+     */
+    searchNodesRanked(query: string, tags?: string[], minImportance?: number, maxImportance?: number, limit?: number): Promise<SearchResult[]>;
+    /**
+     * Search using pre-calculated TF-IDF index (fast path).
+     */
+    private searchWithIndex;
+    /**
+     * Search without index (on-the-fly calculation, slow path).
+     *
+     * OPTIMIZED: Phase 4 Sprint 2 - Uses fallback token cache to avoid
+     * repeated tokenization of entities. Pre-tokenizes all documents once
+     * and caches for subsequent searches.
+     */
+    private searchWithoutIndex;
+}
+//# sourceMappingURL=RankedSearch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RankedSearch.d.ts","sourceRoot":"","sources":["../../src/search/RankedSearch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAU,YAAY,EAA+B,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAM5D;;GAEG;AACH,qBAAa,YAAY;IAYrB,OAAO,CAAC,OAAO;IAXjB,OAAO,CAAC,YAAY,CAAkC;IAEtD;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAA2C;IACrE,OAAO,CAAC,iBAAiB,CAAa;gBAG5B,OAAO,EAAE,YAAY,EAC7B,UAAU,CAAC,EAAE,MAAM;IAQrB;;;OAGG;IACH,eAAe,IAAI,IAAI;IAKvB;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUjC;;;;OAIG;IACG,WAAW,CAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjE;;OAEG;YACW,iBAAiB;IAe/B;;;;;;;;;;;OAWG;IACG,iBAAiB,CACrB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,EACtB,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC,YAAY,EAAE,CAAC;IAsB1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAgEvB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;CAqF3B"}

package/dist/search/RankedSearch.js

@@ -0,0 +1,239 @@
+/**
+ * Ranked Search
+ *
+ * TF-IDF relevance-based search with scoring and pre-calculated indexes.
+ *
+ * @module search/RankedSearch
+ */
+import { calculateTF, calculateIDFFromTokenSets, tokenize } from '../utils/index.js';
+import { SEARCH_LIMITS } from '../utils/constants.js';
+import { TFIDFIndexManager } from './TFIDFIndexManager.js';
+import { SearchFilterChain } from './SearchFilterChain.js';
+/**
+ * Performs TF-IDF ranked search with optional pre-calculated indexes.
+ */
+export class RankedSearch {
+    storage;
+    indexManager = null;
+    /**
+     * Phase 4 Sprint 2: Fallback token cache for entities.
+     * Maps entity name -> pre-tokenized entity data.
+     * Invalidated when graph changes (detected by entity count mismatch).
+     */
+    fallbackTokenCache = new Map();
+    cachedEntityCount = 0;
+    constructor(storage, storageDir) {
+        this.storage = storage;
+        // Initialize index manager if storage directory is provided
+        if (storageDir) {
+            this.indexManager = new TFIDFIndexManager(storageDir);
+        }
+    }
+    /**
+     * Phase 4 Sprint 2: Clear the fallback token cache.
+     * Called when graph changes are detected or explicitly by external code.
+     */
+    clearTokenCache() {
+        this.fallbackTokenCache.clear();
+        this.cachedEntityCount = 0;
+    }
+    /**
+     * Initialize and build the TF-IDF index for fast searches.
+     *
+     * Should be called after graph changes to keep index up-to-date.
+     */
+    async buildIndex() {
+        if (!this.indexManager) {
+            throw new Error('Index manager not initialized. Provide storageDir to constructor.');
+        }
+        const graph = await this.storage.loadGraph();
+        await this.indexManager.buildIndex(graph);
+        await this.indexManager.saveIndex();
+    }
+    /**
+     * Update the index incrementally after entity changes.
+     *
+     * @param changedEntityNames - Names of entities that were created, updated, or deleted
+     */
+    async updateIndex(changedEntityNames) {
+        if (!this.indexManager) {
+            return; // No index manager, skip
+        }
+        const graph = await this.storage.loadGraph();
+        await this.indexManager.updateIndex(graph, changedEntityNames);
+        await this.indexManager.saveIndex();
+    }
+    /**
+     * Load the TF-IDF index from disk if available.
+     */
+    async ensureIndexLoaded() {
+        if (!this.indexManager) {
+            return null;
+        }
+        // Return cached index if already loaded
+        const cached = this.indexManager.getIndex();
+        if (cached) {
+            return cached;
+        }
+        // Try to load from disk
+        return await this.indexManager.loadIndex();
+    }
+    /**
+     * Search with TF-IDF relevance ranking.
+     *
+     * Uses pre-calculated index if available, falls back to on-the-fly calculation.
+     *
+     * @param query - Search query
+     * @param tags - Optional tags filter
+     * @param minImportance - Optional minimum importance
+     * @param maxImportance - Optional maximum importance
+     * @param limit - Maximum results to return (default 50, max 200)
+     * @returns Array of search results sorted by relevance
+     */
+    async searchNodesRanked(query, tags, minImportance, maxImportance, limit = SEARCH_LIMITS.DEFAULT) {
+        // Enforce maximum search limit
+        const effectiveLimit = Math.min(limit, SEARCH_LIMITS.MAX);
+        const graph = await this.storage.loadGraph();
+        // Apply tag and importance filters using SearchFilterChain
+        const filters = { tags, minImportance, maxImportance };
+        const filteredEntities = SearchFilterChain.applyFilters(graph.entities, filters);
+        // Try to use pre-calculated index
+        const index = await this.ensureIndexLoaded();
+        const queryTerms = tokenize(query);
+        if (index) {
+            // Use pre-calculated index for fast search
+            return this.searchWithIndex(filteredEntities, queryTerms, index, effectiveLimit);
+        }
+        else {
+            // Fall back to on-the-fly calculation
+            return this.searchWithoutIndex(filteredEntities, queryTerms, effectiveLimit);
+        }
+    }
+    /**
+     * Search using pre-calculated TF-IDF index (fast path).
+     */
+    searchWithIndex(entities, queryTerms, index, limit) {
+        const results = [];
+        for (const entity of entities) {
+            const docVector = index.documents.get(entity.name);
+            if (!docVector) {
+                continue; // Entity not in index
+            }
+            // Calculate total terms in document (sum of all term frequencies)
+            const totalTerms = Object.values(docVector.terms).reduce((sum, count) => sum + count, 0);
+            if (totalTerms === 0)
+                continue;
+            // Calculate score using pre-calculated term frequencies and IDF
+            let totalScore = 0;
+            const matchedFields = {};
+            for (const term of queryTerms) {
+                const termCount = docVector.terms[term] || 0;
+                const idf = index.idf.get(term) || 0;
+                // Calculate TF-IDF: (termCount / totalTerms) * IDF
+                const tf = termCount / totalTerms;
+                const tfidf = tf * idf;
+                totalScore += tfidf;
+                // Track which fields matched
+                if (termCount > 0) {
+                    if (entity.name.toLowerCase().includes(term)) {
+                        matchedFields.name = true;
+                    }
+                    if (entity.entityType.toLowerCase().includes(term)) {
+                        matchedFields.entityType = true;
+                    }
+                    const matchedObs = entity.observations.filter(o => o.toLowerCase().includes(term));
+                    if (matchedObs.length > 0) {
+                        matchedFields.observations = matchedObs;
+                    }
+                }
+            }
+            // Only include entities with non-zero scores
+            if (totalScore > 0) {
+                results.push({
+                    entity,
+                    score: totalScore,
+                    matchedFields,
+                });
+            }
+        }
+        // Sort by score descending and apply limit
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    /**
+     * Search without index (on-the-fly calculation, slow path).
+     *
+     * OPTIMIZED: Phase 4 Sprint 2 - Uses fallback token cache to avoid
+     * repeated tokenization of entities. Pre-tokenizes all documents once
+     * and caches for subsequent searches.
+     */
+    searchWithoutIndex(entities, queryTerms, limit) {
+        const results = [];
+        // Phase 4 Sprint 2: Check if cache needs invalidation
+        if (entities.length !== this.cachedEntityCount) {
+            this.clearTokenCache();
+            this.cachedEntityCount = entities.length;
+        }
+        // Phase 4 Sprint 2: Get or compute tokenized data for each entity
+        const documentData = entities.map(e => {
+            // Check cache first
+            const cached = this.fallbackTokenCache.get(e.name);
+            if (cached) {
+                return cached;
+            }
+            // Compute and cache tokenized data
+            const text = [e.name, e.entityType, ...e.observations].join(' ');
+            const tokens = tokenize(text);
+            const tokenized = {
+                entity: e,
+                text,
+                tokens,
+                tokenSet: new Set(tokens),
+            };
+            this.fallbackTokenCache.set(e.name, tokenized);
+            return tokenized;
+        });
+        // Pre-compute token sets for IDF calculation (O(1) lookup per document)
+        const tokenSets = documentData.map(d => d.tokenSet);
+        for (const docData of documentData) {
+            const { entity, text } = docData;
+            // Calculate score for each query term
+            let totalScore = 0;
+            const matchedFields = {};
+            for (const term of queryTerms) {
+                // Calculate TF using pre-tokenized tokens
+                const tf = calculateTF(term, text);
+                // Calculate IDF using pre-computed token sets (O(1) per document)
+                const idf = calculateIDFFromTokenSets(term, tokenSets);
+                // TF-IDF score
+                const score = tf * idf;
+                totalScore += score;
+                // Track which fields matched
+                if (entity.name.toLowerCase().includes(term)) {
+                    matchedFields.name = true;
+                }
+                if (entity.entityType.toLowerCase().includes(term)) {
+                    matchedFields.entityType = true;
+                }
+                const matchedObs = entity.observations.filter(o => o.toLowerCase().includes(term));
+                if (matchedObs.length > 0) {
+                    matchedFields.observations = matchedObs;
+                }
+            }
+            // Only include entities with non-zero scores
+            if (totalScore > 0) {
+                results.push({
+                    entity,
+                    score: totalScore,
+                    matchedFields,
+                });
+            }
+        }
+        // Sort by score descending and apply limit
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+}
+//# sourceMappingURL=RankedSearch.js.map

package/dist/search/RankedSearch.js.map

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

package/dist/search/ReflectionManager.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Reflection Manager
+ *
+ * Phase 11: Implements reflection-based iterative retrieval
+ * that refines results until adequate.
+ *
+ * @module search/ReflectionManager
+ */
+import type { ReadonlyKnowledgeGraph, HybridSearchResult, HybridSearchOptions } from '../types/index.js';
+import type { HybridSearchManager } from './HybridSearchManager.js';
+import type { QueryAnalyzer } from './QueryAnalyzer.js';
+/**
+ * Options for reflection-based retrieval.
+ */
+export interface ReflectionOptions {
+    /** Maximum number of reflection iterations (default: 3) */
+    maxIterations?: number;
+    /** Adequacy threshold 0-1 (default: 0.7) */
+    adequacyThreshold?: number;
+    /** Minimum results required (default: 3) */
+    minResults?: number;
+    /** Hybrid search options */
+    searchOptions?: Partial<HybridSearchOptions>;
+    /** Phase 12 Sprint 4: Progressive limit increase factor (default: 1.5) */
+    limitIncreaseFactor?: number;
+    /** Phase 12 Sprint 4: Initial search limit (default: 10) */
+    initialLimit?: number;
+    /** Phase 12 Sprint 4: Focus on specific missing info types */
+    focusMissingTypes?: boolean;
+}
+/**
+ * Phase 12 Sprint 4: Refinement history entry.
+ */
+export interface RefinementHistoryEntry {
+    /** Iteration number (1-based) */
+    iteration: number;
+    /** Query used in this iteration */
+    query: string;
+    /** Search limit used */
+    limit: number;
+    /** Results found in this iteration */
+    resultsFound: number;
+    /** Adequacy score after this iteration */
+    adequacyScore: number;
+    /** Reason for refinement (if not final) */
+    refinementReason?: string;
+    /** Missing info types that triggered refinement */
+    missingInfoTypes?: string[];
+}
+/**
+ * Result of reflection-based retrieval.
+ */
+export interface ReflectionResult {
+    results: HybridSearchResult[];
+    iterations: number;
+    adequate: boolean;
+    refinements: string[];
+    adequacyScore: number;
+    /** Phase 12 Sprint 4: Detailed refinement history */
+    refinementHistory: RefinementHistoryEntry[];
+    /** Phase 12 Sprint 4: Final search limit used */
+    finalLimit: number;
+}
+/**
+ * Reflection Manager for iterative retrieval refinement.
+ *
+ * Implements the SimpleMem-inspired reflection loop:
+ * 1. Execute initial search
+ * 2. Check result adequacy
+ * 3. If inadequate, refine query and repeat
+ * 4. Combine results from all iterations
+ *
+ * @example
+ * ```typescript
+ * const reflection = new ReflectionManager(hybridSearch, analyzer);
+ * const result = await reflection.retrieveWithReflection(
+ *   graph,
+ *   'What projects did Alice work on?',
+ *   { maxIterations: 3 }
+ * );
+ * ```
+ */
+export declare class ReflectionManager {
+    private hybridSearch;
+    private analyzer;
+    constructor(hybridSearch: HybridSearchManager, analyzer: QueryAnalyzer);
+    /**
+     * Perform retrieval with reflection-based refinement.
+     *
+     * Phase 12 Sprint 4 enhancements:
+     * - Progressive limit increase per round
+     * - Focused query refinement based on missing information
+     * - Detailed refinement history tracking
+     */
+    retrieveWithReflection(graph: ReadonlyKnowledgeGraph, query: string, options?: ReflectionOptions): Promise<ReflectionResult>;
+    /**
+     * Find missing information types based on analysis requirements.
+     * @private
+     */
+    private findMissingInfoTypes;
+    /**
+     * Refine query with focus on missing information types.
+     * @private
+     */
+    private refineQueryFocused;
+    /**
+     * Get human-readable reason for refinement.
+     * @private
+     */
+    private getRefinementReason;
+    /**
+     * Calculate result adequacy score.
+     */
+    private calculateAdequacy;
+    /**
+     * Refine query based on current results and analysis.
+     */
+    private refineQuery;
+}
+//# sourceMappingURL=ReflectionManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReflectionManager.d.ts","sourceRoot":"","sources":["../../src/search/ReflectionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,sBAAsB,EAEtB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;IAC5C,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,QAAQ;gBADR,YAAY,EAAE,mBAAmB,EACjC,QAAQ,EAAE,aAAa;IAGjC;;;;;;;OAOG;IACG,sBAAsB,CAC1B,KAAK,EAAE,sBAAsB,EAC7B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC;IAwG5B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAqC1B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,OAAO,CAAC,WAAW;CA6BpB"}