pynect 0.0.0-stage → 0.2.0

package/dist/core/PyRuntime.d.ts

@@ -0,0 +1,112 @@
+/**
+ * pynect - PyRuntime
+ * The central manager for the Python interpreter lifecycle.
+ * Creates, configures, and shuts down the embedded CPython instance.
+ */
+import type { NativeAddon } from '../types/addon';
+import type { PynectConfig, ResolvedPynectConfig } from '../types/config';
+import { PyModule } from './PyModule';
+import { PyContext } from './PyContext';
+import { type IsolatedCallOptions } from './IsolatedWorker';
+/**
+ * PyRuntime - manages the lifecycle of the embedded Python interpreter.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await PyRuntime.create({
+ * virtualenv: { path: '.venv', packages: ['pandas'], autoInstall: true },
+ * });
+ *
+ * const pd = await runtime.import('pandas');
+ * const df = await pd.read_csv('data.csv');
+ * const result = await df.to_dict('records');
+ *
+ * await runtime.shutdown();
+ * ```
+ */
+export declare class PyRuntime {
+    private readonly _config;
+    private _pythonExecutable;
+    private readonly _pythonLibrary;
+    private readonly _addon;
+    private readonly _pluginManager;
+    private readonly _memoryMonitor;
+    private _isolatedWorker?;
+    private _running;
+    private constructor();
+    /**
+     * Create and initialize a PyRuntime instance.
+     */
+    static create(config?: PynectConfig): Promise<PyRuntime>;
+    private _initialize;
+    private _setupPythonEnvironment;
+    private _bootstrapPythonRuntime;
+    /**
+     * Import a Python module and return a PyProxy.
+     *
+     * @example
+     * ```typescript
+     * const pd = await runtime.import('pandas');
+     * const df = await pd.read_csv('data.csv');
+     * ```
+     */
+    import(moduleName: string): Promise<PyModule>;
+    /**
+     * Import multiple modules at once (concurrent).
+     */
+    importAll(moduleNames: string[]): Promise<Record<string, PyModule>>;
+    /**
+     * Call a JSON-compatible Python function in a killable child process.
+     * This is a process boundary, not an operating-system sandbox.
+     */
+    callIsolated<T = unknown>(moduleName: string, functionName: string, args?: unknown[], options?: IsolatedCallOptions): Promise<T>;
+    /**
+     * Evaluate a Python expression.
+     */
+    eval(expression: string): Promise<unknown>;
+    /**
+     * Execute Python statements.
+     */
+    exec(code: string): Promise<void>;
+    /**
+     * Run a Python script file.
+     */
+    runFile(filePath: string): Promise<unknown>;
+    /**
+     * Create an isolated Python execution context.
+     */
+    createContext(): Promise<PyContext>;
+    /**
+     * Install Python packages into the active environment.
+     */
+    installPackages(packages: string[]): Promise<void>;
+    /**
+     * Get current memory statistics.
+     */
+    getMemoryStats(): ReturnType<NativeAddon['getMemoryStats']>;
+    /**
+     * Trigger Python garbage collection.
+     */
+    collectGarbage(): Promise<void>;
+    /**
+     * Get the underlying native addon.
+     * Advanced use only.
+     */
+    getAddon(): NativeAddon;
+    isRunning(): boolean;
+    getConfig(): ResolvedPynectConfig;
+    /**
+     * Gracefully shut down the Python runtime.
+     * Releases all Python objects and finalizes the interpreter.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Synchronous shutdown (for process.on('exit') handler).
+     * Best-effort only - may not complete all cleanup.
+     */
+    shutdownSync(): void;
+    private _ensureRunning;
+    private _ensureUnsafeCodeAllowed;
+    private _parseBytes;
+}
+//# sourceMappingURL=PyRuntime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PyRuntime.d.ts","sourceRoot":"","sources":["../../src/core/PyRuntime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG1E,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAsB5E;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,eAAe,CAAC,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO;IAgBP;;OAEG;WACU,MAAM,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,SAAS,CAAC;YAuKpD,WAAW;YA2DX,uBAAuB;YAMvB,uBAAuB;IAkCrC;;;;;;;;OAQG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IA2CnD;;OAEG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAOzE;;;OAGG;IACG,YAAY,CAAC,CAAC,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE,OAAO,EAAO,EACpB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,CAAC,CAAC;IAUb;;OAEG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4ChD;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvC;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BjD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,SAAS,CAAC;IAQzC;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBxD;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAK3D;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrC;;;OAGG;IACH,QAAQ,IAAI,WAAW;IAOvB,SAAS,IAAI,OAAO;IAIpB,SAAS,IAAI,oBAAoB;IAMjC;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB/B;;;OAGG;IACH,YAAY,IAAI,IAAI;IAYpB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,WAAW;CAUpB"}

package/dist/core/PyRuntime.js

@@ -0,0 +1,546 @@
+"use strict";
+/**
+ * pynect - PyRuntime
+ * The central manager for the Python interpreter lifecycle.
+ * Creates, configures, and shuts down the embedded CPython instance.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyRuntime = void 0;
+const path_1 = __importDefault(require("path"));
+const project_1 = require("../config/project");
+const config_1 = require("../types/config");
+const PyProxy_1 = require("./PyProxy");
+const PyModule_1 = require("./PyModule");
+const PyContext_1 = require("./PyContext");
+const IsolatedWorker_1 = require("./IsolatedWorker");
+const PluginManager_1 = require("../plugins/PluginManager");
+const PackageInstaller_1 = require("../env/PackageInstaller");
+const PyfigAdapter_1 = require("../env/PyfigAdapter");
+const ProjectEnvironment_1 = require("../env/ProjectEnvironment");
+const NativeAddonLoader_1 = require("../native/NativeAddonLoader");
+const MemoryMonitor_1 = require("../utils/MemoryMonitor");
+const Logger_1 = require("../utils/Logger");
+const ErrorTranslator_1 = require("../utils/ErrorTranslator");
+const logger = new Logger_1.Logger('PyRuntime');
+/**
+ * PyRuntime - manages the lifecycle of the embedded Python interpreter.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await PyRuntime.create({
+ * virtualenv: { path: '.venv', packages: ['pandas'], autoInstall: true },
+ * });
+ *
+ * const pd = await runtime.import('pandas');
+ * const df = await pd.read_csv('data.csv');
+ * const result = await df.to_dict('records');
+ *
+ * await runtime.shutdown();
+ * ```
+ */
+class PyRuntime {
+    _config;
+    _pythonExecutable;
+    _pythonLibrary;
+    _addon;
+    _pluginManager;
+    _memoryMonitor;
+    _isolatedWorker;
+    _running = false;
+    constructor(config, addon, pythonLibrary) {
+        this._config = config;
+        this._pythonExecutable = config.pythonExecutable;
+        this._pythonLibrary = pythonLibrary;
+        this._addon = addon;
+        this._pluginManager = new PluginManager_1.PluginManager();
+        this._memoryMonitor = new MemoryMonitor_1.MemoryMonitor({
+            gcThreshold: this._parseBytes(config.gcThreshold),
+        });
+        this._memoryMonitor.attach(addon);
+    }
+    /**
+     * Create and initialize a PyRuntime instance.
+     */
+    static async create(config = {}) {
+        const project = (0, project_1.resolveProjectConfig)({
+            projectRoot: config.projectRoot,
+            python: config.python ?? config.pythonPath,
+            requiresPython: config.requiresPython,
+            managedPython: config.managedPython,
+            uvVersion: config.uvVersion,
+            installPython: config.installPython ?? config.autoInstallPython,
+            installUv: config.installUv ?? config.autoInstallUv,
+            createVirtualEnvironment: config.createVirtualEnvironment ?? config.autoCreateVirtualEnvironment,
+            autoSync: config.autoSync,
+            lockfile: config.lockfile,
+            env: config.env,
+        });
+        const plan = (0, ProjectEnvironment_1.createProjectPlan)({
+            projectRoot: project.projectRoot,
+            python: project.python,
+            requiresPython: project.requiresPython,
+            managedPython: project.managedPython,
+            uvVersion: project.uvVersion,
+            installPython: project.installPython,
+            installUv: project.installUv,
+            createVirtualEnvironment: project.createVirtualEnvironment,
+            autoSync: project.autoSync,
+            lockfile: project.lockfile,
+            env: project.env,
+        });
+        let environmentState;
+        if ((0, ProjectEnvironment_1.requiresProjectSync)(plan)) {
+            if (project.autoSync === 'if-missing') {
+                try {
+                    environmentState = (0, ProjectEnvironment_1.validateProjectEnvironment)(plan);
+                }
+                catch {
+                    environmentState = (await (0, ProjectEnvironment_1.syncProject)({
+                        projectRoot: project.projectRoot,
+                        python: project.python,
+                        requiresPython: project.requiresPython,
+                        managedPython: project.managedPython,
+                        uvVersion: project.uvVersion,
+                        installPython: project.installPython,
+                        installUv: project.installUv,
+                        createVirtualEnvironment: project.createVirtualEnvironment,
+                        lockfile: project.lockfile,
+                        env: project.env,
+                    })).state;
+                }
+            }
+            else {
+                environmentState = (0, ProjectEnvironment_1.validateProjectEnvironment)(plan);
+            }
+        }
+        if (config.virtualenv?.autoInstall && (config.virtualenv.packages?.length ?? 0) > 0) {
+            throw new Error('virtualenv.autoInstall is no longer supported. Declare Python dependencies in the ' +
+                'root package.json pynect.requirements field and run "pynect sync".');
+        }
+        // Resolve Python before loading the native addon. On Windows the addon
+        // depends on the selected Python DLL, so its directory must already be on
+        // PATH when Node loads the .node file.
+        const { python: selected } = await (0, PyfigAdapter_1.ensurePynectPython)({
+            autoInstallPython: project.installPython,
+            autoInstallUv: project.installUv,
+            autoCreateVirtualEnvironment: project.createVirtualEnvironment,
+            managedPython: project.managedPython,
+            uvVersion: project.uvVersion,
+            pythonRange: plan.pythonRange,
+            pythonPath: project.python,
+            projectRoot: project.projectRoot,
+            env: project.env,
+        });
+        if (environmentState) {
+            const selectedAbi = `${selected.implementation}-${selected.version}-` +
+                `${selected.architecture}-${selected.pointerBits}`;
+            if (!pathsEqual(environmentState.pythonExecutable, selected.executable) ||
+                environmentState.pythonAbi !== selectedAbi) {
+                throw new Error('Pynect environment Python changed since the last sync. Run "pynect sync" before ' +
+                    'starting the application.');
+            }
+        }
+        const selectedProjectRoot = selected.virtualEnvironment
+            ? path_1.default.dirname(selected.virtualEnvironment)
+            : config.projectRoot ?? process.cwd();
+        if (config.virtualenv?.path) {
+            const configuredVenv = path_1.default.resolve(config.virtualenv.path);
+            if (!selected.virtualEnvironment || !pathsEqual(configuredVenv, selected.virtualEnvironment)) {
+                throw new Error(`virtualenv.path must resolve to the repository .venv at ${selected.virtualEnvironment}.`);
+            }
+        }
+        const preparedConfig = {
+            ...config,
+            python: selected.executable,
+            requiresPython: plan.pythonRange,
+            projectRoot: selectedProjectRoot,
+            installPython: project.installPython,
+            installUv: project.installUv,
+            createVirtualEnvironment: project.createVirtualEnvironment,
+            managedPython: project.managedPython,
+            uvVersion: project.uvVersion,
+            autoSync: project.autoSync,
+            lockfile: project.lockfile,
+            env: project.env,
+            dispatcher: {
+                ...config.dispatcher,
+                include: [
+                    ...(config.dispatcher?.include ?? []),
+                    ...(0, ProjectEnvironment_1.moduleDispatcherIncludes)(plan),
+                ],
+            },
+        };
+        if (process.platform === 'win32') {
+            const requiredDirectories = [
+                selected.basePrefix,
+                selected.embedding.libraryDirectory,
+                path_1.default.dirname(selected.executable),
+            ];
+            const entries = (process.env['PATH'] ?? '').split(path_1.default.delimiter);
+            for (const directory of requiredDirectories.reverse()) {
+                if (!entries.some((entry) => entry.toLowerCase() === directory.toLowerCase())) {
+                    process.env['PATH'] = `${directory}${path_1.default.delimiter}${process.env['PATH'] ?? ''}`;
+                }
+            }
+        }
+        const resolved = (0, config_1.resolveConfig)(preparedConfig);
+        // Set log level
+        Logger_1.Logger.setGlobalLevel(resolved.logLevel);
+        logger.info('Creating PyRuntime...');
+        // Load the native addon
+        let addon;
+        try {
+            addon = (0, NativeAddonLoader_1.loadOrBuildNativeAddon)({
+                projectRoot: selectedProjectRoot,
+                pythonExecutable: selected.executable,
+            });
+            logger.debug('Native addon loaded');
+        }
+        catch (err) {
+            logger.error('Failed to load the Pynect native addon.', err);
+            throw new Error('Pynect native addon could not be loaded or built by the active JavaScript runtime.\n' +
+                `Original error: ${err.message}`);
+        }
+        const runtime = new PyRuntime(resolved, addon, selected.embedding.libraryPath);
+        try {
+            await runtime._initialize();
+            return runtime;
+        }
+        catch (error) {
+            if (addon.isInitialized()) {
+                await addon.finalizePython().catch(() => undefined);
+            }
+            throw error;
+        }
+    }
+    // Initialization
+    async _initialize() {
+        const startTime = performance.now();
+        // 1. Detect/setup Python environment
+        const pythonExecutable = await this._setupPythonEnvironment();
+        this._pythonExecutable = pythonExecutable;
+        if (this._config.isolation.enabled) {
+            const packagedPython = path_1.default.join(__dirname, '..', '..', 'python');
+            this._isolatedWorker = new IsolatedWorker_1.IsolatedWorker({
+                pythonExecutable,
+                projectRoot: this._config.projectRoot,
+                scriptPath: path_1.default.join(packagedPython, 'isolated_worker.py'),
+                cwd: this._config.isolation.cwd,
+                timeout: this._config.isolation.timeout,
+                env: this._config.env,
+                pythonPath: [packagedPython, ...this._config.pythonPathExtra],
+                dispatcher: this._config.dispatcher,
+                includeTracebacks: this._config.includeTracebacks,
+            });
+        }
+        // 2. Initialize Python interpreter via C++ addon
+        logger.debug(`Initializing Python interpreter: ${pythonExecutable}`);
+        await this._addon.initializePython({
+            pythonHome: this._config.pythonHome || '',
+            pythonExecutable,
+            pythonLibrary: this._pythonLibrary,
+            threadPoolSize: this._config.threadPoolSize,
+            maxQueueSize: this._config.maxQueueSize,
+            gilReleaseInterval: this._config.gil.releaseInterval,
+            callTimeout: this._config.callTimeout,
+            pythonPathExtra: [
+                path_1.default.join(__dirname, '..', '..', 'python'),
+                ...this._config.pythonPathExtra,
+            ],
+            env: this._config.env,
+            enableProfiling: this._config.profilingEnabled,
+            includeTracebacks: this._config.includeTracebacks,
+        });
+        logger.debug('Python interpreter initialized');
+        // 3. Bootstrap Python runtime helpers
+        await this._bootstrapPythonRuntime();
+        // 4. Register built-in plugins
+        await this._pluginManager.registerBuiltins();
+        // 5. Start memory monitoring
+        this._memoryMonitor.startMonitoring(10000);
+        this._running = true;
+        const elapsed = (performance.now() - startTime).toFixed(0);
+        logger.success(`PyRuntime ready in ${elapsed}ms (Python: ${pythonExecutable})`);
+    }
+    async _setupPythonEnvironment() {
+        const pythonExecutable = this._config.pythonExecutable;
+        logger.info(`Using repository virtualenv: ${path_1.default.dirname(path_1.default.dirname(pythonExecutable))}`);
+        return pythonExecutable;
+    }
+    async _bootstrapPythonRuntime() {
+        try {
+            const dispatcherConfig = Buffer.from(JSON.stringify(this._config.dispatcher), 'utf8').toString('base64');
+            // Initialize pynect Python runtime helpers
+            const bootstrapCode = `
+# Initialize optional upstream helpers. The packaged Python directory is
+# already inserted into sys.path by the native initialization options.
+try:
+    import pynect_runtime
+    pynect_runtime.initialize()
+except ImportError:
+    pass  # Runtime helpers not available, basic operation only
+
+import base64 as _pynect_base64
+import json as _pynect_json
+import pynect_dispatcher
+pynect_dispatcher.configure(
+    _pynect_json.loads(_pynect_base64.b64decode('${dispatcherConfig}'))
+)
+`;
+            await this._addon.runPythonCode(bootstrapCode);
+            logger.debug('Python runtime helpers bootstrapped');
+        }
+        catch (err) {
+            logger.error('Failed to bootstrap the Python dispatcher', err);
+            throw err;
+        }
+    }
+    // Module Import
+    /**
+     * Import a Python module and return a PyProxy.
+     *
+     * @example
+     * ```typescript
+     * const pd = await runtime.import('pandas');
+     * const df = await pd.read_csv('data.csv');
+     * ```
+     */
+    async import(moduleName) {
+        this._ensureRunning();
+        logger.debug(`Importing Python module: ${moduleName}`);
+        const result = await this._addon.importModule(moduleName);
+        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 import Python module '${moduleName}'`);
+        }
+        if (!result.objectId) {
+            throw new Error(`Module '${moduleName}' imported but no object ID returned`);
+        }
+        // Run plugin hooks
+        await this._pluginManager.onModuleImported(moduleName, result.objectId);
+        // Create PyModule
+        const module = PyModule_1.PyModule.fromRef(result.objectId, moduleName, this._addon, this._config.callTimeout, this._config.executionTimeout);
+        logger.debug(`Module '${moduleName}' imported (id=${result.objectId})`);
+        return module;
+    }
+    /**
+     * Import multiple modules at once (concurrent).
+     */
+    async importAll(moduleNames) {
+        const modules = await Promise.all(moduleNames.map(async (name) => [name, await this.import(name)]));
+        return Object.fromEntries(modules);
+    }
+    /**
+     * Call a JSON-compatible Python function in a killable child process.
+     * This is a process boundary, not an operating-system sandbox.
+     */
+    async callIsolated(moduleName, functionName, args = [], options = {}) {
+        this._ensureRunning();
+        if (!this._isolatedWorker) {
+            throw new Error('Isolated calls are disabled; initialize with isolation.enabled: true.');
+        }
+        return this._isolatedWorker.call(moduleName, functionName, args, options);
+    }
+    // Code Execution
+    /**
+     * Evaluate a Python expression.
+     */
+    async eval(expression) {
+        this._ensureRunning();
+        this._ensureUnsafeCodeAllowed('eval');
+        const result = await this._addon.evalPython(expression);
+        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('Python eval failed');
+        }
+        if (result.isObject && result.objectId) {
+            return PyProxy_1.PyProxy._createFromObjectId(result.objectId, [], this._addon, this._config.callTimeout, this._config.executionTimeout);
+        }
+        if (result.resultJson !== undefined) {
+            try {
+                return JSON.parse(result.resultJson);
+            }
+            catch {
+                return result.resultJson;
+            }
+        }
+        return null;
+    }
+    /**
+     * Execute Python statements.
+     */
+    async exec(code) {
+        this._ensureRunning();
+        this._ensureUnsafeCodeAllowed('exec');
+        const result = await this._addon.runPythonCode(code);
+        if (!result.success && result.error) {
+            throw (0, ErrorTranslator_1.translatePythonError)({
+                type: result.error.type,
+                message: result.error.message,
+                traceback: result.error.traceback || '',
+            });
+        }
+    }
+    /**
+     * Run a Python script file.
+     */
+    async runFile(filePath) {
+        this._ensureRunning();
+        this._ensureUnsafeCodeAllowed('runFile');
+        const result = await this._addon.runPythonFile(filePath);
+        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 run Python file');
+        }
+        return null;
+    }
+    // Context Management
+    /**
+     * Create an isolated Python execution context.
+     */
+    async createContext() {
+        this._ensureRunning();
+        this._ensureUnsafeCodeAllowed('createContext');
+        return PyContext_1.PyContext.create(this._addon);
+    }
+    // Package Management
+    /**
+     * Install Python packages into the active environment.
+     */
+    async installPackages(packages) {
+        this._ensureRunning();
+        if (!this._config.allowPackageInstall) {
+            throw new Error('Runtime package installation is disabled; set allowPackageInstall: true.');
+        }
+        const installer = new PackageInstaller_1.PackageInstaller({
+            pythonExecutable: this._pythonExecutable,
+            cwd: this._config.projectRoot,
+        });
+        await installer.install(packages);
+    }
+    // Memory Management
+    /**
+     * Get current memory statistics.
+     */
+    getMemoryStats() {
+        this._ensureRunning();
+        return this._addon.getMemoryStats();
+    }
+    /**
+     * Trigger Python garbage collection.
+     */
+    async collectGarbage() {
+        this._ensureRunning();
+        await this._addon.collectGarbage();
+    }
+    // Direct Addon Access
+    /**
+     * Get the underlying native addon.
+     * Advanced use only.
+     */
+    getAddon() {
+        this._ensureUnsafeCodeAllowed('getAddon');
+        return this._addon;
+    }
+    // State
+    isRunning() {
+        return this._running;
+    }
+    getConfig() {
+        return { ...this._config };
+    }
+    // Shutdown
+    /**
+     * Gracefully shut down the Python runtime.
+     * Releases all Python objects and finalizes the interpreter.
+     */
+    async shutdown() {
+        if (!this._running) {
+            return;
+        }
+        logger.info('Shutting down PyRuntime...');
+        // Stop memory monitoring
+        this._memoryMonitor.stopMonitoring();
+        await this._isolatedWorker?.close();
+        this._isolatedWorker = undefined;
+        // Finalize Python interpreter
+        try {
+            await this._addon.runPythonCode('import pynect_dispatcher as _d; _d.shutdown()');
+            await this._addon.finalizePython();
+            this._running = false;
+            logger.success('PyRuntime shut down');
+        }
+        catch (err) {
+            logger.error('Error during Python finalization', err);
+            throw err;
+        }
+    }
+    /**
+     * Synchronous shutdown (for process.on('exit') handler).
+     * Best-effort only - may not complete all cleanup.
+     */
+    shutdownSync() {
+        if (!this._running) {
+            return;
+        }
+        this._running = false;
+        this._memoryMonitor.stopMonitoring();
+        this._isolatedWorker?.closeSync();
+        this._isolatedWorker = undefined;
+        // Cannot await here - best effort
+        logger.debug('Synchronous shutdown initiated');
+    }
+    // Private Helpers
+    _ensureRunning() {
+        if (!this._running) {
+            throw new ErrorTranslator_1.PynectShutdownError('PyRuntime has been shut down. Create a new runtime with PyRuntime.create().');
+        }
+    }
+    _ensureUnsafeCodeAllowed(operation) {
+        if (!this._config.allowUnsafeCode) {
+            throw new Error(`${operation} is disabled by default; set allowUnsafeCode: true for trusted local code.`);
+        }
+    }
+    _parseBytes(str) {
+        const match = str.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB|TB)?$/i);
+        if (!match) {
+            return 1_073_741_824;
+        }
+        const value = parseFloat(match[1]);
+        const unit = (match[2] ?? 'B').toUpperCase();
+        const units = {
+            B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3, TB: 1024 ** 4,
+        };
+        return Math.floor(value * (units[unit] ?? 1));
+    }
+}
+exports.PyRuntime = PyRuntime;
+function pathsEqual(left, right) {
+    const normalize = (value) => {
+        const resolved = path_1.default.resolve(value);
+        return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    };
+    return normalize(left) === normalize(right);
+}
+//# sourceMappingURL=PyRuntime.js.map