@framers/agentos 0.1.56 → 0.1.57

package/dist/extensions/packs/pii-redaction/recognizers/LlmJudgeRecognizer.js

@@ -1,420 +0,0 @@
-/**
- * @file LlmJudgeRecognizer.ts
- * @description Tier 4 LLM-powered judge that re-examines individual PII
- * entity candidates using a chain-of-thought (CoT) prompt.
- *
- * Unlike the other recognisers, this class does **not** implement
- * {@link IEntityRecognizer} because it operates on already-detected entities
- * rather than raw text.  Its primary entry point is
- * {@link LlmJudgeRecognizer.judge}, which takes a single {@link PiiEntity}
- * plus the surrounding full text and returns either a confirmed/reclassified
- * entity or `null` if the LLM determines the span is not PII.
- *
- * ### Key features
- * - **Chain-of-thought prompt**: Forces the LLM to reason before classifying,
- *   improving accuracy on ambiguous spans.
- * - **LRU cache**: Keyed by `(span_text, context_hash)` to avoid redundant
- *   calls for identical spans in similar contexts.
- * - **Semaphore**: Limits concurrent LLM requests to prevent rate-limit
- *   exhaustion on high-throughput agents.
- * - **Fail-open**: If the LLM call fails for any reason, the original entity
- *   is returned unchanged (conservative — prefer false positive over leak).
- *
- * @module pii-redaction/recognizers
- */
-// ---------------------------------------------------------------------------
-// LRU cache implementation
-// ---------------------------------------------------------------------------
-/**
- * Simple LRU (Least Recently Used) cache backed by a `Map`.
- *
- * Leverages the insertion-order guarantee of ES2015 Maps: the least recently
- * used entry is always the first entry in iteration order.  On each `get`,
- * the entry is deleted and re-inserted to move it to the "most recent" end.
- *
- * @typeParam V - The cached value type.
- */
-class LruCache {
-    /**
-     * @param maxSize - Maximum cache capacity.
-     */
-    constructor(maxSize) {
-        /** Internal ordered map storage. */
-        this.map = new Map();
-        this.maxSize = maxSize;
-    }
-    /**
-     * Retrieve a cached value, promoting it to most-recently-used.
-     *
-     * @param key - Cache key.
-     * @returns The cached value, or `undefined` if not present.
-     */
-    get(key) {
-        const value = this.map.get(key);
-        if (value === undefined)
-            return undefined;
-        // Move to most-recently-used position by deleting and re-inserting.
-        this.map.delete(key);
-        this.map.set(key, value);
-        return value;
-    }
-    /**
-     * Insert or update a value, evicting the oldest entry if at capacity.
-     *
-     * @param key   - Cache key.
-     * @param value - Value to cache.
-     */
-    set(key, value) {
-        // If the key already exists, delete it first to reset its position.
-        if (this.map.has(key)) {
-            this.map.delete(key);
-        }
-        this.map.set(key, value);
-        // Evict the oldest entry if we've exceeded capacity.
-        if (this.map.size > this.maxSize) {
-            const oldestKey = this.map.keys().next().value;
-            this.map.delete(oldestKey);
-        }
-    }
-    /** Current number of entries in the cache. */
-    get size() {
-        return this.map.size;
-    }
-}
-// ---------------------------------------------------------------------------
-// Semaphore implementation
-// ---------------------------------------------------------------------------
-/**
- * Counting semaphore for limiting concurrent async operations.
- *
- * Callers {@link acquire} a permit before starting work and {@link release}
- * it when done.  If all permits are taken, `acquire()` returns a promise
- * that resolves once a permit becomes available.
- */
-class Semaphore {
-    /**
-     * @param maxConcurrency - Maximum number of simultaneous permits.
-     */
-    constructor(maxConcurrency) {
-        /** Queue of waiters blocked on permit acquisition. */
-        this.waiters = [];
-        this.permits = maxConcurrency;
-    }
-    /**
-     * Acquire a permit.  Resolves immediately if a permit is available,
-     * otherwise blocks until one is released.
-     */
-    async acquire() {
-        if (this.permits > 0) {
-            this.permits--;
-            return;
-        }
-        // No permits available — queue a waiter.
-        return new Promise((resolve) => {
-            this.waiters.push(resolve);
-        });
-    }
-    /**
-     * Release a permit, waking the next queued waiter if any.
-     */
-    release() {
-        const next = this.waiters.shift();
-        if (next) {
-            // Hand the permit directly to the next waiter.
-            next();
-        }
-        else {
-            this.permits++;
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// System prompt
-// ---------------------------------------------------------------------------
-/**
- * System prompt that instructs the LLM to perform chain-of-thought PII
- * classification.  The prompt requests a strict JSON response format.
- */
-const SYSTEM_PROMPT = `You are a PII (Personally Identifiable Information) classification expert.
-
-Your task: given a text span that was flagged as potential PII, determine whether it truly contains PII that should be redacted.
-
-Think step-by-step:
-1. What is the span text?
-2. What is the surrounding context?
-3. Is this genuinely identifying information about a real person, or is it generic/fictional/public knowledge?
-4. What specific PII type does it represent?
-
-Respond with ONLY a valid JSON object (no markdown, no explanation outside the JSON):
-{
-  "isPii": true/false,
-  "entityType": "PERSON" | "ORGANIZATION" | "LOCATION" | "EMAIL" | "PHONE" | "SSN" | "CREDIT_CARD" | "IP_ADDRESS" | "DATE_OF_BIRTH" | "API_KEY" | "AWS_KEY" | "CRYPTO_ADDRESS" | "IBAN" | "PASSPORT" | "DRIVERS_LICENSE" | "GOV_ID" | "MEDICAL_TERM" | "UNKNOWN_PII" | "NOT_PII",
-  "confidence": 0.0-1.0,
-  "reasoning": "brief explanation of your classification"
-}`;
-// ---------------------------------------------------------------------------
-// LlmJudgeRecognizer
-// ---------------------------------------------------------------------------
-/**
- * Tier 4 LLM-powered judge that confirms or reclassifies individual PII
- * entity candidates using chain-of-thought reasoning.
- *
- * ### Usage pattern
- * ```ts
- * const judge = new LlmJudgeRecognizer(config);
- * const result = await judge.judge(candidateEntity, fullText);
- * if (result === null) {
- *   // LLM says it's not PII — discard the candidate.
- * } else {
- *   // Use the confirmed/reclassified entity.
- * }
- * ```
- *
- * ### Caching
- * Results are cached by a composite key of the span text and a hash of
- * the surrounding context.  This means identical spans in similar contexts
- * won't trigger redundant LLM calls.
- *
- * ### Concurrency control
- * A counting semaphore limits the number of in-flight LLM requests to
- * {@link LlmJudgeConfig.maxConcurrency} (default 3), preventing rate-limit
- * errors when many entities are judged in parallel.
- *
- * ### Failure mode
- * The judge is **fail-open**: if the LLM call fails (network error, invalid
- * response, timeout), the original entity is returned unchanged.  This is
- * the conservative choice — a false positive (over-redaction) is preferable
- * to leaking real PII.
- */
-export class LlmJudgeRecognizer {
-    /**
-     * Construct a new LlmJudgeRecognizer.
-     *
-     * @param config    - LLM provider/model configuration.
-     * @param fetchImpl - Optional injectable fetch function for testing.
-     *                    Defaults to the global `fetch`.
-     */
-    constructor(config, fetchImpl) {
-        /** Human-readable name for logging/diagnostics. */
-        this.name = 'LlmJudgeRecognizer';
-        this.config = config;
-        this.cache = new LruCache(config.cacheSize ?? 256);
-        this.semaphore = new Semaphore(config.maxConcurrency ?? 3);
-        this.fetchImpl = fetchImpl ?? globalThis.fetch;
-    }
-    /**
-     * Judge a single PII entity candidate in context.
-     *
-     * @param entity   - The candidate entity to evaluate.
-     * @param fullText - The full text from which the entity was extracted,
-     *                   providing the LLM with surrounding context.
-     * @returns The confirmed/reclassified entity, or `null` if the LLM
-     *          determines the span is not PII.
-     */
-    async judge(entity, fullText) {
-        // Build the cache key from the span text and a hash of the context.
-        const cacheKey = this.buildCacheKey(entity.text, fullText);
-        // Check cache first.
-        const cached = this.cache.get(cacheKey);
-        if (cached !== undefined) {
-            return cached;
-        }
-        // Acquire a semaphore permit to respect concurrency limits.
-        await this.semaphore.acquire();
-        try {
-            // Build the user prompt with the span and its context.
-            const userPrompt = this.buildUserPrompt(entity, fullText);
-            // Call the LLM via OpenAI-compatible chat completions API.
-            const judgement = await this.callLlm(userPrompt);
-            // Process the LLM's judgement.
-            const result = this.processJudgement(judgement, entity);
-            // Cache the result.
-            this.cache.set(cacheKey, result);
-            return result;
-        }
-        catch {
-            // Fail-open: if the LLM call fails, return the original entity
-            // unchanged to avoid accidentally leaking PII.
-            return entity;
-        }
-        finally {
-            // Always release the semaphore permit.
-            this.semaphore.release();
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Private helpers
-    // -----------------------------------------------------------------------
-    /**
-     * Builds the cache key from the span text and a simple hash of the
-     * surrounding context.
-     *
-     * The context hash uses a fast DJB2 hash — sufficient for cache-key
-     * purposes without requiring a cryptographic hash function.
-     *
-     * @param spanText - The matched text span.
-     * @param context  - The full surrounding text.
-     * @returns A composite cache key string.
-     */
-    buildCacheKey(spanText, context) {
-        const contextHash = this.djb2Hash(context);
-        return `${spanText}::${contextHash}`;
-    }
-    /**
-     * DJB2 hash function by Daniel J. Bernstein.
-     * Fast, non-cryptographic hash suitable for hash-table keys.
-     *
-     * @param str - String to hash.
-     * @returns Hex string representation of the hash.
-     */
-    djb2Hash(str) {
-        let hash = 5381;
-        for (let i = 0; i < str.length; i++) {
-            // hash * 33 + charCode
-            hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
-        }
-        return (hash >>> 0).toString(16);
-    }
-    /**
-     * Builds the user prompt containing the span text and its surrounding
-     * context for the LLM to evaluate.
-     *
-     * @param entity   - The candidate entity.
-     * @param fullText - The full text for context.
-     * @returns The formatted user prompt string.
-     */
-    buildUserPrompt(entity, fullText) {
-        // Extract a window of context around the entity for the LLM.
-        const contextWindow = 200; // characters on each side
-        const ctxStart = Math.max(0, entity.start - contextWindow);
-        const ctxEnd = Math.min(fullText.length, entity.end + contextWindow);
-        const surroundingContext = fullText.slice(ctxStart, ctxEnd);
-        return [
-            `Span text: "${entity.text}"`,
-            `Current classification: ${entity.entityType} (confidence: ${entity.score.toFixed(2)})`,
-            `Source tier: ${entity.source}`,
-            `Surrounding context: "${surroundingContext}"`,
-        ].join('\n');
-    }
-    /**
-     * Calls the LLM via OpenAI-compatible chat completions API.
-     *
-     * Uses raw `fetch` (no SDK dependency) to keep the extension lightweight
-     * and to support any OpenAI-compatible endpoint (OpenRouter, vLLM, etc.).
-     *
-     * @param userPrompt - The user message content.
-     * @returns Parsed LLM judgement response.
-     * @throws If the API call fails or the response is not valid JSON.
-     */
-    async callLlm(userPrompt) {
-        const baseUrl = this.config.baseUrl ?? 'https://api.openai.com/v1';
-        const apiKey = this.config.apiKey ?? '';
-        const response = await this.fetchImpl(`${baseUrl}/chat/completions`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${apiKey}`,
-            },
-            body: JSON.stringify({
-                model: this.config.model,
-                messages: [
-                    { role: 'system', content: SYSTEM_PROMPT },
-                    { role: 'user', content: userPrompt },
-                ],
-                temperature: 0.1, // Low temperature for deterministic classification
-                max_tokens: 300,
-            }),
-        });
-        if (!response.ok) {
-            throw new Error(`LLM API returned status ${response.status}`);
-        }
-        const data = await response.json();
-        // Extract the content string from the chat completion response.
-        const content = data.choices?.[0]?.message?.content ?? '';
-        // Parse the JSON response, handling potential markdown fences.
-        return this.parseJudgement(content);
-    }
-    /**
-     * Parses the LLM's response content into a structured judgement object.
-     *
-     * Handles common LLM response quirks:
-     * - Markdown code fences around JSON
-     * - Leading/trailing whitespace
-     *
-     * @param content - Raw response content string from the LLM.
-     * @returns Parsed {@link LlmJudgement}.
-     * @throws If the content cannot be parsed as valid JSON.
-     */
-    parseJudgement(content) {
-        // Strip markdown code fences if present.
-        let cleaned = content.trim();
-        if (cleaned.startsWith('```')) {
-            // Remove opening fence (```json or ```)
-            cleaned = cleaned.replace(/^```(?:json)?\s*/, '');
-            // Remove closing fence
-            cleaned = cleaned.replace(/\s*```$/, '');
-        }
-        return JSON.parse(cleaned);
-    }
-    /**
-     * Processes the LLM's judgement and returns the appropriate result.
-     *
-     * - If the LLM says the span is NOT PII, returns `null`.
-     * - If the LLM confirms PII, returns an updated entity with the LLM's
-     *   classification and confidence, preserving the original values in
-     *   metadata for audit.
-     *
-     * @param judgement - The parsed LLM response.
-     * @param original  - The original candidate entity.
-     * @returns Updated entity or `null`.
-     */
-    processJudgement(judgement, original) {
-        // If the LLM says it's not PII, discard the entity.
-        if (!judgement.isPii || judgement.entityType === 'NOT_PII') {
-            return null;
-        }
-        // Map the LLM's entity type string to our PiiEntityType, falling back
-        // to the original type if the LLM returns something unexpected.
-        const newEntityType = this.mapLlmEntityType(judgement.entityType, original.entityType);
-        return {
-            entityType: newEntityType,
-            text: original.text,
-            start: original.start,
-            end: original.end,
-            score: judgement.confidence,
-            source: 'llm',
-            metadata: {
-                ...original.metadata,
-                llmReasoning: judgement.reasoning,
-                llmModel: this.config.model,
-                originalEntityType: original.entityType,
-                originalScore: original.score,
-                originalSource: original.source,
-            },
-        };
-    }
-    /**
-     * Maps the LLM's entity type string to our {@link PiiEntityType}.
-     *
-     * If the LLM returns a recognised type string, it is used directly.
-     * Otherwise, the original entity type is preserved.
-     *
-     * @param llmType  - Entity type string from the LLM response.
-     * @param fallback - Original entity type to use as fallback.
-     * @returns Resolved PiiEntityType.
-     */
-    mapLlmEntityType(llmType, fallback) {
-        // List of all valid PiiEntityType values for validation.
-        const validTypes = new Set([
-            'SSN', 'CREDIT_CARD', 'EMAIL', 'PHONE', 'IP_ADDRESS', 'IBAN',
-            'PASSPORT', 'DRIVERS_LICENSE', 'GOV_ID', 'DATE_OF_BIRTH', 'API_KEY',
-            'AWS_KEY', 'CRYPTO_ADDRESS', 'PERSON', 'ORGANIZATION', 'LOCATION',
-            'MEDICAL_TERM', 'UNKNOWN_PII',
-        ]);
-        if (validTypes.has(llmType)) {
-            return llmType;
-        }
-        return fallback;
-    }
-}
-//# sourceMappingURL=LlmJudgeRecognizer.js.map

package/dist/extensions/packs/pii-redaction/recognizers/LlmJudgeRecognizer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"LlmJudgeRecognizer.js","sourceRoot":"","sources":["../../../../../src/extensions/packs/pii-redaction/recognizers/LlmJudgeRecognizer.ts"],"names":[],"mappings":"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"}

package/dist/extensions/packs/pii-redaction/recognizers/NerModelRecognizer.d.ts

@@ -1,145 +0,0 @@
-/**
- * @file NerModelRecognizer.ts
- * @description Tier 3 NER-model recogniser that uses a HuggingFace
- * Transformers pipeline for high-accuracy named-entity recognition.
- *
- * This recogniser loads a pre-trained BERT-style NER model via the
- * `@huggingface/transformers` library and maps BIO-tagged outputs
- * (B-PER, I-PER, B-LOC, I-LOC, B-ORG, I-ORG, B-MISC, I-MISC) to the
- * pipeline's {@link PiiEntityType} values.
- *
- * The model is lazily loaded through the {@link ISharedServiceRegistry} so
- * that only one instance exists per agent, and it is shared across any
- * extensions that need NER capabilities.
- *
- * @module pii-redaction/recognizers
- */
-import type { PiiEntity, PiiEntityType } from '../types';
-import type { IEntityRecognizer, RecognizeOptions } from './IEntityRecognizer';
-import type { ISharedServiceRegistry } from '../../../ISharedServiceRegistry';
-/**
- * Shape of a single token-level NER result from the HuggingFace
- * transformers pipeline.
- */
-export interface NerToken {
-    /** BIO-tagged entity label, e.g. `'B-PER'`, `'I-LOC'`, `'O'`. */
-    entity: string;
-    /** The sub-word or word text for this token. */
-    word: string;
-    /** Confidence score from the model (0–1). */
-    score: number;
-    /** Character start offset in the original input. */
-    start: number;
-    /** Character end offset in the original input. */
-    end: number;
-}
-/**
- * Tier 3 entity recogniser that runs a HuggingFace BERT NER model for
- * high-accuracy named-entity recognition.
- *
- * ### How it works
- * 1. On first `recognize()` call, the `@huggingface/transformers` library is
- *    loaded and a `token-classification` pipeline is created via the shared
- *    service registry.
- * 2. The pipeline tokenises the input and runs it through the NER model,
- *    returning BIO-tagged token predictions.
- * 3. Contiguous BIO tokens are merged: a `B-PER` followed by `I-PER` tokens
- *    becomes a single PERSON entity.  The final score is the average of the
- *    constituent token scores.
- * 4. Merged entities are mapped to {@link PiiEntity} objects.
- *
- * ### Graceful degradation
- * If `@huggingface/transformers` is not installed or the model fails to load,
- * the recogniser sets `unavailable = true` and returns empty arrays on all
- * subsequent calls, ensuring the pipeline degrades without crashing.
- *
- * @example
- * ```ts
- * const registry = new SharedServiceRegistry();
- * const recognizer = new NerModelRecognizer(registry);
- * const entities = await recognizer.recognize('John Smith lives in London');
- * // entities: [{ entityType: 'PERSON', text: 'John Smith', ... },
- * //            { entityType: 'LOCATION', text: 'London', ... }]
- * ```
- */
-export declare class NerModelRecognizer implements IEntityRecognizer {
-    /** @inheritdoc */
-    readonly name = "NerModelRecognizer";
-    /** @inheritdoc */
-    readonly supportedEntities: PiiEntityType[];
-    /**
-     * When `true`, the transformers library or model failed to load and all
-     * future calls will return empty arrays.
-     */
-    private unavailable;
-    /**
-     * Reference to the shared service registry for lazy-loading the NER
-     * pipeline.
-     */
-    private readonly services;
-    /**
-     * Construct a new NerModelRecognizer.
-     *
-     * @param services - Shared service registry for lazy-loading the
-     *   HuggingFace NER pipeline.
-     */
-    constructor(services: ISharedServiceRegistry);
-    /**
-     * Scan the input text for named entities using a BERT NER model.
-     *
-     * BIO-tagged tokens are merged into contiguous entity spans and mapped
-     * to {@link PiiEntity} objects.
-     *
-     * @param input   - Raw text to analyse.
-     * @param options - Optional filtering and context hints.
-     * @returns Array of detected {@link PiiEntity} objects.
-     */
-    recognize(input: string, options?: RecognizeOptions): Promise<PiiEntity[]>;
-    /** @inheritdoc */
-    dispose(): Promise<void>;
-    /**
-     * Determines which of our supported entity types the caller wants.
-     *
-     * @param entityTypes - Optional entity-type filter from the caller.
-     * @returns Set of wanted types intersected with our supported types.
-     */
-    private resolveWantedTypes;
-    /**
-     * Merges BIO-tagged tokens into contiguous entity spans.
-     *
-     * The BIO tagging scheme works as follows:
-     * - `B-XXX` — Beginning of a new entity of type XXX.
-     * - `I-XXX` — Inside/continuation of the current entity of type XXX.
-     * - `O`     — Outside any entity (ignored).
-     *
-     * A `B-PER` followed by one or more `I-PER` tokens produces a single
-     * merged span.  When a `B-XXX` appears while another entity is open,
-     * the previous entity is flushed and a new one begins.
-     *
-     * @param tokens - Raw BIO-tagged token array from the NER pipeline.
-     * @returns Array of merged entity spans with aggregated metadata.
-     */
-    private mergeBioTokens;
-    /**
-     * Parses a BIO label string like `'B-PER'` or `'I-LOC'` into its
-     * tag component (`'B'`, `'I'`, `'O'`) and entity label (`'PER'`, `'LOC'`).
-     *
-     * @param bioLabel - The raw BIO label from the NER model.
-     * @returns Parsed tag and label.
-     */
-    private parseBioLabel;
-    /**
-     * Maps merged entity spans to {@link PiiEntity} objects, filtering by
-     * the set of wanted entity types.
-     *
-     * The score for each entity is the arithmetic mean of its constituent
-     * token scores, reflecting the model's average confidence across the
-     * full span.
-     *
-     * @param merged     - Array of merged BIO entity spans.
-     * @param wantedTypes - Set of entity types the caller is interested in.
-     * @returns Filtered array of {@link PiiEntity} objects.
-     */
-    private mapToEntities;
-}
-//# sourceMappingURL=NerModelRecognizer.d.ts.map

package/dist/extensions/packs/pii-redaction/recognizers/NerModelRecognizer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"NerModelRecognizer.d.ts","sourceRoot":"","sources":["../../../../../src/extensions/packs/pii-redaction/recognizers/NerModelRecognizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAsC9E;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;CACb;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IAC1D,kBAAkB;IAClB,SAAgB,IAAI,wBAAwB;IAE5C,kBAAkB;IAClB,SAAgB,iBAAiB,EAAE,aAAa,EAAE,CAKhD;IAEF;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAElD;;;;;OAKG;gBACS,QAAQ,EAAE,sBAAsB;IAI5C;;;;;;;;;OASG;IACU,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAgDvF,kBAAkB;IACL,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IASrC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,cAAc;IAuDtB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAerB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;CAmCtB"}