memento-mcp-server 1.13.1-a2 → 1.13.1-a4

package/dist/domains/relation/tools/visualize-relations-tool.js

@@ -0,0 +1,157 @@
+/**
+ * Visualize Relations Tool - 관계 그래프 시각화 도구
+ * 메모리 간의 관계를 시각화합니다.
+ */
+import { z } from 'zod';
+import { BaseTool } from '../../../tools/base-tool.js';
+import { DatabaseUtils } from '../../../shared/utils/database.js';
+import { RelationGraph } from '../services/relation-graph.js';
+import { RelationVisualizer } from '../../../shared/utils/relation-visualizer.js';
+const VisualizeRelationsSchema = z.object({
+    memory_id: z.string().min(1, 'memory_id는 필수입니다'),
+    max_depth: z.number().int().min(1).max(5).optional().default(2).describe('최대 깊이 (1~5, 기본값: 2)'),
+    format: z.enum(['text', 'subgraph', 'simple', 'json']).optional().default('subgraph').describe('시각화 형식 (text, subgraph, simple, json, 기본값: subgraph)'),
+    min_confidence: z.number().min(0).max(1).optional().describe('최소 신뢰도 (0.0~1.0)'),
+    relation_types: z.array(z.enum(['CAUSES', 'DEPENDS_ON', 'FOLLOWS', 'CONTRASTS_WITH', 'REFERENCES', 'BELONGS_TO'])).optional().describe('관계 유형 필터'),
+    show_memory_ids: z.boolean().optional().default(true).describe('메모리 ID 표시 여부 (기본값: true)'),
+    show_confidence: z.boolean().optional().default(true).describe('신뢰도 표시 여부 (기본값: true)'),
+    show_relation_types: z.boolean().optional().default(true).describe('관계 유형 표시 여부 (기본값: true)')
+});
+export class VisualizeRelationsTool extends BaseTool {
+    constructor() {
+        super('visualize_relations', '메모리 간의 관계를 시각화합니다. text, subgraph, simple, json 형식을 지원합니다.', {
+            type: 'object',
+            properties: {
+                memory_id: {
+                    type: 'string',
+                    description: '중심 메모리 ID'
+                },
+                max_depth: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 5,
+                    description: '최대 깊이 (1~5, 기본값: 2)',
+                    default: 2
+                },
+                format: {
+                    type: 'string',
+                    enum: ['text', 'subgraph', 'simple', 'json'],
+                    description: '시각화 형식 (text, subgraph, simple, json, 기본값: subgraph)',
+                    default: 'subgraph'
+                },
+                min_confidence: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 1,
+                    description: '최소 신뢰도 (0.0~1.0)'
+                },
+                relation_types: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                        enum: ['CAUSES', 'DEPENDS_ON', 'FOLLOWS', 'CONTRASTS_WITH', 'REFERENCES', 'BELONGS_TO']
+                    },
+                    description: '관계 유형 필터'
+                },
+                show_memory_ids: {
+                    type: 'boolean',
+                    description: '메모리 ID 표시 여부 (기본값: true)',
+                    default: true
+                },
+                show_confidence: {
+                    type: 'boolean',
+                    description: '신뢰도 표시 여부 (기본값: true)',
+                    default: true
+                },
+                show_relation_types: {
+                    type: 'boolean',
+                    description: '관계 유형 표시 여부 (기본값: true)',
+                    default: true
+                }
+            },
+            required: ['memory_id']
+        });
+    }
+    /**
+     * Given: memory_id, max_depth, format, 옵션들
+     * When: 관계 그래프 시각화 수행
+     * Then: 시각화된 텍스트 반환
+     */
+    async handle(params, context) {
+        const parsed = VisualizeRelationsSchema.parse(params);
+        const db = context.db;
+        try {
+            // Given: 메모리 존재 확인
+            const memory = DatabaseUtils.get(db, `
+        SELECT id FROM memory_item WHERE id = ?
+      `, [parsed.memory_id]);
+            if (!memory) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                error: 'MEMORY_NOT_FOUND',
+                                message: `메모리를 찾을 수 없습니다: ${parsed.memory_id}`
+                            }, null, 2)
+                        }]
+                };
+            }
+            // RelationGraph 인스턴스 생성 (context에 없으면 새로 생성)
+            const relationGraph = context.services.relationGraph || new RelationGraph(db);
+            // When: 관계 조회
+            const relations = await relationGraph.getRelations(parsed.memory_id, {
+                direction: 'both',
+                relationTypes: parsed.relation_types,
+                minConfidence: parsed.min_confidence
+            });
+            // 시각화 옵션 준비
+            const visualizationOptions = {
+                maxDepth: parsed.max_depth,
+                minConfidence: parsed.min_confidence,
+                relationTypes: parsed.relation_types,
+                showMemoryIds: parsed.show_memory_ids,
+                showConfidence: parsed.show_confidence,
+                showRelationTypes: parsed.show_relation_types
+            };
+            let visualization;
+            // Then: 형식에 따라 시각화
+            switch (parsed.format) {
+                case 'text':
+                    visualization = RelationVisualizer.visualizeAsText(relations, visualizationOptions);
+                    break;
+                case 'subgraph':
+                    visualization = RelationVisualizer.visualizeSubgraph(parsed.memory_id, relations, visualizationOptions);
+                    break;
+                case 'simple':
+                    visualization = RelationVisualizer.visualizeSimple(relations);
+                    break;
+                case 'json':
+                    visualization = RelationVisualizer.visualizeAsJSON(relations, true);
+                    break;
+                default:
+                    // 기본값: subgraph
+                    visualization = RelationVisualizer.visualizeSubgraph(parsed.memory_id, relations, visualizationOptions);
+            }
+            return this.createSuccessResult({
+                memory_id: parsed.memory_id,
+                format: parsed.format,
+                relation_count: relations.length,
+                visualization
+            });
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: 'VISUALIZATION_FAILED',
+                            message: error instanceof Error ? error.message : String(error)
+                        }, null, 2)
+                    }]
+            };
+        }
+    }
+}
+//# sourceMappingURL=visualize-relations-tool.js.map

package/dist/domains/relation/tools/visualize-relations-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualize-relations-tool.js","sourceRoot":"","sources":["../../../../src/domains/relation/tools/visualize-relations-tool.ts"],"names":[],"mappings":"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"}

package/dist/domains/search/algorithms/hybrid-search-engine.d.ts

@@ -0,0 +1,318 @@
+/**
+ * 텍스트 검색과 벡터 검색을 결합하여 검색 정확도와 포괄성을 동시에 확보합니다.
+ * FTS5 전문 검색과 벡터 유사도 검색을 병렬로 수행하여 각각의 장점을 활용합니다.
+ */
+import { type VectorSearchResult } from '../../memory/services/memory-embedding-service.js';
+import { UnifiedEmbeddingService } from '../../embedding/services/unified-embedding-service.js';
+import type { MemorySearchFilters, MemoryType, EmbeddingProvider } from '../../../shared/types/index.js';
+import Database from 'better-sqlite3';
+import { RelationGraph } from '../../relation/services/relation-graph.js';
+export interface ITextSearchEngine {
+    search(db: Database.Database, query: {
+        query: string;
+        filters?: MemorySearchFilters;
+        limit?: number;
+    }): Promise<{
+        items: any[];
+        total_count: number;
+        query_time: number;
+    }>;
+}
+export interface IEmbeddingService {
+    isAvailable(): boolean;
+    searchBySimilarity(db: Database.Database, query: string, options: {
+        type?: MemoryType[];
+        limit?: number;
+        threshold?: number;
+    }): Promise<VectorSearchResult[]>;
+    getEmbeddingStats(db: Database.Database): Promise<any>;
+}
+export interface IVectorSearchEngine {
+    initialize(db: Database.Database): void;
+    getIndexStatus(): {
+        available: boolean;
+    };
+    search(vector: number[], options: {
+        limit?: number;
+        threshold?: number;
+        types?: MemoryType[];
+        includeContent?: boolean;
+    }, provider?: string): Promise<Array<{
+        memory_id: string;
+        content: string;
+        type: string;
+        importance: number;
+        created_at: string;
+        similarity: number;
+    }>>;
+}
+export interface ISearchResultCombiner {
+    combine(textResults: any[], vectorResults: VectorSearchResult[], textWeight: number, vectorWeight: number): HybridSearchResult[];
+}
+export interface IAdaptiveWeightCalculator {
+    calculateWeights(query: string, vectorWeight: number, textWeight: number): {
+        vectorWeight: number;
+        textWeight: number;
+    };
+}
+export interface ISearchLogger {
+    logSearchStart(searchId: string, query: HybridSearchQuery): void;
+    logSearchStep(searchId: string, step: string, data: any): void;
+    logSearchComplete(searchId: string, result: {
+        items: unknown[];
+        total_count: number;
+    }, queryTime: number): void;
+    logSearchError(searchId: string, error: unknown, query: HybridSearchQuery): void;
+    logExperiment?(searchId: string, experimentId: string, variant: Record<string, any>): void;
+}
+export declare enum SearchErrorType {
+    EMBEDDING_GENERATION_FAILED = "EMBEDDING_GENERATION_FAILED",
+    VECTOR_SEARCH_FAILED = "VECTOR_SEARCH_FAILED",
+    TEXT_SEARCH_FAILED = "TEXT_SEARCH_FAILED",
+    RESULT_COMBINATION_FAILED = "RESULT_COMBINATION_FAILED",
+    DATABASE_CONNECTION_FAILED = "DATABASE_CONNECTION_FAILED",
+    INVALID_QUERY = "INVALID_QUERY",
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+}
+export declare class SearchError extends Error {
+    type: SearchErrorType;
+    originalError?: Error | undefined;
+    context?: any | undefined;
+    constructor(type: SearchErrorType, message: string, originalError?: Error | undefined, context?: any | undefined);
+}
+export declare class SearchResultCombiner implements ISearchResultCombiner {
+    combine(textResults: any[], vectorResults: VectorSearchResult[], textWeight: number, vectorWeight: number): HybridSearchResult[];
+    private generateHybridReason;
+}
+export declare class AdaptiveWeightCalculator implements IAdaptiveWeightCalculator {
+    private adaptiveWeights;
+    calculateWeights(query: string, vectorWeight: number, textWeight: number): {
+        vectorWeight: number;
+        textWeight: number;
+    };
+    private analyzeQuery;
+    private normalizeQuery;
+}
+export declare class SearchLogger implements ISearchLogger {
+    logSearchStart(searchId: string, query: HybridSearchQuery): void;
+    logSearchStep(searchId: string, step: string, data: any): void;
+    logSearchComplete(searchId: string, result: {
+        items: unknown[];
+        total_count: number;
+    }, queryTime: number): void;
+    logSearchError(searchId: string, error: unknown, query: HybridSearchQuery): void;
+    /**
+     * A/B 테스트를 통해 검색 알고리즘의 효과를 측정하고 개선합니다.
+     * 실험 ID와 변이 파라미터를 로깅하여 데이터 기반 의사결정을 지원합니다.
+     */
+    logExperiment(searchId: string, experimentId: string, variant: Record<string, any>): void;
+}
+export interface HybridSearchQuery {
+    query: string;
+    filters?: MemorySearchFilters | undefined;
+    limit?: number | undefined;
+    vectorWeight?: number | undefined;
+    textWeight?: number | undefined;
+    includeRelations?: boolean;
+    experiment_id?: string;
+    provider_filter?: EmbeddingProvider[];
+}
+export interface HybridSearchResult {
+    id: string;
+    content: string;
+    type: string;
+    importance: number;
+    created_at: string;
+    last_accessed?: string | undefined;
+    pinned: boolean;
+    tags?: string[] | undefined;
+    textScore: number;
+    vectorScore: number;
+    finalScore: number;
+    recall_reason: string;
+    consolidation_score?: number;
+    relation_weight?: number;
+    relations?: Array<{
+        target_id: string;
+        relation_type: string;
+        confidence: number;
+    }>;
+}
+export declare class HybridSearchEngine {
+    private textSearchEngine;
+    private embeddingService;
+    private vectorSearchEngine;
+    private resultCombiner;
+    private weightCalculator;
+    private logger;
+    private queryEmbeddingService;
+    private readonly defaultVectorWeight;
+    private readonly defaultTextWeight;
+    private searchStats;
+    private ranking;
+    private relationGraph;
+    constructor(textSearchEngine: ITextSearchEngine, embeddingService: IEmbeddingService, vectorSearchEngine: IVectorSearchEngine, resultCombiner: ISearchResultCombiner, weightCalculator: IAdaptiveWeightCalculator, logger: ISearchLogger, queryEmbeddingService?: UnifiedEmbeddingService, relationGraph?: RelationGraph);
+    /**
+     * 관계 그래프를 주입하여 관계 기반 검색 기능을 활성화합니다.
+     * 선택적으로 설정하여 관계 그래프가 없는 환경에서도 동작하도록 합니다.
+     */
+    setRelationGraph(relationGraph: RelationGraph): void;
+    /**
+     * 텍스트 검색과 벡터 검색을 병렬로 실행하고 결과를 결합하여 최적의 검색 결과를 제공합니다.
+     * 쿼리 특성에 따라 적응형 가중치를 적용하여 검색 정확도를 향상시키기 위해
+     */
+    search(db: Database.Database, query: HybridSearchQuery): Promise<{
+        items: HybridSearchResult[];
+        total_count: number;
+        query_time: number;
+    }>;
+    private generateSearchId;
+    private calculateAdaptiveWeights;
+    private executeTextSearch;
+    private executeVectorSearch;
+    /**
+     * 벡터 검색 실행 (다중 provider 지원)
+     *
+     * @param db - 데이터베이스 연결
+     * @param query - 하이브리드 검색 쿼리
+     * @param searchId - 검색 ID (로깅용)
+     * @param startTime - 시작 시간 (성능 측정용)
+     * @returns 벡터 검색 결과 배열
+     */
+    private executeVecSearch;
+    /**
+     * Provider 필터링
+     *
+     * @param detectedProviders - 감지된 모든 provider 목록
+     * @param providerFilter - 필터링할 provider 목록 (선택적, 빈 배열이면 undefined로 처리되어 모든 provider 검색)
+     * @param searchId - 검색 ID (로깅용)
+     * @returns 필터링된 provider 목록
+     */
+    private filterProvidersToSearch;
+    /**
+     * 단일 provider 검색 작업 생성 (타임아웃 포함)
+     *
+     * @param provider - 검색할 provider
+     * @param query - 검색 쿼리 문자열
+     * @param searchOptions - 검색 옵션
+     * @param searchId - 검색 ID (로깅용)
+     * @returns 검색 결과 Promise (타임아웃 포함)
+     */
+    private createProviderSearchTask;
+    /**
+     * 모든 provider 검색 실행 및 결과 수집 (전체 타임아웃 포함)
+     *
+     * @param searchPromises - 각 provider별 검색 Promise 배열
+     * @param providersToSearch - 검색할 provider 목록
+     * @param searchId - 검색 ID (로깅용)
+     * @returns 검색 결과 및 통계
+     */
+    private executeProviderSearchesWithTimeout;
+    /**
+     * 결과 정규화 및 중복 제거
+     * Provider별로 Min-Max 정규화를 수행하고, 중복된 memory_id는 최고 점수만 유지
+     *
+     * @param allResults - 모든 provider의 검색 결과
+     * @returns 정규화 및 중복 제거된 결과 배열
+     */
+    private normalizeAndDeduplicateResults;
+    /**
+     * Provider별로 결과 그룹화
+     */
+    private groupResultsByProvider;
+    /**
+     * Provider별로 Min-Max 정규화 수행
+     */
+    private normalizeResultsByProvider;
+    /**
+     * 중복 제거 (memory_id 기준, 정규화된 점수 중 최고 점수만 유지)
+     */
+    private deduplicateResults;
+    /**
+     * 정규화된 점수로 재랭킹
+     */
+    private rankResults;
+    /**
+     * Fallback 벡터 검색 실행
+     * 벡터 인덱스가 사용 불가능한 경우 임베딩 서비스를 직접 사용하여 검색
+     *
+     * @param db - 데이터베이스 연결
+     * @param query - 하이브리드 검색 쿼리
+     * @param searchId - 검색 ID (로깅용)
+     * @param startTime - 시작 시간 (성능 측정용, 현재는 사용하지 않음)
+     * @returns 벡터 검색 결과 배열
+     */
+    private executeFallbackSearch;
+    /**
+     * Provider 목록 캐시 (메모리 캐시)
+     * Provider 목록은 자주 변경되지 않으므로 캐싱하여 성능 개선
+     */
+    private providerCache;
+    /**
+     * Provider 캐시 TTL (밀리초)
+     * 5분간 캐시 유지
+     */
+    private static readonly PROVIDER_CACHE_TTL_MS;
+    /**
+     * 데이터베이스에 저장된 모든 임베딩 provider를 감지하여 사용 가능한 검색 방법을 파악합니다.
+     * 모든 provider 목록을 반환하고 count 내림차순으로 정렬하여 주요 provider를 우선 확인합니다.
+     * 캐싱을 사용하여 반복적인 데이터베이스 조회를 줄이고 성능을 개선합니다.
+     */
+    private detectAllStoredEmbeddingProviders;
+    /**
+     * 쿼리 임베딩 벡터 생성
+     * preferredProvider가 지정된 경우 해당 provider로만 임베딩 생성
+     * 각 provider는 서로 다른 차원의 임베딩을 사용할 수 있으므로 fallback을 사용하지 않음
+     *
+     * @param query - 검색 쿼리 문자열
+     * @param searchId - 검색 ID (로깅용)
+     * @param preferredProvider - 선호하는 임베딩 provider (필수, 각 provider별로 다른 차원의 임베딩 필요)
+     * @returns 임베딩 벡터 배열
+     * @throws SearchError - 임베딩 생성 실패 시
+     */
+    private generateQueryVector;
+    private combineAndSortResults;
+    /**
+     * 데이터베이스에서 consolidation_score 조회
+     */
+    private fetchConsolidationScores;
+    /**
+     * 관계 가중치 계산 및 조회
+     * 관계 정보도 함께 반환 (선택적)
+     */
+    private fetchRelationWeights;
+    /**
+     * 최근성 점수 계산 (간단한 구현)
+     */
+    private calculateRecency;
+    /**
+     * 사용성 점수 계산 (간단한 구현)
+     */
+    private calculateUsage;
+    private calculateQueryTime;
+    /**
+     * 검색 통계 업데이트
+     */
+    private updateSearchStats;
+    private normalizeQuery;
+    /**
+     * 검색 통계 정보
+     */
+    getSearchStats(db: any): Promise<{
+        textSearchAvailable: boolean;
+        vectorSearchAvailable: boolean;
+        embeddingStats: any;
+        searchStats: Map<string, {
+            textHits: number;
+            vectorHits: number;
+            totalSearches: number;
+        }>;
+    }>;
+    /**
+     * 임베딩 서비스 사용 가능 여부 확인
+     */
+    isEmbeddingAvailable(): boolean;
+}
+export declare function createHybridSearchEngine(textSearchEngine?: ITextSearchEngine, embeddingService?: IEmbeddingService, vectorSearchEngine?: IVectorSearchEngine, resultCombiner?: ISearchResultCombiner, weightCalculator?: IAdaptiveWeightCalculator, logger?: ISearchLogger): HybridSearchEngine;
+export declare function getHybridSearchEngine(): HybridSearchEngine;
+//# sourceMappingURL=hybrid-search-engine.d.ts.map

package/dist/domains/search/algorithms/hybrid-search-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-search-engine.d.ts","sourceRoot":"","sources":["../../../../src/domains/search/algorithms/hybrid-search-engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAA0B,KAAK,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AACpH,OAAO,EAAE,uBAAuB,EAAE,MAAM,uDAAuD,CAAC;AAEhG,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAgC,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACvI,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AA8B1E,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5K;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,IAAI,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC9J,iBAAiB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC;IACxC,cAAc,IAAI;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IACzC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CAChR;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,aAAa,EAAE,kBAAkB,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAAC;CAClI;AAED,MAAM,WAAW,yBAAyB;IACxC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACzH;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjE,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;IAC/D,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAChH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjF,aAAa,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;CAC5F;AAGD,oBAAY,eAAe;IACzB,2BAA2B,gCAAgC;IAC3D,oBAAoB,yBAAyB;IAC7C,kBAAkB,uBAAuB;IACzC,yBAAyB,8BAA8B;IACvD,0BAA0B,+BAA+B;IACzD,aAAa,kBAAkB;IAC/B,mBAAmB,wBAAwB;CAC5C;AAED,qBAAa,WAAY,SAAQ,KAAK;IAE3B,IAAI,EAAE,eAAe;IAErB,aAAa,CAAC,EAAE,KAAK;IACrB,OAAO,CAAC,EAAE,GAAG;gBAHb,IAAI,EAAE,eAAe,EAC5B,OAAO,EAAE,MAAM,EACR,aAAa,CAAC,EAAE,KAAK,YAAA,EACrB,OAAO,CAAC,EAAE,GAAG,YAAA;CAKvB;AAGD,qBAAa,oBAAqB,YAAW,qBAAqB;IAChE,OAAO,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,aAAa,EAAE,kBAAkB,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAqDhI,OAAO,CAAC,oBAAoB;CAe7B;AAED,qBAAa,wBAAyB,YAAW,yBAAyB;IACxE,OAAO,CAAC,eAAe,CAAwE;IAE/F,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAwCvH,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,cAAc;CAMvB;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAWhE,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IAI9D,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAU/G,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAUhF;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;CAO1F;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC1C,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,qBAAa,kBAAkB;IAQ3B,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,kBAAkB;IAC1B,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,qBAAqB;IAb/B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAO;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAO;IACzC,OAAO,CAAC,WAAW,CAA2F;IAC9G,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,aAAa,CAA8B;gBAGzC,gBAAgB,EAAE,iBAAiB,EACnC,gBAAgB,EAAE,iBAAiB,EACnC,kBAAkB,EAAE,mBAAmB,EACvC,cAAc,EAAE,qBAAqB,EACrC,gBAAgB,EAAE,yBAAyB,EAC3C,MAAM,EAAE,aAAa,EACrB,qBAAqB,GAAE,uBAAuD,EACtF,aAAa,CAAC,EAAE,aAAa;IAe/B;;;OAGG;IACH,gBAAgB,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI;IAIpD;;;OAGG;IACG,MAAM,CACV,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC;QAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAuFpF,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,wBAAwB;YAelB,iBAAiB;YA4BjB,mBAAmB;IAgBjC;;;;;;;;OAQG;YACW,gBAAgB;IAoD9B;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IA0B/B;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAsFhC;;;;;;;OAOG;YACW,kCAAkC;IAoHhD;;;;;;OAMG;IACH,OAAO,CAAC,8BAA8B;IAStC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAiB9B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAoClC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;;;;OASG;YACW,qBAAqB;IAsBnC;;;OAGG;IACH,OAAO,CAAC,aAAa,CAGL;IAEhB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAiB;IAE9D;;;;OAIG;YACW,iCAAiC;IA4D/C;;;;;;;;;;OAUG;YACW,mBAAmB;YAwCnB,qBAAqB;IA8FnC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAyBhC;;;OAGG;YACW,oBAAoB;IAqDlC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,kBAAkB;IAM1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,cAAc;IAOtB;;OAEG;IACG,cAAc,CAAC,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC;QACrC,mBAAmB,EAAE,OAAO,CAAC;QAC7B,qBAAqB,EAAE,OAAO,CAAC;QAC/B,cAAc,EAAE,GAAG,CAAC;QACpB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC3F,CAAC;IAWF;;OAEG;IACH,oBAAoB,IAAI,OAAO;CAGhC;AAGD,wBAAgB,wBAAwB,CACtC,gBAAgB,CAAC,EAAE,iBAAiB,EACpC,gBAAgB,CAAC,EAAE,iBAAiB,EACpC,kBAAkB,CAAC,EAAE,mBAAmB,EACxC,cAAc,CAAC,EAAE,qBAAqB,EACtC,gBAAgB,CAAC,EAAE,yBAAyB,EAC5C,MAAM,CAAC,EAAE,aAAa,GACrB,kBAAkB,CASpB;AAKD,wBAAgB,qBAAqB,IAAI,kBAAkB,CAK1D"}