nodepyx 1.0.0

package/src/plugins/PluginManager.ts

@@ -0,0 +1,155 @@
+/**
+ * nodepyx — PluginManager
+ *
+ * Manages registration, lifecycle, and dispatch of nodepyx plugins.
+ * PyRuntime holds a single PluginManager instance.
+ */
+
+import { Logger } from '../utils/Logger';
+import type {
+  nodepyxPlugin,
+  PluginRegistration,
+  PluginInitContext,
+  TypeTransformHandler,
+  PythonTypeName,
+} from './Plugin.interface';
+import type { SerializedValue } from '../types/python';
+
+const logger = new Logger('PluginManager');
+
+export class PluginManager {
+  private readonly _plugins   = new Map<string, PluginRegistration>();
+  private readonly _typeMap   = new Map<PythonTypeName, TypeTransformHandler[]>();
+  private readonly _moduleMap = new Map<string, nodepyxPlugin[]>();
+
+  // ── Registration ────────────────────────────────────────────────────────────
+
+  register(plugin: nodepyxPlugin): this {
+    if (this._plugins.has(plugin.name)) {
+      logger.debug(`Plugin already registered: ${plugin.name} — skipping`);
+      return this;
+    }
+
+    const entry: PluginRegistration = {
+      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(): Promise<void> {
+    const [{ PandasPlugin }, { NumpyPlugin }, { TorchPlugin }] = await Promise.all([
+      import('./builtin/PandasPlugin'),
+      import('./builtin/NumpyPlugin'),
+      import('./builtin/TorchPlugin'),
+    ]);
+    this.register(new PandasPlugin());
+    this.register(new NumpyPlugin());
+    this.register(new TorchPlugin());
+  }
+
+  // ── Lifecycle ────────────────────────────────────────────────────────────────
+
+  async initAll(ctx: PluginInitContext): Promise<void> {
+    const extCtx: PluginInitContext = {
+      ...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(): Promise<void> {
+    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: string, moduleOid: number): Promise<void> {
+    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:    SerializedValue,
+    typeName: string,
+    metadata: Record<string, unknown> = {}
+  ): unknown | null {
+    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: unknown, targetTypeName?: string): SerializedValue | null {
+    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(): string[] { return [...this._plugins.keys()]; }
+  getPlugin(name: string): PluginRegistration | undefined { return this._plugins.get(name); }
+  get active(): PluginRegistration[] { return [...this._plugins.values()].filter((e) => e.active); }
+  get all(): PluginRegistration[] { return [...this._plugins.values()]; }
+  isActive(name: string): boolean { return this._plugins.get(name)?.active === true; }
+}
+

package/src/plugins/builtin/NumpyPlugin.ts

@@ -0,0 +1,36 @@
+/**
+ * nodepyx — NumpyPlugin (built-in)
+ * Routes ndarray wire objects through NumpyBridge.
+ */
+
+import type { nodepyxPlugin, PluginInitContext } from '../Plugin.interface';
+import type { SerializedValue, NumPyArrayResult } from '../../types/python';
+import { NumpyBridge } from '../../serialization/NumpyBridge';
+import { Logger } from '../../utils/Logger';
+
+const logger = new Logger('NumpyPlugin');
+const bridge = new NumpyBridge();
+
+export class NumpyPlugin implements nodepyxPlugin {
+  readonly name             = 'numpy';
+  readonly version          = '1.0.0';
+  readonly description      = 'Enhanced NumPy ndarray → TypedArray mapping';
+  readonly supportedModules = ['numpy', 'np'] as const;
+  readonly handledTypes     = ['ndarray', 'matrix', 'MaskedArray'] as const;
+
+  onInit(ctx: PluginInitContext): void {
+    for (const t of this.handledTypes) {ctx.registerTypeHandler(t, this._handle.bind(this));}
+    logger.debug('NumpyPlugin initialised');
+  }
+
+  transformResult(raw: SerializedValue, typeHint: string): NumPyArrayResult | null {
+    if ((this.handledTypes as readonly string[]).includes(typeHint)) {return this._handle(raw, typeHint, {});}
+    return null;
+  }
+
+  private _handle(raw: SerializedValue, _type?: string, _meta?: Record<string, unknown>): NumPyArrayResult | null {
+    try { return bridge.deserialize(raw); }
+    catch (err) { logger.warn(`ndarray deserialization error: ${err}`); return null; }
+  }
+}
+

package/src/plugins/builtin/PandasPlugin.ts

@@ -0,0 +1,49 @@
+/**
+ * nodepyx — PandasPlugin (built-in)
+ * Intercepts DataFrame/Series wire objects and routes through DataFrameBridge.
+ */
+
+import type { nodepyxPlugin, PluginInitContext } from '../Plugin.interface';
+import type { SerializedValue, DataFrameResult, SeriesResult } from '../../types/python';
+import { DataFrameBridge } from '../../serialization/DataFrameBridge';
+import { Logger } from '../../utils/Logger';
+
+const logger = new Logger('PandasPlugin');
+const bridge = new DataFrameBridge();
+
+export class PandasPlugin implements nodepyxPlugin {
+  readonly name             = 'pandas';
+  readonly version          = '1.0.0';
+  readonly description      = 'Enhanced pandas DataFrame and Series support';
+  readonly supportedModules = ['pandas', 'pd'] as const;
+  readonly handledTypes     = ['DataFrame', 'Series', 'DataFrameGroupBy', 'SeriesGroupBy'] as const;
+
+  onInit(ctx: PluginInitContext): void {
+    ctx.registerTypeHandler('DataFrame',        this._handleDF.bind(this));
+    ctx.registerTypeHandler('DataFrameGroupBy', this._handleDF.bind(this));
+    ctx.registerTypeHandler('Series',           this._handleSeries.bind(this));
+    ctx.registerTypeHandler('SeriesGroupBy',    this._handleSeries.bind(this));
+    logger.debug('PandasPlugin initialised');
+  }
+
+  onModuleImported(moduleName: string): void {
+    logger.debug(`pandas module imported: ${moduleName}`);
+  }
+
+  transformResult(raw: SerializedValue, typeHint: string): DataFrameResult | SeriesResult | null {
+    if (typeHint === 'DataFrame' || typeHint === 'DataFrameGroupBy') {return this._handleDF(raw, typeHint, {});}
+    if (typeHint === 'Series'   || typeHint === 'SeriesGroupBy')    {return this._handleSeries(raw, typeHint, {});}
+    return null;
+  }
+
+  private _handleDF(raw: SerializedValue, _typeHint?: string, _meta?: Record<string, unknown>): DataFrameResult | null {
+    try { return bridge.deserializeDataFrame(raw); }
+    catch (err) { logger.warn(`DataFrame deserialization error: ${err}`); return null; }
+  }
+
+  private _handleSeries(raw: SerializedValue, _typeHint?: string, _meta?: Record<string, unknown>): SeriesResult | null {
+    try { return bridge.deserializeSeries(raw); }
+    catch (err) { logger.warn(`Series deserialization error: ${err}`); return null; }
+  }
+}
+

package/src/plugins/builtin/TorchPlugin.ts

@@ -0,0 +1,56 @@
+/**
+ * nodepyx — TorchPlugin (built-in)
+ * Handles PyTorch Tensor objects — delegates to NumpyBridge (tensors are NumPy-compatible).
+ */
+
+import type { nodepyxPlugin, PluginInitContext } from '../Plugin.interface';
+import type { SerializedValue, NumPyArrayResult } from '../../types/python';
+import { NumpyBridge } from '../../serialization/NumpyBridge';
+import { Logger } from '../../utils/Logger';
+
+const logger = new Logger('TorchPlugin');
+const bridge = new NumpyBridge();
+
+export type TensorResult = NumPyArrayResult & {
+  requiresGrad: boolean;
+  isCuda:       boolean;
+  device:       string;
+  gradFn:       string | null;
+}
+
+export class TorchPlugin implements nodepyxPlugin {
+  readonly name             = 'torch';
+  readonly version          = '1.0.0';
+  readonly description      = 'Enhanced PyTorch Tensor support';
+  readonly supportedModules = ['torch'] as const;
+  readonly handledTypes     = ['Tensor'] as const;
+
+  onInit(ctx: PluginInitContext): void {
+    ctx.registerTypeHandler('Tensor', this._handle.bind(this));
+    logger.debug('TorchPlugin initialised');
+  }
+
+  transformResult(raw: SerializedValue, typeHint: string, meta: Record<string, unknown>): TensorResult | null {
+    return typeHint === 'Tensor' ? this._handle(raw, typeHint, meta) : null;
+  }
+
+  private _handle(raw: SerializedValue, _t?: string, meta?: Record<string, unknown>): TensorResult | null {
+    try {
+      const base = bridge.deserialize(raw);
+      if (!base) {return null;}
+      const isCuda = Boolean(meta?.['isCuda']);
+      if (isCuda) {logger.warn('CUDA Tensor: data was copied to CPU for transfer.');}
+      return {
+        ...base,
+        requiresGrad: Boolean(meta?.['requiresGrad']),
+        isCuda,
+        device:  String(meta?.['device'] ?? 'cpu'),
+        gradFn:  meta?.['gradFn'] !== null && meta?.['gradFn'] !== undefined ? String(meta?.['gradFn']) : null,
+      } as TensorResult;
+    } catch (err) {
+      logger.warn(`Tensor deserialization error: ${err}`);
+      return null;
+    }
+  }
+}
+

package/src/plugins/index.ts

@@ -0,0 +1,7 @@
+export type { nodepyxPlugin, PluginRegistration, PluginInitContext, TypeTransformHandler, PythonTypeName } from './Plugin.interface';
+export { PluginManager } from './PluginManager';
+export { PandasPlugin } from './builtin/PandasPlugin';
+export { NumpyPlugin }  from './builtin/NumpyPlugin';
+export { TorchPlugin }  from './builtin/TorchPlugin';
+export type { TensorResult } from './builtin/TorchPlugin';
+