@goreal-ai/echo-pdk 0.1.0

package/dist/ai-judge/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview AI Judge - LLM-based condition evaluation
+ *
+ * This module handles the #ai_judge operator which queries an LLM
+ * to evaluate boolean conditions.
+ *
+ * FEATURES:
+ * - Provider abstraction for different backends (OpenAI, Anthropic)
+ * - Automatic caching with TTL to avoid redundant API calls
+ * - Structured prompts for consistent yes/no answers
+ * - Graceful error handling
+ *
+ * API KEY CONFIGURATION:
+ * The API key can be provided in three ways (in priority order):
+ * 1. Programmatic: createEcho({ aiProvider: { apiKey: '...' } })
+ * 2. Environment: ECHO_API_KEY or OPENAI_API_KEY
+ * 3. Config file: echo.config.yaml (aiProvider.apiKey)
+ */
+import type { AIProviderConfig } from '../types.js';
+/**
+ * AI Provider interface for evaluating boolean conditions.
+ */
+export interface AIProvider {
+    /**
+     * Evaluate a boolean question about a value.
+     *
+     * @param value - The value to evaluate
+     * @param question - The yes/no question to ask
+     * @returns true or false based on the AI's response
+     */
+    evaluate(value: unknown, question: string): Promise<boolean>;
+}
+/**
+ * Create an OpenAI-based AI provider.
+ *
+ * @param config - Configuration with API key and model
+ * @returns AIProvider using OpenAI
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenAIProvider({
+ *   type: 'openai',
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   model: 'gpt-4o-mini',
+ * });
+ *
+ * const result = await provider.evaluate(
+ *   'This is a family-friendly movie.',
+ *   'Is this content appropriate for children?'
+ * );
+ * ```
+ */
+export declare function createOpenAIProvider(config: AIProviderConfig): AIProvider;
+/**
+ * Build the prompt for the AI judge.
+ *
+ * The prompt is designed to get a clear yes/no answer.
+ *
+ * @param value - The value to evaluate
+ * @param question - The question to ask
+ * @returns Formatted prompt string
+ */
+export declare function buildPrompt(value: unknown, question: string): string;
+/**
+ * Create an AI Judge instance with the given configuration.
+ *
+ * @param config - AI provider configuration
+ * @returns An AIProvider implementation
+ *
+ * @example
+ * ```typescript
+ * const judge = createAIJudge({
+ *   type: 'openai',
+ *   apiKey: process.env.OPENAI_API_KEY,
+ * });
+ *
+ * const isAppropriate = await judge.evaluate(content, 'Is this safe for work?');
+ * ```
+ */
+export declare function createAIJudge(config: AIProviderConfig): AIProvider;
+/**
+ * Options for creating a cache key.
+ */
+export interface CacheKeyOptions {
+    /** The value being evaluated (can be very large, e.g., 200K tokens) */
+    value: unknown;
+    /** The boolean question to ask */
+    question: string;
+    /** The AI provider type (e.g., 'openai', 'anthropic') */
+    provider?: string;
+    /** The model identifier (e.g., 'gpt-4o-mini') */
+    model?: string;
+}
+/**
+ * Create a cache key for an AI judge evaluation.
+ *
+ * Uses SHA-256 hashing to create a fixed-size key regardless of input size.
+ * This is critical because the value being evaluated can be extremely large
+ * (e.g., a 200K token document). Storing the raw value as a Map key would
+ * cause severe memory bloat.
+ *
+ * The hash includes provider and model to prevent cache collisions when
+ * multiple Echo instances use different AI configurations.
+ *
+ * @param options - The cache key options
+ * @returns A 64-character hex hash string
+ *
+ * @example
+ * ```typescript
+ * const key = createCacheKey({
+ *   value: largeDocument,
+ *   question: 'Is this appropriate?',
+ *   provider: 'openai',
+ *   model: 'gpt-4o-mini',
+ * });
+ * // Returns: "a8f4b2c1e9d3..." (64 chars)
+ * ```
+ */
+export declare function createCacheKey(options: CacheKeyOptions): string;
+/**
+ * Get a cached result if available and not expired.
+ *
+ * @param key - The cache key
+ * @returns The cached result or undefined if not found/expired
+ */
+export declare function getCached(key: string): boolean | undefined;
+/**
+ * Store a result in the cache.
+ *
+ * @param key - The cache key
+ * @param result - The result to cache
+ */
+export declare function setCache(key: string, result: boolean): void;
+/**
+ * Clear the entire cache.
+ */
+export declare function clearCache(): void;
+/**
+ * Get the current cache size (for testing/debugging).
+ */
+export declare function getCacheSize(): number;
+/**
+ * Options for the caching wrapper.
+ */
+export interface WithCacheOptions {
+    /** The AI provider type for cache key isolation */
+    providerType: string;
+    /** The model identifier for cache key isolation */
+    model: string;
+}
+/**
+ * Wrap an AI provider with caching.
+ *
+ * The cache is isolated by provider type and model to prevent collisions
+ * when multiple Echo instances use different AI configurations.
+ *
+ * @param provider - The AI provider to wrap
+ * @param options - Cache options including provider/model for key isolation
+ * @returns A caching wrapper around the provider
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenAIProvider(config);
+ * const cachedProvider = withCache(provider, {
+ *   providerType: 'openai',
+ *   model: 'gpt-4o-mini',
+ * });
+ *
+ * // First call hits the API
+ * const result1 = await cachedProvider.evaluate(value, question);
+ *
+ * // Second call with same inputs returns cached result
+ * const result2 = await cachedProvider.evaluate(value, question);
+ * ```
+ */
+export declare function withCache(provider: AIProvider, options: WithCacheOptions): AIProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/ai-judge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai-judge/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAMpD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D;AAiCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA0DzE;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUpE;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAclE;AAYD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAI/D;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAW1D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAK3D;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,GAAG,UAAU,CA2BrF"}

package/dist/ai-judge/index.js

@@ -0,0 +1,299 @@
+/**
+ * @fileoverview AI Judge - LLM-based condition evaluation
+ *
+ * This module handles the #ai_judge operator which queries an LLM
+ * to evaluate boolean conditions.
+ *
+ * FEATURES:
+ * - Provider abstraction for different backends (OpenAI, Anthropic)
+ * - Automatic caching with TTL to avoid redundant API calls
+ * - Structured prompts for consistent yes/no answers
+ * - Graceful error handling
+ *
+ * API KEY CONFIGURATION:
+ * The API key can be provided in three ways (in priority order):
+ * 1. Programmatic: createEcho({ aiProvider: { apiKey: '...' } })
+ * 2. Environment: ECHO_API_KEY or OPENAI_API_KEY
+ * 3. Config file: echo.config.yaml (aiProvider.apiKey)
+ */
+import { createHash } from 'crypto';
+// =============================================================================
+// OPENAI PROVIDER
+// =============================================================================
+/**
+ * Create an OpenAI-based AI provider.
+ *
+ * @param config - Configuration with API key and model
+ * @returns AIProvider using OpenAI
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenAIProvider({
+ *   type: 'openai',
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   model: 'gpt-4o-mini',
+ * });
+ *
+ * const result = await provider.evaluate(
+ *   'This is a family-friendly movie.',
+ *   'Is this content appropriate for children?'
+ * );
+ * ```
+ */
+export function createOpenAIProvider(config) {
+    const apiKey = config.apiKey;
+    const model = config.model ?? 'gpt-4o-mini';
+    const timeout = config.timeout ?? 30000;
+    if (!apiKey) {
+        throw new Error('OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass it in config.');
+    }
+    return {
+        async evaluate(value, question) {
+            const prompt = buildPrompt(value, question);
+            const messages = [
+                {
+                    role: 'system',
+                    content: 'You are a precise yes/no evaluator. Answer ONLY with "yes" or "no" (lowercase, no punctuation). Do not explain or elaborate.',
+                },
+                {
+                    role: 'user',
+                    content: prompt,
+                },
+            ];
+            try {
+                const response = await callOpenAI(apiKey, model, messages, timeout);
+                const answer = response.choices[0]?.message?.content?.trim().toLowerCase();
+                if (answer === 'yes') {
+                    return true;
+                }
+                if (answer === 'no') {
+                    return false;
+                }
+                // Unexpected response - try to interpret
+                if (answer?.includes('yes')) {
+                    return true;
+                }
+                if (answer?.includes('no')) {
+                    return false;
+                }
+                // Default to false for ambiguous responses
+                console.warn(`AI Judge returned unexpected response: "${answer}". Defaulting to false.`);
+                return false;
+            }
+            catch (error) {
+                // Re-throw with more context
+                if (error instanceof Error) {
+                    throw new Error(`AI Judge evaluation failed: ${error.message}`);
+                }
+                throw new Error('AI Judge evaluation failed: Unknown error');
+            }
+        },
+    };
+}
+/**
+ * Call the OpenAI Chat Completions API.
+ */
+async function callOpenAI(apiKey, model, messages, timeout) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetch('https://api.openai.com/v1/chat/completions', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                messages,
+                max_tokens: 10,
+                temperature: 0, // Deterministic responses
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new Error(`OpenAI API error (${response.status}): ${errorBody}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Build the prompt for the AI judge.
+ *
+ * The prompt is designed to get a clear yes/no answer.
+ *
+ * @param value - The value to evaluate
+ * @param question - The question to ask
+ * @returns Formatted prompt string
+ */
+export function buildPrompt(value, question) {
+    const valueStr = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+    return `Given the following value:
+---
+${valueStr}
+---
+
+Answer with ONLY "yes" or "no":
+${question}`;
+}
+// =============================================================================
+// AI JUDGE FACTORY
+// =============================================================================
+/**
+ * Create an AI Judge instance with the given configuration.
+ *
+ * @param config - AI provider configuration
+ * @returns An AIProvider implementation
+ *
+ * @example
+ * ```typescript
+ * const judge = createAIJudge({
+ *   type: 'openai',
+ *   apiKey: process.env.OPENAI_API_KEY,
+ * });
+ *
+ * const isAppropriate = await judge.evaluate(content, 'Is this safe for work?');
+ * ```
+ */
+export function createAIJudge(config) {
+    switch (config.type) {
+        case 'openai':
+            return createOpenAIProvider(config);
+        case 'anthropic':
+            // TODO: Implement Anthropic provider
+            throw new Error('Anthropic provider not yet implemented. Use OpenAI for now.');
+        default:
+            throw new Error(`Unknown AI provider type: ${config.type}`);
+    }
+}
+// =============================================================================
+// CACHING
+// =============================================================================
+/** Module-level cache for AI judge results */
+const cache = new Map();
+/** Cache TTL in milliseconds (5 minutes) */
+const CACHE_TTL = 5 * 60 * 1000;
+/**
+ * Create a cache key for an AI judge evaluation.
+ *
+ * Uses SHA-256 hashing to create a fixed-size key regardless of input size.
+ * This is critical because the value being evaluated can be extremely large
+ * (e.g., a 200K token document). Storing the raw value as a Map key would
+ * cause severe memory bloat.
+ *
+ * The hash includes provider and model to prevent cache collisions when
+ * multiple Echo instances use different AI configurations.
+ *
+ * @param options - The cache key options
+ * @returns A 64-character hex hash string
+ *
+ * @example
+ * ```typescript
+ * const key = createCacheKey({
+ *   value: largeDocument,
+ *   question: 'Is this appropriate?',
+ *   provider: 'openai',
+ *   model: 'gpt-4o-mini',
+ * });
+ * // Returns: "a8f4b2c1e9d3..." (64 chars)
+ * ```
+ */
+export function createCacheKey(options) {
+    const { value, question, provider, model } = options;
+    const data = JSON.stringify({ value, question, provider, model });
+    return createHash('sha256').update(data).digest('hex');
+}
+/**
+ * Get a cached result if available and not expired.
+ *
+ * @param key - The cache key
+ * @returns The cached result or undefined if not found/expired
+ */
+export function getCached(key) {
+    const entry = cache.get(key);
+    if (!entry)
+        return undefined;
+    // Check if expired
+    if (Date.now() - entry.timestamp > CACHE_TTL) {
+        cache.delete(key);
+        return undefined;
+    }
+    return entry.result;
+}
+/**
+ * Store a result in the cache.
+ *
+ * @param key - The cache key
+ * @param result - The result to cache
+ */
+export function setCache(key, result) {
+    cache.set(key, {
+        result,
+        timestamp: Date.now(),
+    });
+}
+/**
+ * Clear the entire cache.
+ */
+export function clearCache() {
+    cache.clear();
+}
+/**
+ * Get the current cache size (for testing/debugging).
+ */
+export function getCacheSize() {
+    return cache.size;
+}
+/**
+ * Wrap an AI provider with caching.
+ *
+ * The cache is isolated by provider type and model to prevent collisions
+ * when multiple Echo instances use different AI configurations.
+ *
+ * @param provider - The AI provider to wrap
+ * @param options - Cache options including provider/model for key isolation
+ * @returns A caching wrapper around the provider
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenAIProvider(config);
+ * const cachedProvider = withCache(provider, {
+ *   providerType: 'openai',
+ *   model: 'gpt-4o-mini',
+ * });
+ *
+ * // First call hits the API
+ * const result1 = await cachedProvider.evaluate(value, question);
+ *
+ * // Second call with same inputs returns cached result
+ * const result2 = await cachedProvider.evaluate(value, question);
+ * ```
+ */
+export function withCache(provider, options) {
+    const { providerType, model } = options;
+    return {
+        async evaluate(value, question) {
+            const key = createCacheKey({
+                value,
+                question,
+                provider: providerType,
+                model,
+            });
+            // Check cache first
+            const cached = getCached(key);
+            if (cached !== undefined) {
+                return cached;
+            }
+            // Call the provider
+            const result = await provider.evaluate(value, question);
+            // Cache the result
+            setCache(key, result);
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/ai-judge/index.js.map

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

package/dist/evaluator/evaluator.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Echo Evaluator - Condition evaluation engine
+ *
+ * This file implements the evaluator for Echo DSL.
+ * The evaluator processes the AST and determines which nodes should be rendered
+ * based on the provided context and condition evaluation.
+ *
+ * KEY OPTIMIZATION: AI JUDGE PARALLELIZATION
+ * Before evaluating the AST, we:
+ * 1. Collect ALL #ai_judge conditions from the tree
+ * 2. Evaluate them in parallel using Promise.all
+ * 3. Cache the results
+ * 4. Use cached results during tree evaluation
+ *
+ * This prevents sequential blocking on AI calls.
+ */
+import type { ASTNode, ConditionalNode, ConditionExpr, EchoConfig, OperatorDefinition } from '../types.js';
+/**
+ * Evaluation context containing variables and resolved AI judges.
+ */
+export interface EvaluationContext {
+    /** Variables from user context */
+    variables: Record<string, unknown>;
+    /** Pre-resolved AI judge results (from parallel evaluation) */
+    aiJudgeResults: Map<string, boolean>;
+    /** Configuration */
+    config: EchoConfig;
+    /** Registered sections (for [#INCLUDE]) */
+    sections: Map<string, ASTNode[]>;
+    /** Custom operators (plugins) */
+    operators: Map<string, OperatorDefinition>;
+}
+/**
+ * Result of evaluating a node.
+ */
+export interface EvaluatedNode {
+    /** The original node */
+    node: ASTNode;
+    /** Whether this node should be rendered */
+    shouldRender: boolean;
+    /** For conditionals: the branch to render */
+    selectedBranch?: ASTNode[];
+}
+/**
+ * Options for variable resolution.
+ */
+export interface ResolveVariableOptions {
+    /** Whether to throw on malformed paths (default: false) */
+    strict?: boolean;
+}
+/**
+ * Resolve a variable path from context.
+ *
+ * Supports:
+ * - Simple: "name" -> context.name
+ * - Nested: "user.name" -> context.user.name
+ * - Array: "items[0]" -> context.items[0]
+ * - Mixed: "users[0].name" -> context.users[0].name
+ *
+ * @param path - The variable path
+ * @param context - The context object
+ * @param options - Resolution options
+ * @returns The resolved value or undefined
+ *
+ * @example
+ * ```typescript
+ * const context = { user: { name: 'Alice' }, items: [1, 2, 3] };
+ * resolveVariable('user.name', context); // 'Alice'
+ * resolveVariable('items[0]', context);  // 1
+ * ```
+ */
+export declare function resolveVariable(path: string, context: Record<string, unknown>, options?: ResolveVariableOptions): unknown;
+/**
+ * Evaluate a condition expression.
+ *
+ * @param condition - The condition to evaluate
+ * @param ctx - The evaluation context
+ * @returns true if condition is satisfied
+ */
+export declare function evaluateCondition(condition: ConditionExpr, ctx: EvaluationContext): Promise<boolean>;
+/**
+ * Pre-evaluate all AI judge conditions in parallel.
+ *
+ * This is the key optimization for performance.
+ * Call this before evaluating the AST to pre-resolve all AI conditions.
+ *
+ * @param ast - The AST to scan for AI judges
+ * @param ctx - The evaluation context (will be mutated with results)
+ */
+export declare function preEvaluateAiJudges(ast: ASTNode[], ctx: EvaluationContext): Promise<void>;
+/**
+ * Evaluate a conditional node and determine which branch to render.
+ *
+ * @param node - The conditional node
+ * @param ctx - The evaluation context
+ * @returns The nodes to render (empty if condition is false with no else)
+ */
+export declare function evaluateConditional(node: ConditionalNode, ctx: EvaluationContext): Promise<ASTNode[]>;
+/**
+ * Evaluate an AST with the given context.
+ *
+ * This is the main entry point for AST evaluation. It:
+ * 1. Collects section definitions (first pass)
+ * 2. Pre-evaluates AI judge conditions in parallel
+ * 3. Evaluates the AST and selects conditional branches
+ * 4. Returns a flattened AST ready for rendering
+ *
+ * @param ast - The AST to evaluate
+ * @param context - Variable context
+ * @param config - Echo configuration
+ * @param operators - Custom operators (from plugins)
+ * @returns Evaluated AST and section map
+ *
+ * @example
+ * ```typescript
+ * const result = await evaluate(ast, { name: 'Alice', age: 25 });
+ * console.log(result.ast); // Flattened, evaluated AST
+ * ```
+ */
+export declare function evaluate(ast: ASTNode[], context: Record<string, unknown>, config?: EchoConfig, operators?: Map<string, OperatorDefinition>): Promise<{
+    ast: ASTNode[];
+    sections: Map<string, ASTNode[]>;
+}>;
+/**
+ * Create an evaluation context manually.
+ * Useful for advanced use cases where you need more control.
+ *
+ * @param options - Context options
+ * @returns A new EvaluationContext
+ */
+export declare function createEvaluationContext(options: {
+    variables: Record<string, unknown>;
+    config?: EchoConfig;
+    operators?: Map<string, OperatorDefinition>;
+}): EvaluationContext;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluator/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,eAAe,EAGf,aAAa,EACb,UAAU,EACV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAQrB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,+DAA+D;IAC/D,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACjC,iCAAiC;IACjC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,YAAY,EAAE,OAAO,CAAC;IACtB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;CAC5B;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAiDT;AAqDD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,OAAO,CAAC,CAwClB;AAiBD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EAAE,EACd,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,IAAI,CAAC,CA6Cf;AAMD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,OAAO,EAAE,CAAC,CAqBpB;AA+HD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,OAAO,EAAE,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,GAAE,UAAe,EACvB,SAAS,GAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAa,GACrD,OAAO,CAAC;IAAE,GAAG,EAAE,OAAO,EAAE,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC,CAoB/D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC7C,GAAG,iBAAiB,CAQpB"}