network-ai 4.12.1 → 4.13.0

package/dist/lib/confidence-filter.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Confidence Filter — Multi-agent result confidence scoring & filtering
+ *
+ * Scores agent findings by confidence, filters by threshold, and optionally
+ * validates low-confidence findings with a secondary agent. Inspired by
+ * Claude Code's confidence-based multi-agent filtering pattern.
+ *
+ * @module ConfidenceFilter
+ * @version 1.0.0
+ */
+import type { AgentPayload, AgentContext } from '../types/agent-adapter';
+import type { AdapterRegistry } from '../adapters/adapter-registry';
+/**
+ * A single finding produced by an agent, annotated with confidence.
+ */
+export interface Finding {
+    /** Unique identifier for this finding */
+    id: string;
+    /** Human-readable description of the finding */
+    description: string;
+    /** Confidence score from 0 to 100 */
+    confidence: number;
+    /** Agent that produced this finding */
+    sourceAgent: string;
+    /** Agent that validated this finding (set after validation) */
+    validatedBy?: string;
+    /** Whether validation passed (set after validation) */
+    validated?: boolean;
+    /** Arbitrary metadata attached to the finding */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of filtering findings by confidence threshold.
+ */
+export interface FilterResult {
+    /** Findings that passed the threshold */
+    accepted: Finding[];
+    /** Findings below the threshold */
+    rejected: Finding[];
+    /** Threshold that was applied */
+    threshold: number;
+}
+/**
+ * Aggregation strategies for combining findings from multiple agents.
+ */
+export type AggregationStrategy = 'highest' | 'average' | 'unanimous' | 'majority';
+/**
+ * Result of aggregating multiple sets of findings.
+ */
+export interface AggregatedResult {
+    /** Merged findings after applying aggregation strategy */
+    findings: Finding[];
+    /** Strategy that was used */
+    strategy: AggregationStrategy;
+    /** Total number of input findings before aggregation */
+    totalInput: number;
+    /** Number of sources that contributed */
+    sourceCount: number;
+}
+/**
+ * Options for the ConfidenceFilter constructor.
+ */
+export interface ConfidenceFilterOptions {
+    /** Default confidence threshold (0–100). Default: 70 */
+    defaultThreshold?: number;
+    /** If true, findings below threshold are auto-validated with a second agent */
+    autoValidate?: boolean;
+    /** Agent to use for validation passes */
+    validatorAgent?: string;
+    /** Payload factory for validation calls */
+    validationPayloadFactory?: (finding: Finding) => AgentPayload;
+}
+/**
+ * Filters and validates multi-agent findings based on confidence scores.
+ *
+ * @example
+ * ```typescript
+ * const filter = new ConfidenceFilter(registry, baseCtx, { defaultThreshold: 70 });
+ *
+ * const findings: Finding[] = [
+ *   { id: '1', description: 'SQL injection in login.ts', confidence: 95, sourceAgent: 'scanner-a' },
+ *   { id: '2', description: 'Possible XSS in comments', confidence: 45, sourceAgent: 'scanner-b' },
+ * ];
+ *
+ * const filtered = filter.filter(findings);
+ * // filtered.accepted → finding #1, filtered.rejected → finding #2
+ *
+ * // Validate a low-confidence finding with a secondary agent
+ * const validated = await filter.validate(findings[1], 'expert-reviewer');
+ * ```
+ */
+export declare class ConfidenceFilter {
+    private registry;
+    private baseContext;
+    private options;
+    /**
+     * @param registry Adapter registry for validation calls (optional — filter-only mode if null)
+     * @param baseContext Default execution context for validation agents
+     * @param options Filter configuration
+     */
+    constructor(registry: AdapterRegistry | null, baseContext: AgentContext | null, options?: ConfidenceFilterOptions);
+    /**
+     * Score a single finding. Returns a normalised 0–100 confidence score.
+     * Currently a pass-through; override or extend for custom scoring logic.
+     */
+    score(finding: Finding): number;
+    /**
+     * Filter findings by confidence threshold.
+     *
+     * @param findings Findings to filter
+     * @param threshold Override the default threshold for this call
+     */
+    filter(findings: Finding[], threshold?: number): FilterResult;
+    /**
+     * Validate a finding using a secondary agent.
+     * The validator agent's result is used to update `validatedBy` and `validated`.
+     *
+     * @param finding The finding to validate
+     * @param validatorAgentId Agent to perform the validation (overrides options)
+     * @returns Updated finding with validation metadata
+     */
+    validate(finding: Finding, validatorAgentId?: string): Promise<Finding>;
+    /**
+     * Validate all rejected findings from a filter result.
+     * Returns the updated filter result with re-scored findings.
+     */
+    validateRejected(filterResult: FilterResult, validatorAgentId?: string): Promise<FilterResult>;
+    /**
+     * Aggregate findings from multiple sources using a strategy.
+     *
+     * - `highest`: Keep the finding with the highest confidence for each id
+     * - `average`: Average the confidence scores for each id
+     * - `unanimous`: Only keep findings that appear in ALL sources
+     * - `majority`: Only keep findings that appear in more than half of sources
+     *
+     * @param findingSets Arrays of findings from different agents
+     * @param strategy Aggregation strategy to use
+     */
+    aggregate(findingSets: Finding[][], strategy?: AggregationStrategy): AggregatedResult;
+}
+//# sourceMappingURL=confidence-filter.d.ts.map

package/dist/lib/confidence-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence-filter.d.ts","sourceRoot":"","sources":["../../lib/confidence-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAe,MAAM,wBAAwB,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAMpE;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,mCAAmC;IACnC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,6BAA6B;IAC7B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,wBAAwB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,YAAY,CAAC;CAC/D;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,OAAO,CAA0B;IAEzC;;;;OAIG;gBAED,QAAQ,EAAE,eAAe,GAAG,IAAI,EAChC,WAAW,EAAE,YAAY,GAAG,IAAI,EAChC,OAAO,GAAE,uBAA4B;IAOvC;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAI/B;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY;IAiB7D;;;;;;;OAOG;IACG,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiC7E;;;OAGG;IACG,gBAAgB,CAAC,YAAY,EAAE,YAAY,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAwBpG;;;;;;;;;;OAUG;IACH,SAAS,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,GAAE,mBAA+B,GAAG,gBAAgB;CA6DjG"}

package/dist/lib/confidence-filter.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Confidence Filter — Multi-agent result confidence scoring & filtering
+ *
+ * Scores agent findings by confidence, filters by threshold, and optionally
+ * validates low-confidence findings with a secondary agent. Inspired by
+ * Claude Code's confidence-based multi-agent filtering pattern.
+ *
+ * @module ConfidenceFilter
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfidenceFilter = void 0;
+// ============================================================================
+// CONFIDENCE FILTER
+// ============================================================================
+/**
+ * Filters and validates multi-agent findings based on confidence scores.
+ *
+ * @example
+ * ```typescript
+ * const filter = new ConfidenceFilter(registry, baseCtx, { defaultThreshold: 70 });
+ *
+ * const findings: Finding[] = [
+ *   { id: '1', description: 'SQL injection in login.ts', confidence: 95, sourceAgent: 'scanner-a' },
+ *   { id: '2', description: 'Possible XSS in comments', confidence: 45, sourceAgent: 'scanner-b' },
+ * ];
+ *
+ * const filtered = filter.filter(findings);
+ * // filtered.accepted → finding #1, filtered.rejected → finding #2
+ *
+ * // Validate a low-confidence finding with a secondary agent
+ * const validated = await filter.validate(findings[1], 'expert-reviewer');
+ * ```
+ */
+class ConfidenceFilter {
+    registry;
+    baseContext;
+    options;
+    /**
+     * @param registry Adapter registry for validation calls (optional — filter-only mode if null)
+     * @param baseContext Default execution context for validation agents
+     * @param options Filter configuration
+     */
+    constructor(registry, baseContext, options = {}) {
+        this.registry = registry;
+        this.baseContext = baseContext;
+        this.options = options;
+    }
+    /**
+     * Score a single finding. Returns a normalised 0–100 confidence score.
+     * Currently a pass-through; override or extend for custom scoring logic.
+     */
+    score(finding) {
+        return Math.max(0, Math.min(100, finding.confidence));
+    }
+    /**
+     * Filter findings by confidence threshold.
+     *
+     * @param findings Findings to filter
+     * @param threshold Override the default threshold for this call
+     */
+    filter(findings, threshold) {
+        const t = threshold ?? this.options.defaultThreshold ?? 70;
+        const accepted = [];
+        const rejected = [];
+        for (const f of findings) {
+            const s = this.score(f);
+            if (s >= t) {
+                accepted.push(f);
+            }
+            else {
+                rejected.push(f);
+            }
+        }
+        return { accepted, rejected, threshold: t };
+    }
+    /**
+     * Validate a finding using a secondary agent.
+     * The validator agent's result is used to update `validatedBy` and `validated`.
+     *
+     * @param finding The finding to validate
+     * @param validatorAgentId Agent to perform the validation (overrides options)
+     * @returns Updated finding with validation metadata
+     */
+    async validate(finding, validatorAgentId) {
+        const agentId = validatorAgentId ?? this.options.validatorAgent;
+        if (!agentId) {
+            throw new Error('No validator agent specified');
+        }
+        if (!this.registry || !this.baseContext) {
+            throw new Error('Registry and baseContext required for validation');
+        }
+        const payload = this.options.validationPayloadFactory
+            ? this.options.validationPayloadFactory(finding)
+            : {
+                action: 'validate',
+                params: { findingId: finding.id, description: finding.description, confidence: finding.confidence },
+            };
+        const ctx = {
+            ...this.baseContext,
+            metadata: { ...this.baseContext.metadata, validating: finding.id },
+        };
+        const result = await this.registry.executeAgent(agentId, payload, ctx);
+        return {
+            ...finding,
+            validatedBy: agentId,
+            validated: result.success,
+            confidence: result.success
+                ? Math.min(100, finding.confidence + 20) // boost confidence if validated
+                : Math.max(0, finding.confidence - 10), // reduce if validation failed
+        };
+    }
+    /**
+     * Validate all rejected findings from a filter result.
+     * Returns the updated filter result with re-scored findings.
+     */
+    async validateRejected(filterResult, validatorAgentId) {
+        const validated = [];
+        for (const f of filterResult.rejected) {
+            validated.push(await this.validate(f, validatorAgentId));
+        }
+        // Re-filter after validation
+        const newAccepted = [];
+        const newRejected = [];
+        for (const f of validated) {
+            if (f.confidence >= filterResult.threshold) {
+                newAccepted.push(f);
+            }
+            else {
+                newRejected.push(f);
+            }
+        }
+        return {
+            accepted: [...filterResult.accepted, ...newAccepted],
+            rejected: newRejected,
+            threshold: filterResult.threshold,
+        };
+    }
+    /**
+     * Aggregate findings from multiple sources using a strategy.
+     *
+     * - `highest`: Keep the finding with the highest confidence for each id
+     * - `average`: Average the confidence scores for each id
+     * - `unanimous`: Only keep findings that appear in ALL sources
+     * - `majority`: Only keep findings that appear in more than half of sources
+     *
+     * @param findingSets Arrays of findings from different agents
+     * @param strategy Aggregation strategy to use
+     */
+    aggregate(findingSets, strategy = 'highest') {
+        const totalInput = findingSets.reduce((sum, s) => sum + s.length, 0);
+        const sourceCount = findingSets.length;
+        if (sourceCount === 0) {
+            return { findings: [], strategy, totalInput: 0, sourceCount: 0 };
+        }
+        // Group by finding id
+        const grouped = new Map();
+        for (const set of findingSets) {
+            for (const f of set) {
+                if (!grouped.has(f.id))
+                    grouped.set(f.id, []);
+                grouped.get(f.id).push(f);
+            }
+        }
+        let findings;
+        switch (strategy) {
+            case 'highest': {
+                findings = [];
+                for (const [, group] of grouped) {
+                    const best = group.reduce((a, b) => (a.confidence > b.confidence ? a : b));
+                    findings.push(best);
+                }
+                break;
+            }
+            case 'average': {
+                findings = [];
+                for (const [, group] of grouped) {
+                    const avgConfidence = Math.round(group.reduce((s, f) => s + f.confidence, 0) / group.length);
+                    findings.push({ ...group[0], confidence: avgConfidence });
+                }
+                break;
+            }
+            case 'unanimous': {
+                findings = [];
+                for (const [, group] of grouped) {
+                    if (group.length === sourceCount) {
+                        const avgConfidence = Math.round(group.reduce((s, f) => s + f.confidence, 0) / group.length);
+                        findings.push({ ...group[0], confidence: avgConfidence });
+                    }
+                }
+                break;
+            }
+            case 'majority': {
+                findings = [];
+                const majorityThreshold = Math.floor(sourceCount / 2) + 1;
+                for (const [, group] of grouped) {
+                    if (group.length >= majorityThreshold) {
+                        const avgConfidence = Math.round(group.reduce((s, f) => s + f.confidence, 0) / group.length);
+                        findings.push({ ...group[0], confidence: avgConfidence });
+                    }
+                }
+                break;
+            }
+        }
+        return { findings, strategy, totalInput, sourceCount };
+    }
+}
+exports.ConfidenceFilter = ConfidenceFilter;
+//# sourceMappingURL=confidence-filter.js.map

package/dist/lib/confidence-filter.js.map

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

package/dist/lib/fan-out.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Fan-Out / Fan-In — Parallel agent spawning and result aggregation
+ *
+ * Launches multiple agents in parallel (fan-out) and combines their results
+ * using pluggable strategies (fan-in). Supports concurrency limits, timeouts,
+ * and custom aggregation. Inspired by Claude Code's parallel agent patterns.
+ *
+ * @module FanOutFanIn
+ * @version 1.0.0
+ */
+import type { AgentPayload, AgentContext, AgentResult } from '../types/agent-adapter';
+import type { AdapterRegistry } from '../adapters/adapter-registry';
+/**
+ * A single agent invocation for the fan-out step.
+ */
+export interface FanOutStep {
+    /** Agent to execute */
+    agentId: string;
+    /** Payload to send */
+    payload: AgentPayload;
+    /** Optional context overrides (merged with baseContext) */
+    context?: Partial<AgentContext>;
+    /** Per-step timeout in ms (overrides global timeout) */
+    timeoutMs?: number;
+    /** Arbitrary label for this step (used in result mapping) */
+    label?: string;
+}
+/**
+ * Result of a single fan-out execution, tagged with its step info.
+ */
+export interface TaggedResult {
+    /** The agent that produced this result */
+    agentId: string;
+    /** Step label (if provided) */
+    label?: string;
+    /** Index of the step in the original fan-out array */
+    index: number;
+    /** Actual agent result */
+    result: AgentResult;
+    /** Execution duration in ms */
+    durationMs: number;
+}
+/**
+ * Fan-in aggregation strategy.
+ *
+ * - `merge`:       Collect all results into an array
+ * - `firstSuccess`: Return the first successful result
+ * - `vote`:        Return the result that occurs most often (by data equality)
+ * - `consensus`:   Return result only if all agents agree
+ * - `custom`:      Use a custom reducer function
+ */
+export type FanInStrategy = 'merge' | 'firstSuccess' | 'vote' | 'consensus' | 'custom';
+/**
+ * Result of a fan-in aggregation.
+ */
+export interface FanInResult {
+    /** Whether aggregation was successful */
+    success: boolean;
+    /** Strategy that was used */
+    strategy: FanInStrategy;
+    /** Aggregated data (depends on strategy) */
+    data: unknown;
+    /** All individual tagged results */
+    results: TaggedResult[];
+    /** Total execution time in ms */
+    totalMs: number;
+    /** Count of successful individual results */
+    successCount: number;
+    /** Count of failed individual results */
+    failureCount: number;
+}
+/**
+ * Custom reducer for the 'custom' fan-in strategy.
+ */
+export type FanInReducer = (results: TaggedResult[]) => {
+    success: boolean;
+    data: unknown;
+};
+/**
+ * Options for FanOutFanIn execution.
+ */
+export interface FanOutOptions {
+    /** Max concurrent agent executions (default: unlimited) */
+    concurrency?: number;
+    /** Global timeout in ms for all fan-out (default: none) */
+    timeoutMs?: number;
+    /** If true, continue even when some agents fail (default: true) */
+    continueOnError?: boolean;
+}
+/**
+ * Parallel agent execution with pluggable result aggregation.
+ *
+ * @example
+ * ```typescript
+ * const fanout = new FanOutFanIn(registry, { agentId: 'orchestrator' });
+ *
+ * const steps: FanOutStep[] = [
+ *   { agentId: 'researcher-a', payload: { action: 'search', params: { q: 'AI safety' } }, label: 'web' },
+ *   { agentId: 'researcher-b', payload: { action: 'search', params: { q: 'AI safety' } }, label: 'papers' },
+ *   { agentId: 'researcher-c', payload: { action: 'search', params: { q: 'AI safety' } }, label: 'news' },
+ * ];
+ *
+ * const results = await fanout.fanOut(steps, { concurrency: 2 });
+ * const aggregated = fanout.fanIn(results, 'merge');
+ * ```
+ */
+export declare class FanOutFanIn {
+    private registry;
+    private baseContext;
+    /**
+     * @param registry Adapter registry for agent execution
+     * @param baseContext Default execution context (merged with step-level overrides)
+     */
+    constructor(registry: AdapterRegistry, baseContext: AgentContext);
+    /**
+     * Execute agents in parallel (fan-out phase).
+     *
+     * @param steps Steps to execute
+     * @param options Concurrency and timeout settings
+     */
+    fanOut(steps: FanOutStep[], options?: FanOutOptions): Promise<TaggedResult[]>;
+    /**
+     * Aggregate results (fan-in phase).
+     *
+     * @param results Tagged results from fan-out
+     * @param strategy Aggregation strategy to apply
+     * @param customReducer Required when strategy is 'custom'
+     */
+    fanIn(results: TaggedResult[], strategy?: FanInStrategy, customReducer?: FanInReducer): FanInResult;
+    /**
+     * Convenience: fan-out + fan-in in a single call.
+     */
+    run(steps: FanOutStep[], strategy?: FanInStrategy, options?: FanOutOptions, customReducer?: FanInReducer): Promise<FanInResult>;
+    private executeStep;
+}
+//# sourceMappingURL=fan-out.d.ts.map

package/dist/lib/fan-out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.d.ts","sourceRoot":"","sources":["../../lib/fan-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAMpE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,OAAO,EAAE,YAAY,CAAC;IACtB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAChC,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,QAAQ,EAAE,aAAa,CAAC;IACxB,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;IACd,oCAAoC;IACpC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5F;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,WAAW,CAAe;IAElC;;;OAGG;gBACS,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY;IAKhE;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA6DvF;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,QAAQ,GAAE,aAAuB,EAAE,aAAa,CAAC,EAAE,YAAY,GAAG,WAAW;IAwE5G;;OAEG;IACG,GAAG,CACP,KAAK,EAAE,UAAU,EAAE,EACnB,QAAQ,GAAE,aAAuB,EACjC,OAAO,CAAC,EAAE,aAAa,EACvB,aAAa,CAAC,EAAE,YAAY,GAC3B,OAAO,CAAC,WAAW,CAAC;YAST,WAAW;CAyB1B"}