rag-lite-ts 1.0.1

package/dist/resource-manager.js

@@ -0,0 +1,389 @@
+import { openDatabase, initializeSchema, getStoredModelInfo, setStoredModelInfo } from './db.js';
+import { IndexManager } from './index-manager.js';
+import { initializeEmbeddingEngine } from './embedder.js';
+import { config, getModelDefaults } from './config.js';
+import { ErrorFactory } from './api-errors.js';
+import { join, resolve } from 'path';
+import { existsSync } from 'fs';
+/**
+ * Internal ResourceManager for automatic initialization and cleanup
+ * Implements singleton pattern for resource sharing across instances
+ * Requirements: 5.1, 5.4 - Automatic resource management and lifecycle handling
+ */
+export class ResourceManager {
+    static instances = new Map();
+    static cleanupHandlersSet = false;
+    database = null;
+    indexManager = null;
+    embedder = null;
+    isInitialized = false;
+    initializationPromise = null;
+    resourceKey;
+    config;
+    /**
+     * Get or create ResourceManager instance for the given configuration
+     * Implements singleton pattern for resource sharing
+     * @param config - Resource configuration
+     * @returns ResourceManager instance
+     */
+    static getInstance(config = {}) {
+        // Create a unique key based on the configuration
+        const resolvedConfig = ResourceManager.resolveConfig(config);
+        const key = `${resolvedConfig.dbPath}:${resolvedConfig.indexPath}:${resolvedConfig.modelName}`;
+        if (!ResourceManager.instances.has(key)) {
+            ResourceManager.instances.set(key, new ResourceManager(key, resolvedConfig));
+        }
+        return ResourceManager.instances.get(key);
+    }
+    /**
+     * Resolve and normalize configuration with defaults
+     */
+    static resolveConfig(resourceConfig) {
+        const basePath = resourceConfig.basePath ? resolve(resourceConfig.basePath) : process.cwd();
+        return {
+            basePath,
+            dbPath: resourceConfig.dbPath ? resolve(resourceConfig.dbPath) : join(basePath, 'db.sqlite'),
+            indexPath: resourceConfig.indexPath ? resolve(resourceConfig.indexPath) : join(basePath, 'vector-index.bin'),
+            modelName: resourceConfig.modelName || config.embedding_model,
+            batchSize: resourceConfig.batchSize || config.batch_size,
+            skipModelCheck: resourceConfig.skipModelCheck || false
+        };
+    }
+    /**
+     * Private constructor - use getInstance() instead
+     */
+    constructor(resourceKey, config) {
+        this.resourceKey = resourceKey;
+        this.config = config;
+        // Set up automatic cleanup handlers
+        this.setupCleanupHandlers();
+    }
+    /**
+     * Initialize all resources with lazy loading
+     * Requirements: 5.1 - Automatic resource management
+     */
+    async initialize() {
+        // Return existing initialization promise if already in progress
+        if (this.initializationPromise) {
+            await this.initializationPromise;
+            return this.getResources();
+        }
+        // Start new initialization if not already initialized
+        if (!this.isInitialized) {
+            this.initializationPromise = this.performInitialization();
+            await this.initializationPromise;
+        }
+        return this.getResources();
+    }
+    /**
+     * Perform the actual initialization steps
+     */
+    async performInitialization() {
+        try {
+            console.log('Initializing resources...');
+            // Step 1: Initialize database
+            await this.initializeDatabase();
+            // Step 2: Initialize embedder (either from stored model info or config)
+            await this.initializeEmbedder();
+            // Step 3: Initialize index manager with model compatibility check
+            await this.initializeIndexManager();
+            this.isInitialized = true;
+            console.log('Resources initialized successfully');
+        }
+        catch (error) {
+            // Clean up partial initialization on failure
+            await this.cleanup();
+            throw ErrorFactory.createResourceError(error, 'initialization');
+        }
+        finally {
+            this.initializationPromise = null;
+        }
+    }
+    /**
+     * Initialize database connection and schema
+     */
+    async initializeDatabase() {
+        if (this.database) {
+            return;
+        }
+        console.log('Opening database connection...');
+        this.database = await openDatabase(this.config.dbPath);
+        await initializeSchema(this.database);
+    }
+    /**
+     * Initialize embedder based on stored model info or configuration
+     * Requirements: 5.1 - Embedder initialization based on stored model info from database
+     */
+    async initializeEmbedder() {
+        if (this.embedder) {
+            return;
+        }
+        if (!this.database) {
+            throw new Error('Database must be initialized before embedder');
+        }
+        let modelName = this.config.modelName;
+        // Try to get stored model info from database first
+        try {
+            const storedModelInfo = await getStoredModelInfo(this.database);
+            if (storedModelInfo && storedModelInfo.modelName) {
+                modelName = storedModelInfo.modelName;
+                console.log(`Using stored model from database: ${modelName}`);
+            }
+            else if (this.config.modelName) {
+                console.log(`No stored model found, using configured model: ${modelName}`);
+                // Store the model info for future use
+                const modelDefaults = getModelDefaults(modelName);
+                await setStoredModelInfo(this.database, modelName, modelDefaults.dimensions);
+            }
+            else {
+                // Use default model from config
+                modelName = config.embedding_model;
+                console.log(`Using default model: ${modelName}`);
+                const modelDefaults = getModelDefaults(modelName);
+                await setStoredModelInfo(this.database, modelName, modelDefaults.dimensions);
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to read stored model info: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            // Fall back to configured or default model
+            if (!modelName) {
+                modelName = config.embedding_model;
+            }
+        }
+        console.log(`Loading embedding model: ${modelName}...`);
+        this.embedder = await initializeEmbeddingEngine(modelName, this.config.batchSize);
+    }
+    /**
+     * Initialize index manager with model compatibility validation
+     */
+    async initializeIndexManager() {
+        if (this.indexManager) {
+            return;
+        }
+        if (!this.database || !this.embedder) {
+            throw new Error('Database and embedder must be initialized before index manager');
+        }
+        console.log('Initializing index manager...');
+        // Get model info for index manager initialization
+        const storedModelInfo = await getStoredModelInfo(this.database);
+        const modelName = storedModelInfo?.modelName || this.embedder.getModelName();
+        const dimensions = storedModelInfo?.dimensions || getModelDefaults(modelName).dimensions;
+        this.indexManager = new IndexManager(this.config.indexPath, this.config.dbPath, dimensions, modelName);
+        await this.indexManager.initialize(this.config.skipModelCheck);
+    }
+    /**
+     * Get initialized resources
+     * @throws Error if resources are not initialized
+     */
+    getResources() {
+        if (!this.isInitialized || !this.database || !this.indexManager || !this.embedder) {
+            throw new Error('Resources not properly initialized');
+        }
+        return {
+            database: this.database,
+            indexManager: this.indexManager,
+            embedder: this.embedder
+        };
+    }
+    /**
+     * Get database connection (lazy initialization)
+     */
+    async getDatabase() {
+        if (!this.database) {
+            await this.initialize();
+        }
+        return this.database;
+    }
+    /**
+     * Get index manager (lazy initialization)
+     */
+    async getIndexManager() {
+        if (!this.indexManager) {
+            await this.initialize();
+        }
+        return this.indexManager;
+    }
+    /**
+     * Get embedder (lazy initialization)
+     */
+    async getEmbedder() {
+        if (!this.embedder) {
+            await this.initialize();
+        }
+        return this.embedder;
+    }
+    /**
+     * Check if resources are initialized
+     */
+    isResourcesInitialized() {
+        return this.isInitialized;
+    }
+    /**
+     * Validate that required files exist for search operations
+     * @throws ResourceError with user-friendly message if files are missing
+     */
+    async validateSearchFiles() {
+        if (!existsSync(this.config.dbPath)) {
+            throw ErrorFactory.createResourceError(new Error(`Database file not found: ${this.config.dbPath}`), 'missing_database');
+        }
+        if (!existsSync(this.config.indexPath)) {
+            throw ErrorFactory.createResourceError(new Error(`Vector index file not found: ${this.config.indexPath}`), 'missing_index');
+        }
+    }
+    /**
+     * Set up automatic cleanup handlers
+     * Requirements: 5.5 - Automatic cleanup on process exit
+     */
+    setupCleanupHandlers() {
+        if (ResourceManager.cleanupHandlersSet) {
+            return;
+        }
+        ResourceManager.cleanupHandlersSet = true;
+        const cleanupAll = async () => {
+            const instances = Array.from(ResourceManager.instances.values());
+            await Promise.all(instances.map(instance => instance.cleanup()));
+        };
+        // Handle various exit scenarios
+        process.on('exit', () => {
+            // Synchronous cleanup for exit event
+            for (const instance of ResourceManager.instances.values()) {
+                try {
+                    instance.performSyncCleanup();
+                }
+                catch (error) {
+                    // Silent cleanup on exit
+                }
+            }
+        });
+        process.on('SIGINT', async () => {
+            await cleanupAll();
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            await cleanupAll();
+            process.exit(0);
+        });
+        process.on('uncaughtException', async (error) => {
+            console.error('Uncaught exception:', error);
+            await cleanupAll();
+            process.exit(1);
+        });
+        process.on('unhandledRejection', async (reason) => {
+            console.error('Unhandled rejection:', reason);
+            await cleanupAll();
+            process.exit(1);
+        });
+    }
+    /**
+     * Synchronous cleanup for process exit handlers
+     */
+    performSyncCleanup() {
+        try {
+            if (this.database) {
+                // Note: Synchronous close is not available in sqlite3, 
+                // but we set to null to prevent further use
+                this.database = null;
+            }
+            this.indexManager = null;
+            this.embedder = null;
+            this.isInitialized = false;
+        }
+        catch (error) {
+            // Silent cleanup
+        }
+    }
+    /**
+     * Clean up all resources with proper error handling
+     * Requirements: 5.5 - Proper resource disposal and error handling during cleanup
+     */
+    async cleanup() {
+        const errors = [];
+        // Clean up database connection
+        if (this.database) {
+            try {
+                await this.database.close();
+                console.log('Database connection closed successfully');
+            }
+            catch (error) {
+                const errorMsg = `Failed to close database: ${error instanceof Error ? error.message : String(error)}`;
+                errors.push(errorMsg);
+                console.error(errorMsg);
+            }
+            finally {
+                this.database = null;
+            }
+        }
+        // Clean up index manager
+        if (this.indexManager) {
+            try {
+                await this.indexManager.close();
+                console.log('Index manager closed successfully');
+            }
+            catch (error) {
+                const errorMsg = `Failed to close index manager: ${error instanceof Error ? error.message : String(error)}`;
+                errors.push(errorMsg);
+                console.error(errorMsg);
+            }
+            finally {
+                this.indexManager = null;
+            }
+        }
+        // Clean up embedder (no explicit cleanup needed, just nullify reference)
+        if (this.embedder) {
+            this.embedder = null;
+            console.log('Embedder reference cleared');
+        }
+        // Reset state
+        this.isInitialized = false;
+        this.initializationPromise = null;
+        // Remove from instances map
+        ResourceManager.instances.delete(this.resourceKey);
+        // Log cleanup completion
+        if (errors.length === 0) {
+            console.log('Resource cleanup completed successfully');
+        }
+        else {
+            console.warn(`Resource cleanup completed with ${errors.length} error(s):`);
+            errors.forEach(error => console.warn(`  - ${error}`));
+        }
+    }
+    /**
+     * Clean up all instances (for testing or shutdown)
+     * Requirements: 5.5 - Ensure resources are properly disposed when no longer needed
+     */
+    static async cleanupAll() {
+        const instances = Array.from(ResourceManager.instances.values());
+        if (instances.length === 0) {
+            console.log('No resource instances to clean up');
+            return;
+        }
+        console.log(`Cleaning up ${instances.length} resource instance(s)...`);
+        const cleanupPromises = instances.map(async (instance, index) => {
+            try {
+                await instance.cleanup();
+                console.log(`Instance ${index + 1}/${instances.length} cleaned up successfully`);
+            }
+            catch (error) {
+                console.error(`Failed to cleanup instance ${index + 1}/${instances.length}:`, error instanceof Error ? error.message : String(error));
+            }
+        });
+        await Promise.allSettled(cleanupPromises);
+        ResourceManager.instances.clear();
+        console.log('All resource instances cleanup completed');
+    }
+    /**
+     * Get the number of active resource instances
+     */
+    static getActiveInstanceCount() {
+        return ResourceManager.instances.size;
+    }
+    /**
+     * Check if a specific resource configuration is already managed
+     */
+    static hasInstance(config) {
+        const resolvedConfig = ResourceManager.resolveConfig(config);
+        const key = `${resolvedConfig.dbPath}:${resolvedConfig.indexPath}:${resolvedConfig.modelName}`;
+        return ResourceManager.instances.has(key);
+    }
+}
+//# sourceMappingURL=resource-manager.js.map

package/dist/resource-manager.js.map

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

package/dist/search-standalone.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Standalone search script for direct node execution
+ * Usage: node search.js <query> [--top-k <number>] [--rerank|--no-rerank]
+ */
+export {};
+//# sourceMappingURL=search-standalone.d.ts.map

package/dist/search-standalone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-standalone.d.ts","sourceRoot":"","sources":["../src/search-standalone.ts"],"names":[],"mappings":";AAEA;;;GAGG"}

package/dist/search-standalone.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * Standalone search script for direct node execution
+ * Usage: node search.js <query> [--top-k <number>] [--rerank|--no-rerank]
+ */
+import { runSearch } from './cli/search.js';
+import { EXIT_CODES, ConfigurationError } from './config.js';
+function parseArgs() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.error('RAG-lite TS Document Search');
+        console.error('');
+        console.error('Usage: node search.js <query> [options]');
+        console.error('');
+        console.error('Arguments:');
+        console.error('  <query>    Search query (wrap in quotes if it contains spaces)');
+        console.error('');
+        console.error('Options:');
+        console.error('  --top-k <number>    Number of results to return (default: 10, max: 100)');
+        console.error('  --rerank           Enable reranking for better results');
+        console.error('  --no-rerank        Disable reranking');
+        console.error('');
+        console.error('Examples:');
+        console.error('  node search.js "machine learning"');
+        console.error('  node search.js "API documentation" --top-k 10');
+        console.error('  node search.js "tutorial" --rerank');
+        console.error('  node search.js "how to install" --top-k 20 --rerank');
+        console.error('');
+        console.error('Note: Make sure you have ingested documents first using:');
+        console.error('  node indexer.js <path>');
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const queryParts = [];
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--top-k') {
+            const nextArg = args[i + 1];
+            if (!nextArg) {
+                console.error('Error: --top-k requires a numeric value');
+                console.error('');
+                console.error('Examples:');
+                console.error('  --top-k 5     # Return 5 results');
+                console.error('  --top-k 20    # Return 20 results');
+                process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+            }
+            const topK = parseInt(nextArg, 10);
+            if (isNaN(topK) || topK <= 0) {
+                console.error('Error: --top-k must be a positive number');
+                console.error('');
+                console.error('Examples:');
+                console.error('  --top-k 5     # Return 5 results');
+                console.error('  --top-k 20    # Return 20 results');
+                process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+            }
+            if (topK > 100) {
+                console.warn(`Warning: Large --top-k value (${topK}) may impact performance. Consider using a smaller value.`);
+            }
+            options['top-k'] = topK;
+            i++; // Skip next argument
+        }
+        else if (arg === '--rerank') {
+            options.rerank = true;
+        }
+        else if (arg === '--no-rerank') {
+            options.rerank = false;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            // Re-show help and exit
+            parseArgs();
+        }
+        else if (arg.startsWith('--')) {
+            console.error(`Error: Unknown option '${arg}'`);
+            console.error('');
+            console.error('Available options:');
+            console.error('  --top-k <number>    Number of results to return');
+            console.error('  --rerank           Enable reranking');
+            console.error('  --no-rerank        Disable reranking');
+            console.error('  --help, -h         Show this help');
+            process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+        }
+        else {
+            queryParts.push(arg);
+        }
+    }
+    const query = queryParts.join(' ');
+    if (!query.trim()) {
+        console.error('Error: Query cannot be empty');
+        console.error('');
+        console.error('Please provide a search query:');
+        console.error('  node search.js "your search terms"');
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    if (query.trim().length > 500) {
+        console.error('Error: Query is too long (maximum 500 characters)');
+        console.error('');
+        console.error('Please use a shorter, more specific query.');
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return { query, options };
+}
+async function main() {
+    const { query, options } = parseArgs();
+    await runSearch(query, options);
+}
+main().catch((error) => {
+    if (error instanceof ConfigurationError) {
+        console.error('Configuration Error:');
+        console.error(error.message);
+        process.exit(error.exitCode);
+    }
+    else {
+        console.error('Fatal Error:', error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.GENERAL_ERROR);
+    }
+});
+//# sourceMappingURL=search-standalone.js.map

package/dist/search-standalone.js.map

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

package/dist/search.d.ts

@@ -0,0 +1,92 @@
+import { EmbeddingEngine } from './embedder.js';
+import { IndexManager } from './index-manager.js';
+import { DatabaseConnection } from './db.js';
+import type { SearchResult, SearchOptions } from './types.js';
+/**
+ * User-friendly error class with actionable suggestions
+ */
+export declare class SearchError extends Error {
+    code: string;
+    suggestions: string[];
+    constructor(message: string, code: string, suggestions: string[]);
+}
+/**
+ * Search engine that provides semantic search capabilities
+ * Implements the core search pipeline: query embedding → vector search → metadata retrieval → optional reranking
+ * Supports concurrent read operations for multiple simultaneous queries
+ */
+export declare class SearchEngine {
+    private static instances;
+    private static cleanupHandlersSet;
+    private embedder;
+    private indexManager;
+    private dbConnection;
+    private reranker;
+    private isInitialized;
+    private indexPath;
+    private dbPath;
+    private enableReranking;
+    /**
+     * Creates a new SearchEngine with simplified constructor
+     * Search engine is ready to use immediately without requiring initialization calls (Requirement 3.5)
+     * @param indexPath - Path to vector index file (defaults to './vector-index.bin')
+     * @param dbPath - Path to database file (defaults to './db.sqlite')
+     */
+    constructor(indexPath?: string, dbPath?: string);
+    /**
+     * Legacy constructor for backward compatibility
+     * @deprecated Use the simple constructor new SearchEngine(indexPath?, dbPath?) instead
+     */
+    static createWithComponents(embedder: EmbeddingEngine, indexManager: IndexManager, dbConnection: DatabaseConnection, enableReranking?: boolean): SearchEngine;
+    /**
+     * Automatically initialize resources on first use with user-friendly error handling
+     * Implements lazy initialization as required by Requirements 3.5, 4.3, 5.1, 5.2
+     */
+    private ensureInitialized;
+    /**
+     * Create user-friendly error messages with actionable suggestions
+     * Implements requirement 5.3: Clear, actionable error messages with specific next steps
+     */
+    private createUserFriendlyError;
+    /**
+     * Initialize the search engine (public method for backward compatibility)
+     * Sets up database, index manager, and embedding engine
+     */
+    initialize(): Promise<void>;
+    /**
+     * Perform semantic search on the indexed documents (matches README API)
+     * Automatically initializes resources on first use (Requirements 4.1, 4.2, 4.4, 4.5)
+     * Supports concurrent read operations for multiple simultaneous queries
+     * @param query - Search query string
+     * @param options - Search options including top_k and rerank settings
+     * @returns Promise resolving to array of search results
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Format search results with proper structure
+     * @param chunks - Database chunks with metadata
+     * @param distances - Similarity distances from vector search
+     * @param embeddingIds - Embedding IDs in search result order
+     * @returns Formatted search results
+     */
+    private formatSearchResults;
+    /**
+     * Get search engine statistics
+     * @returns Object with current search engine stats
+     */
+    getStats(): Promise<{
+        totalChunks: number;
+        indexSize: number;
+        rerankingEnabled: boolean;
+        isInitialized: boolean;
+    }>;
+    /**
+     * Set up automatic cleanup on process exit (Requirement 5.5)
+     */
+    private setupAutomaticCleanup;
+    /**
+     * Clean up resources (Requirement 5.5)
+     */
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA6B,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAA6D,MAAM,SAAS,CAAC;AAExG,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK9D;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAG3B,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,MAAM,EAAE;gBAF5B,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE;CAK/B;AAyBD;;;;GAIG;AACH,qBAAa,YAAY;IAEvB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA2B;IACnD,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAE1C,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,eAAe,CAAkB;IAEzC;;;;;OAKG;gBACS,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAmB/C;;;OAGG;IACH,MAAM,CAAC,oBAAoB,CACzB,QAAQ,EAAE,eAAe,EACzB,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,kBAAkB,EAChC,eAAe,GAAE,OAAe,GAC/B,YAAY;IAgBf;;;OAGG;YACW,iBAAiB;IA+F/B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAmH/B;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAiFjF;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAsC3B;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IAmBF;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0D7B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAsB/B"}