pynect 0.0.0-stage → 0.2.0

package/dist/core/PyIterator.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * pynect - PyIterator
+ * Wraps a Python iterator for use with JavaScript's for await...of.
+ * Provides both async iteration and manual .next() calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyIterator = void 0;
+const ErrorTranslator_1 = require("../utils/ErrorTranslator");
+const PyProxy_1 = require("./PyProxy");
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('PyIterator');
+/**
+ * PyIterator - manages a Python iterator lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const iterator = await PyIterator.create(pyList, addon);
+ *
+ * for await (const item of iterator) {
+ * console.log(item);
+ * }
+ *
+ * // Or manually:
+ * const { value, done } = await iterator.next();
+ * ```
+ */
+class PyIterator {
+    _iteratorId;
+    _addon;
+    _objectId;
+    _options;
+    _done = false;
+    _position = 0;
+    _destroyed = false;
+    constructor(iteratorId, objectId, addon, options = {}) {
+        this._iteratorId = iteratorId;
+        this._objectId = objectId;
+        this._addon = addon;
+        this._options = options;
+    }
+    /**
+     * Create a PyIterator from a PyProxy.
+     */
+    static async create(source, options) {
+        const internal = source[PyProxy_1.PYPROXY_INTERNAL];
+        const addon = internal.addon;
+        const result = await addon.createIterator(internal.objectId, internal.path);
+        if (!result.success) {
+            if (result.error) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: result.error.type,
+                    message: result.error.message,
+                    traceback: result.error.traceback || '',
+                });
+            }
+            throw new Error('Failed to create Python iterator');
+        }
+        let iteratorId;
+        try {
+            const parsed = JSON.parse(result.resultJson || '{}');
+            if (!parsed.iteratorId) {
+                throw new Error('no iteratorId');
+            }
+            iteratorId = parsed.iteratorId;
+        }
+        catch {
+            throw new Error('Failed to parse iterator ID from: ' + result.resultJson);
+        }
+        return new PyIterator(iteratorId, internal.objectId, addon, options);
+    }
+    /**
+     * Create a PyIterator from an object ID and iterator ID directly.
+     */
+    static fromIds(iteratorId, objectId, addon, options) {
+        return new PyIterator(iteratorId, objectId, addon, options);
+    }
+    /** Current position in iteration */
+    get position() {
+        return this._position;
+    }
+    /** Whether iteration is complete */
+    get isDone() {
+        return this._done;
+    }
+    // AsyncIterator Protocol
+    async next() {
+        if (this._done || this._destroyed) {
+            return { value: undefined, done: true };
+        }
+        // Check limit
+        if (this._options.limit && this._position >= this._options.limit) {
+            await this.destroy();
+            return { value: undefined, done: true };
+        }
+        try {
+            const result = await this._addon.iteratorNext(this._iteratorId);
+            if (!result.success) {
+                if (result.error) {
+                    throw (0, ErrorTranslator_1.translatePythonError)({
+                        type: result.error.type,
+                        message: result.error.message,
+                        traceback: result.error.traceback || '',
+                    });
+                }
+                this._done = true;
+                return { value: undefined, done: true };
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(result.resultJson || '{"done":true}');
+            }
+            catch {
+                this._done = true;
+                return { value: undefined, done: true };
+            }
+            if (parsed.done) {
+                this._done = true;
+                return { value: undefined, done: true };
+            }
+            this._position++;
+            // Deserialize the value
+            const rawValue = parsed.value;
+            let value;
+            if (rawValue !== null &&
+                typeof rawValue === 'object' &&
+                '__pyref__' in rawValue) {
+                // It's a Python object reference
+                if (this._options.wrapObjects !== false) {
+                    const refId = rawValue.__pyref__;
+                    value = PyProxy_1.PyProxy._createFromObjectId(refId, [], this._addon);
+                }
+                else {
+                    value = rawValue;
+                }
+            }
+            else {
+                value = rawValue;
+            }
+            return { value, done: false };
+        }
+        catch (err) {
+            this._done = true;
+            throw err;
+        }
+    }
+    async return(value) {
+        await this.destroy();
+        return { value: value, done: true };
+    }
+    async throw(error) {
+        await this.destroy();
+        throw error;
+    }
+    // AsyncIterable Protocol
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    // Utilities
+    /**
+     * Collect all items into an array.
+     * Use with care for large iterators!
+     */
+    async toArray(maxItems = 100000) {
+        const items = [];
+        for await (const item of this) {
+            items.push(item);
+            if (items.length >= maxItems) {
+                break;
+            }
+        }
+        return items;
+    }
+    /**
+     * Process items in batches.
+     */
+    async *batch(batchSize) {
+        let current = [];
+        for await (const item of this) {
+            current.push(item);
+            if (current.length >= batchSize) {
+                yield current;
+                current = [];
+            }
+        }
+        if (current.length > 0) {
+            yield current;
+        }
+    }
+    /**
+     * Map items through a transform function.
+     */
+    async *map(fn) {
+        let i = 0;
+        for await (const item of this) {
+            yield await fn(item, i++);
+        }
+    }
+    /**
+     * Filter items.
+     */
+    async *filter(fn) {
+        let i = 0;
+        for await (const item of this) {
+            if (await fn(item, i++)) {
+                yield item;
+            }
+        }
+    }
+    /**
+     * Take first N items.
+     */
+    async take(n) {
+        const items = [];
+        for await (const item of this) {
+            items.push(item);
+            if (items.length >= n) {
+                break;
+            }
+        }
+        await this.destroy();
+        return items;
+    }
+    /**
+     * Destroy the underlying Python iterator (frees resources).
+     * Called automatically when iteration completes.
+     */
+    async destroy() {
+        if (this._destroyed) {
+            return;
+        }
+        this._destroyed = true;
+        this._done = true;
+        try {
+            await this._addon.destroyIterator(this._iteratorId);
+        }
+        catch (err) {
+            logger.debug('Error destroying iterator', err);
+        }
+    }
+}
+exports.PyIterator = PyIterator;
+//# sourceMappingURL=PyIterator.js.map

package/dist/core/PyIterator.js.map

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

package/dist/core/PyModule.d.ts

@@ -0,0 +1,53 @@
+/**
+ * pynect - PyModule
+ * Represents a Python module with its full namespace.
+ * Inherits from PyProxy but adds module-specific introspection.
+ */
+import { PyProxy } from './PyProxy';
+import type { NativeAddon } from '../types/addon';
+import type { PyObjectId, PyModuleInspection } from '../types/python';
+/**
+ * PyModule extends PyProxy with module-specific utilities.
+ *
+ * @example
+ * ```typescript
+ * const pd = await py.import('pandas');
+ * // pd is a PyModule
+ * const df = await pd.read_csv('data.csv');  // access module attribute
+ * const info = await pd.__pynect_inspect__();  // get module metadata
+ * ```
+ */
+export declare class PyModule extends PyProxy {
+    private readonly _moduleName;
+    constructor(objectId: PyObjectId, moduleName: string, addon: NativeAddon, callTimeout?: number, executionTimeout?: number);
+    /** The Python module name */
+    get moduleName(): string;
+    /** Object ID in Python heap */
+    get objectId(): PyObjectId;
+    /**
+     * Inspect the module and return detailed type information.
+     */
+    inspect(): Promise<PyModuleInspection>;
+    /**
+     * Get list of public names in the module (dir() equivalent).
+     */
+    getNames(): Promise<string[]>;
+    /**
+     * Check if the module has a specific attribute.
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Get module version string.
+     */
+    getVersion(): Promise<string | null>;
+    /**
+     * Reload the module (re-imports from Python).
+     */
+    reload(): Promise<void>;
+    /**
+     * Create a PyModule from an existing addon import result.
+     */
+    static fromRef(objectId: PyObjectId, moduleName: string, addon: NativeAddon, callTimeout?: number, executionTimeout?: number): PyModule;
+    toString(): string;
+}
+//# sourceMappingURL=PyModule.d.ts.map

package/dist/core/PyModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PyModule.d.ts","sourceRoot":"","sources":["../../src/core/PyModule.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKtE;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,OAAO;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGnC,QAAQ,EAAE,UAAU,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,gBAAgB,CAAC,EAAE,MAAM;IAY3B,6BAA6B;IAC7B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,+BAA+B;IAC/B,IAAI,QAAQ,IAAI,UAAU,CAEzB;IAED;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAqE5C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAcnC;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKzC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAK1C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,QAAQ,EAAE,UAAU,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,gBAAgB,CAAC,EAAE,MAAM,GACxB,QAAQ;IAIF,QAAQ,IAAI,MAAM;CAG5B"}

package/dist/core/PyModule.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * pynect - PyModule
+ * Represents a Python module with its full namespace.
+ * Inherits from PyProxy but adds module-specific introspection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyModule = void 0;
+const PyProxy_1 = require("./PyProxy");
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('PyModule');
+/**
+ * PyModule extends PyProxy with module-specific utilities.
+ *
+ * @example
+ * ```typescript
+ * const pd = await py.import('pandas');
+ * // pd is a PyModule
+ * const df = await pd.read_csv('data.csv');  // access module attribute
+ * const info = await pd.__pynect_inspect__();  // get module metadata
+ * ```
+ */
+class PyModule extends PyProxy_1.PyProxy {
+    _moduleName;
+    constructor(objectId, moduleName, addon, callTimeout, executionTimeout) {
+        super({
+            objectId,
+            path: [],
+            addon,
+            callTimeout,
+            executionTimeout,
+        });
+        this._moduleName = moduleName;
+    }
+    /** The Python module name */
+    get moduleName() {
+        return this._moduleName;
+    }
+    /** Object ID in Python heap */
+    get objectId() {
+        return this[PyProxy_1.PYPROXY_INTERNAL].objectId;
+    }
+    /**
+     * Inspect the module and return detailed type information.
+     */
+    async inspect() {
+        const addon = this[PyProxy_1.PYPROXY_INTERNAL].addon;
+        try {
+            // Run Python introspection
+            const result = await addon.runPythonCode(`
+import json
+import sys
+
+def _inspect_module_${this._moduleName.replace(/\./g, '_')}():
+    try:
+        import ${this._moduleName} as _mod
+        import inspect
+
+        result = {
+            'name': '${this._moduleName}',
+            'file': getattr(_mod, '__file__', None),
+            'docstring': (getattr(_mod, '__doc__', '') or '')[:500],
+            'version': getattr(_mod, '__version__', None),
+            'functions': [],
+            'classes': [],
+            'constants': [],
+            'submodules': [],
+        }
+
+        for name in dir(_mod):
+            if name.startswith('_'):
+                continue
+            try:
+                obj = getattr(_mod, name)
+                if inspect.ismodule(obj):
+                    result['submodules'].append(name)
+                elif inspect.isclass(obj):
+                    result['classes'].append({'name': name, 'type': 'class'})
+                elif callable(obj):
+                    result['functions'].append({'name': name, 'type': 'function'})
+                else:
+                    result['constants'].append({'name': name, 'type': type(obj).__name__})
+            except Exception:
+                pass
+
+        return result
+    except Exception as e:
+        return {'name': '${this._moduleName}', 'error': str(e), 'functions': [], 'classes': [], 'constants': [], 'submodules': []}
+
+_result = _inspect_module_${this._moduleName.replace(/\./g, '_')}()
+json.dumps(_result)
+`);
+            const r = result;
+            if (r.success && r.resultJson) {
+                const parsed = JSON.parse(r.resultJson.replace(/^"|"$/g, '').replace(/\\"/g, '"'));
+                return parsed;
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to inspect module ${this._moduleName}`, err);
+        }
+        // Return minimal inspection
+        return {
+            name: this._moduleName,
+            docstring: '',
+            functions: [],
+            classes: [],
+            constants: [],
+            submodules: [],
+        };
+    }
+    /**
+     * Get list of public names in the module (dir() equivalent).
+     */
+    async getNames() {
+        const addon = this[PyProxy_1.PYPROXY_INTERNAL].addon;
+        const result = await addon.getObjectKeys(this.objectId);
+        const r = result;
+        if (r.success && r.resultJson) {
+            try {
+                return JSON.parse(r.resultJson);
+            }
+            catch {
+                return [];
+            }
+        }
+        return [];
+    }
+    /**
+     * Check if the module has a specific attribute.
+     */
+    async has(name) {
+        const addon = this[PyProxy_1.PYPROXY_INTERNAL].addon;
+        return addon.hasAttribute(this.objectId, name);
+    }
+    /**
+     * Get module version string.
+     */
+    async getVersion() {
+        const inspection = await this.inspect();
+        return inspection.version ?? null;
+    }
+    /**
+     * Reload the module (re-imports from Python).
+     */
+    async reload() {
+        const addon = this[PyProxy_1.PYPROXY_INTERNAL].addon;
+        await addon.reloadModule(this.objectId);
+        logger.debug(`Module ${this._moduleName} reloaded`);
+    }
+    /**
+     * Create a PyModule from an existing addon import result.
+     */
+    static fromRef(objectId, moduleName, addon, callTimeout, executionTimeout) {
+        return new PyModule(objectId, moduleName, addon, callTimeout, executionTimeout);
+    }
+    toString() {
+        return `[PyModule '${this._moduleName}' id=${this.objectId}]`;
+    }
+}
+exports.PyModule = PyModule;
+//# sourceMappingURL=PyModule.js.map

package/dist/core/PyModule.js.map

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

package/dist/core/PyProxy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * pynect - PyProxy
+ *
+ * The heart of pynect's JavaScript API.
+ * Every Python object is represented as a PyProxy - a JavaScript Proxy that:
+ *
+ * 1. Intercepts property access -> creates lazy child PyProxy
+ * 2. Intercepts function call -> sends to Python worker thread
+ * 3. Intercepts `then` -> resolves the proxy chain into a value (makes it awaitable)
+ * 4. Intercepts Symbol.iterator -> enables for...of loops
+ * 5. Intercepts Symbol.asyncIterator -> enables for await...of loops
+ * 6. Intercepts property assignment -> sets Python attribute
+ *
+ * The key insight: attributes are NOT resolved eagerly. The chain
+ * `df.groupby('country').agg({'sales': 'sum'}).reset_index()`
+ * creates a chain of PyProxy objects, each recording the operation,
+ * and only executes when you `await` the final result.
+ */
+import type { NativeAddon, PyCallOptions } from '../types/addon';
+import type { PyObjectId, AttributePath, SerializedValue } from '../types/python';
+export declare const PYPROXY_INTERNAL: unique symbol;
+export declare const PYPROXY_OBJECTID: unique symbol;
+export declare const PYPROXY_PATH: unique symbol;
+export declare const PYNECT_WITH_OPTIONS: unique symbol;
+export type PynectFunction<FunctionType extends (...args: never[]) => Promise<unknown>> = FunctionType & {
+    withOptions(options: PyCallOptions, ...args: Parameters<FunctionType>): ReturnType<FunctionType>;
+    [PYNECT_WITH_OPTIONS](options: PyCallOptions, ...args: Parameters<FunctionType>): ReturnType<FunctionType>;
+};
+/**
+ * Internal state of a PyProxy.
+ */
+export interface PyProxyInternal {
+    objectId: PyObjectId;
+    path: AttributePath;
+    addon: NativeAddon;
+    callTimeout?: number;
+    executionTimeout?: number;
+}
+/**
+ * PyProxy - wraps any Python object in JavaScript.
+ *
+ * Usage:
+ * ```typescript
+ * const pd = await py.import('pandas');
+ * const df = await pd.read_csv('data.csv');  // df is a PyProxy
+ * const rows = await df.describe().to_dict('records');  // chained calls
+ * ```
+ */
+export declare class PyProxy {
+    /** Internal state - do not access directly from outside */
+    readonly [PYPROXY_INTERNAL]: PyProxyInternal;
+    constructor(internal: PyProxyInternal);
+    static readonly handler: ProxyHandler<PyProxy>;
+    private _resolve;
+    callWithOptions(args: unknown[], options?: PyCallOptions, kwargs?: Record<string, unknown>): Promise<unknown>;
+    /** Call this Python function with cancellation or timeout overrides. */
+    withOptions(options: PyCallOptions, ...args: unknown[]): Promise<unknown>;
+    /** Collision-free form of withOptions(). */
+    [PYNECT_WITH_OPTIONS](options: PyCallOptions, ...args: unknown[]): Promise<unknown>;
+    private _call;
+    private _makeAsyncIterator;
+    private _setAttr;
+    static _createFromObjectId(objectId: PyObjectId, path: AttributePath, addon: NativeAddon, callTimeout?: number, executionTimeout?: number): PyProxy;
+    static _deserializeAddonResult(result: unknown, internal: PyProxyInternal): unknown;
+    private static _abortError;
+    private static _withAbort;
+    static _serializeArg(value: unknown): Promise<SerializedValue>;
+    static _getTypedArrayDtype(arr: ArrayBufferView): string;
+    static _isPlainObject(obj: unknown): boolean;
+}
+/**
+ * Check if a value is a PyProxy.
+ */
+export declare function isPyProxy(value: unknown): value is PyProxy;
+//# sourceMappingURL=PyProxy.d.ts.map

package/dist/core/PyProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PyProxy.d.ts","sourceRoot":"","sources":["../../src/core/PyProxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAoB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAQzB,eAAO,MAAM,gBAAgB,eAA4B,CAAC;AAC1D,eAAO,MAAM,gBAAgB,eAA4B,CAAC;AAC1D,eAAO,MAAM,YAAY,eAAwB,CAAC;AAClD,eAAO,MAAM,mBAAmB,eAAmC,CAAC;AAEpE,MAAM,MAAM,cAAc,CACxB,YAAY,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,IACzD,YAAY,GAAG;IACjB,WAAW,CACT,OAAO,EAAE,aAAa,EACtB,GAAG,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,GAChC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC5B,CAAC,mBAAmB,CAAC,CACnB,OAAO,EAAE,aAAa,EACtB,GAAG,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,GAChC,UAAU,CAAC,YAAY,CAAC,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,UAAU,CAAC;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,eAAe,CAAC;gBAEjC,QAAQ,EAAE,eAAe;IAkBrC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,CAiK5C;YAIY,QAAQ;IA8BhB,eAAe,CACnB,IAAI,EAAE,OAAO,EAAE,EACf,OAAO,GAAE,aAAkB,EAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,OAAO,CAAC;IAKnB,wEAAwE;IAClE,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/E,4CAA4C;IACtC,CAAC,mBAAmB,CAAC,CACzB,OAAO,EAAE,aAAa,EACtB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,OAAO,CAAC;YAIL,KAAK;YAwEJ,kBAAkB;YAyEnB,QAAQ;IAetB,MAAM,CAAC,mBAAmB,CACxB,QAAQ,EAAE,UAAU,EACpB,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO;IAUV,MAAM,CAAC,uBAAuB,CAC5B,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,eAAe,GACxB,OAAO;IAqDV,OAAO,CAAC,MAAM,CAAC,WAAW;IAM1B,OAAO,CAAC,MAAM,CAAC,UAAU;WAoCZ,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IA0FpE,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM;IAcxD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;CAK7C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAS1D"}