ocr-provenance-mcp 1.0.0

package/dist/services/gemini/circuit-breaker.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Circuit Breaker Pattern for Gemini API
+ * Based on gemini-flash-3-dev-guide.md:
+ * - threshold: 5 failures
+ * - recovery_ms: 60000 (60 seconds)
+ *
+ * Only server-side errors (HTTP 429, 500, 502, 503, network errors) trip the
+ * circuit breaker. Client-side errors (validation, file-not-found,
+ * context-length-exceeded, JSON parse) do NOT trip it.
+ */
+declare enum CircuitState {
+    CLOSED = "CLOSED",// Normal operation
+    OPEN = "OPEN",// Failing, reject requests
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Determine whether an error represents a server-side / transient failure
+ * that should trip the circuit breaker.
+ *
+ * Server errors: HTTP 429 (rate limit), 500, 502, 503, and network errors
+ * like ECONNRESET, ETIMEDOUT, ENOTFOUND, socket hang up, fetch failed.
+ *
+ * Client errors that should NOT trip: ValidationError, file-not-found,
+ * context-length-exceeded, JSON parse errors, unsupported format, etc.
+ */
+export declare function isServerError(error: unknown): boolean;
+export interface CircuitBreakerConfig {
+    failureThreshold: number;
+    recoveryTimeMs: number;
+    halfOpenSuccessThreshold: number;
+}
+export interface CircuitBreakerStatus {
+    state: CircuitState;
+    failureCount: number;
+    lastFailureTime: number | null;
+    timeToRecovery: number | null;
+}
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime;
+    private readonly config;
+    /** Tracks consecutive circuit trips for exponential recovery backoff */
+    private consecutiveTrips;
+    constructor(config?: Partial<CircuitBreakerConfig>);
+    /**
+     * Get current recovery time with exponential backoff on consecutive trips.
+     *
+     * Each consecutive trip doubles the recovery time:
+     * Trip 1: 60s, Trip 2: 120s, Trip 3: 240s, Trip 4: 480s, Trip 5+: 960s (cap)
+     *
+     * @returns Recovery time in milliseconds
+     */
+    getRecoveryTimeMs(): number;
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if the circuit should transition from OPEN to HALF_OPEN
+     */
+    private checkRecovery;
+    /**
+     * Record a successful request
+     */
+    private recordSuccess;
+    /**
+     * Record a failed request
+     */
+    private recordFailure;
+    /**
+     * Get time remaining until recovery attempt.
+     * Uses dynamic recovery time based on consecutive trips.
+     */
+    private getTimeToRecovery;
+    /**
+     * Check if the circuit is currently open
+     */
+    isOpen(): boolean;
+    /**
+     * Get current circuit breaker status
+     */
+    getStatus(): CircuitBreakerStatus;
+    /**
+     * Get the current state
+     */
+    getState(): CircuitState;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Force the circuit open (for testing or manual intervention)
+     */
+    forceOpen(): void;
+}
+/**
+ * Error thrown when circuit breaker is open
+ */
+export declare class CircuitBreakerOpenError extends Error {
+    readonly timeToRecovery: number;
+    constructor(message: string, timeToRecovery: number);
+}
+export {};
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/services/gemini/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/services/gemini/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,aAAK,YAAY;IACf,MAAM,WAAW,CAAE,mBAAmB;IACtC,IAAI,SAAS,CAAE,2BAA2B;IAC1C,SAAS,cAAc;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAiCrD;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAQD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,wEAAwE;IACxE,OAAO,CAAC,gBAAgB,CAAa;gBAEzB,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAItD;;;;;;;OAOG;IACH,iBAAiB,IAAI,MAAM;IAO3B;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiClD;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAuBrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,MAAM,IAAI,OAAO;IAKjB;;OAEG;IACH,SAAS,IAAI,oBAAoB;IAUjC;;OAEG;IACH,QAAQ,IAAI,YAAY;IAKxB;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,SAAS,IAAI,IAAI;CAKlB;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;CAKpD"}

package/dist/services/gemini/circuit-breaker.js

@@ -0,0 +1,237 @@
+/**
+ * Circuit Breaker Pattern for Gemini API
+ * Based on gemini-flash-3-dev-guide.md:
+ * - threshold: 5 failures
+ * - recovery_ms: 60000 (60 seconds)
+ *
+ * Only server-side errors (HTTP 429, 500, 502, 503, network errors) trip the
+ * circuit breaker. Client-side errors (validation, file-not-found,
+ * context-length-exceeded, JSON parse) do NOT trip it.
+ */
+var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "CLOSED";
+    CircuitState["OPEN"] = "OPEN";
+    CircuitState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitState || (CircuitState = {}));
+/**
+ * Determine whether an error represents a server-side / transient failure
+ * that should trip the circuit breaker.
+ *
+ * Server errors: HTTP 429 (rate limit), 500, 502, 503, and network errors
+ * like ECONNRESET, ETIMEDOUT, ENOTFOUND, socket hang up, fetch failed.
+ *
+ * Client errors that should NOT trip: ValidationError, file-not-found,
+ * context-length-exceeded, JSON parse errors, unsupported format, etc.
+ */
+export function isServerError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const msg = error.message || '';
+    const cause = error?.cause;
+    const causeMsg = cause instanceof Error ? cause.message || '' : '';
+    const causeCode = cause?.code || '';
+    const combined = `${msg} ${causeMsg} ${causeCode}`;
+    // HTTP status codes indicating server-side issues
+    if (/\b(429|500|502|503)\b/.test(combined)) {
+        return true;
+    }
+    // Rate limit messages
+    if (/rate.?limit/i.test(combined)) {
+        return true;
+    }
+    // Network-level errors
+    if (/ECONNRESET|ETIMEDOUT|ENOTFOUND|ECONNREFUSED|socket hang up|fetch failed/i.test(combined)) {
+        return true;
+    }
+    // Server overloaded / unavailable messages from Gemini
+    if (/server.?(error|overloaded|unavailable)|service.?unavailable|internal.?server/i.test(combined)) {
+        return true;
+    }
+    // Everything else is a client-side error
+    return false;
+}
+const DEFAULT_CONFIG = {
+    failureThreshold: 5, // From guide
+    recoveryTimeMs: 60000, // From guide: 60 seconds
+    halfOpenSuccessThreshold: 3, // Successes needed to close
+};
+export class CircuitBreaker {
+    state = CircuitState.CLOSED;
+    failureCount = 0;
+    successCount = 0;
+    lastFailureTime = null;
+    config;
+    /** Tracks consecutive circuit trips for exponential recovery backoff */
+    consecutiveTrips = 0;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Get current recovery time with exponential backoff on consecutive trips.
+     *
+     * Each consecutive trip doubles the recovery time:
+     * Trip 1: 60s, Trip 2: 120s, Trip 3: 240s, Trip 4: 480s, Trip 5+: 960s (cap)
+     *
+     * @returns Recovery time in milliseconds
+     */
+    getRecoveryTimeMs() {
+        const baseRecovery = this.config.recoveryTimeMs;
+        const tripExponent = Math.max(0, this.consecutiveTrips - 1);
+        const multiplier = Math.pow(2, Math.min(tripExponent, 4)); // Max 16x = 960s
+        return Math.min(baseRecovery * multiplier, 960000); // Cap at 16 minutes
+    }
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    async execute(fn) {
+        // Check if circuit should transition from OPEN to HALF_OPEN
+        this.checkRecovery();
+        // Reject if circuit is open
+        if (this.state === CircuitState.OPEN) {
+            const timeToRecovery = this.getTimeToRecovery();
+            throw new CircuitBreakerOpenError(`Circuit breaker is OPEN. Try again in ${Math.ceil(timeToRecovery / 1000)}s`, timeToRecovery);
+        }
+        try {
+            const result = await fn();
+            this.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            // Only trip the circuit breaker on server-side / transient errors.
+            // Client-side errors (validation, file-not-found, context-length,
+            // JSON parse) are not the server's fault and should not affect
+            // circuit breaker state.
+            if (isServerError(error)) {
+                this.recordFailure();
+            }
+            else {
+                console.error(`[CircuitBreaker] Client-side error (not counted): ${error instanceof Error ? error.message : String(error)}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if the circuit should transition from OPEN to HALF_OPEN
+     */
+    checkRecovery() {
+        if (this.state === CircuitState.OPEN && this.lastFailureTime !== null) {
+            const elapsed = Date.now() - this.lastFailureTime;
+            const recoveryTime = this.getRecoveryTimeMs();
+            if (elapsed >= recoveryTime) {
+                console.error(`[CircuitBreaker] Transitioning from OPEN to HALF_OPEN (recovery: ${recoveryTime}ms, trip #${this.consecutiveTrips})`);
+                this.state = CircuitState.HALF_OPEN;
+                this.successCount = 0;
+            }
+        }
+    }
+    /**
+     * Record a successful request
+     */
+    recordSuccess() {
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.successCount++;
+            console.error(`[CircuitBreaker] Success in HALF_OPEN (${this.successCount}/${this.config.halfOpenSuccessThreshold})`);
+            if (this.successCount >= this.config.halfOpenSuccessThreshold) {
+                console.error('[CircuitBreaker] Recovery confirmed, transitioning to CLOSED');
+                this.state = CircuitState.CLOSED;
+                this.failureCount = 0;
+                this.successCount = 0;
+                this.lastFailureTime = null;
+                this.consecutiveTrips = 0; // Reset consecutive trips on successful recovery
+            }
+        }
+        else if (this.state === CircuitState.CLOSED) {
+            // Reset failure count on success
+            this.failureCount = 0;
+        }
+    }
+    /**
+     * Record a failed request
+     */
+    recordFailure() {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        console.error(`[CircuitBreaker] Failure recorded (${this.failureCount}/${this.config.failureThreshold})`);
+        if (this.state === CircuitState.HALF_OPEN) {
+            // Any failure in HALF_OPEN immediately opens the circuit
+            this.consecutiveTrips++;
+            console.error(`[CircuitBreaker] Failure in HALF_OPEN, transitioning to OPEN (consecutive trip #${this.consecutiveTrips}, recovery: ${this.getRecoveryTimeMs()}ms)`);
+            this.state = CircuitState.OPEN;
+            this.successCount = 0;
+        }
+        else if (this.failureCount >= this.config.failureThreshold) {
+            this.consecutiveTrips++;
+            console.error(`[CircuitBreaker] Threshold reached (${this.failureCount}), transitioning to OPEN (consecutive trip #${this.consecutiveTrips}, recovery: ${this.getRecoveryTimeMs()}ms)`);
+            this.state = CircuitState.OPEN;
+        }
+    }
+    /**
+     * Get time remaining until recovery attempt.
+     * Uses dynamic recovery time based on consecutive trips.
+     */
+    getTimeToRecovery() {
+        if (this.lastFailureTime === null)
+            return 0;
+        const elapsed = Date.now() - this.lastFailureTime;
+        return Math.max(0, this.getRecoveryTimeMs() - elapsed);
+    }
+    /**
+     * Check if the circuit is currently open
+     */
+    isOpen() {
+        this.checkRecovery();
+        return this.state === CircuitState.OPEN;
+    }
+    /**
+     * Get current circuit breaker status
+     */
+    getStatus() {
+        this.checkRecovery();
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            lastFailureTime: this.lastFailureTime,
+            timeToRecovery: this.state === CircuitState.OPEN ? this.getTimeToRecovery() : null,
+        };
+    }
+    /**
+     * Get the current state
+     */
+    getState() {
+        this.checkRecovery();
+        return this.state;
+    }
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset() {
+        this.state = CircuitState.CLOSED;
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.lastFailureTime = null;
+        this.consecutiveTrips = 0;
+        console.error('[CircuitBreaker] Manually reset to CLOSED');
+    }
+    /**
+     * Force the circuit open (for testing or manual intervention)
+     */
+    forceOpen() {
+        this.state = CircuitState.OPEN;
+        this.lastFailureTime = Date.now();
+        console.error('[CircuitBreaker] Manually forced OPEN');
+    }
+}
+/**
+ * Error thrown when circuit breaker is open
+ */
+export class CircuitBreakerOpenError extends Error {
+    timeToRecovery;
+    constructor(message, timeToRecovery) {
+        super(message);
+        this.name = 'CircuitBreakerOpenError';
+        this.timeToRecovery = timeToRecovery;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/services/gemini/circuit-breaker.js.map

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

package/dist/services/gemini/client.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Gemini API Client
+ * Implements the client patterns from gemini-flash-3-dev-guide.md
+ *
+ * Modes:
+ * - fast(): <2s target, temperature 0.0, JSON output
+ * - thinking(): 3-8s target, extended reasoning with thinkingLevel
+ * - multimodal(): 5-15s target, image/PDF analysis
+ */
+import { type GeminiConfig, type ThinkingLevel, type AllowedMimeType, type MediaResolution } from './config.js';
+import { CircuitBreakerOpenError } from './circuit-breaker.js';
+export { CircuitBreakerOpenError };
+/**
+ * Get a shared GeminiClient singleton.
+ * Use this instead of `new GeminiClient()` for default config.
+ * Rate limiter and circuit breaker state persist across calls.
+ */
+export declare function getSharedClient(): GeminiClient;
+/** Reset all shared state (for testing) */
+export declare function resetSharedClient(): void;
+/**
+ * Token usage from a Gemini response
+ */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    thinkingTokens: number;
+    totalTokens: number;
+}
+/**
+ * Response from Gemini API
+ */
+export interface GeminiResponse {
+    text: string;
+    usage: TokenUsage;
+    model: string;
+    processingTimeMs: number;
+}
+/**
+ * File reference for multimodal requests
+ */
+export interface FileRef {
+    mimeType: AllowedMimeType;
+    data: string;
+    sizeBytes: number;
+}
+/**
+ * Gemini Client with rate limiting and circuit breaker
+ */
+export declare class GeminiClient {
+    private readonly client;
+    private readonly config;
+    private readonly rateLimiter;
+    private readonly circuitBreaker;
+    private readonly _contextCache;
+    constructor(configOverrides?: Partial<GeminiConfig>);
+    /**
+     * Fast mode: <2s target, temperature 0.0, JSON output
+     * Use for quick analysis tasks
+     *
+     * @param prompt - Text prompt
+     * @param schema - Optional JSON response schema
+     * @param options - Optional overrides (e.g. maxOutputTokens for large structured extraction)
+     */
+    fast(prompt: string, schema?: object, options?: {
+        maxOutputTokens?: number;
+        requestTimeout?: number;
+    }): Promise<GeminiResponse>;
+    /**
+     * Thinking mode: 3-8s target, extended reasoning
+     * Uses Gemini 3's thinkingLevel (HIGH or MINIMAL)
+     */
+    thinking(prompt: string, level?: ThinkingLevel): Promise<GeminiResponse>;
+    /**
+     * Multimodal mode: analyze image with prompt
+     * 5-15s target, supports images and PDFs
+     */
+    analyzeImage(prompt: string, file: FileRef, options?: {
+        schema?: object;
+        mediaResolution?: MediaResolution;
+        thinkingConfig?: {
+            thinkingLevel: ThinkingLevel;
+        };
+    }): Promise<GeminiResponse>;
+    /**
+     * Analyze a PDF document
+     */
+    analyzePDF(prompt: string, file: FileRef, schema?: object): Promise<GeminiResponse>;
+    /**
+     * Core generation method with retry logic
+     */
+    private generate;
+    /**
+     * Execute request with exponential backoff retry
+     */
+    private executeWithRetry;
+    /**
+     * Build generation config from options
+     */
+    private buildGenerationConfig;
+    /**
+     * Estimate tokens for a request
+     */
+    private estimateRequestTokens;
+    /**
+     * Create FileRef from a file path
+     */
+    static fileRefFromPath(filePath: string): FileRef;
+    /**
+     * Create FileRef from a buffer
+     */
+    static fileRefFromBuffer(buffer: Buffer, mimeType: AllowedMimeType): FileRef;
+    /**
+     * Create cached content for document context.
+     * Used when processing multiple images from the same document -
+     * cache the OCR text context once, then reference it for each image.
+     *
+     * @param contextText - Document OCR text to cache
+     * @param ttlSeconds - Cache TTL in seconds (default: 3600 = 1 hour)
+     * @returns Cache identifier for use with generateWithCache()
+     */
+    createCachedContent(contextText: string, ttlSeconds?: number): Promise<string>;
+    /**
+     * Remove all expired entries from the context cache.
+     * Called as periodic cleanup when createCachedContent is invoked.
+     */
+    private cleanExpiredCacheEntries;
+    /**
+     * Generate content using cached context + new image.
+     * Prepends cached text context to the image analysis prompt.
+     */
+    generateWithCache(cacheId: string, prompt: string, file: FileRef, options?: {
+        schema?: object;
+        mediaResolution?: MediaResolution;
+    }): Promise<GeminiResponse>;
+    /**
+     * Delete a cached context
+     */
+    deleteCachedContent(cacheId: string): boolean;
+    /**
+     * Process multiple image analysis requests efficiently.
+     * Handles rate limiting and provides progress tracking.
+     * NOT true async batch API (Gemini async batch requires server-side setup) -
+     * this is sequential with optimal rate limiting.
+     */
+    batchAnalyzeImages(requests: Array<{
+        prompt: string;
+        file: FileRef;
+        options?: {
+            schema?: object;
+            mediaResolution?: MediaResolution;
+        };
+    }>, onProgress?: (completed: number, total: number) => void): Promise<Array<{
+        index: number;
+        result?: GeminiResponse;
+        error?: string;
+    }>>;
+    /**
+     * Get client status (rate limiter + circuit breaker)
+     */
+    getStatus(): {
+        model: string;
+        rateLimiter: import("./rate-limiter.js").RateLimiterStatus;
+        circuitBreaker: import("./circuit-breaker.js").CircuitBreakerStatus;
+    };
+    /**
+     * Reset rate limiter and circuit breaker (for testing)
+     */
+    reset(): void;
+    private sleep;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/services/gemini/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/services/gemini/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EACL,KAAK,YAAY,EAKjB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAkB,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/E,OAAO,EAAE,uBAAuB,EAAE,CAAC;AA6BnC;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAK9C;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAG1B;gBAEQ,eAAe,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAqBnD;;;;;;;OAOG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9D,OAAO,CAAC,cAAc,CAAC;IAS1B;;;OAGG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,aAAsB,GAAG,OAAO,CAAC,cAAc,CAAC;IAKtF;;;OAGG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,eAAe,CAAC,EAAE,eAAe,CAAC;QAClC,cAAc,CAAC,EAAE;YAAE,aAAa,EAAE,aAAa,CAAA;SAAE,CAAC;KAC9C,GACL,OAAO,CAAC,cAAc,CAAC;IAgC1B;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAWzF;;OAEG;YACW,QAAQ;IAoBtB;;OAEG;YACW,gBAAgB;IA0I9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAqCjD;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO;IAiB5E;;;;;;;;OAQG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAyC1F;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAchC;;;OAGG;IACG,iBAAiB,CACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,eAAe,CAAA;KAAO,GACnE,OAAO,CAAC,cAAc,CAAC;IAmB1B;;OAEG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7C;;;;;OAKG;IACG,kBAAkB,CACtB,QAAQ,EAAE,KAAK,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,OAAO,CAAC;QACd,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,eAAe,CAAC,EAAE,eAAe,CAAA;SAAE,CAAC;KAClE,CAAC,EACF,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GACtD,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,cAAc,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAuB7E;;OAEG;IACH,SAAS;;;;;IAQT;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,KAAK;CAGd"}