superbrain-distributed-sdk 0.2.1 → 0.7.2

package/README.md

@@ -1,4 +1,4 @@
-# 🧠 superbrain-distributed-sdk v0.2.0 — TypeScript/Node.js
+# 🧠 superbrain-distributed-sdk v0.7.2 — TypeScript/Node.js
 
 [![npm version](https://badge.fury.io/js/superbrain-distributed-sdk.svg)](https://badge.fury.io/js/superbrain-distributed-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -16,17 +16,12 @@ npm install superbrain-distributed-sdk
 
 ---
 
-## ✨ New in v0.2.0 — Phase 3: Automated AI Memory Controller
+## ✨ New in v0.7.1 — Tiered Architecture & Zero-Copy SHM
+Version 0.7.1 introduces the ability to operate as a microsecond-latency **L1 Shared Memory Tier** for agent architectures.
 
-Version 0.2.0 introduces the Phase 3 **Automated AI Memory Controller** — a self-managing, intelligent memory fabric where multiple LLMs running on different machines share context instantly at RAM speed.
-
-### Key Phase 3 Features:
-- **Auto-Discovery**: Zero-config cluster formation via mDNS
-- **KV Cache Pooling**: Identical prefixes shared across models automatically
-- **Smart Prefetching**: Markov-chain access pattern prediction
-- **Self-Tuning Allocator**: Learns from access history to pre-allocate
-- **Anomaly Detection**: Z-score alerting for unusual access patterns
-- **Live Dashboard**: Real-time metrics at `http://localhost:9090`
+- **Coordinator Bypass**: Metadata is cached locally, eliminating the gRPC hop to the Coordinator for established pointers.
+- **Zero-Copy SHM**: When the SDK detects a co-located Memory Node (`127.0.0.1`), it seamlessly switches from gRPC streaming to direct `/dev/shm` memory-mapped file access.
+- **13.5µs Native Latency**: The Native Go core bypass achieves microsecond speed, bypassing the network entirely for local agents.
 
 ---
 
@@ -112,6 +107,44 @@ The Coordinator is ONLY in the control path (allocate + free).
 
 ---
 
+## 🧹 Memory Management
+
+> **The Node.js SDK exposes the raw client layer — `free()` is always required after `allocate()`.**
+
+```typescript
+// ✅ Always do this after you are done with a pointer
+const ptr = await client.allocate(100 * 1024 * 1024);
+await client.write(ptr, 0, data);
+const result = await client.read(ptr, 0, 0);
+await client.free(ptr);   // ← required — leaks memory if skipped
+```
+
+### 🐍 Want Managed Memory? Use the Python SDK
+
+The Python SDK (`pip install superbrain-sdk`) provides higher-level APIs where **free() is never needed**:
+
+| Python API | Free needed? | What it does |
+|------------|:------------:|--------------|
+| `SharedContext.write("key", data)` | ❌ No | Key-based shared state across agents |
+| `fabric.store_kv_cache(prefix)` | ❌ No | Deduped prompt cache, auto-evicted |
+| `SuperBrainMemory` (LangChain) | ❌ No | Chat history in distributed RAM |
+
+```python
+# Python — no free() ever needed with high-level APIs
+from superbrain import DistributedContextFabric
+
+fabric = DistributedContextFabric(coordinator="localhost:50050")
+ctx = fabric.create_context("session-42")
+
+ctx.write("state", {"step": 10})   # written to distributed RAM
+ctx.read("state")                  # read from any machine
+# No free() ✅
+```
+
+→ [Full Memory Management Guide](https://github.com/anispy211/superbrainSdk/blob/main/DOCUMENTATION.md#memory-management--when-to-free)
+
+---
+
 ## 🔐 Security Features
 
 | Feature | Status |
@@ -131,10 +164,14 @@ The Coordinator is ONLY in the control path (allocate + free).
 |---------|-----------|--------|
 | `v0.1.0` | Core Distributed RAM | ✅ Shipped |
 | `v0.1.1` | Secure Fabric (mTLS + E2EE) | ✅ Shipped |
-| `v0.2.0` | **Phase 3: Automated AI Memory Controller** | ✅ **Current** |
-| `v0.3.0` | Raft Replication (Fault-Tolerant Memory) | 🚧 Planned |
-| `v0.4.0` | NVMe Spilling ("Infinite Memory") | 🚧 Planned |
-| `v0.5.0` | GPUDirect RDMA (GPU→Network zero-copy) | 🔬 Research |
+| `v0.2.0` | **Phase 3: Automated AI Memory Controller** | ✅ Shipped |
+| `v0.3.1` | Semantic Memory (FAISS-Backed Distributed Vectors) | ✅ Shipped |
+| `v0.4.0` | Gossip & P2P Membership | ✅ Shipped |
+| `v0.5.0` | High Availability & Partition Tolerance | ✅ Shipped |
+| `v0.6.0` | Decentralized Observability & Metrics | ✅ Shipped |
+| `v0.7.1` | **Tiered Architecture & Zero-Copy SHM Bypass** | ✅ **Current** |
+| `v0.8.0` | Raft Consensus Replication | ✅ Shipped |
+| `v0.9.0` | NVMe Spilling | ✅ Shipped |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbrain-distributed-sdk",
-  "version": "0.2.1",
+  "version": "0.7.2",
   "description": "Premium High-Performance Distributed Memory SDK for AI Agents",
   "main": "index.js",
   "types": "index.d.ts",
@@ -30,6 +30,11 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/*"
+  ],
   "dependencies": {
     "koffi": "^2.15.1"
   },

package/demo.js

@@ -1,29 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const index_1 = require("./index");
-async function main() {
-    console.log("🤖 Node.js Superbrain Agent Demo");
-    try {
-        // We will assume the local cluster is running from earlier commands on port 50050
-        const client = new index_1.Client('localhost:50050');
-        console.log("✅ Custom Client initialized");
-        client.register("typescript-demo-agent");
-        console.log("✅ Agent registered to Secure Fabric");
-        const dataStr = "Hello from Node.js (TypeScript) via Koffi/gRPC!";
-        const dataBytes = Buffer.from(dataStr, 'utf-8');
-        const ptr = client.allocate(dataBytes.length + 128);
-        console.log(`✅ Allocated pointer: ${ptr}`);
-        client.write(ptr, 0, dataBytes);
-        console.log(`✅ Wrote data to pointer`);
-        const readBuf = client.read(ptr, 0, dataBytes.length + 128);
-        // Remove null padding
-        const resultStr = readBuf.toString('utf-8').replace(/\0/g, '');
-        console.log(`✅ Read verified: ${resultStr}`);
-        client.free(ptr);
-        console.log("🧹 Memory freed.");
-    }
-    catch (err) {
-        console.error("Failed to run demo:", err.message);
-    }
-}
-main();

package/demo.ts

@@ -1,37 +0,0 @@
-import { Client, SuperbrainError } from './index';
-
-async function main() {
-    console.log("🤖 Node.js Superbrain Agent Demo");
-
-    try {
-        // We will assume the local cluster is running from earlier commands on port 50050
-        const client = new Client('localhost:50050');
-        console.log("✅ Custom Client initialized");
-
-        client.register("typescript-demo-agent");
-        console.log("✅ Agent registered to Secure Fabric");
-
-        const dataStr = "Hello from Node.js (TypeScript) via Koffi/gRPC!";
-        const dataBytes = Buffer.from(dataStr, 'utf-8');
-
-        const ptr = client.allocate(dataBytes.length + 128);
-        console.log(`✅ Allocated pointer: ${ptr}`);
-
-        client.write(ptr, 0, dataBytes);
-        console.log(`✅ Wrote data to pointer`);
-
-        const readBuf = client.read(ptr, 0, dataBytes.length + 128);
-
-        // Remove null padding
-        const resultStr = readBuf.toString('utf-8').replace(/\0/g, '');
-        console.log(`✅ Read verified: ${resultStr}`);
-
-        client.free(ptr);
-        console.log("🧹 Memory freed.");
-
-    } catch (err: any) {
-        console.error("Failed to run demo:", err.message);
-    }
-}
-
-main();

package/index.ts

@@ -1,118 +0,0 @@
-import koffi from 'koffi';
-import * as os from 'os';
-import * as path from 'path';
-import * as fs from 'fs';
-
-export class SuperbrainError extends Error {
-    constructor(message: string) {
-        super(message);
-        this.name = 'SuperbrainError';
-    }
-}
-
-// Locate shared library
-const libName = os.platform() === 'darwin' ? 'libsuperbrain.dylib' : 'libsuperbrain.so';
-
-// Try finding it correctly in the package or local structure
-let libPath = path.join(__dirname, '..', '..', 'lib', libName);
-if (!fs.existsSync(libPath)) {
-    libPath = path.join(process.cwd(), libName);
-}
-if (!fs.existsSync(libPath)) {
-    libPath = path.join(process.cwd(), '..', 'lib', libName);
-}
-
-if (!fs.existsSync(libPath)) {
-    throw new SuperbrainError(`Shared library ${libName} not found at ${libPath}. Ensure it is built and in the correct path.`);
-}
-
-const lib = koffi.load(libPath);
-
-// C Bindings
-const SB_NewClient = lib.func('SB_NewClient', 'str', ['str']);
-const SB_NewClientWithEncryption = lib.func('SB_NewClientWithEncryption', 'str', ['str', 'uint8_t*', 'int']);
-const SB_Register = lib.func('SB_Register', 'str', ['str', 'str']);
-const SB_Allocate = lib.func('SB_Allocate', 'str', ['str', 'uint64_t']);
-const SB_Write = lib.func('SB_Write', 'str', ['str', 'str', 'uint64_t', 'uint8_t*', 'uint64_t']);
-const SB_Read = lib.func('SB_Read', 'str', ['str', 'str', 'uint64_t', 'uint64_t', '_Out_ uint8_t**', '_Out_ uint64_t*']);
-const SB_Free = lib.func('SB_Free', 'str', ['str', 'str']);
-
-export class Client {
-    private clientId: string;
-
-    constructor(addrs: string, encryptionKey?: Buffer) {
-        let res: string;
-        if (encryptionKey) {
-            if (encryptionKey.length !== 32) {
-                throw new SuperbrainError('Encryption key must be exactly 32 bytes for AES-GCM-256');
-            }
-            res = SB_NewClientWithEncryption(addrs, encryptionKey, encryptionKey.length);
-        } else {
-            res = SB_NewClient(addrs);
-        }
-
-        if (res && res.startsWith('error:')) {
-            throw new SuperbrainError(res);
-        }
-
-        this.clientId = res;
-    }
-
-    public register(agentId: string): void {
-        const res = SB_Register(this.clientId, agentId);
-        if (res && res.startsWith('error:')) {
-            throw new SuperbrainError(res);
-        }
-    }
-
-    public allocate(size: number): string {
-        const res = SB_Allocate(this.clientId, size);
-        if (res && res.startsWith('error:')) {
-            throw new SuperbrainError(res);
-        }
-        return res;
-    }
-
-    public write(ptrId: string, offset: number, data: Buffer): void {
-        const res = SB_Write(this.clientId, ptrId, offset, data, data.length);
-        if (res && res.startsWith('error:')) {
-            throw new SuperbrainError(res);
-        }
-    }
-
-    public read(ptrId: string, offset: number, length: number): Buffer {
-        // Output pointers for koffi
-        const outDataPtr = [null];
-        const outLenPtr = [0];
-
-        const res = SB_Read(this.clientId, ptrId, offset, length, outDataPtr, outLenPtr);
-
-        if (res && res.startsWith('error:')) {
-            throw new SuperbrainError(res);
-        }
-
-        const outBufPtr = outDataPtr[0] as any;
-        const outLen = outLenPtr[0] as number;
-
-        if (!outBufPtr || outLen === 0) {
-            return Buffer.alloc(0);
-        }
-
-        // Decode the C string memory pointer into a Buffer
-        const decodedBuffer = koffi.decode(outBufPtr, 'uint8_t', outLen);
-        const buffer = Buffer.from(decodedBuffer);
-
-        // Note: C-allocated pointer memory leak if we don't C-free, 
-        // but for now Superbrain handles general lifecycle cleanup 
-        // when client exists or pointer freed.
-
-        return buffer;
-    }
-
-    public free(ptrId: string): void {
-        const res = SB_Free(this.clientId, ptrId);
-        if (res && res.startsWith('error:')) {
-            throw new SuperbrainError(res);
-        }
-    }
-}

package/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "es2022",
-    "module": "commonjs",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "resolveJsonModule": true,
-    "types": [
-      "node"
-    ]
-  },
-  "ts-node": {
-    "esm": true
-  }
-}