Python & Electron SDKs
Relevant source files
The following files were used as context for generating this wiki page:
The Python and Electron SDKs provide desktop-class bindings for the RunAnywhere on-device AI runtime. These SDKs bridge high-level application code to a shared C++ core (runanywhere-commons) that implements AI business logic behind a pure C ABI. Both SDKs support capabilities including Large Language Models (LLM), Vision Language Models (VLM), Speech-to-Text (STT), and Text-to-Speech (TTS) running entirely on the host machine.
Sources: bindings/python/AGENTS.md:10-18, bindings/electron/AGENTS.md:7-11, AGENTS.md:53-62
Architecture and Design
Both SDKs follow a tiered architecture where the language-specific layer acts as a thin facade. The Python SDK uses a pybind11 extension while the Electron SDK utilizes a Node-API (N-API) native addon.
Cross-Language Architectural Parity
The SDKs maintain behavioral parity by mirroring the C++ core's semantics. The Python native module is a port of the Electron addon, ensuring consistent handle maps, leases, and streaming behavior across both platforms.
This diagram shows the high-level request flow from application code through the language facades and native bridges into the shared C++ core.
Sources: bindings/python/AGENTS.md:14-18, bindings/electron/AGENTS.md:7-11, AGENTS.md:83-88
Python SDK Structure
The Python SDK utilizes a lazy-load design to ensure the package remains importable even without a native build. Importing runanywhere does not load the compiled _core extension until initialize() is called.
| Component | Path | Description |
|---|---|---|
| Public API | runanywhere/api/ | One module per namespace (llm, vlm, stt, etc.) |
| Runtime | runanywhere/_runtime.py | Manages native lifecycle and resident models |
| Native Bridge | runanywhere/_native/ | Lazy loader for the compiled _core extension |
| Core Stub | runanywhere/_native/_core.pyi | Type stubs mirroring the pybind11 surface |
Sources: bindings/python/AGENTS.md:103-125
Electron SDK Structure
Electron isolation requirements dictate that the native addon runs in an isolated utility process. Communication between the renderer and the utility host occurs via a MessagePort.
This sequence represents the Electron-specific process isolation where the Main process brokers communication between the Renderer and the Native Utility Host.
Sources: bindings/electron/README.md:9-11, 74-78, bindings/electron/example/README.md:65-72
Native Bridging and Safety
Both SDKs implement strict safety measures to manage native resource lifecycles and prevent memory errors.
- Lease Management: Generate, embed, and transcribe paths take
begin_opleases. This prevents Use-After-Free (UAF) errors if an unload occurs during an active generation. - Idle Handling: Unload paths use
take_handle_when_idleto ensure operations complete safely before cleaning up handles. - Stream Adaptation: The SDKs turn blocking native callbacks into language-idiomatic iterators (Python
async foror JSAsyncIterable).
Sources: bindings/electron/AGENTS.md:88-90, bindings/python/AGENTS.md:13-18, 153-155
Platform Support and Requirements
The SDKs target modern desktop environments with specific prebuilt availability.
Prebuilt Availability Table
| Platform | Architecture | Backends Supported |
|---|---|---|
| macOS | darwin-arm64 | LlamaCPP, ONNX, Sherpa |
| Windows | win32-x64 | LlamaCPP, ONNX, Sherpa |
| Windows | win32-arm64 | QHexRT (Qualcomm Hexagon NPU) |
| Linux | N/A | Build from source |
Sources: bindings/electron/AGENTS.md:66-72, bindings/electron/README.md:11-13
OS-Specific Adapters
Native adapters handle platform-specific services like file systems and secure storage.
- Windows: Uses DPAPI for encrypted secure storage via
win32_platform_adapter. - POSIX: Uses plaintext 0600 file permissions for secure storage via
posix_platform_adapter. - HTTP: The Electron SDK uses a bundled
libcurltransport for Phase 2 authentication and telemetry.
Sources: bindings/python/AGENTS.md:52-56, bindings/electron/AGENTS.md:79, 107-110
Development and Verification
Python Verification
The Python suite is pure Python and uses a FakeCore for testing, allowing the suite to run without a native build.
pytest tests: Runs the whole suite.pip install -e .: Installs in editable mode for development.
Sources: bindings/python/AGENTS.md:38-50
Electron Verification
Verification is driven through TypeScript type-checking and unit tests.
npm run build: Compiles TypeScript todist/.npm run typecheck: Performs strict type-checking across all projects (src, test, scripts).npm test: Runs Node.js tests over the compiled outputs.
Sources: bindings/electron/AGENTS.md:43-50
Conclusion
The Python and Electron SDKs provide a consistent, high-performance interface for on-device AI. By delegating all heavy lifting to the C++ core and maintaining architectural parity, the SDKs ensure that AI logic remains robust and identical across different desktop integration environments.