Metadata-Version: 2.4
Name: vaos-engine
Version: 0.1.1
Summary: Virtual Adaptive Offloading System (vAOS) for Extreme-Scale Deep Learning on Constrained GPUs
Home-page: https://github.com/yourusername/vaos-engine
Author: Your Name
Author-email: your.email@college.edu
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0.0
Requires-Dist: numpy
Requires-Dist: psutil
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: seaborn
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Virtual Adaptive Offloading System (vAOS-Engine)

The **vAOS-Engine** is a lightweight, PyTorch-native runtime controller designed to break the GPU Memory Wall on consumer-grade hardware (e.g., 6GB VRAM laptops).

By virtualizing host CPU RAM as an OS-bypass `mmap` pool, dynamically scheduling asynchronous PCIe transfers, and utilizing late-stage register-level INT4 dequantization, vAOS allows you to train Massive Transformer models that natively trigger Out-Of-Memory (OOM) crashes.

## 🚀 Installation
```bash
pip install vaos-engine 
```

## 🛠️ Complete Setup Guide & Live Demo
Want to see vAOS in action on your own hardware? You can run a live diagnostic test. The engine will auto-probe your hardware, intentionally crash a heavy model to prove your physical memory limits, and then use the vAOS runtime to train it successfully.

# Step 1: Create the Test Script
Create a new file named demo.py anywhere on your computer and paste the following code:
```python
import torch
import torch.nn as nn

# Import the vAOS API and our packaged Heavy Transformer
from src.api import evaluate_system
from src.baseline.model import DummyHeavyTransformer

# 1. Setup a heavy model that normally requires >9GB VRAM
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

model = DummyHeavyTransformer(
    d_model=2048, 
    n_layers=4, 
    n_heads=16, 
    d_ff=8192, 
    vocab_size=32000, 
    max_seq_len=512
).to(device)

# 2. Generate dummy training data
dummy_input = torch.randint(0, 32000, (16, 512), device=device)
dummy_target = torch.randint(0, 32000, (16, 512), device=device)
criterion = nn.CrossEntropyLoss()

# 3. Trigger the vAOS Auto-Analyzer
print("Starting vAOS Hardware Evaluation...")
evaluate_system(model, dummy_input, dummy_target, criterion)

```
# Step 2: Run the Script

Open your terminal (PowerShell, CMD, or Linux terminal) and execute the file:

```bash
python demo.py
```
# Step 3: View your Personalized Report

The engine will execute a ruthless native control trace (until the GPU runs out of memory), followed immediately by the vAOS optimized trace.
Once finished, it will automatically generate a comprehensive, personalized Markdown file named vAOS_Evaluation_Report.md in your current directory. Open it to see your exact mathematical metrics, including:

<br>VRAM effectively saved.</br>
<br>PCIe bandwidth reduction (via INT4 dequantization).</br>
<br>Network synchronization payload optimization (via 90th-percentile Adaptive Sparsification).</br>
