agentic-flow 2.0.7 → 3.0.0-alpha.2

package/dist/packages/agentdb/src/controllers/MetadataFilter.js

@@ -0,0 +1,243 @@
+/**
+ * Advanced Metadata Filtering
+ *
+ * Implements MongoDB-style query operators for filtering
+ * episodes and patterns based on metadata fields.
+ *
+ * Supported operators:
+ * - $eq: Equal to
+ * - $ne: Not equal to
+ * - $gt: Greater than
+ * - $gte: Greater than or equal to
+ * - $lt: Less than
+ * - $lte: Less than or equal to
+ * - $in: Value is in array
+ * - $nin: Value is not in array
+ * - $contains: String/array contains value
+ * - $exists: Field exists
+ */
+export class MetadataFilter {
+    /**
+     * Apply filters to a collection of items
+     *
+     * @param items - Items to filter
+     * @param filters - MongoDB-style filter object
+     * @returns Filtered items
+     */
+    static apply(items, filters) {
+        if (!filters || Object.keys(filters).length === 0) {
+            return items;
+        }
+        return items.filter(item => this.matchesFilters(item, filters));
+    }
+    /**
+     * Check if an item matches all filters
+     */
+    static matchesFilters(item, filters) {
+        for (const [field, filter] of Object.entries(filters)) {
+            if (!this.matchesFilter(item, field, filter)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Check if an item matches a single filter
+     */
+    static matchesFilter(item, field, filter) {
+        // Get field value (supports nested paths like "metadata.year")
+        const value = this.getFieldValue(item, field);
+        // Handle simple equality
+        if (typeof filter !== 'object' || Array.isArray(filter)) {
+            return value === filter;
+        }
+        // Handle operator-based filters
+        const operators = filter;
+        for (const [operator, operand] of Object.entries(operators)) {
+            switch (operator) {
+                case '$eq':
+                    if (value !== operand)
+                        return false;
+                    break;
+                case '$ne':
+                    if (value === operand)
+                        return false;
+                    break;
+                case '$gt':
+                    if (!(value > operand))
+                        return false;
+                    break;
+                case '$gte':
+                    if (!(value >= operand))
+                        return false;
+                    break;
+                case '$lt':
+                    if (!(value < operand))
+                        return false;
+                    break;
+                case '$lte':
+                    if (!(value <= operand))
+                        return false;
+                    break;
+                case '$in':
+                    if (!Array.isArray(operand) || !operand.includes(value))
+                        return false;
+                    break;
+                case '$nin':
+                    if (!Array.isArray(operand) || operand.includes(value))
+                        return false;
+                    break;
+                case '$contains':
+                    if (typeof value === 'string') {
+                        if (!value.includes(operand))
+                            return false;
+                    }
+                    else if (Array.isArray(value)) {
+                        if (!value.includes(operand))
+                            return false;
+                    }
+                    else {
+                        return false;
+                    }
+                    break;
+                case '$exists':
+                    const exists = value !== undefined && value !== null;
+                    if (exists !== operand)
+                        return false;
+                    break;
+                default:
+                    console.warn(`Unknown operator: ${operator}`);
+                    return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Get field value from item (supports nested paths)
+     */
+    static getFieldValue(item, field) {
+        const parts = field.split('.');
+        let value = item;
+        for (const part of parts) {
+            if (value === null || value === undefined) {
+                return undefined;
+            }
+            // Parse metadata JSON if needed
+            if (part === 'metadata' && typeof value.metadata === 'string') {
+                try {
+                    value.metadata = JSON.parse(value.metadata);
+                }
+                catch (e) {
+                    return undefined;
+                }
+            }
+            value = value[part];
+        }
+        return value;
+    }
+    /**
+     * Build SQL WHERE clause from filters (for database queries)
+     *
+     * @param filters - Metadata filters
+     * @param tableName - Table name for column references
+     * @returns SQL WHERE clause and parameters
+     */
+    static toSQL(filters, tableName = '') {
+        const conditions = [];
+        const params = [];
+        const prefix = tableName ? `${tableName}.` : '';
+        for (const [field, filter] of Object.entries(filters)) {
+            // For metadata fields, use JSON extraction
+            const isMetadata = field.startsWith('metadata.');
+            const columnRef = isMetadata
+                ? `json_extract(${prefix}metadata, '$.${field.slice(9)}')`
+                : `${prefix}${field}`;
+            if (typeof filter !== 'object' || Array.isArray(filter)) {
+                // Simple equality
+                conditions.push(`${columnRef} = ?`);
+                params.push(filter);
+            }
+            else {
+                // Operator-based filters
+                const operators = filter;
+                for (const [operator, operand] of Object.entries(operators)) {
+                    switch (operator) {
+                        case '$eq':
+                            conditions.push(`${columnRef} = ?`);
+                            params.push(operand);
+                            break;
+                        case '$ne':
+                            conditions.push(`${columnRef} != ?`);
+                            params.push(operand);
+                            break;
+                        case '$gt':
+                            conditions.push(`${columnRef} > ?`);
+                            params.push(operand);
+                            break;
+                        case '$gte':
+                            conditions.push(`${columnRef} >= ?`);
+                            params.push(operand);
+                            break;
+                        case '$lt':
+                            conditions.push(`${columnRef} < ?`);
+                            params.push(operand);
+                            break;
+                        case '$lte':
+                            conditions.push(`${columnRef} <= ?`);
+                            params.push(operand);
+                            break;
+                        case '$in':
+                            if (Array.isArray(operand)) {
+                                const placeholders = operand.map(() => '?').join(', ');
+                                conditions.push(`${columnRef} IN (${placeholders})`);
+                                params.push(...operand);
+                            }
+                            break;
+                        case '$nin':
+                            if (Array.isArray(operand)) {
+                                const placeholders = operand.map(() => '?').join(', ');
+                                conditions.push(`${columnRef} NOT IN (${placeholders})`);
+                                params.push(...operand);
+                            }
+                            break;
+                        case '$contains':
+                            conditions.push(`${columnRef} LIKE ?`);
+                            params.push(`%${operand}%`);
+                            break;
+                        case '$exists':
+                            if (operand) {
+                                conditions.push(`${columnRef} IS NOT NULL`);
+                            }
+                            else {
+                                conditions.push(`${columnRef} IS NULL`);
+                            }
+                            break;
+                    }
+                }
+            }
+        }
+        const where = conditions.length > 0 ? conditions.join(' AND ') : '1=1';
+        return { where, params };
+    }
+    /**
+     * Validate filter object
+     */
+    static validate(filters) {
+        const errors = [];
+        for (const [field, filter] of Object.entries(filters)) {
+            if (!field || field.trim() === '') {
+                errors.push('Filter field name cannot be empty');
+            }
+            if (typeof filter === 'object' && !Array.isArray(filter)) {
+                const operators = Object.keys(filter);
+                for (const op of operators) {
+                    if (!op.startsWith('$')) {
+                        errors.push(`Invalid operator: ${op} (must start with $)`);
+                    }
+                }
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+}
+//# sourceMappingURL=MetadataFilter.js.map

package/dist/packages/agentdb/src/controllers/MetadataFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetadataFilter.js","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/controllers/MetadataFilter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Advanced Metadata Filtering\n *\n * Implements MongoDB-style query operators for filtering\n * episodes and patterns based on metadata fields.\n *\n * Supported operators:\n * - $eq: Equal to\n * - $ne: Not equal to\n * - $gt: Greater than\n * - $gte: Greater than or equal to\n * - $lt: Less than\n * - $lte: Less than or equal to\n * - $in: Value is in array\n * - $nin: Value is not in array\n * - $contains: String/array contains value\n * - $exists: Field exists\n */\n\nexport type FilterOperator = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$nin' | '$contains' | '$exists';\n\nexport type FilterValue = string | number | boolean | string[] | number[] | { [op in FilterOperator]?: any };\n\nexport interface MetadataFilters {\n  [field: string]: FilterValue;\n}\n\nexport interface FilterableItem {\n  metadata?: any;\n  [key: string]: any;\n}\n\nexport class MetadataFilter {\n  /**\n   * Apply filters to a collection of items\n   *\n   * @param items - Items to filter\n   * @param filters - MongoDB-style filter object\n   * @returns Filtered items\n   */\n  static apply<T extends FilterableItem>(items: T[], filters: MetadataFilters): T[] {\n    if (!filters || Object.keys(filters).length === 0) {\n      return items;\n    }\n\n    return items.filter(item => this.matchesFilters(item, filters));\n  }\n\n  /**\n   * Check if an item matches all filters\n   */\n  private static matchesFilters(item: FilterableItem, filters: MetadataFilters): boolean {\n    for (const [field, filter] of Object.entries(filters)) {\n      if (!this.matchesFilter(item, field, filter)) {\n        return false;\n      }\n    }\n    return true;\n  }\n\n  /**\n   * Check if an item matches a single filter\n   */\n  private static matchesFilter(item: FilterableItem, field: string, filter: FilterValue): boolean {\n    // Get field value (supports nested paths like \"metadata.year\")\n    const value = this.getFieldValue(item, field);\n\n    // Handle simple equality\n    if (typeof filter !== 'object' || Array.isArray(filter)) {\n      return value === filter;\n    }\n\n    // Handle operator-based filters\n    const operators = filter as { [op in FilterOperator]?: any };\n\n    for (const [operator, operand] of Object.entries(operators)) {\n      switch (operator as FilterOperator) {\n        case '$eq':\n          if (value !== operand) return false;\n          break;\n\n        case '$ne':\n          if (value === operand) return false;\n          break;\n\n        case '$gt':\n          if (!(value > operand)) return false;\n          break;\n\n        case '$gte':\n          if (!(value >= operand)) return false;\n          break;\n\n        case '$lt':\n          if (!(value < operand)) return false;\n          break;\n\n        case '$lte':\n          if (!(value <= operand)) return false;\n          break;\n\n        case '$in':\n          if (!Array.isArray(operand) || !operand.includes(value)) return false;\n          break;\n\n        case '$nin':\n          if (!Array.isArray(operand) || operand.includes(value)) return false;\n          break;\n\n        case '$contains':\n          if (typeof value === 'string') {\n            if (!value.includes(operand)) return false;\n          } else if (Array.isArray(value)) {\n            if (!value.includes(operand)) return false;\n          } else {\n            return false;\n          }\n          break;\n\n        case '$exists':\n          const exists = value !== undefined && value !== null;\n          if (exists !== operand) return false;\n          break;\n\n        default:\n          console.warn(`Unknown operator: ${operator}`);\n          return false;\n      }\n    }\n\n    return true;\n  }\n\n  /**\n   * Get field value from item (supports nested paths)\n   */\n  private static getFieldValue(item: FilterableItem, field: string): any {\n    const parts = field.split('.');\n    let value: any = item;\n\n    for (const part of parts) {\n      if (value === null || value === undefined) {\n        return undefined;\n      }\n\n      // Parse metadata JSON if needed\n      if (part === 'metadata' && typeof value.metadata === 'string') {\n        try {\n          value.metadata = JSON.parse(value.metadata);\n        } catch (e) {\n          return undefined;\n        }\n      }\n\n      value = value[part];\n    }\n\n    return value;\n  }\n\n  /**\n   * Build SQL WHERE clause from filters (for database queries)\n   *\n   * @param filters - Metadata filters\n   * @param tableName - Table name for column references\n   * @returns SQL WHERE clause and parameters\n   */\n  static toSQL(filters: MetadataFilters, tableName: string = ''): { where: string; params: any[] } {\n    const conditions: string[] = [];\n    const params: any[] = [];\n    const prefix = tableName ? `${tableName}.` : '';\n\n    for (const [field, filter] of Object.entries(filters)) {\n      // For metadata fields, use JSON extraction\n      const isMetadata = field.startsWith('metadata.');\n      const columnRef = isMetadata\n        ? `json_extract(${prefix}metadata, '$.${field.slice(9)}')`\n        : `${prefix}${field}`;\n\n      if (typeof filter !== 'object' || Array.isArray(filter)) {\n        // Simple equality\n        conditions.push(`${columnRef} = ?`);\n        params.push(filter);\n      } else {\n        // Operator-based filters\n        const operators = filter as { [op in FilterOperator]?: any };\n\n        for (const [operator, operand] of Object.entries(operators)) {\n          switch (operator as FilterOperator) {\n            case '$eq':\n              conditions.push(`${columnRef} = ?`);\n              params.push(operand);\n              break;\n\n            case '$ne':\n              conditions.push(`${columnRef} != ?`);\n              params.push(operand);\n              break;\n\n            case '$gt':\n              conditions.push(`${columnRef} > ?`);\n              params.push(operand);\n              break;\n\n            case '$gte':\n              conditions.push(`${columnRef} >= ?`);\n              params.push(operand);\n              break;\n\n            case '$lt':\n              conditions.push(`${columnRef} < ?`);\n              params.push(operand);\n              break;\n\n            case '$lte':\n              conditions.push(`${columnRef} <= ?`);\n              params.push(operand);\n              break;\n\n            case '$in':\n              if (Array.isArray(operand)) {\n                const placeholders = operand.map(() => '?').join(', ');\n                conditions.push(`${columnRef} IN (${placeholders})`);\n                params.push(...operand);\n              }\n              break;\n\n            case '$nin':\n              if (Array.isArray(operand)) {\n                const placeholders = operand.map(() => '?').join(', ');\n                conditions.push(`${columnRef} NOT IN (${placeholders})`);\n                params.push(...operand);\n              }\n              break;\n\n            case '$contains':\n              conditions.push(`${columnRef} LIKE ?`);\n              params.push(`%${operand}%`);\n              break;\n\n            case '$exists':\n              if (operand) {\n                conditions.push(`${columnRef} IS NOT NULL`);\n              } else {\n                conditions.push(`${columnRef} IS NULL`);\n              }\n              break;\n          }\n        }\n      }\n    }\n\n    const where = conditions.length > 0 ? conditions.join(' AND ') : '1=1';\n    return { where, params };\n  }\n\n  /**\n   * Validate filter object\n   */\n  static validate(filters: MetadataFilters): { valid: boolean; errors: string[] } {\n    const errors: string[] = [];\n\n    for (const [field, filter] of Object.entries(filters)) {\n      if (!field || field.trim() === '') {\n        errors.push('Filter field name cannot be empty');\n      }\n\n      if (typeof filter === 'object' && !Array.isArray(filter)) {\n        const operators = Object.keys(filter);\n        for (const op of operators) {\n          if (!op.startsWith('$')) {\n            errors.push(`Invalid operator: ${op} (must start with $)`);\n          }\n        }\n      }\n    }\n\n    return { valid: errors.length === 0, errors };\n  }\n}\n"]}

package/dist/packages/agentdb/src/controllers/NightlyLearner.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Nightly Learner - Automated Causal Discovery and Consolidation
+ *
+ * Runs as a background job to:
+ * 1. Discover new causal edges from episode patterns
+ * 2. Run A/B experiments on promising hypotheses
+ * 3. Calculate uplift for completed experiments
+ * 4. Prune low-confidence edges
+ * 5. Update rerank weights based on performance
+ *
+ * Based on doubly robust learner:
+ * τ̂(x) = μ1(x) − μ0(x) + [a*(y−μ1(x)) / e(x)] − [(1−a)*(y−μ0(x)) / (1−e(x))]
+ *
+ * v2.0.0-alpha.3 Features:
+ * - FlashAttention for memory-efficient episodic consolidation
+ * - Block-wise computation for large episode buffers
+ * - Feature flag: ENABLE_FLASH_CONSOLIDATION (default: false)
+ * - 100% backward compatible with fallback to standard consolidation
+ */
+type Database = any;
+import { CausalEdge } from './CausalMemoryGraph.js';
+import { EmbeddingService } from './EmbeddingService.js';
+import { type FlashAttentionConfig } from '../utils/LegacyAttentionAdapter.js';
+export interface LearnerConfig {
+    minSimilarity: number;
+    minSampleSize: number;
+    confidenceThreshold: number;
+    upliftThreshold: number;
+    pruneOldEdges: boolean;
+    edgeMaxAgeDays: number;
+    autoExperiments: boolean;
+    experimentBudget: number;
+    /** Enable FlashAttention for consolidation (default: false) */
+    ENABLE_FLASH_CONSOLIDATION?: boolean;
+    /** FlashAttention configuration */
+    flashConfig?: Partial<FlashAttentionConfig>;
+}
+export interface LearnerReport {
+    timestamp: number;
+    executionTimeMs: number;
+    edgesDiscovered: number;
+    edgesPruned: number;
+    experimentsCompleted: number;
+    experimentsCreated: number;
+    avgUplift: number;
+    avgConfidence: number;
+    recommendations: string[];
+}
+export declare class NightlyLearner {
+    private config;
+    private db;
+    private causalGraph;
+    private reflexion;
+    private skillLibrary;
+    private embedder;
+    private attentionService?;
+    constructor(db: Database, embedder: EmbeddingService, config?: LearnerConfig);
+    /**
+     * Main learning job - runs all discovery and consolidation tasks
+     */
+    run(): Promise<LearnerReport>;
+    /**
+     * Discover causal edges using doubly robust learner
+     *
+     * τ̂(x) = μ1(x) − μ0(x) + [a*(y−μ1(x)) / e(x)] − [(1−a)*(y−μ0(x)) / (1−e(x))]
+     *
+     * Where:
+     * - μ1(x) = outcome model for treatment
+     * - μ0(x) = outcome model for control
+     * - e(x) = propensity score (probability of treatment)
+     * - a = treatment indicator
+     * - y = observed outcome
+     *
+     * v2: Uses FlashAttention for memory-efficient consolidation if enabled
+     */
+    discover(config: {
+        minAttempts?: number;
+        minSuccessRate?: number;
+        minConfidence?: number;
+        dryRun?: boolean;
+    }): Promise<CausalEdge[]>;
+    /**
+     * Consolidate episodic memories using FlashAttention (v2 feature)
+     *
+     * Processes large episode buffers efficiently using block-wise computation.
+     * Identifies patterns and relationships across episodes for causal edge discovery.
+     *
+     * @param sessionId - Session to consolidate (optional, processes all if not provided)
+     * @returns Number of edges discovered through consolidation
+     */
+    consolidateEpisodes(sessionId?: string): Promise<{
+        edgesDiscovered: number;
+        episodesProcessed: number;
+        metrics?: {
+            computeTimeMs: number;
+            peakMemoryMB: number;
+            blocksProcessed: number;
+        };
+    }>;
+    private discoverCausalEdges;
+    /**
+     * Calculate propensity score e(x) - probability of treatment given context
+     */
+    private calculatePropensity;
+    /**
+     * Calculate outcome model μ(x) - expected outcome given treatment status
+     */
+    private calculateOutcomeModel;
+    /**
+     * Get sample size for a task type
+     */
+    private getSampleSize;
+    /**
+     * Calculate confidence based on sample size and effect size
+     */
+    private calculateConfidence;
+    /**
+     * Complete running A/B experiments and calculate uplift
+     */
+    private completeExperiments;
+    /**
+     * Create new A/B experiments for promising hypotheses
+     */
+    private createExperiments;
+    /**
+     * Prune old or low-confidence edges
+     */
+    private pruneEdges;
+    /**
+     * Calculate overall statistics
+     */
+    private calculateStats;
+    /**
+     * Generate recommendations based on learning results
+     */
+    private generateRecommendations;
+    /**
+     * Print report to console
+     */
+    private printReport;
+    /**
+     * Update learner configuration
+     */
+    updateConfig(config: Partial<LearnerConfig>): void;
+}
+export {};
+//# sourceMappingURL=NightlyLearner.d.ts.map

package/dist/packages/agentdb/src/controllers/NightlyLearner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NightlyLearner.d.ts","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/controllers/NightlyLearner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,KAAK,QAAQ,GAAG,GAAG,CAAC;AACpB,OAAO,EAAqB,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAoB,KAAK,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAGjG,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IAGzB,+DAA+D;IAC/D,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,mCAAmC;IACnC,WAAW,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,qBAAa,cAAc;IAWvB,OAAO,CAAC,MAAM;IAVhB,OAAO,CAAC,EAAE,CAAW;IACrB,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,gBAAgB,CAAC,CAAmB;gBAG1C,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,gBAAgB,EAClB,MAAM,GAAE,aAUf;IAmBH;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,aAAa,CAAC;IA6DnC;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,MAAM,EAAE;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAczB;;;;;;;;OAQG;IACG,mBAAmB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QACrD,eAAe,EAAE,MAAM,CAAC;QACxB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,OAAO,CAAC,EAAE;YACR,aAAa,EAAE,MAAM,CAAC;YACtB,YAAY,EAAE,MAAM,CAAC;YACrB,eAAe,EAAE,MAAM,CAAC;SACzB,CAAC;KACH,CAAC;YA8GY,mBAAmB;IA+EjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;OAEG;YACW,mBAAmB;IAuBjC;;OAEG;YACW,iBAAiB;IAsD/B;;OAEG;YACW,UAAU;IAaxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA0B/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAwBnB;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;CAGnD"}