@danielsimonjr/memoryjs 1.0.0 → 1.1.0

package/dist/utils/constants.js

@@ -1,253 +0,0 @@
-/**
- * Application Constants
- *
- * Centralized configuration constants for file paths, extensions, and default values.
- *
- * @module utils/constants
- */
-/**
- * File extensions used by the memory system.
- */
-export const FILE_EXTENSIONS = {
-    /** JSONL format for line-delimited JSON storage */
-    JSONL: '.jsonl',
-    /** Legacy JSON format (backward compatibility) */
-    JSON: '.json',
-};
-/**
- * File name suffixes for auxiliary data files.
- * These suffixes are appended to the base memory file name.
- */
-export const FILE_SUFFIXES = {
-    /** Suffix for saved searches file */
-    SAVED_SEARCHES: '-saved-searches',
-    /** Suffix for tag aliases file */
-    TAG_ALIASES: '-tag-aliases',
-};
-/**
- * Default file names used by the memory system.
- */
-export const DEFAULT_FILE_NAMES = {
-    /** Default memory file name */
-    MEMORY: 'memory',
-    /** Legacy memory file name (for backward compatibility) */
-    MEMORY_LEGACY: 'memory',
-};
-/**
- * Environment variable names used for configuration.
- */
-export const ENV_VARS = {
-    /** Environment variable for custom memory file path */
-    MEMORY_FILE_PATH: 'MEMORY_FILE_PATH',
-};
-/**
- * Default base directory relative to the compiled code.
- */
-export const DEFAULT_BASE_DIR = '../';
-/**
- * Log message prefixes for consistent logging.
- */
-export const LOG_PREFIXES = {
-    /** Informational message prefix */
-    INFO: '[INFO]',
-    /** Error message prefix */
-    ERROR: '[ERROR]',
-    /** Warning message prefix */
-    WARN: '[WARN]',
-};
-/**
- * Similarity scoring weights for duplicate detection.
- * These weights determine the relative importance of each factor
- * when calculating entity similarity for duplicate detection.
- * Total weights must sum to 1.0 (100%).
- */
-export const SIMILARITY_WEIGHTS = {
-    /** Name similarity weight (40%) - Uses Levenshtein distance */
-    NAME: 0.4,
-    /** Entity type match weight (20%) - Exact match required */
-    TYPE: 0.2,
-    /** Observation overlap weight (30%) - Uses Jaccard similarity */
-    OBSERVATIONS: 0.3,
-    /** Tag overlap weight (10%) - Uses Jaccard similarity */
-    TAGS: 0.1,
-};
-/**
- * Default threshold for duplicate detection (80% similarity required).
- */
-export const DEFAULT_DUPLICATE_THRESHOLD = 0.8;
-/**
- * Search result limits to prevent resource exhaustion.
- */
-export const SEARCH_LIMITS = {
-    /** Default number of results to return */
-    DEFAULT: 50,
-    /** Maximum number of results allowed */
-    MAX: 200,
-    /** Minimum number of results (must be at least 1) */
-    MIN: 1,
-};
-/**
- * Entity importance range validation constants.
- * Importance is used to prioritize entities (0 = lowest, 10 = highest).
- */
-export const IMPORTANCE_RANGE = {
-    /** Minimum importance value */
-    MIN: 0,
-    /** Maximum importance value */
-    MAX: 10,
-};
-/**
- * Graph size limits to prevent resource exhaustion and ensure performance.
- * These limits help maintain system stability and responsiveness.
- */
-export const GRAPH_LIMITS = {
-    /** Maximum number of entities in the graph */
-    MAX_ENTITIES: 100000,
-    /** Maximum number of relations in the graph */
-    MAX_RELATIONS: 1000000,
-    /** Maximum graph file size in megabytes */
-    MAX_FILE_SIZE_MB: 500,
-    /** Maximum observations per entity */
-    MAX_OBSERVATIONS_PER_ENTITY: 1000,
-    /** Maximum tags per entity */
-    MAX_TAGS_PER_ENTITY: 100,
-};
-/**
- * Query complexity limits to prevent expensive query operations.
- * These limits protect against denial-of-service through complex queries.
- */
-export const QUERY_LIMITS = {
-    /** Maximum nesting depth for boolean queries */
-    MAX_DEPTH: 10,
-    /** Maximum number of terms in a single query */
-    MAX_TERMS: 50,
-    /** Maximum number of boolean operators (AND/OR/NOT) */
-    MAX_OPERATORS: 20,
-    /** Maximum query string length */
-    MAX_QUERY_LENGTH: 5000,
-};
-/**
- * Brotli compression configuration constants.
- * Brotli is built into Node.js >=11.7.0 via the zlib module.
- * No external dependencies required.
- *
- * Quality levels determine compression ratio vs speed tradeoff:
- * - Lower values (0-4): Faster compression, lower ratio
- * - Higher values (9-11): Slower compression, higher ratio
- */
-export const COMPRESSION_CONFIG = {
-    // Quality levels (0-11)
-    /** Fast compression for real-time entity writes (quality 4) */
-    BROTLI_QUALITY_REALTIME: 4,
-    /** Balanced compression for exports and imports (quality 6) */
-    BROTLI_QUALITY_BATCH: 6,
-    /** Maximum compression for backups and archives (quality 11) */
-    BROTLI_QUALITY_ARCHIVE: 11,
-    /** Fast decompress for cache compression (quality 5) */
-    BROTLI_QUALITY_CACHE: 5,
-    // Auto-compression thresholds (in bytes)
-    /** Auto-compress exports larger than 100KB */
-    AUTO_COMPRESS_EXPORT_SIZE: 100 * 1024,
-    /** Auto-compress MCP responses larger than 256KB */
-    AUTO_COMPRESS_RESPONSE_SIZE: 256 * 1024,
-    /** Always compress backups by default */
-    AUTO_COMPRESS_BACKUP: true,
-    // File extension for compressed files
-    /** Brotli compressed file extension */
-    BROTLI_EXTENSION: '.br',
-    // Performance tuning
-    /** Chunk size for streaming compression (64KB) */
-    COMPRESSION_CHUNK_SIZE: 65536,
-    /** Default window size for brotli (lgwin parameter) */
-    COMPRESSION_WINDOW_SIZE: 22,
-};
-// ==================== Semantic Search Configuration (Phase 4 Sprint 10-12) ====================
-/**
- * Environment variable names for embedding configuration.
- */
-export const EMBEDDING_ENV_VARS = {
-    /** Embedding provider: 'openai', 'local', or 'none' (default: 'none') */
-    PROVIDER: 'MEMORY_EMBEDDING_PROVIDER',
-    /** OpenAI API key (required when provider is 'openai') */
-    OPENAI_API_KEY: 'MEMORY_OPENAI_API_KEY',
-    /** Optional model override for the embedding service */
-    MODEL: 'MEMORY_EMBEDDING_MODEL',
-    /** Auto-index entities on creation: 'true' or 'false' (default: 'false') */
-    AUTO_INDEX: 'MEMORY_AUTO_INDEX_EMBEDDINGS',
-};
-/**
- * Default embedding configuration values.
- */
-export const EMBEDDING_DEFAULTS = {
-    /** Default provider (disabled by default) */
-    PROVIDER: 'none',
-    /** Default OpenAI model for embeddings (1536 dimensions) */
-    OPENAI_MODEL: 'text-embedding-3-small',
-    /** Default local model for embeddings (384 dimensions) */
-    LOCAL_MODEL: 'Xenova/all-MiniLM-L6-v2',
-    /** OpenAI embedding dimensions for text-embedding-3-small */
-    OPENAI_DIMENSIONS: 1536,
-    /** Local embedding dimensions for all-MiniLM-L6-v2 */
-    LOCAL_DIMENSIONS: 384,
-    /** Maximum texts per batch for OpenAI */
-    OPENAI_MAX_BATCH_SIZE: 2048,
-    /** Default batch size for embedding operations */
-    DEFAULT_BATCH_SIZE: 100,
-    /** Whether to auto-index entities by default */
-    AUTO_INDEX: false,
-};
-/**
- * Semantic search configuration limits.
- */
-export const SEMANTIC_SEARCH_LIMITS = {
-    /** Default number of results for semantic search */
-    DEFAULT_LIMIT: 10,
-    /** Maximum number of results for semantic search */
-    MAX_LIMIT: 100,
-    /** Minimum similarity score for results (0.0-1.0) */
-    MIN_SIMILARITY: 0.0,
-};
-/**
- * OpenAI API configuration.
- */
-export const OPENAI_API_CONFIG = {
-    /** Base URL for OpenAI API */
-    BASE_URL: 'https://api.openai.com/v1',
-    /** Embeddings endpoint */
-    EMBEDDINGS_ENDPOINT: '/embeddings',
-    /** Maximum retries for rate limiting */
-    MAX_RETRIES: 3,
-    /** Initial backoff delay in milliseconds */
-    INITIAL_BACKOFF_MS: 1000,
-    /** Maximum backoff delay in milliseconds */
-    MAX_BACKOFF_MS: 10000,
-};
-/**
- * Get embedding configuration from environment variables.
- *
- * @returns EmbeddingConfig object with values from environment or defaults
- */
-export function getEmbeddingConfig() {
-    const provider = (process.env[EMBEDDING_ENV_VARS.PROVIDER] || EMBEDDING_DEFAULTS.PROVIDER);
-    const apiKey = process.env[EMBEDDING_ENV_VARS.OPENAI_API_KEY];
-    const model = process.env[EMBEDDING_ENV_VARS.MODEL];
-    const autoIndex = process.env[EMBEDDING_ENV_VARS.AUTO_INDEX] === 'true';
-    return { provider, apiKey, model, autoIndex };
-}
-// ==================== Streaming Export Configuration (Phase 7 Sprint 1) ====================
-/**
- * Streaming export configuration.
- *
- * Controls when to use streaming mode and buffer sizes for optimal memory usage.
- */
-export const STREAMING_CONFIG = {
-    /** Minimum entity count to trigger streaming mode */
-    STREAMING_THRESHOLD: 5000,
-    /** Chunk size for batched streaming operations */
-    CHUNK_SIZE: 500,
-    /** High water mark for stream buffers (bytes) */
-    HIGH_WATER_MARK: 64 * 1024,
-    /** Flush interval for long-running streams (ms) */
-    FLUSH_INTERVAL_MS: 100,
-};
-//# sourceMappingURL=constants.js.map

package/dist/utils/constants.js.map

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

package/dist/utils/entityUtils.d.ts

@@ -1,379 +0,0 @@
-/**
- * Entity Utilities
- *
- * Consolidated module for entity-related utilities including:
- * - Entity lookup and manipulation functions
- * - Tag normalization and matching
- * - Date parsing and validation
- * - Entity filtering by various criteria
- * - Path utilities and validation
- *
- * @module utils/entityUtils
- */
-import type { Entity, KnowledgeGraph } from '../types/index.js';
-/**
- * FNV-1a hash function for fast string hashing.
- *
- * This is a non-cryptographic hash function that provides good distribution
- * for bucketing and deduplication purposes. It's optimized for speed
- * and produces a 32-bit unsigned integer.
- *
- * FNV-1a has the following properties:
- * - Fast computation (single pass through string)
- * - Good distribution for hash table use
- * - Deterministic output for same input
- *
- * @param text - The string to hash
- * @returns A 32-bit unsigned integer hash value
- *
- * @example
- * ```typescript
- * const hash = fnv1aHash('hello');
- * console.log(hash); // 1335831723
- *
- * // Use for bucketing similar entities
- * const bucket = fnv1aHash(entity.name.toLowerCase()) % numBuckets;
- * ```
- */
-export declare function fnv1aHash(text: string): number;
-/**
- * Finds an entity by name in the graph.
- * Overloaded to provide type-safe returns based on throwIfNotFound parameter.
- *
- * @param graph - The knowledge graph to search
- * @param name - The entity name to find
- * @param throwIfNotFound - Whether to throw if entity doesn't exist (default: true)
- * @returns The entity if found, null if not found and throwIfNotFound is false
- * @throws EntityNotFoundError if entity not found and throwIfNotFound is true
- */
-export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound: true): Entity;
-export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound: false): Entity | null;
-export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound?: boolean): Entity | null;
-/**
- * Finds multiple entities by name.
- *
- * @param graph - The knowledge graph to search
- * @param names - Array of entity names to find
- * @param throwIfAnyNotFound - Whether to throw if any entity doesn't exist (default: true)
- * @returns Array of found entities (may be shorter than names if throwIfAnyNotFound is false)
- * @throws EntityNotFoundError if any entity not found and throwIfAnyNotFound is true
- */
-export declare function findEntitiesByNames(graph: KnowledgeGraph, names: string[], throwIfAnyNotFound?: boolean): Entity[];
-/**
- * Checks if an entity exists in the graph.
- *
- * @param graph - The knowledge graph to search
- * @param name - The entity name to check
- * @returns true if entity exists, false otherwise
- */
-export declare function entityExists(graph: KnowledgeGraph, name: string): boolean;
-/**
- * Gets the index of an entity in the graph's entities array.
- *
- * @param graph - The knowledge graph to search
- * @param name - The entity name to find
- * @returns The index if found, -1 otherwise
- */
-export declare function getEntityIndex(graph: KnowledgeGraph, name: string): number;
-/**
- * Removes an entity from the graph by name.
- * Mutates the graph's entities array in place.
- *
- * @param graph - The knowledge graph to modify
- * @param name - The entity name to remove
- * @returns true if entity was removed, false if not found
- */
-export declare function removeEntityByName(graph: KnowledgeGraph, name: string): boolean;
-/**
- * Gets all entity names as a Set for fast lookup.
- *
- * @param graph - The knowledge graph
- * @returns Set of all entity names
- */
-export declare function getEntityNameSet(graph: KnowledgeGraph): Set<string>;
-/**
- * Groups entities by their type.
- *
- * @param entities - Array of entities to group
- * @returns Map of entity type to array of entities
- */
-export declare function groupEntitiesByType(entities: Entity[]): Map<string, Entity[]>;
-/**
- * Updates the lastModified timestamp on an entity.
- * Mutates the entity in place.
- *
- * @param entity - The entity to update
- * @returns The updated entity (same reference)
- */
-export declare function touchEntity(entity: Entity): Entity;
-/**
- * Normalizes a single tag to lowercase and trimmed.
- *
- * @param tag - Tag to normalize
- * @returns Normalized tag
- */
-export declare function normalizeTag(tag: string): string;
-/**
- * Normalizes an array of tags to lowercase.
- * Handles undefined/null input gracefully.
- *
- * @param tags - Array of tags to normalize, or undefined
- * @returns Normalized tags array, or empty array if input is undefined/null
- */
-export declare function normalizeTags(tags: string[] | undefined | null): string[];
-/**
- * Checks if an entity's tags include any of the specified search tags.
- * Both inputs are normalized before comparison.
- *
- * @param entityTags - Tags on the entity (may be undefined)
- * @param searchTags - Tags to search for (may be undefined)
- * @returns true if any search tag matches any entity tag, false if no match or either is empty
- */
-export declare function hasMatchingTag(entityTags: string[] | undefined, searchTags: string[] | undefined): boolean;
-/**
- * Checks if entity tags include ALL of the specified required tags.
- *
- * @param entityTags - Tags on the entity (may be undefined)
- * @param requiredTags - All tags that must be present
- * @returns true if all required tags are present
- */
-export declare function hasAllTags(entityTags: string[] | undefined, requiredTags: string[]): boolean;
-/**
- * Filters entities by tag match.
- * Returns all entities if searchTags is empty or undefined.
- *
- * @param entities - Array of entities with optional tags property
- * @param searchTags - Tags to filter by
- * @returns Filtered entities that have at least one matching tag
- */
-export declare function filterByTags<T extends {
-    tags?: string[];
-}>(entities: T[], searchTags: string[] | undefined): T[];
-/**
- * Adds new tags to an existing tag array, avoiding duplicates.
- * All tags are normalized to lowercase.
- *
- * @param existingTags - Current tags (may be undefined)
- * @param newTags - Tags to add
- * @returns Combined tags array with no duplicates
- */
-export declare function addUniqueTags(existingTags: string[] | undefined, newTags: string[]): string[];
-/**
- * Removes specified tags from an existing tag array.
- * Comparison is case-insensitive.
- *
- * @param existingTags - Current tags (may be undefined)
- * @param tagsToRemove - Tags to remove
- * @returns Tags array with specified tags removed
- */
-export declare function removeTags(existingTags: string[] | undefined, tagsToRemove: string[]): string[];
-/**
- * Check if a date falls within a specified range.
- *
- * @param date - ISO 8601 date string to check (may be undefined)
- * @param start - Optional start date (inclusive)
- * @param end - Optional end date (inclusive)
- * @returns True if date is within range or no filters are set
- *
- * @example
- * ```typescript
- * isWithinDateRange('2024-06-15T00:00:00Z', '2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z'); // true
- * isWithinDateRange('2024-06-15T00:00:00Z', '2024-07-01T00:00:00Z'); // false
- * isWithinDateRange(undefined); // true (no filters)
- * isWithinDateRange(undefined, '2024-01-01T00:00:00Z'); // false (has filter but no date)
- * ```
- */
-export declare function isWithinDateRange(date: string | undefined, start?: string, end?: string): boolean;
-/**
- * Parse and validate date range strings.
- *
- * @param startDate - Optional ISO 8601 start date
- * @param endDate - Optional ISO 8601 end date
- * @returns Parsed Date objects or null
- */
-export declare function parseDateRange(startDate?: string, endDate?: string): {
-    start: Date | null;
-    end: Date | null;
-};
-/**
- * Validate if a string is a valid ISO 8601 date.
- *
- * @param date - Date string to validate
- * @returns True if valid ISO 8601 date
- */
-export declare function isValidISODate(date: string): boolean;
-/**
- * Get current timestamp in ISO 8601 format.
- *
- * @returns Current timestamp string
- */
-export declare function getCurrentTimestamp(): string;
-/**
- * Checks if an entity's importance is within the specified range.
- * Entities without importance are treated as not matching if any filter is set.
- *
- * @param importance - The entity's importance value (may be undefined)
- * @param minImportance - Minimum importance filter (inclusive)
- * @param maxImportance - Maximum importance filter (inclusive)
- * @returns true if importance is within range or no filters are set
- *
- * @example
- * ```typescript
- * // Check if entity passes importance filter
- * if (isWithinImportanceRange(entity.importance, 5, 10)) {
- *   // Entity has importance between 5 and 10
- * }
- * ```
- */
-export declare function isWithinImportanceRange(importance: number | undefined, minImportance?: number, maxImportance?: number): boolean;
-/**
- * Filters entities by importance range.
- * Returns all entities if no importance filters are specified.
- *
- * @param entities - Array of entities to filter
- * @param minImportance - Minimum importance filter (inclusive)
- * @param maxImportance - Maximum importance filter (inclusive)
- * @returns Filtered entities within the importance range
- */
-export declare function filterByImportance(entities: Entity[], minImportance?: number, maxImportance?: number): Entity[];
-/**
- * Filters entities by creation date range.
- *
- * @param entities - Array of entities to filter
- * @param startDate - Start of date range (inclusive)
- * @param endDate - End of date range (inclusive)
- * @returns Filtered entities created within the date range
- */
-export declare function filterByCreatedDate(entities: Entity[], startDate?: string, endDate?: string): Entity[];
-/**
- * Filters entities by last modified date range.
- *
- * @param entities - Array of entities to filter
- * @param startDate - Start of date range (inclusive)
- * @param endDate - End of date range (inclusive)
- * @returns Filtered entities modified within the date range
- */
-export declare function filterByModifiedDate(entities: Entity[], startDate?: string, endDate?: string): Entity[];
-/**
- * Filters entities by entity type.
- *
- * @param entities - Array of entities to filter
- * @param entityType - Entity type to filter by (case-sensitive)
- * @returns Filtered entities of the specified type
- */
-export declare function filterByEntityType(entities: Entity[], entityType?: string): Entity[];
-/**
- * Common search filters that can be applied to entities.
- */
-export interface CommonSearchFilters {
-    tags?: string[];
-    minImportance?: number;
-    maxImportance?: number;
-    entityType?: string;
-    createdAfter?: string;
-    createdBefore?: string;
-    modifiedAfter?: string;
-    modifiedBefore?: string;
-}
-/**
- * Checks if an entity passes all the specified filters.
- * Short-circuits on first failing filter for performance.
- *
- * Note: Tag filtering should be handled separately using hasMatchingTag
- * as it requires special normalization logic.
- *
- * @param entity - Entity to check
- * @param filters - Filters to apply
- * @returns true if entity passes all filters
- */
-export declare function entityPassesFilters(entity: Entity, filters: Omit<CommonSearchFilters, 'tags'>): boolean;
-/**
- * Sanitizes an object by removing potentially dangerous keys.
- * This prevents prototype pollution attacks when using Object.assign() or spread operators.
- *
- * @param obj - The object to sanitize
- * @returns A new object with dangerous keys removed
- *
- * @example
- * ```typescript
- * // Safe usage with Object.assign
- * const updates = sanitizeObject(userInput);
- * Object.assign(entity, updates);
- *
- * // Protects against prototype pollution
- * const malicious = { __proto__: { admin: true } };
- * const safe = sanitizeObject(malicious); // { }
- * ```
- */
-export declare function sanitizeObject<T extends Record<string, unknown>>(obj: T): Partial<T>;
-/**
- * Escapes a CSV field to prevent formula injection attacks.
- * Prepends a single quote to values that start with dangerous characters.
- *
- * @param field - The field value to escape
- * @returns Escaped field value safe for CSV export
- *
- * @example
- * ```typescript
- * escapeCsvFormula('=SUM(A1:A10)'); // "'=SUM(A1:A10)"
- * escapeCsvFormula('normal text'); // 'normal text'
- * ```
- */
-export declare function escapeCsvFormula(field: string | undefined | null): string;
-/**
- * Validate and normalize a file path to prevent path traversal attacks.
- *
- * This function:
- * - Normalizes the path to canonical form
- * - Converts relative paths to absolute paths
- * - Detects and prevents path traversal attempts (..)
- *
- * @param filePath - The file path to validate
- * @param baseDir - Optional base directory for relative paths (defaults to process.cwd())
- * @returns Validated absolute file path
- * @throws {FileOperationError} If path traversal is detected or path is invalid
- *
- * @example
- * ```typescript
- * // Valid paths
- * validateFilePath('/var/data/memory.jsonl'); // Returns absolute path
- * validateFilePath('data/memory.jsonl'); // Returns absolute path from cwd
- *
- * // Invalid paths (throws FileOperationError)
- * validateFilePath('../../../etc/passwd'); // Path traversal detected
- * validateFilePath('/var/data/../../../etc/passwd'); // Path traversal detected
- * ```
- */
-export declare function validateFilePath(filePath: string, baseDir?: string): string;
-/**
- * Default memory file path (in project root directory, outside dist/).
- */
-export declare const defaultMemoryPath: string;
-/**
- * Ensure memory file path with backward compatibility migration.
- *
- * Handles:
- * 1. Custom MEMORY_FILE_PATH environment variable (with path traversal protection)
- * 2. Backward compatibility: migrates memory.json to memory.jsonl
- * 3. Absolute vs relative path resolution
- *
- * @returns Resolved and validated memory file path
- * @throws {FileOperationError} If path traversal is detected in MEMORY_FILE_PATH
- *
- * @example
- * ```typescript
- * // Use environment variable
- * process.env.MEMORY_FILE_PATH = '/data/memory.jsonl';
- * const path = await ensureMemoryFilePath(); // '/data/memory.jsonl'
- *
- * // Use default path
- * delete process.env.MEMORY_FILE_PATH;
- * const path = await ensureMemoryFilePath(); // './memory.jsonl'
- *
- * // Invalid path (throws error)
- * process.env.MEMORY_FILE_PATH = '../../../etc/passwd';
- * await ensureMemoryFilePath(); // Throws FileOperationError
- * ```
- */
-export declare function ensureMemoryFilePath(): Promise<string>;
-//# sourceMappingURL=entityUtils.d.ts.map

package/dist/utils/entityUtils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"entityUtils.d.ts","sourceRoot":"","sources":["../../src/utils/entityUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO9C;AAID;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,IAAI,GACpB,MAAM,CAAC;AACV,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,KAAK,GACrB,MAAM,GAAG,IAAI,CAAC;AACjB,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,OAAO,GACxB,MAAM,GAAG,IAAI,CAAC;AAajB;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,EAAE,EACf,kBAAkB,GAAE,OAAc,GACjC,MAAM,EAAE,CAaV;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAK/E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,CAAC,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAY7E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGlD;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,EAAE,CAGzE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,GAC/B,OAAO,CAQT;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAChC,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAMT;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EACxD,QAAQ,EAAE,CAAC,EAAE,EACb,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,GAC/B,CAAC,EAAE,CAYL;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EAAE,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,EAAE,CAMV;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,MAAM,EAAE,GAAG,SAAS,EAClC,YAAY,EAAE,MAAM,EAAE,GACrB,MAAM,EAAE,CAKV;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAsCT;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,CAmB1C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGpD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAqBT;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAAE,EAClB,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,EAAE,CAOV;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,EAAE,CAOV;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,EAAE,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAAE,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,EAAE,CAKV;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,GACzC,OAAO,CAsBT;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAuBpF;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CASzE;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,MAAM,CAuB1F;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAG7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAmC5D"}