ramjetio 0.4.0__tar.gz

ramjetio-0.4.0/.gitignore

@@ -0,0 +1,150 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+cache_data/
+*.cache
+*.tmp
+
+# Development and testing scripts (not needed for users)
+quick_start_testing.sh
+test_*.sh
+run_*.sh
+*_test_local.py
+*_local_test.py
+DEPLOYMENT_GUIDE.md
+
+# Build artifacts (regenerated on pip install)
+ramjet.egg-info/

ramjetio-0.4.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-10-22
+
+### Added
+- Initial release of RAMJET distributed cache
+- Consistent hashing implementation for key distribution
+- HTTP-based cache server with disk storage
+- Distributed cache client with retry logic
+- PyTorch integration utilities:
+  - `CachedDataset` for caching dataset items
+  - `CacheCheckpoint` for model checkpoint management
+  - Forward hooks for activation caching
+- Command-line interfaces:
+  - `ramjet-server` for starting cache servers
+  - `ramjet-client` for command-line cache operations
+- Comprehensive test suite
+- Example scripts demonstrating usage
+- Documentation and README
+
+### Features
+- Scalable to N servers with M TB each
+- Automatic node addition/removal with minimal redistribution
+- Optional data compression
+- Configurable replication factor
+- TTL support for cache entries
+- PyTorch tensor serialization
+- Statistics and monitoring endpoints
+
+[Unreleased]: https://github.com/ramjetinc/ramjet/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ramjetinc/ramjet/releases/tag/v0.1.0

ramjetio-0.4.0/LICENSE

@@ -0,0 +1,141 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright NxGen Inc.
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the
+**software** is the software the licensor makes available under
+these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+---
+
+Required Notice: Copyright 2025 NxGen Inc.
+
+---
+
+## Commercial Licensing
+
+For commercial use, please contact jogrms@gmail.com

ramjetio-0.4.0/Makefile

@@ -0,0 +1,89 @@
+.PHONY: help install install-dev test test-cov format lint type-check clean build upload docs run-server run-examples
+
+help:
+	@echo "RAMJET - Distributed Cache for PyTorch Training"
+	@echo ""
+	@echo "Available targets:"
+	@echo "  install        - Install package"
+	@echo "  install-dev    - Install package with dev dependencies"
+	@echo "  test           - Run tests"
+	@echo "  test-cov       - Run tests with coverage"
+	@echo "  format         - Format code with black and isort"
+	@echo "  lint           - Run linters (flake8)"
+	@echo "  type-check     - Run type checker (mypy)"
+	@echo "  clean          - Clean build artifacts"
+	@echo "  build          - Build distribution packages"
+	@echo "  upload         - Upload to PyPI (requires credentials)"
+	@echo "  docs           - Generate documentation"
+	@echo "  run-server     - Start test cache servers (3 nodes)"
+	@echo "  run-examples   - Run all example scripts"
+
+install:
+	pip install -e .
+
+install-dev:
+	pip install -e ".[dev]"
+	pre-commit install
+
+test:
+	pytest tests/
+
+test-cov:
+	pytest --cov=ramjet --cov-report=html --cov-report=term tests/
+
+format:
+	black ramjet tests examples
+	isort ramjet tests examples
+
+lint:
+	flake8 ramjet tests examples --max-line-length=120 --extend-ignore=E203,W503
+
+type-check:
+	mypy ramjet --ignore-missing-imports
+
+clean:
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	rm -rf htmlcov/
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+build: clean
+	python -m build
+
+upload: build
+	python -m twine upload dist/*
+
+docs:
+	@echo "Documentation is in markdown files:"
+	@echo "  - README.md"
+	@echo "  - QUICKSTART.md"
+	@echo "  - INSTALLATION.md"
+	@echo "  - PROJECT_STRUCTURE.md"
+	@echo "  - CONTRIBUTING.md"
+
+run-server:
+	@echo "Starting 3 cache server nodes..."
+	@echo "Node 1: http://localhost:9000"
+	@echo "Node 2: http://localhost:9001"
+	@echo "Node 3: http://localhost:9002"
+	@echo ""
+	@echo "Press Ctrl+C to stop all servers"
+	@trap 'kill 0' SIGINT; \
+	ramjet-server --port 9000 --storage-path /tmp/ramjet_cache_0 --capacity 1GB & \
+	ramjet-server --port 9001 --storage-path /tmp/ramjet_cache_1 --capacity 1GB & \
+	ramjet-server --port 9002 --storage-path /tmp/ramjet_cache_2 --capacity 1GB & \
+	wait
+
+run-examples:
+	@echo "Running basic usage example..."
+	python examples/basic_usage.py
+	@echo ""
+	@echo "Running PyTorch DataLoader example..."
+	python examples/pytorch_dataloader.py
+	@echo ""
+	@echo "Running checkpoint caching example..."
+	python examples/checkpoint_caching.py

ramjetio-0.4.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: ramjetio
+Version: 0.4.0
+Summary: Distributed cache system for PyTorch training
+Author-email: RAMJET <support@ramjet.io>
+License-Expression: LicenseRef-PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://ramjet.io
+Keywords: distributed,cache,pytorch,deep-learning,machine-learning,training
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.9.0
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: grpcio>=1.50.0
+Requires-Dist: grpcio-tools>=1.50.0
+Requires-Dist: protobuf>=4.0.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: pyyaml>=5.4.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: mmh3>=3.0.0
+Requires-Dist: diskcache>=5.4.0
+Requires-Dist: psutil>=5.8.0
+Requires-Dist: boto3>=1.26.0
+Dynamic: license-file
+
+# RAMJET — Distributed Data Cache for PyTorch Training
+
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-1.9+-red.svg)](https://pytorch.org/)
+[![PyPI](https://img.shields.io/pypi/v/ramjetio.svg)](https://pypi.org/project/ramjetio/)
+[![License](https://img.shields.io/badge/License-PolyForm%20NC-green.svg)](LICENSE)
+
+**RAMJET** accelerates PyTorch distributed training by caching preprocessed data across your cluster. Works with any DDP setup — `torchrun`, DeepSpeed, Accelerate, or custom launchers.
+
+## Why RAMJET?
+
+| Problem | Solution |
+|---------|----------|
+| Slow data preprocessing | Cache preprocessed samples across nodes |
+| Network bottleneck from shared storage | Local SSD cache on each node |
+| Repeated data loading across epochs | First epoch caches, next epochs are instant |
+| No visibility into training | Real-time metrics dashboard |
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install ramjetio
+```
+
+### 2. Get API Key
+
+1. Go to [app.ramjet.io](https://app.ramjet.io)
+2. Create a cluster
+3. Copy your API key
+
+### 3. Add to Your Training Script
+
+```python
+import ramjetio
+from torch.utils.data import DataLoader
+
+# Initialize RAMJET (connects to dashboard, starts local cache server)
+ramjetio.init()
+
+# Wrap your dataset
+dataset = ramjetio.CachedDataset(your_dataset)
+
+# Use with DataLoader as usual
+loader = DataLoader(dataset, batch_size=32)
+
+for batch in loader:
+    train_step(batch)
+```
+
+### 4. Run Training
+
+```bash
+export RAMJET_API_KEY="your_api_key_here"
+
+# Works with any launcher
+torchrun --nproc_per_node=2 train.py
+```
+
+That's it! Your nodes will appear in the dashboard within seconds.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Your Training Cluster                    │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
+│  │   Node 0    │    │   Node 1    │    │   Node 2    │     │
+│  │  ┌───────┐  │    │  ┌───────┐  │    │  ┌───────┐  │     │
+│  │  │ Train │  │    │  │ Train │  │    │  │ Train │  │     │
+│  │  └───┬───┘  │    │  └───┬───┘  │    │  └───┬───┘  │     │
+│  │      │      │    │      │      │    │      │      │     │
+│  │  ┌───▼───┐  │    │  ┌───▼───┐  │    │  ┌───▼───┐  │     │
+│  │  │ RAMJET  │◄─┼────┼──┤ RAMJET  │◄─┼────┼──┤ RAMJET  │  │     │
+│  │  │ Cache │──┼────┼──► Cache │──┼────┼──► Cache │  │     │
+│  │  └───────┘  │    │  └───────┘  │    │  └───────┘  │     │
+│  │   500GB SSD │    │   500GB SSD │    │   500GB SSD │     │
+│  └─────────────┘    └─────────────┘    └─────────────┘     │
+│                            │                                 │
+│                            ▼                                 │
+│                   ┌─────────────────┐                       │
+│                   │  RAMJET Dashboard │                       │
+│                   │   (Metrics UI)  │                       │
+│                   └─────────────────┘                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Features
+
+- 🚀 **Zero-config caching** — `ramjetio.init()` handles everything
+- 📊 **Real-time dashboard** — monitor cache hits, throughput, GPU utilization
+- 🔄 **Consistent hashing** — data distributed evenly across nodes
+- 💾 **Disk-backed cache** — survives restarts, uses NVMe SSDs efficiently
+- 🔌 **Works with any setup** — torchrun, DeepSpeed, Accelerate, custom launchers
+- ☁️ **S3/MinIO integration** — configure data source in dashboard, not in code
+
+## Integration Examples
+
+See [docs/INTEGRATION.md](docs/INTEGRATION.md) for detailed examples with:
+- PyTorch DDP with `torchrun`
+- DeepSpeed
+- HuggingFace Accelerate
+- Custom training loops
+- Multi-node clusters
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RAMJET_API_KEY` | Your API key (required) | — |
+| `RAMJET_CACHE_PATH` | Local cache directory | `/tmp/ramjet_cache` |
+| `RAMJET_CACHE_SIZE` | Max cache size | `100GB` |
+| `RAMJET_PORT` | Cache server port | `9000` |
+
+### Dashboard Settings
+
+Configure in the web dashboard (no code changes needed):
+- **Data Source**: S3/MinIO endpoint, bucket, credentials
+- **Cache Settings**: TTL, replication factor, eviction policy
+
+## Distributed Training (DDP)
+
+RAMJET automatically detects `torchrun` and DDP environments:
+
+### Single Machine, Multiple GPUs (torchrun)
+
+```bash
+# 4 GPUs on one machine
+torchrun --nproc_per_node=4 train.py
+```
+
+```python
+import ramjetio
+import torch.distributed as dist
+
+# Only LOCAL_RANK=0 starts cache server - others wait and share it
+ramjetio.init()
+
+# All ranks use the same cache
+dataset = ramjetio.CachedDataset(your_dataset)
+```
+
+### Multi-Node Training
+
+```bash
+# Node 0 (master)
+torchrun --nnodes=2 --node_rank=0 --nproc_per_node=4 \
+         --master_addr=node0 --master_port=29500 train.py
+
+# Node 1
+torchrun --nnodes=2 --node_rank=1 --nproc_per_node=4 \
+         --master_addr=node0 --master_port=29500 train.py
+```
+
+Each node runs one cache server (on LOCAL_RANK=0), and all nodes share data via consistent hashing.
+
+### Separate Processes per Rank
+
+```bash
+# If not using torchrun, set env vars manually:
+export RANK=0 WORLD_SIZE=4 LOCAL_RANK=0
+python train.py
+
+# On another terminal/machine:
+export RANK=1 WORLD_SIZE=4 LOCAL_RANK=0  
+python train.py
+```
+
+RAMJET reads `LOCAL_RANK`, `RANK`, `WORLD_SIZE` from environment to coordinate.
+
+## CLI Tools
+
+```bash
+# Start cache server manually (usually not needed — ramjetio.init() does this)
+ramjetio-server --port 9000 --capacity 100GB
+
+# Check cache status
+ramjetio-client stats
+
+# Clear cache
+ramjetio-client clear
+```
+
+## Requirements
+
+- Python 3.8+
+- PyTorch 1.9+
+- Linux (recommended for production)
+- SSD storage for cache (recommended)
+
+## Documentation
+
+- [Integration Guide](docs/INTEGRATION.md) — detailed examples for all frameworks
+- [API Reference](docs/API.md) — full API documentation
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — common issues and solutions
+
+## License
+
+PolyForm Noncommercial License 1.0.0 — free for personal and non-commercial use.
+For commercial licensing, contact licensing@ramjet.dev. See [LICENSE](LICENSE) for details.
+
+## Support
+
+- 📧 Email: support@ramjet.io
+- 💬 Discord: [discord.gg/ramjet](https://discord.gg/ramjet)
+- 📖 Docs: [docs.ramjet.io](https://docs.ramjet.io)