Complete API Reference
ClusterNode, GuardProxy, and MemoryPool — Python & Node.js ESM
ClusterNode (symmetric master/worker binary)
| Method | Signature | Returns | Description |
ClusterNode.__init__ | (role: str = 'auto', port: int = 29500, memory_budget_mb: int = 0, auth_secret: str = '', guard_band_mb: int = 300) | — | role is 'master', 'worker', or 'auto' (auto-detects based on whether a master is reachable). memory_budget_mb = 0 means use all available LPDDR minus guard_band_mb. |
.start | () → None | — | Binds the TCP listener (master) or connects to the master (worker) and begins memory-pool registration. |
.stop | () → None | — | Gracefully deregisters from the pool and closes all TCP connections. |
.get_status | () → dict | {"role": str, "pool_mb": int, "workers": int, "failover_active": bool} | Returns current pool state. failover_active is True when at least one worker has disconnected and UFS flash mmap streaming is active. |
.read_tensor | (offset_mb: float, size_mb: float) → bytes | bytes | Fetches a contiguous tensor shard from the disaggregated memory pool. Transparently falls over to local flash if the responsible worker is offline. |
ClusterConfig
| Field | Type | Default | Description |
role | str | 'auto' | Node role: 'master' | 'worker' | 'auto'. |
port | int | 29500 | TCP port for master–worker communication. |
memory_budget_mb | int | 0 | Maximum LPDDR to donate. 0 = all available minus guard-band. |
guard_band_mb | int | 300 | Reserved memory headroom to prevent Android LMK kills on the worker node. |
auth_secret | str | '' | Shared HMAC-SHA256 secret for GuardProxy authentication. Empty string disables auth (development only). |
failover_path | str | '/data/data/com.termux/files/home/cluster_swap' | Local UFS path used for flash-backed storage-assisted failover when a worker disconnects. |
GuardProxy
| Method | Signature | Returns | Description |
GuardProxy.__init__ | (secret: str, fail_fast_ms: float = 1.0) | — | Creates an HMAC-SHA256 guard proxy. Connections failing verification within fail_fast_ms are rejected immediately. |
.verify | (token: str, payload: bytes) → bool | bool | Verifies an incoming HMAC token against the payload. Returns False on mismatch; does not raise. |
.sign | (payload: bytes) → str | str | Produces an HMAC-SHA256 hex token for an outgoing payload. |