Metadata-Version: 2.4
Name: latzero
Version: 0.2.0
Summary: Zero-latency, zero-fuss shared memory for Python — dynamic, encrypted, and insanely fast.
Home-page: https://github.com/Latency-Zero/python-client
Author: BRAHMAI
Author-email: BRAHMAI <hello@brahmai.in>
License: MIT
Project-URL: Homepage, https://github.com/Latency-Zero/python-client
Project-URL: Documentation, https://github.com/Latency-Zero/python-client#readme
Project-URL: Repository, https://github.com/Latency-Zero/python-client.git
Project-URL: Issues, https://github.com/Latency-Zero/python-client/issues
Keywords: ipc,shared-memory,inter-process-communication,memory,cache,fast,zero-latency,encryption
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=3.4
Requires-Dist: psutil>=5.8
Provides-Extra: fast
Requires-Dist: msgpack>=1.0; extra == "fast"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# latzero

**Zero-latency, zero-fuss shared memory for Python — dynamic, encrypted, and insanely fast.**

🚀 **170,000+ ops/sec** | ⚡ **0.006ms latency** | 🔒 **AES-256 encryption**

## Overview

**latzero** is a Python package designed to make inter-process communication (IPC) and shared-memory data exchange effortless. Unlike traditional shared memory systems that require fixed buffer sizes and manual serialization, latzero enables developers to:

- Create dynamic shared-memory pools accessible by multiple processes or clients
- Pass any pickleable object directly — no manual encoding/decoding
- Enable optional encryption and authentication for secure multi-process collaboration

latzero is ideal for AI workloads, distributed systems, and low-latency microservices that need real-time shared state management.

## Core Features

**Dynamic Shared Memory Pools**  
No predefined memory size. Pools expand and contract dynamically as new data arrives.

**Multi-Client Access**  
Multiple processes/clients can connect to the same pool simultaneously and share data in real time.

**Auto Cleanup**  
Data can have optional timeouts (`auto_clean=5`), automatically clearing entries after specified seconds.

**Encryption & Authentication**  
Pools can be protected with passwords. If `encryption=True`, the password becomes the encryption key.

**Data-Type Preservation**  
Stored data retains its type (`int`, `str`, `dict`, etc.) across clients.

**High-Performance Batched Writes**  
Use `set_fast()` + `flush()` for 77,000+ writes/sec. Standard `set()` syncs immediately.

**Self-Destructing Pools**  
Pools live only as long as one or more connected processes are active. When all disconnect, the pool is automatically destroyed.

**Pickle + msgpack Serialization**  
Any pickleable Python object can be stored. Use msgpack for 3-5x faster serialization.

**Event Hooks**  
Hooks for client events: `on_connect`, `on_disconnect`, `on_update`, `on_delete`.

**Async Support**  
Full async/await API with `AsyncSharedMemoryPool`.

**CLI Tool**  
Manage pools from command line: `latzero list`, `latzero inspect`, etc.

## Installation

```bash
pip install latzero
```

## Quick Start

### Creating a Pool

```python
from latzero import SharedMemoryPool

pool_manager = SharedMemoryPool()
pool_manager.create(
    name="myPool",
    auth=True,
    auth_key="super_secret",
    encryption=True
)
```

### Connecting to a Pool

```python
ipc = pool_manager.connect(
    name="myPool",
    auth_key="super_secret"
)
```

### Basic Operations

```python
# Set values with optional auto-cleanup
ipc.set("key", value, auto_clean=5)

# Retrieve values
result = ipc.get("key")
```

### Type-Safe Example

```python
ipc.set("number", 42)
ipc.set("text", "yo bro")
ipc.set("data", {"a": 1, "b": 2})

print(ipc.get("number"))  # 42 (int)
print(ipc.get("text"))    # "yo bro" (str)
print(ipc.get("data"))    # {"a": 1, "b": 2} (dict)
```

### High-Performance Batched Writes

```python
with pool_manager.connect("myPool", auth_key="super_secret") as client:
    # Use set_fast() for batched writes (100x faster)
    for i in range(1000):
        client.set_fast(f"key_{i}", {"value": i})
    
    # Flush to persist all writes
    client.flush()
    
    # Reads are always instant
    print(client.get("key_0"))  # {'value': 0}
```

## System Architecture

### Core Components

**Memory Controller**  
Manages shared memory segments dynamically.

**Pool Registry**  
Tracks all active pools via metadata.

**Encryption Layer**  
AES-GCM encryption for secure reads/writes.

**Data Layer (Pickle Serializer)**  
Automatic serialization with zlib compression.

**IPC Protocol**  
Uses `multiprocessing.shared_memory` for communication.

**Auto-Reclaim Daemon**  
Monitors idle pools and clears them when unused.

## Security Model

| Concern             | Mechanism                                                             |
|---------------------|-----------------------------------------------------------------------|
| Unauthorized access | Password-based authentication                                         |
| Data leakage        | AES-256 encryption when `encryption=True`                             |
| Data tampering      | Integrity checked using HMAC                                          |
| Memory persistence  | Pools are ephemeral; memory is released after last client disconnects |

## Performance

| Operation | Throughput | Latency |
|-----------|------------|--------|
| `set_fast()` (batched) | **77,000+ ops/sec** | ~0.01ms |
| `get()` | **287,000+ ops/sec** | ~0.003ms |
| `set()` (immediate sync) | 600 ops/sec | ~1.6ms |
| Mixed workload | **146,000+ ops/sec** | ~0.007ms |

### vs Other Methods

| Method | Throughput | Speedup |
|--------|------------|----------|
| **latzero** | **170,000 ops/sec** | — |
| Raw Socket | 5,277 ops/sec | 32x faster |
| HTTP (Flask) | 133 ops/sec | 1,280x faster |

## Examples

Check the `examples/` directory for usage demos:

- `simple_pool.py` - Basic pool operations
- `encrypted_pool.py` - Secure pool with encryption
- `multi_client_demo.py` - Concurrent multi-client access

## Dependencies

- `multiprocessing.shared_memory`
- `cryptography` (for AES)
- `pickle`, `zlib`
- `threading`, `multiprocessing`
- `psutil` (for process detection)

## Roadmap

**Phase 1:** Core shared memory pools + pickle serialization  
**Phase 2:** Auth + encryption  
**Phase 3:** Dynamic memory expansion + auto-clean  
**Phase 4:** Performance optimization + PyPI release  
**Phase 5:** Real-time event hooks, WebSocket bridges

## Use Cases

- AI agents sharing memory
- Game servers syncing states
- Local caching for microservices
- High-speed analytics pipelines
- Multi-agent orchestration systems

## About

latzero makes shared-memory IPC as easy as Redis, without the network overhead. Fast, simple, encrypted, ephemeral — a zero-latency memory layer for Python developers.

**Created by BRAHMAI**  
https://brahmai.in
