pynect 0.0.0 → 0.2.1

package/dist/plugins/plugin-manager.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * pynect - PluginManager
+ *
+ * Manages registration, lifecycle, and dispatch of pynect plugins.
+ * PyRuntime holds a single PluginManager instance.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginManager = void 0;
+const logger_1 = require("../utils/logger");
+const logger = new logger_1.Logger('PluginManager');
+class PluginManager {
+    _plugins = new Map();
+    _typeMap = new Map();
+    _moduleMap = new Map();
+    // Registration
+    register(plugin) {
+        if (this._plugins.has(plugin.name)) {
+            logger.debug(`Plugin already registered: ${plugin.name}; skipping`);
+            return this;
+        }
+        const entry = {
+            plugin,
+            active: false,
+            loadedAt: Date.now(),
+            modulesBound: new Set(),
+        };
+        this._plugins.set(plugin.name, entry);
+        for (const typeName of plugin.handledTypes ?? []) {
+            const handlers = this._typeMap.get(typeName) ?? [];
+            if (plugin.transformResult) {
+                handlers.push(plugin.transformResult.bind(plugin));
+            }
+            this._typeMap.set(typeName, handlers);
+        }
+        for (const mod of plugin.supportedModules) {
+            const list = this._moduleMap.get(mod) ?? [];
+            list.push(plugin);
+            this._moduleMap.set(mod, list);
+        }
+        logger.debug(`Registered plugin: ${plugin.name} v${plugin.version}`);
+        return this;
+    }
+    async registerBuiltins() {
+        const [{ PandasPlugin }, { NumpyPlugin }, { TorchPlugin }] = await Promise.all([
+            Promise.resolve().then(() => __importStar(require('./builtin/pandas-plugin'))),
+            Promise.resolve().then(() => __importStar(require('./builtin/numpy-plugin'))),
+            Promise.resolve().then(() => __importStar(require('./builtin/torch-plugin'))),
+        ]);
+        this.register(new PandasPlugin());
+        this.register(new NumpyPlugin());
+        this.register(new TorchPlugin());
+    }
+    // Lifecycle
+    async initAll(ctx) {
+        const extCtx = {
+            ...ctx,
+            registerTypeHandler: (typeName, handler) => {
+                const handlers = this._typeMap.get(typeName) ?? [];
+                handlers.push(handler);
+                this._typeMap.set(typeName, handlers);
+            },
+        };
+        for (const [name, entry] of this._plugins) {
+            try {
+                await entry.plugin.onInit?.(extCtx);
+                entry.active = true;
+                logger.debug(`Initialised plugin: ${name}`);
+            }
+            catch (err) {
+                logger.warn(`Plugin ${name} init failed (non-fatal): ${err}`);
+            }
+        }
+    }
+    async shutdownAll() {
+        for (const [name, entry] of this._plugins) {
+            if (!entry.active) {
+                continue;
+            }
+            try {
+                await entry.plugin.onShutdown?.();
+                entry.active = false;
+            }
+            catch (err) {
+                logger.warn(`Plugin ${name} shutdown error (non-fatal): ${err}`);
+            }
+        }
+    }
+    async onModuleImported(moduleName, moduleOid) {
+        const plugins = this._moduleMap.get(moduleName) ?? [];
+        for (const plugin of plugins) {
+            try {
+                await plugin.onModuleImported?.(moduleName, moduleOid);
+            }
+            catch (err) {
+                logger.warn(`Plugin ${plugin.name} onModuleImported error: ${err}`);
+            }
+        }
+    }
+    // Transform chain
+    transformResult(value, typeName, metadata = {}) {
+        const handlers = this._typeMap.get(typeName) ?? [];
+        for (const handler of handlers) {
+            try {
+                const result = handler(value, typeName, metadata);
+                if (result !== null) {
+                    return result;
+                }
+            }
+            catch (err) {
+                logger.warn(`Type transform error for ${typeName}: ${err}`);
+            }
+        }
+        return null;
+    }
+    serializeValue(value, targetTypeName) {
+        for (const [, entry] of this._plugins) {
+            if (!entry.active || !entry.plugin.serializeValue) {
+                continue;
+            }
+            try {
+                const result = entry.plugin.serializeValue(value, targetTypeName);
+                if (result !== null) {
+                    return result;
+                }
+            }
+            catch (err) {
+                logger.warn(`Plugin serialize error: ${err}`);
+            }
+        }
+        return null;
+    }
+    // Introspection
+    get names() { return [...this._plugins.keys()]; }
+    getPlugin(name) { return this._plugins.get(name); }
+    get active() { return [...this._plugins.values()].filter((e) => e.active); }
+    get all() { return [...this._plugins.values()]; }
+    isActive(name) { return this._plugins.get(name)?.active === true; }
+}
+exports.PluginManager = PluginManager;
+//# sourceMappingURL=plugin-manager.js.map

package/dist/plugins/plugin-manager.js.map

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

package/dist/plugins/plugin.interface.d.ts

@@ -0,0 +1,41 @@
+/**
+ * pynect - Plugin Interface
+ *
+ * Every pynect plugin must implement this interface. Plugins can:
+ * - Transform Python object values as they cross the JS boundary
+ * - Register custom type mappings
+ * - Hook into lifecycle events (init, shutdown)
+ * - Add convenience methods to PyProxy instances
+ */
+import type { SerializedValue } from '../types/python';
+export type PythonTypeName = string;
+export interface PluginInitContext {
+    runtimeVersion: string;
+    pythonVersion: {
+        major: number;
+        minor: number;
+        patch: number;
+    };
+    registerTypeHandler(typeName: PythonTypeName, handler: TypeTransformHandler): void;
+}
+export type TypeTransformHandler = (raw: SerializedValue, typeHint: string, metadata: Record<string, unknown>) => unknown | null;
+export interface PynectPlugin {
+    readonly name: string;
+    readonly version: string;
+    readonly supportedModules: readonly string[];
+    readonly handledTypes?: readonly PythonTypeName[];
+    readonly description?: string;
+    readonly homepage?: string;
+    onInit?(ctx: PluginInitContext): Promise<void> | void;
+    onShutdown?(): Promise<void> | void;
+    onModuleImported?(moduleName: string, moduleOid: number): Promise<void> | void;
+    transformResult?: TypeTransformHandler;
+    serializeValue?(value: unknown, targetTypeName?: string): SerializedValue | null;
+}
+export interface PluginRegistration {
+    plugin: PynectPlugin;
+    active: boolean;
+    loadedAt: number;
+    modulesBound: Set<string>;
+}
+//# sourceMappingURL=plugin.interface.d.ts.map

package/dist/plugins/plugin.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.interface.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIvD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACpF;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,GAAG,EAAO,eAAe,EACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,GAAG,IAAI,CAAC;AAEpB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAc,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAW,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAK,SAAS,cAAc,EAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAM,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAS,MAAM,CAAC;IAElC,MAAM,CAAC,CAAC,GAAG,EAAE,iBAAiB,GAAwB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,IAA2C,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,gBAAgB,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAE/E,eAAe,CAAC,EAAE,oBAAoB,CAAC;IACvC,cAAc,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;CAClF;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAQ,YAAY,CAAC;IAC3B,MAAM,EAAQ,OAAO,CAAC;IACtB,QAAQ,EAAM,MAAM,CAAC;IACrB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B"}

package/dist/plugins/plugin.interface.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * pynect - Plugin Interface
+ *
+ * Every pynect plugin must implement this interface. Plugins can:
+ * - Transform Python object values as they cross the JS boundary
+ * - Register custom type mappings
+ * - Hook into lifecycle events (init, shutdown)
+ * - Add convenience methods to PyProxy instances
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=plugin.interface.js.map

package/dist/plugins/plugin.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.interface.js","sourceRoot":"","sources":["../../src/plugins/plugin.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}

package/dist/serialization/data-frame-bridge.d.ts

@@ -0,0 +1,141 @@
+/**
+ * pynect - DataFrameBridge
+ * Converts Pandas DataFrames and Series to/from JavaScript objects.
+ *
+ * Wire Protocol
+ *
+ * DataFrames use the "split" orientation of pandas JSON:
+ * {
+ * "columns": ["col1", "col2", ...],
+ * "data":    [[row0_val0, row0_val1], [row1_val0, row1_val1], ...],
+ * "index":   [0, 1, 2, ...],
+ * "dtypes":  {"col1": "int64", "col2": "object", ...},
+ * "shape":   [nrows, ncols]
+ * }
+ *
+ * For large DataFrames (>64KB) the JSON is embedded in a MessagePack
+ * binary to reduce parse overhead.  The format field in SerializedValue
+ * tells the bridge which path to take:
+ * format === 'pandas_dataframe'  -> DataFrame decode
+ * format === 'pandas_series'     -> Series decode
+ *
+ * Series wire format:
+ * {
+ * "name":   "my_series",
+ * "data":   [1, 2, 3, 4],
+ * "index":  [0, 1, 2, 3],
+ * "dtype":  "int64",
+ * "length": 4
+ * }
+ *
+ * JavaScript representation
+ *
+ * DataFrameResult (records orientation is built client-side):
+ * {
+ * columns: string[],
+ * data:    Record<string, unknown>[],   <- row objects
+ * index:   unknown[],
+ * dtypes:  Record<string, string>,
+ * shape:   [number, number]
+ * }
+ *
+ * SeriesResult:
+ * {
+ * name:   string,
+ * data:   unknown[],
+ * index:  unknown[],
+ * dtype:  string,
+ * length: number
+ * }
+ */
+import type { SerializedValue, DataFrameResult, SeriesResult } from '../types/python';
+interface DataFrameSerializeOptions {
+    /**
+     * Row limit when serializing JS -> Python.
+     * Excess rows are truncated.  Default: unlimited.
+     */
+    maxRows?: number;
+    /**
+     * Use MessagePack instead of JSON for the wire format.
+     * Default: true when data size > 64 KB.
+     */
+    forceMsgPack?: boolean;
+}
+/**
+ * DataFrameBridge - bidirectional conversion for Pandas DataFrames and Series.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new DataFrameBridge();
+ *
+ * // Deserialize a DataFrame received from Python
+ * const df: DataFrameResult = bridge.deserializeDataFrame(sv);
+ * console.log(df.columns);   // ['city', 'population']
+ * console.log(df.data[0]);   // { city: 'Algiers', population: 3500000 }
+ *
+ * // Serialize a records-array back to Python
+ * const sv2 = bridge.serializeDataFrame(df.data, df.columns);
+ * ```
+ */
+export declare class DataFrameBridge {
+    /**
+     * Deserialize a PANDAS_DATAFRAME SerializedValue -> DataFrameResult.
+     */
+    deserializeDataFrame(sv: SerializedValue): DataFrameResult;
+    /**
+     * Deserialize a PANDAS_SERIES SerializedValue -> SeriesResult.
+     */
+    deserializeSeries(sv: SerializedValue): SeriesResult;
+    /**
+     * Serialize a records-array (array of row objects) into a PANDAS_DATAFRAME
+     * SerializedValue that Python can reconstruct with pd.DataFrame(wire).
+     *
+     * @param records - array of row objects (e.g. [{col1: val1, col2: val2}, ...])
+     * @param columns - explicit column order; inferred from first record if omitted
+     */
+    serializeDataFrame(records: Record<string, unknown>[], columns?: string[], options?: DataFrameSerializeOptions): SerializedValue;
+    /**
+     * Serialize a plain array of values into a PANDAS_SERIES SerializedValue.
+     *
+     * @param data  - the series values
+     * @param name  - series name
+     * @param index - optional explicit index
+     */
+    serializeSeries(data: unknown[], name?: string, index?: unknown[]): SerializedValue;
+    /**
+     * Convert a DataFrameResult to a 2-D array (column-major).
+     * Useful for charting libraries.
+     */
+    static toColumnArrays(df: DataFrameResult): Record<string, unknown[]>;
+    /**
+     * Convert a DataFrameResult to a 2-D raw array (no column keys).
+     * Row-major: result[row][colIndex].
+     */
+    static toMatrix(df: DataFrameResult): unknown[][];
+    /**
+     * Filter rows of a DataFrameResult.
+     */
+    static filterRows(df: DataFrameResult, predicate: (row: Record<string, unknown>, index: unknown) => boolean): DataFrameResult;
+    /**
+     * Select specific columns from a DataFrameResult.
+     */
+    static selectColumns(df: DataFrameResult, cols: string[]): DataFrameResult;
+    /**
+     * Compute basic descriptive stats for a numeric column in a DataFrameResult.
+     */
+    static describeColumn(df: DataFrameResult, col: string): {
+        count: number;
+        mean: number;
+        std: number;
+        min: number;
+        max: number;
+        sum: number;
+    };
+    private _decodeWire;
+    private _encodeWire;
+    private _buildDataFrameResult;
+    private _buildSeriesResult;
+    private _inferDtype;
+}
+export {};
+//# sourceMappingURL=data-frame-bridge.d.ts.map

package/dist/serialization/data-frame-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-frame-bridge.d.ts","sourceRoot":"","sources":["../../src/serialization/data-frame-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAGH,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EACf,YAAY,EACb,MAAM,iBAAiB,CAAC;AAyBzB,UAAU,yBAAyB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAe;IAI1B;;OAEG;IACH,oBAAoB,CAAC,EAAE,EAAE,eAAe,GAAG,eAAe;IAU1D;;OAEG;IACH,iBAAiB,CAAC,EAAE,EAAE,eAAe,GAAG,YAAY;IAYpD;;;;;;OAMG;IACH,kBAAkB,CAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAClC,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,OAAO,GAAE,yBAA8B,GACtC,eAAe;IAiBlB;;;;;;OAMG;IACH,eAAe,CACb,IAAI,EAAE,OAAO,EAAE,EACf,IAAI,GAAE,MAAW,EACjB,KAAK,CAAC,EAAE,OAAO,EAAE,GAChB,eAAe;IAclB;;;OAGG;IACH,MAAM,CAAC,cAAc,CACnB,EAAE,EAAE,eAAe,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IAQ5B;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,EAAE,EAAE;IAIjD;;OAEG;IACH,MAAM,CAAC,UAAU,CACf,EAAE,EAAE,eAAe,EACnB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,GACnE,eAAe;IAsBlB;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe;IAa1E;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG;QACvD,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;KACb;IAoBD,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,qBAAqB;IA2B7B,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,WAAW;CAYpB"}