Metadata-Version: 2.4
Name: superbrain-sdk
Version: 0.1.1
Summary: Premium Python SDK for Superbrain Distributed Memory Fabric
Author: Anispy
Author-email: Anispy <anispy211@gmail.com>
Project-URL: Homepage, https://github.com/anispy211/superbrainSdk
Project-URL: Bug Tracker, https://github.com/anispy211/superbrainSdk/issues
Keywords: distributed,memory,ai,agents,grpc
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author

# Superbrain Python SDK

[![PyPI version](https://img.shields.io/pypi/v/superbrain-sdk.svg)](https://pypi.org/project/superbrain-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Superbrain** is a high-performance, distributed RAM fabric designed specifically for AI agents. It allows agents to share gigabytes of context and data at microsecond speeds using a **Zero-Blob Architecture**.

Instead of passing massive data blobs over JSON or gRPC, agents pass 36-byte memory pointers, allowing multiple agents to read from the same distributed RAM pool without network overhead.

## 🚀 Key Features

- **Zero-Blob Architecture**: Pass data by pointer, not by value.
- **Microsecond Latency**: Distributed RAM speeds for inter-agent communication.
- **Secure Fabric**: Enterprise-grade mTLS identity and AES-GCM-256 end-to-end encryption.
- **Natively Fast**: Powered by a high-performance C-bridge.

## 🛠️ Installation

```bash
pip install superbrain-sdk
```

> [!IMPORTANT]
> This SDK requires the `libsuperbrain` shared library. Download it from the [GitHub Releases](https://github.com/anispy211/superbrainSdk/releases) and ensure it's in your `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH`.

## 💻 Quick Start (Python)

```python
from superbrain import Client

# 1. Initialize the client
client = Client('localhost:50050')

# 2. Allocate a 10MB memory segment
ptr_id = client.allocate(10 * 1024 * 1024)
print(f"Allocated pointer: {ptr_id}")

# 3. Write data to the fabric
data = b"Hello from Python Agent!"
client.write(ptr_id, 0, data)

# 4. Read data back (or from another agent)
read_data = client.read(ptr_id, 0, len(data))
print(f"Read: {read_data.decode('utf-8')}")

# 5. Free memory
client.free(ptr_id)
```

## 🔒 Secure Fabric (E2EE)

```python
encryption_key = b"your-32-byte-aes-encryption-key-"
client = Client('localhost:60050', encryption_key=encryption_key)

# Data is now automatically encrypted before leaving the agent!
```

## 📄 Documentation

For full API reference, visit the [Comprehensive Consumption Guide](https://github.com/anispy211/superbrainSdk/blob/main/DOCUMENTATION.md).

## ⚖️ License

MIT License. See [LICENSE](https://github.com/anispy211/superbrainSdk/blob/main/LICENSE) for more details.
