obix-binding-python

Previous name: @obinexusltd/obix-binding-python — OBIX packages are named without an npm scope since decision D-102 (2026-09-29); the package, its version and its exports are unchanged.

OBIX Python Binding — ML/AI integration and data science workflows. Connects the native FFI/polyglot bridge to the Python runtime.

Installation

npm install obix-binding-python

Quick Start

import { createPythonBinding } from 'obix-binding-python';

const binding = createPythonBinding({
  ffiPath: '/path/to/libnativebridge.so',
  pythonPath: '/usr/bin/python3',
  schemaMode: 'hybrid',
  memoryModel: 'gc',
});

await binding.initialize();

const result = await binding.invoke('my_python_function', [1, 2, 3]);

await binding.destroy();

Architecture

The binding is composed of six sub-modules, each accessible as a readonly property on the bridge:

| Module | Property | Description | |---|---|---| | FFI Transport | ffiTransport | Envelope building, function ID normalization, ABI dispatch | | GC Tracker | gcTracker | Python generational garbage collector simulation (gen0/gen1/gen2) | | GIL Manager | gilManager | Global Interpreter Lock state and contention tracking | | Asyncio Executor | asyncioExecutor | asyncio-like cooperative FIFO task executor | | Module Registry | moduleRegistry | Python module/package registration and lifecycle | | Schema Resolver | schemaResolver | Schema mode resolution with ctypes/cffi/numpy properties |

Configuration

interface PythonBindingConfig {
  ffiPath: string;            // Path to native FFI library (required)
  pythonPath: string;         // Path to Python interpreter (required)
  schemaMode: SchemaMode;     // 'monoglot' | 'polyglot' | 'hybrid' (required)
  memoryModel: 'gc' | 'manual' | 'hybrid'; // Memory management strategy (required)
  virtualEnv?: string;        // Virtual environment path
  pythonVersion?: string;     // Python version string
  numpyInterop?: boolean;     // Enable numpy array interop
  pandasInterop?: boolean;    // Enable pandas DataFrame interop
  torchInterop?: boolean;     // Enable PyTorch tensor interop
  tensorflowInterop?: boolean; // Enable TensorFlow interop
  executorPoolSize?: number;  // Asyncio executor concurrency (default: 4)
  gcCollectCyclesInterval?: number; // GC cycle collection interval
}

Schema Modes

| Mode | ctypes | cffi | numpy | Multi-language | |---|---|---|---|---| | monoglot | Yes | No | No | No | | polyglot | Yes | Yes | Yes | Yes | | hybrid | Yes | Yes | No | Yes |

Sub-module Usage

GC Tracker

const { gcTracker } = binding;

gcTracker.recordRef();           // Track reference creation
gcTracker.recordDeref();         // Track reference release
gcTracker.collectGeneration(0);  // Collect youngest generation
gcTracker.collectAll();          // Full collection cycle
gcTracker.snapshot();            // Get current GC stats

GIL Manager

const { gilManager } = binding;

gilManager.acquire();   // Acquire the GIL
gilManager.release();   // Release the GIL
gilManager.getState();  // 'held' | 'released'
gilManager.getStats();  // { acquireCount, releaseCount, contentionCount, currentState }

Asyncio Executor

const { asyncioExecutor } = binding;

const result = await asyncioExecutor.submit('task-1', 'async_fn', [arg1]);
const stats = asyncioExecutor.getStats(); // { activeTasks, queuedTasks, completedTasks }
await asyncioExecutor.drain();            // Wait for all tasks to complete

Module Registry

const { moduleRegistry } = binding;

moduleRegistry.register('numpy', '1.26.0', '/usr/lib/python3/numpy');
moduleRegistry.get('numpy');      // { name, version, path, loaded }
moduleRegistry.listLoaded();      // All currently loaded modules
moduleRegistry.unload('numpy');   // Mark module as unloaded

Development

npm run build   # Compile TypeScript
npm run test    # Run test suite

Documentation

In-depth guides live in docs/:

| # | Guide | |---|-------| | 01 | Overview | | 02 | Installation and Setup | | 03 | Binding Lifecycle and Configuration | | 04 | FFI Transport and the ABI Boundary | | 05 | Schema Modes | | 06 | Runtime Features | | 07 | Best Practices |

License

MIT

Installation

npm install obix-binding-python

API surface

• obix-binding-python — 8 value exports: createAsyncioExecutor, createFFITransport, createGCTracker, createGILManager, createModuleRegistry, createPythonBinding, createSchemaResolver, normalizeFunctionIdentifier
• Type declarations: ./dist/index.d.ts (and a declaration next to every JS entry point).

Architecture role

obix-binding-python is a binding: it connects OBIX to another syntax, paradigm or language.

The architecture of OBIX — the package families and which packages are public API — is indexed in the umbrella: docs/architecture.md.

Package relationships

• Depends on (OBIX): no other OBIX package.
• Used by (OBIX): no other OBIX package.

Testing

• 7 test files ship in the npm package (__tests__/): the evidence of the package's contract, published so that its verification can be inspected — not runtime code (no entry point reaches them).
• Standalone: 7 of 7 — they read nothing outside the package.
• Run them with npm test (vitest run) in the OBIX monorepo, which provides the test tooling (Node's test runner, Vitest, TypeScript) and the harness.

Documentation

• docs/01-overview.md
• docs/02-installation-and-setup.md
• docs/03-binding-lifecycle.md
• docs/04-ffi-transport-and-abi.md
• docs/05-schema-modes.md
• docs/06-runtime-features.md
• docs/07-best-practices.md
• CHANGELOG.md
• The OBIX architecture index: obix/docs/architecture.md

Repository

• https://github.com/obinexus/obix-binding-python — [email protected]:obinexus/obix-binding-python.git
• Issues: https://github.com/obinexus/obix-binding-python/issues
• The repository is a clean export of the package from the OBIX monorepo. Its lineage — the sources it was recovered from and its earlier names — is PROVENANCE.json, shipped in this package; the repository's copy also records the monorepo commit it was exported from.

License

MIT — see LICENSE.